|
1 | 1 | # 3D Camera Path Editor Reengineering Design |
2 | 2 |
|
3 | | -Task: PR_26124_021-tool-folder-design-reset |
4 | | -Tool ID: `3d-camera-path-editor` |
| 3 | +Task: PR_26124_022-tighten-tool-design-docs |
| 4 | +Classification: rebuildable tool |
| 5 | +Core priority: core-13 |
5 | 6 | Source folder: `tools/3D Camera Path Editor` |
| 7 | +Publish target: `tools.3d-camera-path-editor` |
6 | 8 |
|
7 | | -## 1. Tool Purpose |
8 | | -Edit 3D camera waypoint paths and export deterministic camera path JSON. |
| 9 | +## Tool Purpose |
| 10 | +3D camera path authoring. This tool owns `cameraPath`, waypoint editing, path normalization, export, and publish to `tools.3d-camera-path-editor`. |
9 | 11 |
|
10 | | -## 2. Folder/Files Inspected |
| 12 | +## Exact Folder/Files Inspected |
11 | 13 | - `tools/3D Camera Path Editor/how_to_use.html` |
12 | 14 | - `tools/3D Camera Path Editor/index.html` |
13 | 15 | - `tools/3D Camera Path Editor/main.js` |
14 | 16 | - `tools/3D Camera Path Editor/README.md` |
15 | 17 |
|
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 |
| 18 | +## Exact Current Controls Found |
| 19 | +- `tools/3D Camera Path Editor/index.html`: `button[button]#addCameraPointButton` - Add Waypoint |
| 20 | +- `tools/3D Camera Path Editor/index.html`: `button[button]#normalizeCameraPathButton` - Normalize Path |
| 21 | +- `tools/3D Camera Path Editor/index.html`: `textarea#cameraPathInput` - cameraPathInput |
| 22 | +- `tools/3D Camera Path Editor/main.js`: `addCameraPointButton` via addButton |
| 23 | +- `tools/3D Camera Path Editor/main.js`: `normalizeCameraPathButton` via normalizeButton |
| 24 | +- `tools/3D Camera Path Editor/main.js`: `cameraPathStatus` via statusText |
| 25 | +- `tools/3D Camera Path Editor/main.js`: `cameraPathInput` via input |
| 26 | +- `tools/3D Camera Path Editor/main.js`: `cameraPathOutput` via output |
| 27 | + |
| 28 | +## Current Panels And 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 | +## Exact Current Functions And Classes |
36 | 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 | 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. |
| 38 | +## Target Controls |
| 39 | +Keep: |
| 40 | +- Add Waypoint |
| 41 | +- Normalize Path |
| 42 | +- camera path input textarea |
| 43 | +- normalized output panel |
| 44 | + |
| 45 | +Remove or rename: |
| 46 | +- none identified in the current folder |
| 47 | + |
| 48 | +Add: |
| 49 | +- Load Camera Path JSON |
| 50 | +- delete/reorder waypoint controls |
| 51 | +- Export Camera Path JSON |
| 52 | +- Publish `tools.3d-camera-path-editor` |
| 53 | + |
| 54 | +## JSON Contract Owned By This Tool |
| 55 | +Baseline schema: `tools/schemas/tools/3d-camera-path-editor.schema.json`. Required top-level fields: cameraPath. Allowed top-level fields: cameraPath. Additional top-level properties are rejected by the current schema. The tool owns import/load, validation, edit/process, export/save, and publish of this payload. Workspace may pass a launch payload, but nested JSON remains tool-owned. |
| 56 | + |
| 57 | +## Hosted/Launch Payload Boundary |
| 58 | +- Launch payloads may seed this tool, but they do not become workspace-owned internals. |
| 59 | +- toolState copies may be created later from the published output, but the copied JSON must still match this tool contract. |
| 60 | +- Use file/path/name fields for assets. Do not persist `imageDataUrl`. |
| 61 | + |
| 62 | +## Invalid JSON Behavior |
| 63 | +- Reject malformed JSON before state mutation. |
| 64 | +- Reject missing required fields from the schema baseline. |
| 65 | +- Reject unsupported top-level fields when the schema disallows extras. |
| 66 | +- Keep export/save/publish disabled until the current payload validates. |
| 67 | +- Show a tool-specific error that names the failing field or control group. |
| 68 | + |
| 69 | +## Manual Test Plan |
| 70 | +- Load or paste a valid camera path. |
| 71 | +- Add a waypoint, normalize the path, and export. |
| 72 | +- Try malformed JSON, empty waypoint arrays, and nonnumeric positions; publish must stay blocked. |
0 commit comments