Merge pull request #11 from russlank/feature/ui-upgrade

feat: responsive UI, reproducible export, and project sessions

Author: russlank

.gitignore

@@ -94,6 +94,8 @@ requirements.txt
 /build/**/*
 /artifacts/**/*
 /src/XpressFormula/imgui.ini
+/buildtmp_*/**/*
+/.github/upgrades/**/*
 
 .ai/**/*
 **/*/.ai/**/*

README.md

@@ -18,7 +18,9 @@ The app supports:
 - `f(x,y,z)` scalar-field cross-sections at configurable `z` slices
 - `F(x,y,z)=0` implicit 3D surfaces (e.g. spheres and torus equations)
 - Auto/Force 2D/3D rendering preference with projected 3D grid-plane interleaving (`z=0`) for clearer depth ordering
-- Plot export dialog with size presets/scales, background modes including transparency, scene toggles, export-only quality/supersampling, `.png`/`.bmp` save, clipboard copy, and post-save actions
+- Resizable ImGui sidebar with aligned 3D camera/display property rows, per-control resets, and a compact plot toolbar for common view/export actions
+- Versioned `.xfplot` project files with New/Open/Save/Save As, recent projects, dirty-state tracking, and unsaved-change protection
+- Plot export profiles, aspect-safe framing, preview quality controls, transparent output, quality overrides, and optional JSON metadata sidecars
 - Startup/manual update checks against GitHub releases with quick link to the releases page
 - Versioned binary metadata and installer packaging (`.msi` + setup `.exe`)
 

doc/algorithms-guide.md

@@ -454,6 +454,12 @@ Then triangles are:
 2. sorted by depth
 3. drawn with fill color and optional wireframe
 
+Wire density is separate from mesh resolution:
+
+- explicit `z=f(x,y)` surfaces draw wire rows/columns using `Wire Stride`
+- implicit meshes draw a stride-filtered subset of mesh edges
+- changing stride affects readability and draw cost, but does not resample the surface
+
 Important alignment detail (recent fix):
 
 - 3D projected geometry is anchored to the same world origin (`0,0`) used by the 2D grid/axes.

doc/architecture.md

@@ -22,13 +22,19 @@ XpressFormula is organized into three primary layers:
 - [`src/XpressFormula/Core/UpdateVersionUtils.h`](../src/XpressFormula/Core/UpdateVersionUtils.h)
   - Small header-only utilities for semantic-version parsing/comparison and extracting GitHub release fields from API JSON.
 - [`src/XpressFormula/UI/Application.h`](../src/XpressFormula/UI/Application.h) and [`src/XpressFormula/UI/Application.cpp`](../src/XpressFormula/UI/Application.cpp)
-  - Owns Win32 window, D3D11 resources, ImGui lifecycle, frame loop.
+  - Owns Win32 window, D3D11 resources, ImGui lifecycle, frame loop, main sidebar/plot layout state, plot toolbar actions, and export workflow.
+- [`src/XpressFormula/UI/UiKit`](../src/XpressFormula/UI/UiKit)
+  - Thin immediate-mode UI helpers: shared metrics, pure responsive layout planners, RAII ImGui scopes, deterministic toolbar rows, property grids, splitter sizing, and modal sizing.
+- [`src/XpressFormula/UI/Components`](../src/XpressFormula/UI/Components)
+  - Reusable XpressFormula-specific UI components such as `PlotToolbar` and `FormulaCard`. Components may edit ordinary widget state passed by reference, but collection mutations and application commands stay with panels or `Application`.
 - [`src/XpressFormula/UI/FormulaPanel.h`](../src/XpressFormula/UI/FormulaPanel.h) and [`src/XpressFormula/UI/FormulaPanel.cpp`](../src/XpressFormula/UI/FormulaPanel.cpp)
-  - Formula list management and per-formula controls.
+  - Formula list management, editor modal workflow, collection mutations, and action handling returned by formula-card components.
 - [`src/XpressFormula/UI/ControlPanel.h`](../src/XpressFormula/UI/ControlPanel.h) and [`src/XpressFormula/UI/ControlPanel.cpp`](../src/XpressFormula/UI/ControlPanel.cpp)
