Modernize architecture and harden core application workflows

[russlank]

Summary

This PR completes a broad architectural modernization of XpressFormula.

The application has been reorganized as a modular C++ monolith with explicit boundaries between expression processing, domain state, plotting, infrastructure, UI, application workflows, and the executable host.

The work also strengthens formula validation, project persistence, export handling, geometry generation, resource limits, update checking, CI validation, and public documentation.

Motivation

The previous structure had several responsibilities concentrated in the UI/application layer, with persistence, rendering, export, formula editing, and platform operations closely coupled.

This made the code harder to test, extend, and reason about.

The modernization aims to provide:

• clearer ownership of responsibilities;
• enforceable dependency direction;
• smaller and more testable components;
• safer persistence and export workflows;
• more predictable dirty-state handling;
• reusable expression and plotting foundations;
• stronger handling of malformed or excessive input.

Main changes

Architecture

Introduces first-party static-library boundaries for:

• Expression
• Model
• Plotting
• Infrastructure
• UI
• Application
• Executable host

Architecture rules are documented and enforced through:

tools/check-architecture-boundaries.ps1

The CI check validates include dependencies, project references, production source ownership, test linkage, warning/toolset policy, and public/private documentation separation.

Document and application state

• Added Model::Document as the live project aggregate.
• Added revision-based dirty-state tracking.
• Persistent mutations increment the document revision.
• No-op operations do not dirty the document.
• Runtime viewport and auto-rotation state remain transient.
• Added focused document commands for formula, view, and plot-setting changes.
• Added ProjectController for New, Open, Save, Save As, recent projects, and unsaved-change workflows.

Expression compiler and runtime

• Centralized built-in functions and constants in registries.
• Added fixed-slot evaluation for x, y, and z.
• Removed map lookups and per-function-call heap allocation from plotting evaluation paths.
• Added non-throwing numeric-literal parsing.
• Added compile-time function-arity validation.
• Added formula length, token, nesting, AST-node, and AST-depth limits.
• Improved diagnostics for malformed expressions and equations.
• Prevented stale compiled formula state after expression changes.

Formula editor

• Replaced per-frame mutable formula snapshots with explicit typed commands.
• Added stable formula-ID targeting.
• Made Add Formula transactional:
  • Apply inserts the formula.
  • Cancel leaves the document unchanged.
• Edit operations preserve identity and ignore stale targets safely.
• Added dynamic, lossless formula text editing and live validation.

Plotting and geometry

• Separated pure sampling and meshing from ImGui rendering.
• Added reusable geometry generation for:
  • curves;
  • scalar grids;
  • implicit contours;
  • explicit surfaces;
  • implicit 3D surfaces.
• Added render-plan and cache foundations.
• Added centralized plot-quality and rendering policies.
• Added Marching Squares saddle disambiguation.
• Improved exact-zero, non-finite, and degenerate geometry handling.
• Added unique Surface Nets cell-intersection handling and degenerate-triangle rejection.

Persistence and JSON

• Added versioned project DTOs, serializer, mapper, repository, and recent-project store.
• Kept .xfplot schema version 1.
• Added strict internal JSON parsing with:
  • duplicate-key rejection;
  • UTF-8 validation;
  • surrogate validation;
  • nesting and value-count limits;
  • strict numeric parsing.
• Added bounded project-file reads.
• Added formula-count, expression-length, and serialized-size validation.
• Added unique same-directory temporary files and atomic replacement.
• Failed loads preserve the active document.
• Failed saves preserve the previous target file.

Export and Windows services

• Extracted export settings, image processing, output workflow, and metadata handling.
• Extracted Windows services for dialogs, clipboard, shell operations, WIC encoding, UTF conversion, and HTTP.
• Added checked image-buffer arithmetic.
• Added safe fallback handling for invalid or non-finite export bounds.
• Added HTTP response-size limits.
• Update checks no longer block application shutdown.

Documentation and CI

Added or substantially updated:

• architecture overview;
• dependency rules;
• architecture decision records;
• expression-language reference;
• algorithms guide;
• testing guide;
• run and debugging guide;
• release-packaging guide;
• contributing guide.

PR Validation now performs:

1. architecture-boundary checks;
2. Debug application build;
3. Debug test build and execution;
4. Release application build;
5. Release test build and execution.

Release packaging also runs architecture and Release test checks before packaging.

Compatibility

• .xfplot remains at schema version 1.
• Existing project workflows remain supported.
• Export metadata compatibility is preserved.
• No private modernization roadmap or prompt-tracking material is included.
• The repository and CI now default to Visual Studio 2026 / MSVC toolset v145.
• Visual Studio 2022 users may explicitly retarget local builds to an installed toolset such as v143.

Verification

Automated verification on the current branch:

• Architecture-boundary check passes.
• Debug x64 application builds.
• Release x64 application builds.
• Debug test project builds.
• Release test project builds.
• Debug tests: 531/531 passed.
• Release tests: 531/531 passed.
• Zero first-party compiler warnings and errors.
• Local release workflow dry run passes.
• PR Validation run #8 passed.

The expression benchmark was not rerun for the final closure commit because that commit did not change evaluator runtime behavior.

Manual verification before release

The following interactive checks should still be completed before creating the release tag:

• Formula editor Add/Apply, Add/Cancel, Edit/Apply, and Edit/Cancel.
• Closing the application during a pending update check.
• 2D curves, discontinuities, contours, heatmaps, and scalar slices.
• Explicit and implicit 3D surfaces, including multiple surfaces.
• Camera presets, auto-rotation, grid, coordinates, wires, and envelope.
• New, Open, Save, Save As, Recent, and unsaved-change dialogs.
• Malformed, unsupported, oversized, and Unicode project files.
• PNG/BMP, transparent, grayscale, metadata, clipboard, and shell export actions.
• Wide, compact, narrow, and high-DPI UI layouts.

Review notes

Because this is a large architectural PR, review is easiest by area:

1. project and document ownership;
2. expression compiler/runtime;
3. plotting and meshing;
4. persistence and JSON;
5. export and platform services;
6. CI, tests, and documentation.