Skip to content

Commit 83f3057

Browse files
author
DavidQ
committed
Document Workspace V2 dispatcher architecture and per-tool re-engineering contracts to prevent implementation drift - PR_26124_020-workspace-tools-reengineering-design-docs
1 parent 989e92c commit 83f3057

33 files changed

Lines changed: 2086 additions & 15 deletions

‎docs/design/tools/3d-asset-viewer/REENGINEERING_DESIGN.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 3D Asset Viewer Reengineering Design (3d-asset-viewer)
2+
3+
## Purpose
4+
- Baseline 3D asset metadata viewer for vertices, bounds, and normalized runtime payload inspection.
5+
6+
## Current V1 Capability
7+
- Active in registry-driven tools surface.
8+
- Runtime entry point: `3D Asset Viewer/index.html`.
9+
- Runtime implementation file: `tools/3D Asset Viewer/main.js`.
10+
11+
## Current V2 / Workspace Status
12+
- Legacy/first-class tool present in registry; not fully mapped into Workspace V2 toolState lane.
13+
- Workspace integration classification:
14+
- global tool: no
15+
- toolState-capable tool: no
16+
- published `tools.*` output candidate: yes
17+
- Readiness: Needs additional schema/contract alignment
18+
19+
## Expected JSON Schema/Input
20+
- Schema ref: `tools/schemas/tools/3d-asset-viewer.schema.json`. Required root keys: `asset3d`. Defined root properties: `asset3d`.
21+
22+
## Valid JSON Load Behavior (Target)
23+
- Parse incoming tool payload once.
24+
- Validate against the tool schema/contract before rendering.
25+
- Render the fully valid state and expose clear contract readout text.
26+
27+
## Invalid JSON Rejection Behavior (Target)
28+
- Reject before rendering domain state.
29+
- Show one clear actionable invalid message.
30+
- Avoid fallback/default injections and avoid mutating inbound payload structure.
31+
32+
## Current Components/Functions
33+
- Top-level functions: `normalizeSamplePresetPath()`, `buildPresetLoadedStatus()`, `setStatus()`, `sanitizeNumber()`, `computeBounds()`, `normalizeAssetPayload()`, `inspectAssetPayload()`, `boot3dAssetViewer()`.
34+
35+
## Target Components/Functions
36+
- Separate explicit JSON contract functions (`import`, `validate`, `load`, `export`) from view-only rendering methods.
37+
- Keep tool-specific logic inside the tool runtime; avoid Workspace V2 owning tool-specific compare/merge/edit behavior.
38+
- Keep one visible invalid-state path that blocks render before any partial state draws.
39+
40+
## Tool-Owned JSON Functions
41+
- Import: `buildPresetLoadedStatus()`, `normalizeAssetPayload()`, `inspectAssetPayload()`
42+
- Validate: `normalizeSamplePresetPath()`, `sanitizeNumber()`, `normalizeAssetPayload()`
43+
- Edit/process: No explicit edit/process helper surfaced in current file inventory.
44+
- Export: No explicit export helper surfaced in current file inventory.
45+
- Add/copy to Workspace toolState: Not yet explicit in current tool runtime.
46+
- Publish to `tools.3d-asset-viewer`: Supported as target ownership in design; concrete publish path varies by tool.
47+
- Compare/merge for own schema: Not currently tool-local; Workspace V2 has cross-toolState compare/merge UI today.
48+
49+
## Workspace Integration Contract
50+
- Workspace launch path exists via tools index/workspace-manager registry entry points.
51+
- Explicit Workspace V2 toolState contract is not yet completed for this tool.
52+
53+
## Playwright Expectations
54+
- Valid payload path should show visible valid-state surface.
55+
- Invalid payload path should show visible invalid-state surface and hide valid state.
56+
- Workspace launch handoff should open the tool with hostContext/toolState payload when applicable.
57+
58+
## Manual Test Expectations
59+
- Launch from `tools/index.html` and confirm baseline UI renders.
60+
- Launch from Workspace V2 when applicable and confirm payload handoff path.
61+
- Provide an invalid JSON contract and confirm the tool blocks render with explicit error.
62+
63+
## Known Gaps
64+
- Tool is not fully in the current Workspace V2 toolState-capable Playwright lane.