-  - Global 2D view controls, display toggles (grid/coordinates/wires), 3D surface camera settings, and export dialog launch action.
+  - Global 2D view controls, display toggles (grid/coordinates/wires), reusable property-grid rows for 3D/heatmap controls, and export dialog launch action.
 - [`src/XpressFormula/UI/PlotPanel.h`](../src/XpressFormula/UI/PlotPanel.h) and [`src/XpressFormula/UI/PlotPanel.cpp`](../src/XpressFormula/UI/PlotPanel.cpp)
   - Interactive plotting area, mouse interactions, and export-time plot render overrides (background/grid/coordinates/wires).
+- [`src/XpressFormula/UI/ProjectSession.h`](../src/XpressFormula/UI/ProjectSession.h)
+  - Versioned `.xfplot` persistence boundary: plain session records, JSON serialization/parsing, schema validation, and safe application of loaded values.
 - [`src/XpressFormula/Version.h`](../src/XpressFormula/Version.h)
   - Centralized semantic version metadata used by window title, resources, and packaging.
 - [`src/XpressFormula/Plotting/PlotRenderer.h`](../src/XpressFormula/Plotting/PlotRenderer.h) and [`src/XpressFormula/Plotting/PlotRenderer.cpp`](../src/XpressFormula/Plotting/PlotRenderer.cpp)
@@ -43,7 +49,36 @@ XpressFormula is organized into three primary layers:
 5. `PlotPanel` updates `ViewTransform` from current viewport and delegates drawing to `PlotRenderer`.
 6. `PlotRenderer` evaluates formulas through `Core::Evaluator` and draws based on variable dimensionality and equation form.
 7. `Application` also polls a background GitHub release check future and updates sidebar notification state when a result arrives.
-8. Export requests trigger a plot-only offscreen render pass (temporary D3D11 render target) with export-specific overrides, then post-processing (pixel-format normalization, optional resize/grayscale) before file/clipboard output.
+8. Export requests resolve aspect/framing settings, trigger a plot-only offscreen render pass (temporary D3D11 render target) with export-specific overrides, then post-processing (pixel-format normalization, optional resize/grayscale) before file/clipboard output.
+9. Project New/Open/Save/Save As workflows stay in `Application`; `.xfplot` parsing completes before active formulas, view, or plot settings are mutated.
+
+## Project Persistence Boundary
+
+`ProjectSession` is the versioned boundary for `.xfplot` files. `Application` still owns live state (`FormulaEntry`, `ViewTransform`, `PlotSettings`, project path, dirty flag, and recent list), while the serializer works on plain records that do not depend on ImGui widgets.
+
+Important rules:
+
+- Build a `ProjectSession` snapshot from application state before saving.
+- Parse and validate a full project file before mutating active application state.
+- Retain invalid loaded formulas where possible and report load warnings after reparsing.
+- Clamp or ignore unsafe numeric values before applying them to the live view and plot settings.
+- Keep unknown fields tolerated for schema version 1 so future writers can add data without breaking older builds.
+- Write project files through a temporary file followed by replacement so failed writes do not leave a partial target file.
+- Treat dirty state as a serialized-state comparison against the last clean snapshot.
+
+`ProjectSession.h` currently contains both the schema records and the small JSON parser/serializer. That can be split later if the format grows, but file size alone is not a reason to refactor it.
+
+## UI Toolkit Boundary
+
+The UI toolkit is intentionally small and immediate-mode. `UiKit` does not own application state, retain widget objects, or replace ordinary ImGui controls. It centralizes policies that are easy to get wrong when repeated inline:
+
+- responsive breakpoints and shared dimensions in `UiMetrics`
+- pure layout decisions that can be unit tested
+- row-height and cursor placement mechanics for responsive toolbars
+- scope safety for ImGui push/pop and disabled blocks
+- repeated table layout behavior for property controls
+
+Domain components live one level above `UiKit`. They render reusable XpressFormula UI surfaces and return explicit action structs for one-shot commands. Panels and `Application` remain responsible for workflows, vector mutation, file/clipboard actions, export processing, and persistent state.
 
 ## Formula Rendering Modes
 

