Build combined vector showcase + geometry runtime final docs-driven integration

- productize first-class tools landing/showcase surface
- enforce engine theme across all active tools
- finalize deterministic vector geometry runtime contracts
- preserve legacy sprite editor path while excluding it from active platform surface

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -1,31 +1,36 @@
+# Codex Commands
+
+## Primary build
 MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION as a single combined build PR.
+Create `BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL` as a docs-driven implementation PR that combines the final public-facing vector platform showcase with deterministic geometry runtime finalization.
+
+### Goals
+- registry-driven showcase surface
+- mandatory engine theme across all active first-class tools
+- deterministic vector geometry runtime contracts
+- stable transform/render/precision behavior
+- preserve `tools/SpritEditor_old_keep/` but exclude it from active platform surface
 
-GOAL:
-Finish the active tools platform in the fewest remaining steps by making all first-class tools use the engine theme and closing remaining platform-surface integration gaps.
+### Active first-class tools
+- `tools/Vector Map Editor/`
+- `tools/Vector Asset Studio/`
+- `tools/Tile Map Editor/`
+- `tools/Parallax Editor/`
 
-DO:
-1. Identify the existing engine theme source of truth
-2. Normalize/extract a reusable shared theme contract only if needed
-3. Apply the engine theme to all active tools under tools/
-   - Vector Map Editor
-   - Vector Asset Studio
-   - Tile Map Editor
-   - Parallax Editor
-4. Unify shared shell/surface elements across active tools
-5. Ensure active tools surface/index/navigation reflects only active tools
-6. Preserve but exclude tools/SpritEditor_old_keep from active tool listings
-7. Fix broken paths/imports/assets caused by the consolidation if encountered
-8. Validate active tool loading and visual consistency
+### Constraints
+- keep changes surgical
+- do not delete legacy sprite editor preserved path
+- no obsolete `Sprite Editor V3` references
+- no runtime-breaking engine rewrites
+- do not hardcode duplicate tool lists outside registry
+- prefer shared engine/theme and shared vector runtime over tool-specific behavior
 
-DO NOT:
-- delete legacy Sprite content
-- invent a second theme system
-- perform unrelated refactors
-- split into multiple PRs unless a true blocker is discovered
+### Package output
+Create:
+`<project folder>/tmp/BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.zip`
 
-OUTPUT:
-<project folder>/tmp/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.zip
+## Commit comment
+Use `docs/dev/commit_comment.txt`.

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Complete final active-tools platform integration by rebasing the shared shell onto the engine theme, preserving registry-driven navigation, and excluding preserved sprite tooling from the first-class surface.
+Finalize the registry-driven vector platform showcase and deterministic geometry runtime contract while preserving legacy sprite paths outside the active surface.

docs/dev/reports/change_summary.txt

@@ -1,16 +1,13 @@
-BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION
+CHANGE SUMMARY
 
-Summary:
-- makes engine theme mandatory for all active first-class tools
-- combines remaining theme/surface integration into one build PR
-- preserves legacy Sprite editor while excluding it from active tool surface
-- aims to finish platform polish in the fewest possible remaining steps
+Bundle:
+BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL
 
-Active tools in scope:
-- tools/Vector Map Editor/
-- tools/Vector Asset Studio/
-- tools/Tile Map Editor/
-- tools/Parallax Editor/
+Intent:
+Combine the last two major remaining docs-only steps into one Codex-ready PR bundle.
 
-Legacy preserved:
-- tools/SpritEditor_old_keep/
+What this bundle tells Codex to do:
+1. Build the public-facing platform showcase / landing surface.
+2. Make active tools registry-driven and engine-theme consistent.
+3. Finalize deterministic vector geometry runtime contracts.
+4. Keep legacy sprite editor preserved but excluded from the active platform surface.

docs/dev/reports/file_tree.txt

@@ -1,10 +1,11 @@
-docs/
-  pr/
-    BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md
-  dev/
-    codex_commands.md
-    commit_comment.txt
-    reports/
-      change_summary.txt
-      validation_checklist.txt
-      file_tree.txt
+BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL/
+└── docs/
+    ├── pr/
+    │   └── BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.md
+    └── dev/
+        ├── codex_commands.md
+        ├── commit_comment.txt
+        └── reports/
+            ├── change_summary.txt
+            ├── validation_checklist.txt
+            └── file_tree.txt

