Add shared project system across active tools with manifest, save/load flows, validation, migration hooks, dirty-state tracking, and shared asset/palette references while keeping Sprite Editor first-class and legacy hidden.

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -1,57 +1,40 @@
 MODEL: GPT-5.4
 REASONING: high
 
-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:
+COMMAND:
+Create BUILD_PR_PROJECT_SYSTEM as a docs-first but implementation-ready platform slice.
+
+GOALS:
+1. Add a shared project system for all active first-class tools.
+2. Keep Sprite Editor first-class.
+3. Keep SpriteEditor_old_keep hidden legacy.
+4. Keep tools/index.html tool-only.
+5. Persist assets and palettes by shared references, not tool-local duplication.
+
+IMPLEMENT:
+- shared project service/context
+- project manifest contract
+- serializer + validator + migration entry points
+- new/open/save/save-as/close flows in the shared shell
+- dirty-state tracking
+- project name in header
+- per-tool persistence adapters for active tools only
+
+ACTIVE TOOLS:
 - 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. 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
+- Asset Browser / Import Hub
+- Palette Browser / Manager
 
-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
+RULES:
+- no samples added back
+- no legacy tooling on active surface
+- no per-tool independent project roots
+- use engine theme for all project UI
+- preserve registry-driven tool surfacing
 
 OUTPUT:
-<project folder>/tmp/BUILD_PR_ASSET_USAGE_INTEGRATION.zip
+<project folder>/tmp/BUILD_PR_PROJECT_SYSTEM.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-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.
+Add shared project system across active tools with manifest, shell flows, adapter-based persistence, dirty-state tracking, and shared asset/palette references while keeping Sprite Editor first-class and legacy hidden.

docs/dev/reports/change_summary.txt

@@ -1,27 +1,25 @@
-CHANGE SUMMARY
+BUILD_PR_PROJECT_SYSTEM 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
+- Added shared project manifest/version/migration contract under `tools/shared/`
+- Added project controller wiring to the shared engine-themed shell
+- Added shell actions:
+  - New Project
+  - Open Project
+  - Save Project
+  - Save Project As
+  - Close Project
+- Added project name + dirty-state header/status rendering
+- Added active-tool adapters for:
+  - Vector Map Editor
+  - Vector Asset Studio
+  - Tilemap Studio
+  - Parallax Scene Studio
+  - Sprite Editor
+  - Asset Browser / Import Hub
+  - Palette Browser / Manager
+- Added active-tool bootstrap globals needed by the shared adapter layer
+- Added project-system validator/report output
+- Preserved current platform rules:
+  - Sprite Editor first-class and visible
+  - SpriteEditor_old_keep hidden legacy
+  - tools/index remains tool-only and sample-free

docs/dev/reports/file_tree.txt

@@ -1,11 +1,19 @@
-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/
+  pr/
+    BUILD_PR_PROJECT_SYSTEM.md
+  specs/
+    project_manifest_contract.md
+  dev/
+    COMMIT_COMMENT.txt
+    reports/
+      change_summary.txt
+      file_tree.txt
+      project_system_validation.txt
+      validation_checklist.txt
+scripts/
+  validate-project-system.mjs
+tools/
+  shared/
+    projectManifestContract.js
+    projectSystem.js
+    projectSystemAdapters.js

docs/dev/reports/project_system_validation.txt

@@ -0,0 +1,17 @@
+BUILD_PR_PROJECT_SYSTEM validation report
+
+STATUS: PASS
+
+Checks:
+- found tools/shared/projectManifestContract.js
+- found tools/shared/projectSystem.js
+- found tools/shared/projectSystemAdapters.js
+- found docs/specs/project_manifest_contract.md
+- active tools match expected first-class list (7)
+- Sprite Editor remains first-class and visible
+- SpriteEditor_old_keep remains hidden legacy
+- shared shell is wired to project system controller
+- tools/index.html remains tool-only
+
+Issues:
+- none

docs/dev/reports/validation_checklist.txt

@@ -1,25 +1,22 @@
-VALIDATION CHECKLIST
+BUILD_PR_PROJECT_SYSTEM validation checklist
 