‎docs/design/tools/3d-camera-path-editor/REENGINEERING_DESIGN.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 3D Camera Path Editor Reengineering Design (3d-camera-path-editor)
2+
3+
## Purpose
4+
- Baseline 3D camera path editor for waypoint timeline authoring and deterministic JSON export.
5+
6+
## Current V1 Capability
7+
- Active in registry-driven tools surface.
8+
- Runtime entry point: `3D Camera Path Editor/index.html`.
9+
- Runtime implementation file: `tools/3D Camera Path Editor/main.js`.
10+
11+
## Current V2 / Workspace Status
12+
- Legacy/first-class tool present in registry; not fully mapped into Workspace V2 toolState lane.
13+
- Workspace integration classification:
14+
- global tool: no
15+
- toolState-capable tool: no
16+
- published `tools.*` output candidate: yes
17+
- Readiness: Needs additional schema/contract alignment
18+
19+
## Expected JSON Schema/Input
20+
- Schema ref: `tools/schemas/tools/3d-camera-path-editor.schema.json`. Required root keys: `cameraPath`. Defined root properties: `cameraPath`.
21+
22+
## Valid JSON Load Behavior (Target)
23+
- Parse incoming tool payload once.
24+
- Validate against the tool schema/contract before rendering.
25+
- Render the fully valid state and expose clear contract readout text.
26+
27+
## Invalid JSON Rejection Behavior (Target)
28+
- Reject before rendering domain state.
29+
- Show one clear actionable invalid message.
30+
- Avoid fallback/default injections and avoid mutating inbound payload structure.
31+
32+
## Current Components/Functions
33+
- Top-level functions: `sanitizeNumber()`, `normalizeCameraPathPayload()`, `normalizeSamplePresetPath()`, `buildPresetLoadedStatus()`, `setStatus()`, `parseInputPayload()`, `normalizeCameraPath()`, `addWaypoint()`, `boot3dCameraPathEditor()`.
34+
35+
## Target Components/Functions
36+
- Separate explicit JSON contract functions (`import`, `validate`, `load`, `export`) from view-only rendering methods.
37+
- Keep tool-specific logic inside the tool runtime; avoid Workspace V2 owning tool-specific compare/merge/edit behavior.
38+
- Keep one visible invalid-state path that blocks render before any partial state draws.
39+
40+
## Tool-Owned JSON Functions
41+
- Import: `normalizeCameraPathPayload()`, `buildPresetLoadedStatus()`, `parseInputPayload()`
42+
- Validate: `sanitizeNumber()`, `normalizeCameraPathPayload()`, `normalizeSamplePresetPath()`, `normalizeCameraPath()`
43+
- Edit/process: `addWaypoint()`, `boot3dCameraPathEditor()`
44+
- Export: No explicit export helper surfaced in current file inventory.
45+
- Add/copy to Workspace toolState: Not yet explicit in current tool runtime.
46+
- Publish to `tools.3d-camera-path-editor`: Supported as target ownership in design; concrete publish path varies by tool.
47+
- Compare/merge for own schema: Not currently tool-local; Workspace V2 has cross-toolState compare/merge UI today.
48+
49+
## Workspace Integration Contract
50+
- Workspace launch path exists via tools index/workspace-manager registry entry points.
51+
- Explicit Workspace V2 toolState contract is not yet completed for this tool.
52+
53+
## Playwright Expectations
54+
- Valid payload path should show visible valid-state surface.
55+
- Invalid payload path should show visible invalid-state surface and hide valid state.
56+
- Workspace launch handoff should open the tool with hostContext/toolState payload when applicable.
57+
58+
## Manual Test Expectations
59+
- Launch from `tools/index.html` and confirm baseline UI renders.
60+
- Launch from Workspace V2 when applicable and confirm payload handoff path.
61+
- Provide an invalid JSON contract and confirm the tool blocks render with explicit error.
62+
63+
## Known Gaps
64+
- Tool is not fully in the current Workspace V2 toolState-capable Playwright lane.