doc/imgui-implementation-guide.md

@@ -40,6 +40,8 @@ The UI is split into focused panels:
   - plot canvas region, mouse interaction, renderer dispatch
 - [`src/XpressFormula/UI/PlotSettings.h`](../src/XpressFormula/UI/PlotSettings.h)
   - shared settings for rendering and camera behavior
+- [`src/XpressFormula/UI/ProjectSession.h`](../src/XpressFormula/UI/ProjectSession.h)
+  - versioned `.xfplot` records, JSON serialization/parsing, and safe session application helpers
 
 Why this split works well:
 
@@ -114,9 +116,10 @@ This is the core frame template you can reuse in similar apps.
 
 ## 6. Layout Strategy in This App
 
-The app uses two fixed ImGui windows that fill the OS window:
+The app uses borderless ImGui windows that fill the OS window:
 
 - left sidebar (`##Sidebar`)
+- vertical splitter (`##SidebarSplitter`)
 - right plot area (`##Plot`)
 
 This is done each frame by setting:
@@ -131,12 +134,44 @@ and then creating borderless windows with flags like:
 - `NoMove`
 - `NoCollapse`
 
+The sidebar width is owned by `Application` state and adjusted through the splitter each frame, with min/max constraints so the plot retains usable space. The plot window reserves a small toolbar child before the canvas; the toolbar mutates the same `ViewTransform` and `PlotSettings` objects as the sidebar, so both control surfaces stay synchronized.
+
 Why this pattern is useful:
 
 - simple, deterministic layout
-- no docking complexity
+- resizable controls without docking complexity
 - easy to extend for desktop tooling apps
 
+## UI Toolkit Design Rules
+
+XpressFormula has a thin UI toolkit in [`src/XpressFormula/UI/UiKit`](../src/XpressFormula/UI/UiKit) and XpressFormula-specific components in [`src/XpressFormula/UI/Components`](../src/XpressFormula/UI/Components).
+
+Use `UiKit` for recurring ImGui mechanics:
+
+- shared spacing, breakpoints, and dimensions in `UiMetrics`
+- pure responsive plans such as toolbar, formula-card, splitter, and modal sizing decisions
+- RAII guards for `Push/Pop`, `Begin/EndDisabled`, and text wrapping
+- small structural helpers such as `ResponsiveRows` and `PropertyGrid`
+
+Use `Components` for reusable app UI that still follows immediate mode:
+
+- `PlotToolbar` renders the plot toolbar and returns one-shot app commands
+- `FormulaCard` renders one formula row/card and returns one formula action
+
+Panels and dialogs still own workflows and state. For example, `FormulaPanel` owns editor state and vector mutations, while `FormulaCard` only renders one card and reports the selected action.
+
+Direct ImGui remains the default for ordinary controls such as buttons, text, sliders, checkboxes, and one-off layouts. Do not add wrappers that only rename ImGui calls.
+
+> Add a toolkit abstraction only after the same layout or safety problem appears in at least two places, or when a pure tested plan can replace fragile cursor arithmetic.
+
+When adding a reusable layout primitive:
+
+1. Put pure decisions in a testable planner where practical.
+2. Keep application state outside the toolkit.
+3. Keep row counts, heights, and cursor placement derived from one calculation.
+4. Return explicit action structs for one-shot commands instead of performing workflow side effects inside components.
+5. Keep escape hatches simple by allowing direct ImGui alongside toolkit helpers.
+
 ## 7. State Ownership (Most Important ImGui Rule Here)
 
 ImGui draws widgets, but your app owns the state.
@@ -147,6 +182,7 @@ In XpressFormula:
 - camera/view state in `m_viewTransform`
 - render settings in `m_plotSettings`
 - transient export requests in booleans/action flags
+- project path, dirty state, recent projects, and unsaved-change prompts in `Application`
 
 Panels receive references to these objects and render widgets directly from them.
 
@@ -161,6 +197,22 @@ This is the recommended mental model:
 
 - UI is just a view/editor for your application state
 