docs/dev/reports/validation_checklist.txt

@@ -1,14 +1,21 @@
-BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION Validation Checklist
+VALIDATION CHECKLIST
 
-[ ] Engine theme source of truth identified
-[ ] Shared theme contract reusable by active tools
-[ ] Vector Map Editor uses engine theme
-[ ] Vector Asset Studio uses engine theme
-[ ] Tile Map Editor uses engine theme
-[ ] Parallax Editor uses engine theme
-[ ] Shared shell/surface behavior consistent across active tools
-[ ] Active tool list excludes SpritEditor_old_keep
-[ ] No stale deprecated tool-name references remain on active surface
-[ ] No broken imports/paths/assets introduced by theme consolidation
-[ ] Active tools load without obvious console/runtime errors
-[ ] Final visual result reads as one coherent platform
+[ ] `tools/` remains the first-class active tool root
+[ ] Active tools shown only via registry
+[ ] Showcase surface lists only:
+    [ ] Vector Map Editor
+    [ ] Vector Asset Studio
+    [ ] Tile Map Editor
+    [ ] Parallax Editor
+[ ] `tools/SpritEditor_old_keep/` preserved
+[ ] Legacy sprite editor excluded from active showcase surface
+[ ] No `Sprite Editor V3` references remain
+[ ] All active tools consume engine theme tokens
+[ ] Shared shell/header/nav language is normalized
+[ ] Deterministic transform order documented
+[ ] Deterministic render ordering documented
+[ ] Precision / epsilon policy documented
+[ ] Path normalization rules documented
+[ ] Vector-native sample scenarios render stably
+[ ] No broken active tool links
+[ ] Combined PR remains surgical and docs-first

docs/pr/BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.md

@@ -0,0 +1,84 @@
+# BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL
+
+## Purpose
+Deliver the final public-facing vector platform showcase and deterministic vector geometry runtime finalization in one surgical build PR.
+
+## Scope
+In scope:
+- registry-driven showcase surface for the active first-class tools
+- mandatory engine theme framing for the active tools platform
+- explicit deterministic vector geometry runtime policy
+- stable transform, render-order, and precision contract visibility
+- preserved-but-excluded legacy sprite tooling
+
+Out of scope:
+- gameplay feature work
+- engine rewrites
+- duplicate tool navigation lists outside the registry
+- deletion of preserved sprite paths
+
+## Active First-Class Tools
+- `tools/Vector Map Editor/`
+- `tools/Vector Asset Studio/`
+- `tools/Tilemap Studio/`
+- `tools/Parallax Scene Studio/`
+
+## Preserved But Excluded
+- actual preserved legacy path on disk: `tools/SpriteEditor_old_keep/`
+- preserved current sprite workspace on disk: `tools/Sprite Editor/`
+- neither preserved sprite path appears in the active platform showcase or shared navigation
+
+## Modules Created Or Changed
+- `tools/toolRegistry.js`
+- `tools/renderToolsIndex.js`
+- `tools/index.html`
+- `tools/shared/platformShell.css`
+- `tools/shared/vectorGeometryRuntime.js`
+- `tests/tools/VectorGeometryRuntime.test.mjs`
+- `docs/pr/BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.md`
+- `docs/dev/COMMIT_COMMENT.txt`
+
+## Showcase Surface Summary
+- the tools landing surface remains registry-driven through `tools/toolRegistry.js`
+- active showcase cards now render richer public-facing metadata from the registry instead of hardcoded per-page content
+- each first-class tool card now exposes its canonical open action and registry-owned sample/help entry points where available
+- the landing page explicitly calls out the shared engine theme and deterministic geometry runtime proof without duplicating the active tool list outside the registry
+
+## Geometry Runtime Finalization
+- `tools/shared/vectorGeometryRuntime.js` now exports `VECTOR_GEOMETRY_RUNTIME_POLICY`
+- the policy makes the deterministic runtime contract explicit:
+  - fixed six-decimal rounding
+  - epsilon `0.000001`
+  - transform order `scale -> rotate -> translate`
+  - render order `layer order -> shape order`
+  - collision primitives follow render order
+- prepared runtime assets now carry the shared `runtimePolicy` payload and a deterministic policy report
+
+## Shared Boundaries Preserved
+- `engine/ui/hubCommon.css` remains the engine theme source of truth
+- `tools/shared/platformShell.css` remains the shared tool-shell layer consuming engine theme tokens
+- `tools/toolRegistry.js` remains the single source of truth for active tool visibility and showcase metadata
+- geometry runtime behavior remains shared infrastructure, not tool-specific logic
+
+## Validation Performed
+- `node --check tools/toolRegistry.js`
+- `node --check tools/renderToolsIndex.js`
+- `node --check tools/shared/platformShell.js`
+- `node --check tools/shared/vectorGeometryRuntime.js`
+- `node --check scripts/validate-active-tools-surface.mjs`
+- `node --check tests/tools/VectorGeometryRuntime.test.mjs`
+- `node scripts/validate-active-tools-surface.mjs`
+- `node scripts/run-node-tests.mjs`
+
+## Validation Summary
+- active showcase cards still come from the registry only
+- active landing and navigation still exclude preserved sprite paths
+- no obsolete deprecated sprite-rename references remain in the validated surface
+- active tools still load the engine theme and shared shell
+- repeated vector geometry runtime preparation now asserts deep deterministic equality in tests
+- vector-native template and sample-game flows continue to consume `runtimeKind: "vector-geometry"` assets under the shared runtime contract
+
+## Follow-Up Recommendations
+- keep future showcase-card changes in `tools/toolRegistry.js` and `tools/renderToolsIndex.js`
+- keep future geometry runtime precision changes centralized in `tools/shared/vectorGeometryRuntime.js`
+- avoid adding tool-local geometry policy forks