‎docs/design/tools/3d-json-payload/REENGINEERING_DESIGN.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 3D JSON Payload Reengineering Design (3d-json-payload)
2+
3+
## Purpose
4+
- 3D payload normalization utility for point/segment JSON documents with deterministic sanitized output.
5+
6+
## Current V1 Capability
7+
- Active in registry-driven tools surface.
8+
- Runtime entry point: `3D JSON Payload/index.html`.
9+
- Runtime implementation file: `tools/3D JSON Payload/main.js`.
10+
11+
## Current V2 / Workspace Status
12+
- Legacy/first-class tool present in registry; not fully mapped into Workspace V2 toolState lane.
13+
- Workspace integration classification:
14+
- global tool: no
15+
- toolState-capable tool: no
16+
- published `tools.*` output candidate: yes
17+
- Readiness: Needs additional schema/contract alignment
18+
19+
## Expected JSON Schema/Input
20+
- Schema ref: `tools/schemas/tools/3d-json-payload.schema.json`. Required root keys: `mapPayload`. Defined root properties: `mapPayload`.
21+
22+
## Valid JSON Load Behavior (Target)
23+
- Parse incoming tool payload once.
24+
- Validate against the tool schema/contract before rendering.
25+
- Render the fully valid state and expose clear contract readout text.
26+
27+
## Invalid JSON Rejection Behavior (Target)
28+
- Reject before rendering domain state.
29+
- Show one clear actionable invalid message.
30+
- Avoid fallback/default injections and avoid mutating inbound payload structure.
31+
32+
## Current Components/Functions
33+
- Top-level functions: `sanitizeNumber()`, `normalizeMapPayload()`, `normalizeSamplePresetPath()`, `buildPresetLoadedStatus()`, `setStatus()`, `normalizeMapPayloadAction()`, `boot3dMapEditor()`.
34+
35+
## Target Components/Functions
36+
- Separate explicit JSON contract functions (`import`, `validate`, `load`, `export`) from view-only rendering methods.
37+
- Keep tool-specific logic inside the tool runtime; avoid Workspace V2 owning tool-specific compare/merge/edit behavior.
38+
- Keep one visible invalid-state path that blocks render before any partial state draws.
39+
40+
## Tool-Owned JSON Functions
41+
- Import: `normalizeMapPayload()`, `buildPresetLoadedStatus()`, `normalizeMapPayloadAction()`
42+
- Validate: `sanitizeNumber()`, `normalizeMapPayload()`, `normalizeSamplePresetPath()`, `normalizeMapPayloadAction()`
43+
- Edit/process: `boot3dMapEditor()`
44+
- Export: No explicit export helper surfaced in current file inventory.
45+
- Add/copy to Workspace toolState: Not yet explicit in current tool runtime.
46+
- Publish to `tools.3d-json-payload`: Supported as target ownership in design; concrete publish path varies by tool.
47+
- Compare/merge for own schema: Not currently tool-local; Workspace V2 has cross-toolState compare/merge UI today.
48+
49+
## Workspace Integration Contract
50+
- Workspace launch path exists via tools index/workspace-manager registry entry points.
51+
- Explicit Workspace V2 toolState contract is not yet completed for this tool.
52+
53+
## Playwright Expectations
54+
- Valid payload path should show visible valid-state surface.
55+
- Invalid payload path should show visible invalid-state surface and hide valid state.
56+
- Workspace launch handoff should open the tool with hostContext/toolState payload when applicable.
57+
58+
## Manual Test Expectations
59+
- Launch from `tools/index.html` and confirm baseline UI renders.
60+
- Launch from Workspace V2 when applicable and confirm payload handoff path.
61+
- Provide an invalid JSON contract and confirm the tool blocks render with explicit error.
62+
63+
## Known Gaps
64+
- Tool is not fully in the current Workspace V2 toolState-capable Playwright lane.

