From 05bc283d59b27942507142ae87b50f0641957cf1 Mon Sep 17 00:00:00 2001 From: sladro Date: Fri, 10 Apr 2026 10:57:22 +0800 Subject: [PATCH] Add STEP tree deletion design spec --- .../specs/2026-04-10-step-tree-edit-design.md | 250 ++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-10-step-tree-edit-design.md diff --git a/docs/superpowers/specs/2026-04-10-step-tree-edit-design.md b/docs/superpowers/specs/2026-04-10-step-tree-edit-design.md new file mode 100644 index 0000000..784900e --- /dev/null +++ b/docs/superpowers/specs/2026-04-10-step-tree-edit-design.md @@ -0,0 +1,250 @@ +# STEP Tree Deletion And Save Design + +## Background + +This project already supports: + +- Loading and visualizing STEP models in the browser. +- Navigating model hierarchy in the existing tree panel. +- Downloading the original file. +- Exporting display-oriented formats such as OBJ, GLTF, STL, PLY, OFF, 3DM, and BIM. + +The requested feature is different from the existing export flow. The new flow must allow the user to: + +1. Open a STEP model. +2. Select an assembly node or a leaf part node in the hierarchy. +3. Delete the selected node together with all of its descendants. +4. Save a new `.stp` or `.step` file that reflects the deletion result. + +The feature is for demo use. The design should stay simple, stable, and isolated from the current download and export behavior. + +## Goals + +- Add a minimal deletion flow for STEP hierarchy editing. +- Keep the existing UI mostly unchanged. +- Keep the current `Download` and `Export` behavior unchanged. +- Generate a real new STEP file after deletion. +- Prioritize successful export over full metadata preservation. + +## Non Goals + +- No drag and drop hierarchy editing. +- No rename, merge, split, or reparent operations. +- No undo stack in the first version. +- No remote backend deployment. +- No attempt to preserve every original STEP attribute if that makes the demo unstable. + +## Chosen Approach + +Use the current browser UI for selection and preview, and add a small local STEP service for deletion-aware save. + +### Why this approach + +- The browser side already has the tree, the viewer, and selection behavior. +- The current project can import STEP but cannot write STEP. +- Writing a real STEP file needs CAD-side functionality outside the current browser export pipeline. +- A local service is enough for a demo and avoids introducing a full remote backend. + +## User Experience + +### Scope + +- The feature is only active for `.stp` and `.step` models. +- The user can delete: + - An assembly node. + - A leaf part node. +- Deleting a node removes the whole subtree under that node. + +### UI Changes + +- Reuse the existing navigator tree. +- Add one deletion action for the current selection: + - Preferred entry: `Delete Selected`. + - Optional secondary entry: tree context menu action if needed later. +- Add one new toolbar action: `Save STEP`. +- Keep the existing `Download` action unchanged. +- Keep the existing `Export` dialog unchanged. + +### Interaction Rules + +1. The user selects a deletable node from the current hierarchy tree. +2. The user clicks `Delete Selected`. +3. A confirmation dialog asks: `Delete selected node and all its children?` +4. After confirmation: + - The node disappears from the tree. + - The corresponding geometry disappears from the viewer. +5. The user clicks `Save STEP`. +6. The browser downloads a new STEP file generated from the edited hierarchy. + +### Reset Behavior + +- No undo in the first version. +- Reloading the original file resets the deletion state. + +## Architecture + +### Frontend Responsibilities + +- Detect whether the current model is a STEP model. +- Track deleted hierarchy nodes. +- Update the tree and viewer immediately after deletion. +- Call the local STEP service only for `Save STEP`. +- Leave existing export code paths untouched. + +### Local STEP Service Responsibilities + +- Accept the original STEP file and the deletion list. +- Reconstruct the export hierarchy from the original file. +- Remove the requested subtrees. +- Write a new STEP file. +- Return the generated file to the browser for download. + +### Isolation Rule + +The new feature must use its own save path and must not be added into the current generic `ExportDialog`. + +This keeps three behaviors separate: + +- `Download`: returns the original uploaded file. +- `Export`: converts the current visualization model into the already supported formats. +- `Save STEP`: creates a new STEP file from the deletion result. + +## Data Model + +### Deletion Representation + +Frontend deletion state is stored as a set of stable hierarchy path identifiers. + +Each deletable node gets a path-based identifier derived from its position in the tree, for example: + +- `0` +- `0/2` +- `0/2/1` + +This represents child index traversal from the root and avoids relying on names. + +### Why path identifiers + +- Runtime `nodeId` values in the viewer are temporary and only valid for the current in-memory import. +- Names are not safe because duplicates are common in CAD assemblies. +- Path identifiers are simple and deterministic for a demo. + +### Deletion Semantics + +- Deleting a node marks its path as deleted. +- Any child path under a deleted path is implicitly deleted. +- The frontend may prune redundant child deletions when a parent is already deleted. + +## Save Flow + +1. User opens a STEP file. +2. Frontend builds deletion-capable node metadata for the current tree. +3. User deletes one or more nodes. +4. Frontend updates the visible tree and viewer state. +5. User clicks `Save STEP`. +6. Frontend sends: + - The original STEP file. + - The normalized deleted path list. +7. Local STEP service creates a new STEP file with those paths removed. +8. Browser downloads the returned file. + +## Local Service Design + +### Recommended Form + +- A small local HTTP service running on `127.0.0.1`. +- Implemented in Python for simple scripting and process control. +- Backed by local CAD-capable tooling that can read and write STEP. + +### Recommended Backend Choice + +Use a local Python-based STEP processing implementation first, with FreeCAD or OCC-backed scripting as the practical demo backend. + +Reason: + +- It is outside the browser, which is required for real STEP writing. +- It is easier to demo locally than a remote service. +- It keeps the web app changes small. + +### API Shape + +Keep the API minimal: + +- `POST /save-step` + - Multipart form fields: + - `file`: original STEP file + - `deletedPaths`: JSON array of deleted hierarchy paths + - Response: + - Binary STEP file stream + +No persistent session is required for the first version. + +## Compatibility And Stability Rules + +- Only show or enable `Save STEP` when the current file is `.stp` or `.step`. +- Do not change the existing behavior for non-STEP files. +- If the local service is unavailable, show a clear error and keep the current in-browser state intact. +- If saving fails, the deletion preview remains visible so the user can retry. +- The feature should not break the existing viewer even if the local service is not running. + +## Error Handling + +### Frontend Errors + +- No valid selection for deletion: + - Show a small message and do nothing. +- Selected node is not deletable: + - Keep delete action disabled. +- Local service unreachable: + - Show a blocking message that the local STEP save service is not running. + +### Save Errors + +- Invalid response from local service: + - Show save failure dialog. +- STEP processing failure: + - Show the backend error message if available. +- Empty export result: + - Treat as failure and do not trigger download. + +## Testing Strategy + +### Manual Demo Tests + +1. Load a sample STEP model. +2. Delete a leaf part node. +3. Save a new STEP file. +4. Reopen the generated STEP file and verify the deleted part is missing. + +5. Load a sample STEP model again. +6. Delete an assembly branch. +7. Save a new STEP file. +8. Reopen the generated STEP file and verify the whole subtree is missing. + +9. Verify `Download` still returns the original uploaded file. +10. Verify the existing `Export` dialog still exports supported non-STEP formats exactly as before. +11. Verify non-STEP models never show an active `Save STEP` action. + +### Regression Focus + +- Tree deletion must not break mesh visibility toggling. +- Existing selection and fit-to-window behavior must continue to work. +- Existing toolbar actions must not change behavior. + +## Implementation Boundaries + +- Keep frontend changes focused on the navigator and toolbar integration. +- Do not refactor the current exporter architecture unless required by this feature. +- Do not merge the new save action into the current export dialog. +- Prefer a direct, demo-friendly implementation over generalized framework work. + +## Final Decision + +Build a minimal STEP subtree deletion demo with: + +- Existing viewer and tree as the interaction surface. +- One delete action for the selected node. +- One separate `Save STEP` action. +- One local service dedicated to generating the new STEP file. + +This is the shortest path that satisfies the requested workflow without creating conflicts with the current export and download features.