feat(viewer): restore reproducible archival rendering

.gitattributes

@@ -1 +1,2 @@
 *.bat text eol=crlf
+viewer/fixtures/**/*.off binary

.gitignore

@@ -46,6 +46,7 @@ output*
 errors
 *.off
 !reference/raw/**/*.off
+!viewer/fixtures/**/*.off
 *.dat
 slurm-*.out
 

.zed/debug.json

@@ -0,0 +1,28 @@
+[
+  {
+    "label": "CDT++: Debug initializer",
+    "adapter": "CodeLLDB",
+    "request": "launch",
+    "build": "CDT++: Build Debug",
+    "program": "$ZED_WORKTREE_ROOT/out/build/debug/src/initialize",
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "args": [
+      "--spherical",
+      "--simplices",
+      "64",
+      "--timeslices",
+      "3",
+      "--seed",
+      "92"
+    ]
+  },
+  {
+    "label": "CDT++: Debug simulator CLI",
+    "adapter": "CodeLLDB",
+    "request": "launch",
+    "build": "CDT++: Build Debug",
+    "program": "$ZED_WORKTREE_ROOT/out/build/debug/src/cdt",
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "args": ["--help"]
+  }
+]

.zed/tasks.json

@@ -0,0 +1,44 @@
+[
+  {
+    "label": "CDT++: Check",
+    "command": "just",
+    "args": ["check"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  },
+  {
+    "label": "CDT++: Build",
+    "command": "just",
+    "args": ["build"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  },
+  {
+    "label": "CDT++: Build Debug",
+    "command": "just",
+    "args": ["build-debug"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  },
+  {
+    "label": "CDT++: Build Parallel",
+    "command": "just",
+    "args": ["build-parallel"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  },
+  {
+    "label": "CDT++: CI",
+    "command": "just",
+    "args": ["ci"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  },
+  {
+    "label": "CDT++: Render Viewer",
+    "command": "just",
+    "args": ["viewer-render"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "save": "all"
+  }
+]

CMakeLists.txt

@@ -119,6 +119,8 @@ option(BUILD_SHARED_LIBS "Enable compilation of shared libraries" OFF)
 option(ENABLE_TESTING "Enable building of tests" ON)
 option(ENABLE_PARALLEL_TRIANGULATION
        "Enable CGAL parallel Delaunay insertion and removal in production targets" OFF)
+option(ENABLE_VIEWER
+       "Build the opt-in CGAL/Qt archival viewer and artifact smoke test" OFF)
 option(ENABLE_DEPRECATION_ERRORS
        "Treat deprecated C++ and CGAL API use in project targets as an error" ON)
 
@@ -174,7 +176,18 @@ endif()
 set(CGAL_DONT_OVERRIDE_CMAKE_FLAGS
     TRUE
     CACHE BOOL "Force CGAL to maintain CMAKE flags")
-find_package(CGAL 6.2 EXACT CONFIG REQUIRED)
+if(ENABLE_VIEWER)
+  find_package(CGAL 6.2 EXACT CONFIG REQUIRED COMPONENTS Qt6)
+  find_package(Qt6 REQUIRED COMPONENTS Core Gui OpenGLWidgets Widgets)
+  if(NOT TARGET CGAL::CGAL_Basic_viewer)
+    message(
+      FATAL_ERROR
+        "ENABLE_VIEWER requires CGAL's Qt feature and CGAL::CGAL_Basic_viewer. Use the viewer preset or install the equivalent CGAL/Qt dependencies."
+    )
+  endif()
+else()
+  find_package(CGAL 6.2 EXACT CONFIG REQUIRED)
+endif()
 
 # https://howardhinnant.github.io/date/date.html
 find_package(date CONFIG REQUIRED)

CMakePresets.json

@@ -76,6 +76,22 @@
         "ENABLE_PARALLEL_TRIANGULATION": true
       }
     },
+    {
+      "name": "viewer",
+      "displayName": "Archival CGAL/Qt viewer",
+      "description": "Configure the opt-in macOS artifact renderer without changing the headless reference build",
+      "inherits": "reference",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Darwin"
+      },
+      "binaryDir": "${sourceDir}/out/build/viewer",
+      "cacheVariables": {
+        "ENABLE_VIEWER": true,
+        "VCPKG_MANIFEST_FEATURES": "viewer"
+      }
+    },
     {
       "name": "debug",
       "displayName": "Local debug build",
@@ -136,6 +152,14 @@
       "displayName": "Build the supported CGAL/oneTBB targets",
       "configurePreset": "parallel"
     },
+    {
+      "name": "viewer",
+      "displayName": "Build the archival CGAL/Qt viewer",
+      "configurePreset": "viewer",
+      "targets": [
+        "cdt-viewer"
+      ]
+    },
     {
       "name": "debug",
       "displayName": "Build production targets with CDT++ assertions enabled",
@@ -173,6 +197,24 @@
         "stopOnFailure": false
       }
     },
+    {
+      "name": "viewer-smoke",
+      "displayName": "Render the tracked hero fixture without interaction",
+      "description": "Load and validate the versioned OFF fixture, initialize CGAL/Qt, and write a nonempty PNG",
+      "configurePreset": "viewer",
+      "filter": {
+        "include": {
+          "label": "^viewer$"
+        }
+      },
+      "output": {
+        "outputOnFailure": true
+      },
+      "execution": {
+        "noTestsAction": "error",
+        "stopOnFailure": true
+      }
+    },
     {
       "name": "debug-cli",
       "displayName": "Run CLI integration tests with CDT++ assertions",

Justfile

@@ -25,7 +25,10 @@ python_version := "3.14.6"
 reference_fixture_binary := if os_family() == "windows" { "out/build/reference/tests/CDT_reference_fixture.exe" } else { "out/build/reference/tests/CDT_reference_fixture" }
 rng_benchmark_binary := if os_family() == "windows" { "out/build/reference/tests/CDT_rng_benchmark.exe" } else { "out/build/reference/tests/CDT_rng_benchmark" }
 typos_version := "1.49.0"
-uv_version := "0.12.2"
+uv_version := "0.12.3"
+viewer_binary := "out/build/viewer/src/cdt-viewer"
+viewer_image := "docs/images/S3-7-27528-I1-R1.png"
+viewer_manifest := "viewer/manifests/v1/hero.json"
 zizmor_version := "1.28.0"
 
 [private]
@@ -80,6 +83,15 @@ _build-unix:
     fi
     exec ./scripts/build.sh
 
+[private]
+_build-viewer-unix:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if command -v pkgx >/dev/null; then
+      exec ./scripts/pkgx-build.sh --preset viewer
+    fi
+    exec ./scripts/build.sh viewer
+
 [private]
 _cmake-check:
     #!/usr/bin/env bash
@@ -294,7 +306,7 @@ changelog-unreleased version: _ensure-git-cliff _sync-python-dev
 
 # Run fast, non-mutating local validation.
 [group('workflows')]
-check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check reference-check semgrep semgrep-test spell-check
+check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check reference-check semgrep semgrep-test spell-check viewer-check
     @echo "Checks complete."
 
 # Run the comprehensive pre-commit/pre-push validation gate.
@@ -396,6 +408,22 @@ python-entrypoint-test: _sync-python-dev
     uv run --no-sync cdt-tag-release --help >/dev/null
     uv run --no-sync python scripts/sync_vcpkg_tool_pins.py --help >/dev/null
 
+# Build the opt-in macOS CGAL/Qt viewer and run its noninteractive render smoke test.
+[group('workflows')]
+viewer-build:
+    {{ if os() == "macos" { "just _build-viewer-unix" } else if os() == "windows" { "cmd.exe //d //c \"echo The archival viewer is not supported on Windows. 1>&2 & exit /b 2\"" } else if os() == "linux" { "sh -c 'echo The archival viewer is not supported on Linux. 1>&2; exit 2'" } else { "sh -c 'echo The archival viewer is supported only on macOS. 1>&2; exit 2'" } }}
+
+# Validate the tracked viewer fixture, render manifest, and canonical hero image.
+[group('workflows')]
+viewer-check: _sync-python-dev
+    uv run --no-sync python scripts/validate_viewer_artifacts.py
+
+# Regenerate the README hero image from the tracked fixture and render manifest.
+[group('workflows')]
+viewer-render: viewer-build
+    {{ viewer_binary }} --manifest {{ quote(viewer_manifest) }} --output {{ quote(viewer_image) }}
+    just viewer-check
+
 # Apply Ruff lint fixes and formatting to Python source.
 [group('workflows')]
 python-fix: _sync-python-dev
@@ -443,6 +471,7 @@ python-package-check: _sync-python-dev
     (
       cd "$consumer_directory"
       "$python" -c "import scripts"
+      "$python" -c "import importlib.util, sys; sys.exit('repository-only viewer validator leaked into wheel') if importlib.util.find_spec('scripts.validate_viewer_artifacts') is not None else None"
       "$scripts_directory/cdt-bootstrap-vcpkg$executable_suffix" --help >/dev/null
       "$scripts_directory/cdt-compare$executable_suffix" --help >/dev/null
       "$scripts_directory/cdt-optimize-initialize$executable_suffix" --help >/dev/null

README.md

@@ -11,6 +11,9 @@
 
 ![Small foliated Delaunay triangulation](docs/images/S3-7-27528-I1-R1.png "7 timeslices 27528 simplices")
 
+This reproducible archival rendering is generated from a tracked triangulation fixture; see the
+[viewer and visual-artifact contract](docs/viewer.md).
+
 ## Maintenance status
 
 CDT++ v1.0.0-rc3 is the current C++23 release candidate. The repository remains maintained as an independent
@@ -133,8 +136,8 @@ exact transition replay requires an identical starting manifold; CDT++ does
 not alter its spherical construction to force CGAL to reproduce one of several
 valid cospherical tetrahedralizations.
 
-- `cdt-viewer` is currently disabled and will be restored as an opt-in v1.0.0
-  target by [#98](https://github.com/acgetchell/CDT-plusplus/issues/98).
+- `cdt-viewer` is an opt-in macOS archival target. Build it with `just viewer-build`, regenerate the tracked hero image
+  with `just viewer-render`, and see the [viewer contract](docs/viewer.md) for its narrower support boundary.
 - `initialize` is also used by the dependency-free local parameter sweep described under
   [offline comparison](#offline-comparison).
 
@@ -162,7 +165,7 @@ Build and dependency instructions begin at [Quickstart](#quickstart).
 - [x] Use [{fmt}] library (instead of `iostream`)
 - [x] 3D Metropolis algorithm
 - [x] Multithreaded logging with [spdlog]
-- [ ] Restore optional visualization with [Qt] ([#98](https://github.com/acgetchell/CDT-plusplus/issues/98))
+- [x] Restore optional visualization with [Qt] ([#98](https://github.com/acgetchell/CDT-plusplus/issues/98))
 - [ ] Initialize two masses
 - [ ] The shortest path algorithm
 - [ ] Einstein tensor
@@ -399,6 +402,11 @@ preserve a compatible CMake cache and refresh it only when the selected vcpkg to
 invocations must expose CMake 4.4.0 or newer on `PATH`; the canonical pkgx-backed `just` recipes select the tested
 4.4.1 toolchain automatically.
 
+The archival Qt viewer is deliberately outside that cross-platform headless contract. On macOS, `just viewer-build`
+selects the separate `viewer` preset and vcpkg feature, builds `cdt-viewer` under `out/build/viewer`, and runs its
+noninteractive image smoke test. Qt and Eigen are installed only in that build tree. See
+[`docs/viewer.md`](docs/viewer.md) for regeneration, version pins, and portability rules.
+
 ### Project Layout
 
 The project is similar to [PitchFork Layout], as follows:
@@ -412,6 +420,7 @@ The project is similar to [PitchFork Layout], as follows:
 - scripts - Build, test, and run scripts
 - src - Source files
 - tests - Unit tests
+- viewer - Versioned archival render fixtures, manifests, and schemas
 
 ## Command-line reference
 
@@ -666,10 +675,10 @@ triangulations remain subject to the [reproducibility contract](docs/reproducibi
 
 ## Visualization
 
-The Qt-based `cdt-viewer` target is currently disabled. Its opt-in dependency feature, deterministic smoke fixture,
-supported desktop matrix, and v1.0.0 restoration are tracked by
-[#98](https://github.com/acgetchell/CDT-plusplus/issues/98); Qt and Eigen are intentionally absent from the default
-headless build until that work is complete.
+The restored Qt-based `cdt-viewer` is an opt-in macOS archival renderer. Its tracked OFF fixture, render manifest,
+noninteractive smoke test, exact canonical-image policy, and inventory of historical visuals are documented in the
+[viewer and visual-artifact contract](docs/viewer.md). The default build remains headless and does not install Qt or
+Eigen.
 
 ## Contributing
 

docs/cgal-integration.md

@@ -46,7 +46,7 @@ CDT++ does not disable CGAL triangulation assertions or postconditions.
 | Checked Delaunay and TDS flips | Retained | CGAL establishes combinatorial/geometric flippability; typed applicable moves independently establish CDT causal admissibility. |
 | Persistence and fingerprints | Modernized | Use finite handle ranges while preserving canonical sorting. Native CGAL stream data remains version-coupled and is not claimed as a stable interchange format. |
 | Spherical point generation | Retained | A caller-owned CDT random stream seeds `CGAL::Random`; the generated sequence and the limits of cospherical topology replay are documented separately. |
-| CGAL timers and visualization | Removed from production | Production code uses standard timing and has no CGAL timer dependency. Qt visualization remains separately owned by issue #98. |
+| CGAL timers and visualization | Archival opt-in only | Production code uses standard timing and has no CGAL timer dependency. The separate macOS-only `viewer` feature restores CGAL 6.2's Qt basic viewer without changing the default headless graph; see the [viewer contract](viewer.md). |
 | Periodic 3D and d-dimensional torus prototypes | Excluded | These remain under `cdt::experimental`, outside supported-header compilation and production dependency decisions. They are archival source, not supported CGAL 6.2 APIs. |
 
 No production path uses a deprecated CGAL triangulation API. Canonical

docs/reproducibility.md

@@ -141,6 +141,16 @@ does not override CGAL's non-unique cospherical tetrahedralization. Exact
 transition replay is conditional on supplying an identical starting manifold;
 it is not checkpoint resume.
 
+The tracked OFF fixture used by the archival renderer is therefore the canonical rendering input. Its recorded seed
+and producer command reproduce stochastic inputs but are provenance, not a promise that fresh CGAL construction will
+produce the same topology. The neighboring metadata manifest, render manifest, and image policy are specified in the
+[viewer contract](viewer.md).
+
+Canonical PNG regeneration is version-locked separately from stochastic replay: `viewer/manifests/v1/hero.json`
+records the exact CGAL and Qt versions and the same vcpkg baseline pinned by `vcpkg.json`. Run `just viewer-render`
+only on the manifest's canonical macOS toolchain when updating the committed raster; other environments use the
+structural smoke policy documented by the viewer contract.
+
 Payload parsing is supported for the repository's declared build matrix and
 pinned dependency set. Exact PCG prefixes replay on the same supported
 toolchain; transition traces replay when the starting manifold is identical.