Wire shared assets and palettes into active tools

Connect Asset Browser / Import Hub and Palette Browser / Manager into all active first-class tools, keep Sprite Editor first-class, keep SpriteEditor_old_keep hidden legacy, preserve tool-only tools/index.html, and normalize shared engine-themed actions and handoff contracts.

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -1,28 +1,57 @@
 MODEL: GPT-5.4
 REASONING: high
 
-COMMAND:
-Create BUILD_PR_ASSET_BROWSER_IMPORT_HUB_AND_PALETTE_BROWSER_MANAGER using the latest uploaded GitHub repo as the baseline.
+TASK:
+Create BUILD_PR_ASSET_USAGE_INTEGRATION.
+
+OBJECTIVE:
+Wire the shared asset system into all active first-class tools, using the latest uploaded GitHub repo state.
+
+IN SCOPE:
+- Vector Map Editor
+- Vector Asset Studio
+- Tilemap Studio
+- Parallax Scene Studio
+- Sprite Editor
+- shared Asset Browser / Import Hub integration
+- shared Palette Browser / Manager integration
+- registry-safe tool surfacing
+- engine theme consistency
+- contract documentation
+
+OUT OF SCOPE:
+- SpriteEditor_old_keep
+- restoring samples to tools/index.html
+- showcase game content
+- unrelated refactors
 
 REQUIREMENTS:
-1. Build two new first-class tools under tools/:
-   - tools/Asset Browser/  -> display name: Asset Browser / Import Hub
-   - tools/Palette Browser/ -> display name: Palette Browser / Manager
-2. Register both in tools/toolRegistry.js as active first-class tools.
-3. Ensure tools/index.html renders them through the shared registry-driven surface.
-4. Remove the planned placeholder cards for these two tools once the real tools are live.
-5. Ensure any remaining older Asset Browser naming is normalized to "Asset Browser / Import Hub".
-6. Keep Sprite Editor first-class and visible.
-7. Keep SpriteEditor_old_keep legacy and hidden.
-8. Keep samples off the tools landing page.
-9. Use shared engine/platform shell + theme for both new tools.
-10. Update the registry validator so it verifies:
-    - both new tools exist in registry
-    - folder path matches registry path
-    - active first-class tools are surfaced
-    - legacy tools remain excluded
-    - placeholder cards are not left behind for live tools
-11. Keep changes surgical and aligned to current repo conventions.
-
-PACKAGE OUTPUT:
-<project folder>/tmp/BUILD_PR_ASSET_BROWSER_IMPORT_HUB_AND_PALETTE_BROWSER_MANAGER.zip
+1. Sprite Editor must remain first-class and visible.
+2. SpriteEditor_old_keep must remain hidden legacy.
+3. tools/index.html must stay tool-only.
+4. Tools consume shared assets/palettes; they do not own duplicated private copies by default.
+5. Normalize shared action labels:
+   - Browse Assets
+   - Import Assets
+   - Browse Palettes
+   - Manage Palettes
+6. Preserve engine theme and shared shell consistency.
+7. Update/extend the registry validator if needed so surfacing remains correct.
+
+IMPLEMENTATION TARGETS:
+- add shared launch hooks/actions in each active tool
+- connect each tool to Asset Browser / Import Hub
+- connect each tool to Palette Browser / Manager
+- document the asset and palette handoff contracts
+- avoid structural churn unless required for the integration
+
+VALIDATE:
+- all active tools can launch asset/palette flows
+- no samples reappear on tools/index.html
+- no legacy leakage
+- no broken paths
+- action labels consistent
+- engine theme consistent
+
+OUTPUT:
+<project folder>/tmp/BUILD_PR_ASSET_USAGE_INTEGRATION.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Build Asset Browser / Import Hub and Palette Browser / Manager as first-class registry-backed tools using the shared engine/platform shell, remove their planned placeholders from tools/index, keep Sprite Editor first-class, keep SpriteEditor_old_keep hidden legacy, and extend registry validation to prevent future drift.
+Wire shared asset usage into all active first-class tools through the shared shell, normalize shared asset/palette handoff contracts, keep Sprite Editor first-class, keep SpriteEditor_old_keep hidden legacy, and preserve a tool-only tools/index surface.