scripts/validate-active-tools-surface.mjs

@@ -25,7 +25,7 @@ const SCAN_TARGETS = [
   "tools/renderToolsIndex.js",
   "tools/shared/platformShell.js",
   "tools/shared/platformShell.css",
-  "docs/pr/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md",
+  "docs/pr/BUILD_PR_VECTOR_SHOWCASE_AND_GEOMETRY_RUNTIME_FINAL.md",
   "docs/dev/commit_comment.txt"
 ];
 
@@ -81,6 +81,13 @@ async function main() {
     if (TOOL_NAME_SUFFIX_PATTERN.test(tool.displayName) || TOOL_NAME_SUFFIX_PATTERN.test(tool.folderName)) {
       issues.push(`Disallowed active naming suffix detected for ${tool.displayName} (${tool.folderName}).`);
     }
+    const sampleEntryPoints = Array.isArray(tool.sampleEntryPoints) ? tool.sampleEntryPoints : [];
+    for (const sampleEntry of sampleEntryPoints) {
+      const samplePath = path.join(repoRoot, "tools", sampleEntry.path);
+      if (!(await pathExists(samplePath))) {
+        issues.push(`Missing showcase sample/help entry point for ${tool.displayName}: tools/${sampleEntry.path}`);
+      }
+    }
   }
 
   const visibleLegacyTools = toolRegistry.filter((tool) => tool.status === "legacy" && tool.visibleInToolsList === true);

tests/tools/VectorGeometryRuntime.test.mjs

@@ -3,7 +3,8 @@ import { loadPackagedProjectRuntime } from "../../tools/shared/runtimeAssetLoade
 import {
   inspectVectorGeometryRuntimeAsset,
   prepareVectorGeometryRuntimeAsset,
-  summarizeVectorGeometryRuntime
+  summarizeVectorGeometryRuntime,
+  VECTOR_GEOMETRY_RUNTIME_POLICY
 } from "../../tools/shared/vectorGeometryRuntime.js";
 import { normalizeSvgToVectorAsset } from "../../tools/shared/vector/vectorAssetBridge.js";
 import { VECTOR_ASSET_FORMAT } from "../../tools/shared/vector/vectorAssetContract.js";