‎docs/design/tools/TOOLS_REENGINEERING_INDEX.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Tools Reengineering Index
2+
3+
This index is generated from current repo tool registry entries, Workspace V2 lane tools, and Workspace Manager entry points.
4+
5+
| Tool ID | Display Name | Global-Only | ToolState-Capable | Published Output Capable | Status |
6+
|---|---|---|---|---|---|
7+
| `3d-asset-viewer` | 3D Asset Viewer | no | no | yes | Needs additional schema/contract alignment |
8+
| `3d-camera-path-editor` | 3D Camera Path Editor | no | no | yes | Needs additional schema/contract alignment |
9+
| `3d-json-payload` | 3D JSON Payload | no | no | yes | Needs additional schema/contract alignment |
10+
| `asset-browser` | Asset Browser / Import Hub | no | no | yes | Needs additional schema/contract alignment |
11+
| `asset-manager-v2` | asset-manager-v2 | no | yes | yes | In active lane |
12+
| `asset-pipeline` | Asset Pipeline | no | no | yes | Needs additional schema/contract alignment |
13+
| `palette-browser` | Palette Browser / Manager | yes | no | yes | In active lane |
14+
| `palette-manager-v2` | palette-manager-v2 | yes | no | no | Needs additional schema/contract alignment |
15+
| `parallax-editor` | Parallax Scene Studio | no | no | yes | Needs additional schema/contract alignment |
16+
| `performance-profiler` | Performance Profiler | no | no | yes | Needs additional schema/contract alignment |
17+
| `physics-sandbox` | Physics Sandbox | no | no | yes | Needs additional schema/contract alignment |
18+
| `replay-visualizer` | Replay Visualizer | no | no | yes | Needs additional schema/contract alignment |
19+
| `skin-editor` | Primitive Skin Editor | no | no | yes | Needs additional schema/contract alignment |
20+
| `sprite-editor` | Sprite Editor | no | no | yes | Needs additional schema/contract alignment |
21+
| `state-inspector` | State Inspector | no | no | yes | Needs additional schema/contract alignment |
22+
| `svg-asset-studio` | SVG Asset Studio | no | no | yes | Needs additional schema/contract alignment |
23+
| `svg-asset-studio-v2` | svg-asset-studio-v2 | no | yes | yes | In active lane |
24+
| `tile-map-editor` | Tilemap Studio | no | no | yes | Needs additional schema/contract alignment |
25+
| `tile-model-converter` | Tile Model Converter | no | no | yes | Needs additional schema/contract alignment |
26+
| `tilemap-studio-v2` | tilemap-studio-v2 | no | yes | yes | In active lane |
27+
| `vector-map-editor` | Vector Map Editor | no | no | yes | Needs additional schema/contract alignment |
28+
| `vector-map-editor-v2` | vector-map-editor-v2 | no | yes | yes | In active lane |
29+
| `workspace-manager` | Workspace Manager | yes | no | no | Needs additional schema/contract alignment |
30+
| `workspace-v2` | workspace-v2 | yes | no | no | In active lane |
31+
32+
## Classification Notes
33+
- Global-only means the tool/state is workspace-wide and should not be treated as a draft toolState library entry.
34+
- ToolState-capable means Workspace V2 producer and hostContext launch path currently supports the tool.
35+
- Published output capable means the tool payload is an intended `tools.<toolId>` manifest output target.
36+
- "Needs additional schema/contract alignment" means current runtime exists but full Workspace V2 contract + schema ownership is not complete in this lane.
37+
38+
## Sample Alignment Note
39+
- Sample alignment remains a separate phase. These design docs do not require sample JSON changes.