docs/dev/reports/change_summary.txt

@@ -1,10 +1,27 @@
-Change Summary
-
-- Added two new first-class tools:
-  - Asset Browser / Import Hub
-  - Palette Browser / Manager
-- Registered both in the shared active tools registry.
-- Removed the static planned placeholder cards for the two now-live tools.
-- Kept the tools landing page registry-driven and sample-free.
-- Kept Sprite Editor first-class and SpriteEditor_old_keep hidden legacy.
-- Extended validator coverage for new tool folders, active surface participation, and placeholder drift.
+CHANGE SUMMARY
+
+PR:
+BUILD_PR_ASSET_USAGE_INTEGRATION
+
+SUMMARY:
+Wire shared asset and palette systems into all active first-class tools through the shared platform shell and documented handoff contracts.
+
+INCLUDED:
+- shared shell action hooks for every active first-class tool
+- normalized action labels:
+  - Browse Assets
+  - Import Assets
+  - Browse Palettes
+  - Manage Palettes
+- documented shared asset/palette handoff contract
+- Asset Browser launch-context and asset handoff publishing
+- Palette Browser launch-context and palette handoff publishing
+- Sprite Editor remains first-class
+- SpriteEditor_old_keep remains hidden legacy
+- tools/index.html remains tool-only
+
+EXCLUDED:
+- samples on tools/index.html
+- showcase game/sample content
+- legacy revival
+- unrelated platform restructuring

docs/dev/reports/file_tree.txt

@@ -1,13 +1,11 @@
-HTML-JavaScript-Gaming-main/
-  docs/
-    pr/
-      BUILD_PR_ASSET_BROWSER_IMPORT_HUB_AND_PALETTE_BROWSER_MANAGER.md
-    dev/
-      codex_commands.md
-      commit_comment.txt
-      reports/
-        change_summary.txt
-        validation_checklist.txt
-        file_tree.txt
-  tmp/
-    BUILD_PR_ASSET_BROWSER_IMPORT_HUB_AND_PALETTE_BROWSER_MANAGER.zip
+BUILD_PR_ASSET_USAGE_INTEGRATION/
+└── docs/
+    ├── pr/
+    │   └── BUILD_PR_ASSET_USAGE_INTEGRATION.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,17 +1,25 @@
-Validation Checklist
+VALIDATION CHECKLIST
 
-[x] tools/Asset Browser/ exists
-[x] tools/Palette Browser/ exists
-[x] Both tools load through shared engine/platform shell
-[x] Both tools use engine theme
-[x] tools/toolRegistry.js contains active entries for both tools
-[x] tools/index.html shows both tools as first-class launchable tools
-[x] tools/index.html does not show samples
-[x] Static placeholder for Palette Browser / Manager removed after activation
-[x] Static placeholder for Asset Browser / Import Hub removed after activation
-[x] No non-validator references remain to the old Asset Browser name
-[x] Sprite Editor remains visible as first-class tool
-[x] SpriteEditor_old_keep remains hidden legacy
-[x] Registry validator checks both new tools
-[x] Registry validator flags placeholder drift for live tools
-[x] No broken paths from tools landing page
+[x] Sprite Editor is still first-class and visible
+[x] SpriteEditor_old_keep is hidden legacy
+[x] tools/index.html remains tool-only
+[x] Vector Map Editor can launch Browse Assets
+[x] Vector Map Editor can launch Import Assets
+[x] Vector Map Editor can launch Browse Palettes / Manage Palettes
+[x] Vector Asset Studio can launch Browse Assets
+[x] Vector Asset Studio can launch Import Assets
+[x] Vector Asset Studio can launch Browse Palettes / Manage Palettes
+[x] Tilemap Studio can launch Browse Assets
+[x] Tilemap Studio can launch Import Assets
+[x] Tilemap Studio can launch Browse Palettes / Manage Palettes
+[x] Parallax Scene Studio can launch Browse Assets
+[x] Parallax Scene Studio can launch Import Assets
+[x] Parallax Scene Studio can launch Browse Palettes / Manage Palettes
+[x] Sprite Editor can launch Browse Assets
+[x] Sprite Editor can launch Import Assets
+[x] Sprite Editor can launch Browse Palettes / Manage Palettes
+[x] Shared asset references are used instead of tool-private duplication by default
+[x] Shared palettes remain the single source of truth
+[x] Shared contract doc exists at docs/specs/asset_usage_contract.md
+[x] No broken paths or dead launchers
+[x] Engine theme is consistent across the integrated flows