@@ -146,11 +147,22 @@ export async function run() {
   assert.equal(runtimeAsset.renderables.length, 2);
   assert.equal(runtimeAsset.collisionPrimitives.length, 2);
   assert.deepEqual(runtimeAsset.bounds.center, { x: 10, y: 3 });
+  assert.deepEqual(runtimeAsset.runtimePolicy, VECTOR_GEOMETRY_RUNTIME_POLICY);
+  assert.equal(runtimeAsset.reports.at(-1)?.code, "VECTOR_RUNTIME_POLICY");
   assert.equal(
     summarizeVectorGeometryRuntime(runtimeAsset),
     "Vector geometry runtime ready for vector.contract.sample with 2 renderable primitives."
   );
 
+  const repeatedRuntimeAsset = prepareVectorGeometryRuntimeAsset(contractAsset, {
+    transform: {
+      translate: { x: 10, y: 5 },
+      rotateRadians: 0,
+      scale: { x: 1, y: 1 }
+    }
+  });
+  assert.deepEqual(repeatedRuntimeAsset, runtimeAsset);
+
   const legacyAsset = normalizeSvgToVectorAsset({
     id: "vector.legacy.sample",
     name: "Legacy Sample",

tools/index.html

@@ -23,18 +23,22 @@
 
     <section class="hero">
       <h1>ToolboxAid - Active Tools</h1>
-      <p class="subtitle">Registry-driven tooling surface for vector maps, vector assets, tile maps, and parallax scenes, all framed by the shared engine theme from <code>engine/ui/hubCommon.css</code>. Preserved legacy editors stay on disk without appearing in the first-class navigation.</p>
+      <p class="subtitle">Registry-driven vector platform showcase for geometry authoring, vector assets, tile maps, and parallax scenes, all framed by the shared engine theme from <code>engine/ui/hubCommon.css</code>. Deterministic geometry runtime behavior remains shared platform infrastructure, not tool-local behavior.</p>
     </section>
 
     <section>
-      <h2>Active Tools</h2>
+      <h2>Vector Platform Showcase</h2>
       <div class="grid" data-active-tools-grid>
       </div>
       <noscript>
         <p class="callout"><strong>JavaScript required:</strong> the active tools list is generated from the shared tools registry.</p>
       </noscript>
     </section>
 
+    <div class="callout">
+      <strong>Geometry runtime proof:</strong> active vector-native flows share one deterministic runtime contract for transform order, render preparation, rounding precision, and collision-ready output.
+    </div>
+
     <section>
       <h2>Planned Next</h2>
       <p>Palette management and additional workflow tools are next priorities, followed by supporting tools that round out the asset workflow.</p>

tools/renderToolsIndex.js

@@ -10,14 +10,28 @@ function escapeHtml(value) {
 }
 
 function renderToolCard(tool) {
+  const sampleLinks = Array.isArray(tool.sampleEntryPoints) && tool.sampleEntryPoints.length > 0
+    ? `
+      <div class="meta">
+        ${tool.sampleEntryPoints.map((entry) => `
+          <a class="tools-platform-card__action tools-platform-card__action--secondary" href="${escapeHtml(entry.path)}">${escapeHtml(entry.label)}</a>
+        `).join("")}
+      </div>
+    `
+    : "";
+
   return `
-    <div class="card">
+    <div class="card tools-platform-card">
+      <div class="meta">
+        <span class="pill live">${escapeHtml(tool.showcaseTag || "Active Tool")}</span>
+        <span class="pill planned">${escapeHtml(tool.showcaseStatus || "Engine Theme")}</span>
+      </div>
       <h3><a href="${escapeHtml(tool.entryPoint)}">${escapeHtml(tool.displayName)}</a></h3>
       <p>${escapeHtml(tool.description)}</p>
       <div class="meta">
-        <span class="pill live">Active Tool</span>
-        <span class="pill planned">Engine Theme</span>
+        <a class="tools-platform-card__action" href="${escapeHtml(tool.entryPoint)}">Open Tool</a>
       </div>
+      ${sampleLinks}
     </div>
   `;
 }