‎docs/design/tools/asset-browser/REENGINEERING_DESIGN.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Asset Browser / Import Hub Reengineering Design (asset-browser)
2+
3+
## Purpose
4+
- Approved asset browsing and non-destructive import planning surface for vectors, palettes, parallax, tilemaps, and sprite workflow assets.
5+
6+
## Current V1 Capability
7+
- Active in registry-driven tools surface.
8+
- Runtime entry point: `Asset Browser/index.html`.
9+
- Runtime implementation file: `tools/Asset Browser/main.js`.
10+
11+
## Current V2 / Workspace Status
12+
- Legacy/first-class tool present in registry; not fully mapped into Workspace V2 toolState lane.
13+
- Workspace integration classification:
14+
- global tool: no
15+
- toolState-capable tool: no
16+
- published `tools.*` output candidate: yes
17+
- Readiness: Needs additional schema/contract alignment
18+
19+
## Expected JSON Schema/Input
20+
- Schema ref: `tools/schemas/tools/asset-browser.schema.json`. Required root keys: `assets`. Defined root properties: `assets`, `assetBrowserPreset`, `approvedAssets`, `importHubPreset`.
21+
22+
## Valid JSON Load Behavior (Target)
23+
- Parse incoming tool payload once.
24+
- Validate against the tool schema/contract before rendering.
25+
- Render the fully valid state and expose clear contract readout text.
26+
27+
## Invalid JSON Rejection Behavior (Target)
28+
- Reject before rendering domain state.
29+
- Show one clear actionable invalid message.
30+
- Avoid fallback/default injections and avoid mutating inbound payload structure.
31+
32+
## Current Components/Functions
33+
- Top-level functions: `normalizeSamplePresetPath()`, `buildPresetLoadedStatus()`, `setAssetBrowserLifecycle()`, `ensureFirstVisibleAssetSelection()`, `syncAssetBrowserUxContract()`, `sanitizeText()`, `normalizeSampleId()`, `normalizeToolId()`, `normalizeLocalPath()`, `toTitleCase()`, `humanizeAssetId()`, `normalizeExplicitCatalogPath()`, `findCompanionPresetPath()`, `extractCompanionAssetPayload()`, `mapCompanionPresetToEntries()`, `readActiveProjectManifest()`, `collectCatalogPathCandidates()`, `mapKindToCategory()`, `normalizeCatalogEntries()`, `normalizePresetAssetEntries()`, `extractAssetBrowserCatalogFromPreset()`, `inferAssetKindFromPath()`, `normalizeManifestAssetEntries()`, `normalizeManifestToolAssetEntries()`, `inspectManifestAssetBrowserSource()`, `classifyApprovedAssetState()`, `emitAssetBrowserControlReadiness()`, `buildApprovedAssetStatusText()`, `buildApprovedAssetEmptyStateText()`, `getActiveAssetEmptyStateMessage()`, `getCategoryOrder()`, `extractAssetBrowserPreset()`, `applyAssetBrowserPreset()`, `resolveInitialSelectedAssetId()`, `getAssetTypeFromCategory()`, `applyLaunchContext()`, `getVisibleAssets()`, `getSelectedAsset()`, `getPathExtension()`, `populateCategoryControls()`, `populateDestinationOptions()`, `renderAssetList()`, `inferCategoryFromFileName()`, `normalizeImportName()`, `buildImportPlan()`, `renderImportPlan()`, `downloadImportPlan()`, `useSelectedAssetInActiveTool()`, `syncImportFormFromFile()`, `bindEvents()`, `bootAssetBrowser()`.
34+
35+
## Target Components/Functions
36+
- Separate explicit JSON contract functions (`import`, `validate`, `load`, `export`) from view-only rendering methods.
37+
- Keep tool-specific logic inside the tool runtime; avoid Workspace V2 owning tool-specific compare/merge/edit behavior.
38+
- Keep one visible invalid-state path that blocks render before any partial state draws.
39+
40+
## Tool-Owned JSON Functions
41+
- Import: `buildPresetLoadedStatus()`, `extractCompanionAssetPayload()`, `readActiveProjectManifest()`, `emitAssetBrowserControlReadiness()`, `normalizeImportName()`, `buildImportPlan()`, `renderImportPlan()`, `downloadImportPlan()`, `syncImportFormFromFile()`
42+
- Validate: `normalizeSamplePresetPath()`, `sanitizeText()`, `normalizeSampleId()`, `normalizeToolId()`, `normalizeLocalPath()`, `normalizeExplicitCatalogPath()`, `normalizeCatalogEntries()`, `normalizePresetAssetEntries()`, `normalizeManifestAssetEntries()`, `normalizeManifestToolAssetEntries()`, `normalizeImportName()`
43+
- Edit/process: `applyAssetBrowserPreset()`, `applyLaunchContext()`, `renderAssetList()`, `renderImportPlan()`
44+
- Export: `downloadImportPlan()`
45+
- Add/copy to Workspace toolState: Not yet explicit in current tool runtime.
46+
- Publish to `tools.asset-browser`: Supported as target ownership in design; concrete publish path varies by tool.
47+
- Compare/merge for own schema: Not currently tool-local; Workspace V2 has cross-toolState compare/merge UI today.
48+
49+
## Workspace Integration Contract
50+
- Workspace launch path exists via tools index/workspace-manager registry entry points.
51+
- Explicit Workspace V2 toolState contract is not yet completed for this tool.
52+
53+
## Playwright Expectations
54+
- Valid payload path should show visible valid-state surface.
55+
- Invalid payload path should show visible invalid-state surface and hide valid state.
56+
- Workspace launch handoff should open the tool with hostContext/toolState payload when applicable.
57+
58+
## Manual Test Expectations
59+
- Launch from `tools/index.html` and confirm baseline UI renders.
60+
- Launch from Workspace V2 when applicable and confirm payload handoff path.
61+
- Provide an invalid JSON contract and confirm the tool blocks render with explicit error.
62+
63+
## Known Gaps
64+
- Tool is not fully in the current Workspace V2 toolState-capable Playwright lane.

0 commit comments

Comments
 (0)