ModelHandle/docs/superpowers/specs/2026-04-10-step-tree-edit-design.md

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.