+### Project Persistence State
+
+Project files are deliberately outside the widget layer:
+
+- `Application` owns live state and project workflow commands.
+- `ProjectSession` converts live state to/from plain records.
+- Serializers do not know about ImGui IDs, popups, panels, or layout.
+- Open parses the full file before replacing active formulas, view, and plot settings.
+- Invalid loaded formulas are copied into edit buffers, reparsed, and surfaced as warnings instead of being silently dropped.
+- Dirty state is based on serialized state comparison with the last clean snapshot.
+- Save writes to a temporary file, then replaces the target path.
+
+The unsaved-change modal may request a close, but it must not destroy the Win32 window while ImGui is still rendering. It sets a deferred close flag; `Application::run()` processes that flag after the current frame is complete.
+
+`ProjectSession.h` currently contains both the schema and JSON parser/serializer. Keep it as the persistence boundary unless the format grows enough to justify splitting schema records from parsing code.
+
 ## 8. Panel Communication Pattern
 
 XpressFormula uses two patterns for panel communication:
@@ -179,6 +231,12 @@ Used by `ControlPanel` for one-shot actions:
 
 - open export settings dialog
 
+Used by the plot toolbar for direct application-level commands:
+
+- fit/reset the view
+- open export settings dialog
+- apply deterministic 3D camera presets
+
 Used by `Application` (outside panel code) for other side-effecting actions:
 
 - background update checks (GitHub releases)
@@ -208,6 +266,19 @@ Why "next frame" popup opening is common:
 - ImGui popups are frame-driven
 - opening and rendering often happens in a controlled sequence
 
+### Formula Cards and List Actions
+
+The formula sidebar renders each formula as a compact card:
+
+- header row: visibility, color, formula index, validation status, edit/actions/delete controls
+- expression row: clipped preview text with a full wrapped tooltip
+- metadata row: parsed render type and validation state
+- optional `z slice` control for scalar-field formulas
+
+The card list defers structural mutations until after all cards are drawn for the frame. This matters because duplicating, moving, or deleting a `std::vector<FormulaEntry>` item during the loop would invalidate references used by later cards.
+
+Reusable formula-list operations live in [`src/XpressFormula/UI/FormulaListActions.h`](../src/XpressFormula/UI/FormulaListActions.h). The helper covers duplicate, reorder, delete-index adjustment, hide-others, and exact expression-copy behavior, and is tested outside ImGui. Keep future formula-list state changes in that helper when practical.
+
 ### Live Validation in the Formula Editor
 
 The editor does realtime validation while typing:
@@ -260,6 +331,7 @@ Then it delegates rendering to `PlotRenderer`, which draws:
 - background
 - grid
 - axes
+- corner HUD
 - labels
 - curves/heatmaps/triangles
 
@@ -268,6 +340,19 @@ This separation is important:
 - `PlotPanel` handles interaction and viewport bounds
 - `PlotRenderer` handles math and draw primitives
 
+### Plot HUD and Wire Readability
+
+`PlotSettings` owns the configurable plot HUD mode and the wire styling values. `PlotPanel` renders the HUD in a stable plot corner instead of using a cursor-following tooltip, so it does not cover central geometry while reading coordinates.
+
+The wire controls are intentionally separate:
+
+- `Surface Density` and `Implicit Resolution` change sampling/mesh quality
+- `Wire Opacity` changes visual strength
+- `Wire Thickness` changes line width
+- `Wire Stride` changes displayed wire density without changing mesh sampling
+
+Export preview/final rendering clones `PlotSettings`, so wire opacity, thickness, and stride match the interactive plot. Export overrides disable the interactive HUD so saved images do not include the corner readout.
+
 ## 11. Why the Plot Uses `ImDrawList` Instead of ImGui Widgets
 
 The plotting output is custom geometry, not forms/controls.
@@ -306,11 +391,12 @@ The UI does not directly save images when a button is clicked.
 Instead:
 
 1. `ControlPanel` returns a one-shot action to open the export dialog.