docs/pr/BUILD_PR_ASSET_USAGE_INTEGRATION.md

@@ -0,0 +1,83 @@
+# BUILD_PR_ASSET_USAGE_INTEGRATION
+
+## Goal
+Wire the shared asset and palette systems into all active first-class tools without changing the tool-only launcher surface, without reviving legacy sprite tooling, and without introducing tool-private asset duplication as the default path.
+
+## Scope
+Integrated tools:
+- `Vector Map Editor`
+- `Vector Asset Studio`
+- `Tilemap Studio`
+- `Parallax Scene Studio`
+- `Sprite Editor`
+- `Asset Browser / Import Hub`
+- `Palette Browser / Manager`
+
+Out of scope:
+- `SpriteEditor_old_keep`
+- sample restoration on `tools/index.html`
+- showcase/game content
+- unrelated structural refactors
+
+## Files Added
+- `tools/shared/assetUsageIntegration.js`
+- `docs/specs/asset_usage_contract.md`
+
+## Files Updated
+- `tools/shared/platformShell.js`
+- `tools/shared/platformShell.css`
+- `tools/Asset Browser/index.html`
+- `tools/Asset Browser/main.js`
+- `tools/Palette Browser/index.html`
+- `tools/Palette Browser/main.js`
+- `scripts/validate-active-tools-surface.mjs`
+- `docs/dev/COMMIT_COMMENT.txt`
+- `docs/dev/reports/change_summary.txt`
+- `docs/dev/reports/validation_checklist.txt`
+
+## Implementation Summary
+
+### Shared Shell Integration
+- Added a shared asset-usage integration module under `tools/shared/`.
+- The shared platform shell now renders normalized launch actions for every active tool page:
+  - `Browse Assets`
+  - `Import Assets`
+  - `Browse Palettes`
+  - `Manage Palettes`
+- The shared shell also shows the current shared asset and shared palette handoff summaries.
+
+### Shared Handoff Contracts
+- Added a documented contract in `docs/specs/asset_usage_contract.md`.
+- Normalized shared storage keys:
+  - `toolboxaid.shared.assetHandoff`
+  - `toolboxaid.shared.paletteHandoff`
+- Tools consume shared references by contract instead of creating private default copies.
+
+### Asset Browser / Import Hub
+- Added launch-context handling through query params.
+- Added a `Use In Active Tool` action that publishes a normalized shared asset handoff.
+- Preserved non-destructive import planning behavior.
+
+### Palette Browser / Manager
+- Added launch-context handling through query params.
+- Updated palette handoff publishing to use the normalized shared contract.
+- Preserved built-in palette browsing and local editable palette workflows.
+
+## Surface and Visibility Rules
+- `Sprite Editor` remains first-class and visible.
+- `SpriteEditor_old_keep` remains preserved and hidden from active surfacing.
+- `tools/index.html` remains tool-only.
+- No samples were reintroduced to the tools launcher.
+
+## Validation
+- `node --check tools/shared/assetUsageIntegration.js`
+- `node --check tools/shared/platformShell.js`
+- `node --check tools/Asset Browser/main.js`
+- `node --check tools/Palette Browser/main.js`
+- `node scripts/validate-tool-registry.mjs`
+- `node scripts/validate-active-tools-surface.mjs`
+
+## Acceptance Summary
+- Every active first-class tool page now exposes the same shared asset/palette launch actions through the engine-themed shell.
+- Asset and palette handoffs are normalized and documented.
+- Surfacing remains registry-safe and legacy-safe.