build(assets): enforce shared tool asset and palette handoff contract

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,30 +1,11 @@
 MODEL: GPT-5.4
 REASONING: high
+COMMAND: Create BUILD_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT as a docs-first, repo-structured delta. Use docs/pr/BUILD_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT.md as the source of truth. Implement the smallest safe enforcement slice that makes first-class tools launch and consume shared asset/palette handoffs through the normalized contract established by 09_04. Keep scope limited to first-class tools, shared launch/handoff helpers, and focused tests only. Do not modify engine core APIs, game runtime behavior, legacy tool surfacing, or perform broad UI cleanup.
 
-GOAL:
-Simplify asset structure by removing redundant container layers.
+FINAL STEP:
+- Package all created and modified files into a repo-structured ZIP
+- Write the result ZIP to: <project folder>/tmp/BUILD_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT.zip
+- Preserve exact repo-relative structure inside the ZIP
+- Include only files relevant to this PR
+- Do not include unrelated files, full-repo copies, dependencies, or build artifacts
 
-RULES:
-- eliminate data/ if it is just a wrapper
-- eliminate platform/ as default container
-- keep only type-first folders under assets/
-- allow nested grouping only when needed
-
-TARGET STRUCTURE:
-assets/
-  palettes/
-  sprites/
-  tilemaps/
-
-OPTIONAL:
-assets/sprites/platform/
-assets/tilemaps/platform/
-
-CONSTRAINTS:
-- preserve files
-- update references
-- do not touch runtime code
-- one PR scope only
-
-OUTPUT:
-ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Level 09.04 — simplify asset structure by removing redundant data/platform containers
+build(assets): enforce shared tool asset and palette handoff contract

docs/dev/NEXT_COMMAND.txt

@@ -1,3 +1 @@
-# Validate BUILD_PR_LEVEL_09_03_ASSET_BUCKET_TAXONOMY_STANDARD
-rg -n ""assets/platform/"" games samples tools src tests --glob '!start_of_day/**'
-node tests/tools/VectorAssetSystem.test.mjs
+APPLY_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT

docs/dev/reports/change_summary.txt

@@ -1 +1,8 @@
-Removes redundant asset container layers (data/platform) and standardizes to type-first structure.
+BUILD bundle created for the post-09_04 enforcement slice.
+
+Summary:
+- continues directly from 09_04 asset structure simplification
+- preserves the 09_04 asset usage contract as the source baseline
+- narrows the next PR to first-class tool shared handoff enforcement only
+- avoids engine changes, gameplay changes, and broad tool cleanup
+- requires focused validation for canonical query parameters, storage keys, payload shapes, and safe fallback behavior

docs/dev/reports/validation_checklist.txt

@@ -1,5 +1,12 @@
-Validation:
-- no data/platform nesting remains
-- top-level assets folders are type-only
-- plural naming enforced
-- references updated
+[ ] PR scope remains limited to shared handoff enforcement.
+[ ] Asset Browser launch flows use normalized `view` and `sourceToolId` parameters.
+[ ] Shared action labels remain exact and normalized.
+[ ] `toolboxaid.shared.assetHandoff` is the only asset handoff key used.
+[ ] `toolboxaid.shared.paletteHandoff` is the only palette handoff key used.
+[ ] Asset payload preserves canonical top-level fields.
+[ ] Palette payload preserves canonical top-level fields.
+[ ] Consuming tools prefer valid shared handoffs over hidden private defaults.
+[ ] Invalid/missing handoff payloads degrade safely.
+[ ] Starter template remains compatible.
+[ ] Legacy tools remain excluded.
+[ ] No engine core API files are changed.

docs/dev/start_of_day/restart/RESTART_BUNDLE_TOMORROW_FIXED_PATH.zip

@@ -0,0 +1,165 @@
+# BUILD_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT
+
+## Purpose
+Implement the smallest enforcement slice that makes the shared asset and shared palette handoff contract real across first-class tools after 09_04 asset structure simplification.
+
+This PR must tighten launch/consume behavior for shared asset flows without widening into engine refactors, sample work, or broad UI redesign.
+
+## Why This PR Exists
+09_04 established the asset usage contract, moved active template surfaces under `tools/templates/`, and proved normalized shared asset locations across Asteroids and the starter project baseline. However, the contract is still only partially effective until active tools consistently:
+- launch shared browse/import/manage flows through the common shell
+- publish normalized handoff payloads under the approved storage keys
+- consume shared handoff summaries without silently forking tool-private defaults
+
+This PR closes that enforcement gap.
+
+## Source Baseline
+Treat these as the architectural baseline for this PR:
+- `docs/specs/asset_usage_contract.md`
+- `tools/shared/vectorAssetSystem.js`
+- `tools/Asset Browser/main.js`
+- `tools/templates/starter-project-template/config/starter.project.json`
+- `tests/tools/VectorAssetSystem.test.mjs`
+
+## In Scope
+- first-class tool launch and consume enforcement for shared asset/palette handoff
+- shared shell action normalization where required for the in-scope tools
+- storage-key and payload-shape enforcement against the 09_04 contract
+- narrow validation/tests that prove the contract is being used consistently
+- starter template compatibility only where required to preserve the contract
+
+## Out of Scope
+- engine core API changes
+- game runtime behavior changes
+- sample curriculum work
+- broad tool UI cleanup or redesign
+- legacy tool reintegration
+- filesystem mutation/import-copy automation expansion
+- broad asset registry redesign
+
+## Required Contract Enforcement
+
+### 1. Shared action labels remain exact
+For active first-class tools in scope, shared actions must continue using these exact labels:
+- `Browse Assets`
+- `Import Assets`
+- `Browse Palettes`
+- `Manage Palettes`
+
+Do not introduce tool-specific label drift.
+
+### 2. Shared launch query contract must be real
+When an in-scope tool launches the shared Asset Browser or Palette Browser flow, it must use the normalized query-parameter contract defined in `docs/specs/asset_usage_contract.md`:
+- `view`
+- `sourceToolId`
+
+Examples:
+- `../Asset Browser/index.html?view=import&sourceToolId=tile-map-editor`
+- `../Palette Browser/index.html?view=browse&sourceToolId=sprite-editor`
+
+No alternate ad hoc query names may be introduced.
+
+### 3. Shared handoff storage keys must be canonical
+Asset handoff must use:
+- `toolboxaid.shared.assetHandoff`
+
+Palette handoff must use:
+- `toolboxaid.shared.paletteHandoff`
+
+Do not add duplicate parallel keys for the same responsibility.
+
+### 4. Handoff payload shape must be normalized
+For the tools touched in this PR, handoff payloads must preserve the stable top-level fields documented in the contract.
+
+Asset handoff must preserve at minimum:
+- `assetId`
+- `assetType`
+- `sourcePath`
+- `displayName`
+- `metadata`
+- `sourceToolId`
+- `selectedAt`
+
+Palette handoff must preserve at minimum:
+- `paletteId`
+- `displayName`
+- `colors`
+- `metadata`
+- `sourceToolId`
+- `selectedAt`
+
+Metadata may extend the shape but must not replace the stable top-level fields.
+
+### 5. Active tools must consume the shared handoff, not fork private defaults
+For each in-scope tool, consuming a handoff must prefer the shared contract payload over hidden tool-private default copies whenever the handoff payload is valid.
+
+Graceful degradation is required:
+- invalid or missing handoff payloads must not crash the tool
+- invalid or missing payloads may fall back safely
+- fallback must not overwrite the canonical handoff contract with malformed data
+
+## Required Implementation Shape
+Implement the smallest safe slice that proves the contract across the most important active tools.
+
+### Minimum in-scope tools
+At minimum, cover:
+- `Asset Browser / Import Hub`
+- `Sprite Editor`
+- `Vector Map Editor`
+- `Vector Asset Studio`
+- `Tile Map Editor`
+- `Parallax Editor`
+
+If some tools already comply, keep edits surgical and only normalize the drift that still exists.
+
+### Likely file targets
+Use only if needed; do not expand beyond proven necessity.
+- `tools/shared/...` shared launch/handoff helper(s)
+- active tool entry scripts for the in-scope tools
+- `tools/Asset Browser/main.js`
+- palette browser/manager entry script if present and required
+- focused tests under `tests/tools/`
+- starter template config only if compatibility needs a narrow update
+
+## Acceptance Criteria
+1. In-scope first-class tools launch shared browse/import/manage flows using the normalized query contract.
+2. Asset and palette handoffs use the canonical storage keys only.
+3. Published handoff payloads preserve the stable top-level contract fields.
+4. Consuming tools prefer valid shared handoff payloads over hidden tool-private defaults.
+5. Invalid or missing handoff payloads degrade safely without crashes.
+6. Legacy tools remain excluded.
+7. No engine core API files change.
+8. No unrelated tool-shell cleanup is bundled into this PR.
+
+## Validation Requirements
+Provide focused proof, not broad regression theater.
+
+### Required validation lanes
+- targeted unit/integration coverage for launch query generation and handoff payload normalization
+- targeted coverage for consumer-side safe fallback on invalid/missing payloads
+- targeted coverage that shared asset selection preserves canonical fields and source paths
+- targeted coverage that shared palette selection preserves canonical fields and colors
+
+### Manual validation checklist
+1. Launch each in-scope tool and confirm shared actions use normalized labels.
+2. Trigger `Browse Assets` or `Import Assets` from at least two tools and confirm the browser opens with `view` and `sourceToolId`.
+3. Select a shared asset and confirm `toolboxaid.shared.assetHandoff` stores the normalized payload.
+4. Select a shared palette and confirm `toolboxaid.shared.paletteHandoff` stores the normalized payload.
+5. Re-open a consuming tool and confirm it reads the shared handoff without creating a hidden private duplicate.
+6. Corrupt the stored handoff payload and confirm the tool degrades safely.
+7. Confirm starter project template still opens without contract breakage.
+8. Confirm no engine-core files changed.
+
+## Constraints
+- Docs-first, surgical PR only.
+- One purpose only: enforce shared handoff behavior.
+- Preserve 09_04 asset ownership and template relocation outcomes.
+- Do not move assets again in this PR.
+- Do not add new showcase/sample surfacing.
+- Do not change engine/game runtime contracts.
+
+## Approved Commit Comment
+build(assets): enforce shared tool asset and palette handoff contract
+
+## Next Command
+APPLY_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT

docs/pr/BUILD_PR_LEVEL_09_05_SHARED_ASSET_HANDOFF_ENFORCEMENT.md

@@ -86,6 +86,7 @@ import { run as runProductionReadiness } from './production/ProductionReadiness.
 import { run as runEnginePublicBarrelImports } from './production/EnginePublicBarrelImports.test.mjs';
 import { run as runStorageService } from './persistence/StorageService.test.mjs';
 import { run as runAssetValidationEngine } from './tools/AssetValidationEngine.test.mjs';
+import { run as runAssetUsageIntegration } from './tools/AssetUsageIntegration.test.mjs';
 import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem.test.mjs';
 import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
 import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
@@ -197,6 +198,7 @@ const tests = [
     ['MouseState', runMouseState],
     ['StorageService', runStorageService],
     ['AssetValidationEngine', runAssetValidationEngine],
+    ['AssetUsageIntegration', runAssetUsageIntegration],
     ['AssetRemediationSystem', runAssetRemediationSystem],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
     ['RuntimeAssetLoader', runRuntimeAssetLoader],

tests/run-tests.mjs

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import {
+  SHARED_ACTION_LABELS,
+  SHARED_ASSET_HANDOFF_KEY,
+  SHARED_PALETTE_HANDOFF_KEY,
+  createAssetHandoff,
+  createPaletteHandoff,
+  getSharedShellActions,
+  readSharedAssetHandoff,
+  readSharedPaletteHandoff,
+  writeSharedAssetHandoff,
+  writeSharedPaletteHandoff
+} from "../../tools/shared/assetUsageIntegration.js";
+
+function createLocalStorageHarness() {
+  const store = new Map();
+  return {
+    getItem(key) {
+      return store.has(key) ? store.get(key) : null;
+    },
+    setItem(key, value) {
+      store.set(String(key), String(value));
+    },
+    removeItem(key) {
+      store.delete(String(key));
+    }
+  };
+}
+
+export async function run() {
+  const previousWindow = globalThis.window;
+  const localStorage = createLocalStorageHarness();
+  globalThis.window = {
+    localStorage,
+    location: {
+      search: ""
+    }
+  };
+
+  try {
+    const actions = getSharedShellActions("sprite-editor", "tool");
+    assert.equal(actions.length, 4);
+    assert.deepEqual(
+      actions.map((entry) => entry.label),
+      [
+        SHARED_ACTION_LABELS.browseAssets,
+        SHARED_ACTION_LABELS.importAssets,
+        SHARED_ACTION_LABELS.browsePalettes,
+        SHARED_ACTION_LABELS.managePalettes
+      ]
+    );
+    assert.equal(
+      actions[0].href,
+      "../Asset Browser/index.html?view=browse&sourceToolId=sprite-editor"
+    );
+    assert.equal(
+      actions[3].href,
+      "../Palette Browser/index.html?view=manage&sourceToolId=sprite-editor"
+    );
+
+    const validAsset = createAssetHandoff({
+      assetId: "asset-vector-player",
+      assetType: "vector",
+      sourcePath: "../../games/Asteroids/assets/vectors/asteroids-ship.vector.json",
+      displayName: "Asteroids Ship Vector",
+      metadata: { category: "Vector Assets" },
+      sourceToolId: "tile-map-editor"
+    });
+    assert.equal(writeSharedAssetHandoff(validAsset), true);
+    const storedAsset = readSharedAssetHandoff();
+    assert.equal(storedAsset.assetId, "asset-vector-player");
+    assert.equal(storedAsset.assetType, "vector");
+    assert.equal(storedAsset.sourcePath, "../../games/Asteroids/assets/vectors/asteroids-ship.vector.json");
+    assert.equal(storedAsset.displayName, "Asteroids Ship Vector");
+    assert.equal(storedAsset.sourceToolId, "tile-map-editor");
+    assert.equal(typeof storedAsset.selectedAt, "string");
+    assert.equal(storedAsset.metadata.category, "Vector Assets");
+
+    assert.equal(writeSharedAssetHandoff({ assetId: "broken-only-id" }), false);
+    const stillStoredAsset = readSharedAssetHandoff();
+    assert.equal(stillStoredAsset.assetId, "asset-vector-player");
+
+    const validPalette = createPaletteHandoff({
+      paletteId: "builtin:crayola032",
+      displayName: "crayola032",
+      colors: [{ symbol: "!", hex: "#232323", name: "Black" }],
+      metadata: { source: "engine" },
+      sourceToolId: "sprite-editor"
+    });
+    assert.equal(writeSharedPaletteHandoff(validPalette), true);
+    const storedPalette = readSharedPaletteHandoff();
+    assert.equal(storedPalette.paletteId, "builtin:crayola032");
+    assert.equal(storedPalette.displayName, "crayola032");
+    assert.equal(storedPalette.colors[0].hex, "#232323");
+    assert.equal(storedPalette.sourceToolId, "sprite-editor");
+    assert.equal(typeof storedPalette.selectedAt, "string");
+    assert.equal(storedPalette.metadata.source, "engine");
+
+    assert.equal(writeSharedPaletteHandoff({ displayName: "missing-id" }), false);
+    const stillStoredPalette = readSharedPaletteHandoff();
+    assert.equal(stillStoredPalette.paletteId, "builtin:crayola032");
+
+    localStorage.setItem(SHARED_ASSET_HANDOFF_KEY, '{"assetId":"only-id"}');
+    localStorage.setItem(SHARED_PALETTE_HANDOFF_KEY, '{"paletteId":"only-id"}');
+    assert.equal(readSharedAssetHandoff(), null);
+    assert.equal(readSharedPaletteHandoff().paletteId, "only-id");
+  } finally {
+    globalThis.window = previousWindow;
+  }
+}

tests/tools/AssetUsageIntegration.test.mjs

@@ -348,8 +348,10 @@ function useSelectedAssetInActiveTool() {
     },
     sourceToolId: context.sourceToolId || "asset-browser"
   });
-  writeSharedAssetHandoff(handoff);
-  refs.launchContextText.textContent = `Shared asset handoff updated for ${getToolDisplayName(context.sourceToolId, "active tool")}: ${selectedAsset.label}`;
+  const stored = writeSharedAssetHandoff(handoff);
+  refs.launchContextText.textContent = stored
+    ? `Shared asset handoff updated for ${getToolDisplayName(context.sourceToolId, "active tool")}: ${selectedAsset.label}`
+    : "Shared asset handoff was not updated because the payload was invalid.";
 }
 
 function syncImportFormFromFile() {