-2. `Application` owns and renders the export settings window (size, colors, background, include/exclude overlays).
-3. When the user clicks **Save** or **Copy**, `Application` stores pending export flags + a snapshot of export settings.
-4. Export dialog preview uses a cached offscreen render texture (refreshed outside the main UI frame to avoid nested ImGui frames).
-5. `PlotPanel` receives temporary render overrides for export and is rendered into a temporary offscreen D3D11 render target (plot-only ImGui frame).
-6. Export is processed after frame rendering (`processPendingExportActions()`), including pixel-format normalization (RGBA->BGRA, alpha handling) and post-processing (optional resize/grayscale), then file/clipboard output.
+2. `Application` owns and renders the export settings window (size, aspect mode, colors, background, include/exclude overlays, preview controls).
+3. Export aspect/framing is resolved through `ExportSettings` helpers before rendering so default exports preserve mathematical proportions.
+4. When the user clicks **Save As...** or **Copy**, `Application` stores pending export flags + a snapshot of export settings.
+5. Export dialog preview uses a cached offscreen render texture (refreshed outside the main UI frame to avoid nested ImGui frames), with Draft/Normal preview quality capped separately from final output.
+6. `PlotPanel` receives temporary render overrides for export and is rendered into a temporary offscreen D3D11 render target (plot-only ImGui frame).
+7. Export is processed after frame rendering (`processPendingExportActions()`), including pixel-format normalization (RGBA->BGRA, alpha handling) and post-processing (optional resize/grayscale), then file/clipboard output.
 
 This avoids mixing:
 

doc/release-packaging.md

@@ -130,6 +130,35 @@ $expectedTag = "v$version"
 Write-Host "Expected release tag: $expectedTag"
 ```
 
+## v1.6.0 Release Verification Record
+
+Last updated: 2026-07-18
+
+Automated verification completed locally with Visual Studio MSBuild 18.8.2:
+
+- [x] Debug x64 app build succeeds:
+  `MSBuild src\XpressFormula\XpressFormula.vcxproj /p:Configuration=Debug /p:Platform=x64 /p:SolutionDir="C:\MyData\Projects\Digixoil\XpressFormula\src\" /m`
+- [x] Release x64 app build succeeds:
+  `MSBuild src\XpressFormula\XpressFormula.vcxproj /p:Configuration=Release /p:Platform=x64 /p:SolutionDir="C:\MyData\Projects\Digixoil\XpressFormula\src\" /m`
+- [x] Debug x64 test project builds:
+  `MSBuild src\XpressFormula.Tests\XpressFormula.Tests.vcxproj /p:Configuration=Debug /p:Platform=x64 /m`
+- [x] Release x64 test project builds:
+  `MSBuild src\XpressFormula.Tests\XpressFormula.Tests.vcxproj /p:Configuration=Release /p:Platform=x64 /m`
+- [x] No new compiler warnings in the above builds (`0 Warning(s)`).
+- [x] Automated tests pass: `src\XpressFormula.Tests\x64\Debug\XpressFormula.Tests.exe` reported `359/359 tests passed`.
+- [x] Release test executable also reported `359/359 tests passed`.
+- [x] Existing core tests pass.
+- [x] New project-session tests pass.
+- [x] Export settings and metadata tests pass.
+- [x] UI layout-plan tests pass.
+- [x] Formula-list action tests pass.
+
+Manual verification still required before tagging:
+
+- [ ] Project workflows: New, Open valid `.xfplot`, Save, Save As, Recent reopen, dirty marker set/clear, Save/Discard/Cancel before New/Open/Close, unsupported schema error, malformed file error, invalid formula warning, Unicode formula round trip, multiple save/load cycles retaining values.
+- [ ] Export workflows: every export profile, transparent PNG, grayscale export, metadata sidecar output, metadata JSON opens in a parser/editor, preview/final export parity, offscreen fallback behavior if reproducible.
+- [ ] Responsive UI: wide/medium/compact/extra-compact toolbar, minimum/default/maximum sidebar width, narrow/short windows, formula cards at narrow widths, and 100%, 125%, 150%, and 200% Windows scaling where available.
+
 ## How to Change Versions
 
 1. Application version: