|
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. |
| 1 | +# 3D Camera Path Editor Reengineering Design |
| 2 | + |
| 3 | +Task: PR_26124_021-tool-folder-design-reset |
| 4 | +Tool ID: `3d-camera-path-editor` |
| 5 | +Source folder: `tools/3D Camera Path Editor` |
| 6 | + |
| 7 | +## 1. Tool Purpose |
| 8 | +Edit 3D camera waypoint paths and export deterministic camera path JSON. |
| 9 | + |
| 10 | +## 2. Folder/Files Inspected |
| 11 | +- `tools/3D Camera Path Editor/how_to_use.html` |
| 12 | +- `tools/3D Camera Path Editor/index.html` |
| 13 | +- `tools/3D Camera Path Editor/main.js` |
| 14 | +- `tools/3D Camera Path Editor/README.md` |
| 15 | + |
| 16 | +Skipped from inspection for this design reset: sample/data JSON, image assets, generated preview assets, and schema history notes outside the current contract baseline. |
| 17 | + |
| 18 | +## 3. Current Controls/Buttons/Inputs/Selects/Textareas/Tables/Panels |
| 19 | +Counts found: buttons 2, inputs 0, selects 0, textareas 1, tables 0, inferred DOM controls/panels 5. |
| 20 | +- `tools/3D Camera Path Editor/index.html`: button[button] #addCameraPointButton - Add Waypoint |
| 21 | +- `tools/3D Camera Path Editor/index.html`: button[button] #normalizeCameraPathButton - Normalize Path |
| 22 | +- `tools/3D Camera Path Editor/index.html`: textarea #cameraPathInput - cameraPathInput |
| 23 | +- `tools/3D Camera Path Editor/main.js`: button #addCameraPointButton - inferred from JS DOM lookup |
| 24 | +- `tools/3D Camera Path Editor/main.js`: button #normalizeCameraPathButton - inferred from JS DOM lookup |
| 25 | +- `tools/3D Camera Path Editor/main.js`: panel #cameraPathStatus - inferred from JS DOM lookup |
| 26 | +- `tools/3D Camera Path Editor/main.js`: input #cameraPathInput - inferred from JS DOM lookup |
| 27 | +- `tools/3D Camera Path Editor/main.js`: panel #cameraPathOutput - inferred from JS DOM lookup |
| 28 | +- Panels/surfaces found: |
| 29 | + - `tools/3D Camera Path Editor/index.html`: .debug-tool-shell |
| 30 | + - `tools/3D Camera Path Editor/index.html`: .app-shell |
| 31 | + - `tools/3D Camera Path Editor/index.html`: .panel |
| 32 | + - `tools/3D Camera Path Editor/index.html`: .debug-tool-panel |
| 33 | + - `tools/3D Camera Path Editor/index.html`: .debug-tool-grid |
| 34 | + |
| 35 | +## 4. Current Component/Class/Function Inventory |
| 36 | +- `tools/3D Camera Path Editor/main.js`: function addWaypoint; function boot3dCameraPathEditor; function buildPresetLoadedStatus; function normalizeCameraPath; function normalizeCameraPathPayload; function normalizeSamplePresetPath; function parseInputPayload; function sanitizeNumber; function setStatus; function tryLoadPresetFromQuery; method getApi; method registerToolBootContract |
| 37 | + |
| 38 | +## 5. JSON Schema/Input Contract Currently Expected |
| 39 | +Schema baseline: `tools/schemas/tools/3d-camera-path-editor.schema.json`. Title: 3d-camera-path-editor Payload. Required top-level fields: cameraPath. Allowed top-level fields: cameraPath. Additional top-level properties: rejected. |
| 40 | + |
| 41 | +JSON handling signals found: download/export, safeParseJson, schema, tools.*. |
| 42 | + |
| 43 | +## 6. Valid JSON Behavior |
| 44 | +Valid JSON must parse cleanly, match the current schema baseline or tool-owned normalized shape, update the local editor/preview state, and remain exportable as path/file-field JSON without embedding `imageDataUrl`. |
| 45 | + |
| 46 | +## 7. Invalid JSON Rejection Behavior |
| 47 | +Malformed JSON, missing required fields, unsupported top-level fields, wrong nested types, and empty required editor payloads must be rejected in the tool UI before export/save/publish. |
| 48 | + |
| 49 | +## 8. Tool-Owned JSON Responsibilities |
| 50 | +- import/load: tool-owned; load files, pasted JSON, or hosted session payloads inside the tool. |
| 51 | +- validate: tool-owned validation against the current schema/input contract before state mutation. |
| 52 | +- edit/process: tool-owned editor or processing state. |
| 53 | +- export/save: tool-owned normalized JSON/export artifacts. |
| 54 | +- publish to `tools.3d-camera-path-editor` if applicable: yes, publish normalized output under `tools.3d-camera-path-editor` when this tool is the producer. |
| 55 | +- copy/create toolState if applicable: only if a future workspace flow copies a published `tools.*` entry into a toolState; the tool JSON remains tool-owned. |
| 56 | + |
| 57 | +## 9. Workspace Integration Contract |
| 58 | +- Workspace validates and launches only. |
| 59 | +- Workspace may provide `hostContextId`, launch URL state, or a workspace manifest shell, but it does not manage tool JSON internals. |
| 60 | +- The tool owns its JSON behavior after launch: import/load, validate, edit/process, export/save, publish output, and any copy/create `toolState` behavior listed above. |
| 61 | +- Workspace rejection should stop at invalid launch/session/manifest envelope; nested payload rules stay with the tool. |
| 62 | + |
| 63 | +## 10. Published `tools.*` Output Contract For Games/Samples |
| 64 | +Published output key: `tools.3d-camera-path-editor`. The value must match the current contract baseline, contain only JSON-safe values, use file/path/name fields for assets, and never persist `imageDataUrl`. Games and samples should consume the published payload as data, not as workspace-managed tool internals. |
| 65 | + |
| 66 | +## 11. Playwright Expectations |
| 67 | +Open `tools/3D Camera Path Editor/index.html`; verify the page renders without console errors, expected controls are present, valid JSON/session data reaches the success state, and invalid JSON/session data stays in the tool-owned rejection path. No Playwright run is expected for this documentation-only PR. |
| 68 | + |
| 69 | +## 12. Manual Test Expectations |
| 70 | +Manually launch `tools/3D Camera Path Editor/index.html`, exercise import/load controls or hosted launch parameters, confirm edit/process controls do not delegate JSON internals to workspace, export/save the normalized output, and confirm invalid JSON blocks export/save. |
| 71 | + |
| 72 | +## 13. Known Gaps |
| 73 | +- Controls need cleanup during the tool rebuild so import, validate, edit/process, export/save, and publish actions are explicit. |
| 74 | +- Playwright/manual checks are documented as expectations only; this PR does not change runtime behavior or add tests. |
| 75 | + |
| 76 | +## 14. Rebuild Order Priority |
| 77 | +P18: 3D Camera Path Editor. This priority is used by `docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md` and keeps the rebuild anchored on Palette / Palette Browser first, then dependent tool families. |
0 commit comments