-[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
+[x] Project system lives in shared platform layer, not scattered across tools
+[x] New/Open/Save/Save As/Close flows exist in shared shell
+[x] Active project name is visible in header
+[x] Dirty-state indicator is visible in shared project chrome
+[x] Dirty-state prompt is wired for tool navigation, new/open, and close
+[x] Asset references are captured through shared project references
+[x] Palette references are captured through shared project references
+[x] Vector Map Editor has a shared project adapter
+[x] Vector Asset Studio has a shared project adapter
+[x] Tilemap Studio has a shared project adapter
+[x] Parallax Scene Studio has a shared project adapter
+[x] Sprite Editor has a shared project adapter
+[x] Asset Browser / Import Hub has a shared project adapter
+[x] Palette Browser / Manager has a shared project adapter
+[x] Project schema version is validated
+[x] Migration entry point exists for future versions
+[x] Sprite Editor remains first-class in registry/UI
+[x] SpriteEditor_old_keep remains hidden and excluded from active surface
+[x] tools/index.html remains tool-only and sample-free
+[x] Validation report emitted at docs/dev/reports/project_system_validation.txt

docs/pr/BUILD_PR_PROJECT_SYSTEM.md

@@ -0,0 +1,71 @@
+# BUILD_PR_PROJECT_SYSTEM
+
+## Runtime scope
+- Shared project manifest contract for active first-class tools
+- Shared project controller in the engine-themed shell
+- Serializer, validator, and migration entry points
+- Dirty-state tracking, prompts, and project header status
+- Per-tool persistence adapters for active tools only
+
+## Modules created
+- `tools/shared/projectManifestContract.js`
+- `tools/shared/projectSystem.js`
+- `tools/shared/projectSystemAdapters.js`
+- `docs/specs/project_manifest_contract.md`
+- `scripts/validate-project-system.mjs`
+
+## Modules changed
+- `tools/shared/platformShell.js`
+- `tools/shared/platformShell.css`
+- `tools/Tilemap Studio/main.js`
+- `tools/Parallax Scene Studio/main.js`
+- `tools/Sprite Editor/main.js`
+- `tools/Sprite Editor/modules/spriteEditorApp.js`
+- `tools/Vector Asset Studio/main.js`
+- `tools/Asset Browser/main.js`
+- `tools/Palette Browser/main.js`
+
+## Public/runtime boundaries
+- The shell owns project actions: New, Open, Save, Save As, Close
+- The manifest contract owns schema/version/validation/migration rules
+- Adapters own tool-specific capture/apply behavior
+- Shared asset/palette references stay rooted in manifest `sharedReferences`
+- `tools/index.html` remains tool-only
+- `Sprite Editor` remains first-class
+- `SpriteEditor_old_keep` remains hidden legacy and excluded
+
+## Implementation summary
+- Added `html-js-gaming.project` as the shared project root with `version: 1`
+- Added migration and validation entry points before manifest use
+- Added shell project controls and project-name/dirty-state chrome in the shared header
+- Added unsaved-change prompts for tool navigation, new/open, and close flows
+- Added per-tool adapters for:
+  - Vector Map Editor
+  - Vector Asset Studio
+  - Tilemap Studio
+  - Parallax Scene Studio
+  - Sprite Editor
+  - Asset Browser / Import Hub
+  - Palette Browser / Manager
+- Persisted shared asset/palette handoffs through manifest references instead of duplicating them in shell state
+
+## Validation performed
+- `node --check tools/shared/projectManifestContract.js`
+- `node --check tools/shared/projectSystem.js`
+- `node --check tools/shared/projectSystemAdapters.js`
+- `node --check tools/shared/platformShell.js`
+- `node --check tools/Tilemap Studio/main.js`
+- `node --check tools/Parallax Scene Studio/main.js`
+- `node --check tools/Sprite Editor/main.js`
+- `node --check tools/Sprite Editor/modules/spriteEditorApp.js`
+- `node --check tools/Vector Asset Studio/main.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`
+- `node scripts/validate-project-system.mjs`
+
+## Follow-up recommendations
+- Add focused browser/manual QA for cross-tool open/save navigation flows
+- Add explicit automated round-trip tests for each adapter
+- Add future manifest migrations through `migrateProjectManifest()` only

docs/specs/project_manifest_contract.md

@@ -0,0 +1,87 @@
+# Project Manifest Contract
+
+## Purpose and scope
+`html-js-gaming.project` is the shared project root for active first-class tools under `tools/`. It gives the platform one save/open/close contract, one migration entry point, and one place to carry shared asset and palette references across tools.
+
+## Version
+- Schema: `html-js-gaming.project`
+- Initial version: `1`
+- Migration rule: future versions must load through explicit migration functions, not ad hoc tool-local mutation
+
+## Canonical shape
+```json
+{
+  "schema": "html-js-gaming.project",
+  "version": 1,
+  "id": "project-20260405-abcdef",
+  "name": "Untitled Project",
+  "createdAt": "2026-04-05T12:00:00.000Z",
+  "updatedAt": "2026-04-05T12:00:00.000Z",
+  "activeToolId": "vector-map-editor",
+  "dirty": false,
+  "sharedReferences": {
+    "asset": null,
+    "palette": null
+  },
+  "tools": {
+    "vector-map-editor": {},
+    "vector-asset-studio": {},
+    "tile-map-editor": {},
+    "parallax-editor": {},
+    "sprite-editor": {},
+    "asset-browser": {},
+    "palette-browser": {}
+  },
+  "workspace": {
+    "lastOpenTool": "vector-map-editor",
+    "notes": ""
+  },
+  "migration": {
+    "sourceVersion": 1,
+    "applied": []
+  }
+}
+```
+
+## Shared reference rules
+- Shared assets and shared palettes live in `sharedReferences`
+- Tools consume those references and may mirror ids inside their own documents, but the manifest stays the canonical cross-tool handoff root
+- Consumers should prefer ids and source paths over duplicating shared asset or palette payloads
+
+## Tool-state rules
+- `tools.<toolId>` stores only that tool's persistence payload
+- Tool payloads may include tool-native document state
+- Tool payloads must be serializable JSON
+- Unknown tool keys are tolerated for forward compatibility
+
+## Serializer requirements
+- Produce stable pretty-printed JSON
+- Preserve `id`, `createdAt`, and supported tool payloads
+- Update `updatedAt` on capture/save
+- Keep `sharedReferences` synchronized with the latest shared asset/palette handoff state
+
+## Validator requirements
+- Confirm schema id
+- Confirm supported or migratable version
+- Confirm required root fields exist
+- Confirm `tools` is an object
+- Emit warnings, not silent drops, for incomplete shared references
+
+## Migration entry point
+- `migrateProjectManifest(rawManifest)` is the only accepted migration entry
+- Migration must preserve data when safe
+- Migration metadata must record source version and applied migration labels
+
+## Active tool coverage
+- Vector Map Editor
+- Vector Asset Studio
+- Tilemap Studio
+- Parallax Scene Studio
+- Sprite Editor
+- Asset Browser / Import Hub
+- Palette Browser / Manager
+
+## Explicit non-goals
+- No legacy `SpriteEditor_old_keep` participation
+- No samples or showcase content embedded in manifest roots
+- No per-tool isolated project roots as the primary save format