Erase

Adjacency-edge erase — a plan-level topology operation. Accessed via snaptrude.design.erase.

Erase is NOT delete. The erase tool operates on an edge, and the effect is derived from that edge: erasing an internal edge between two masses unions them (DirectUnion); erasing an external boundary edge of a single mass drops it behind the edge (DirectDelete). For hard entity removal use design.delete.entities; for CSG geometry delete use design.boolean.subtract.

The workflow is two-step: listErasableEdges to enumerate, then edge to commit one ref (single undo entry). Scoped to 2D plan adjacency edges in v1.

Types

EraseStrategy

The erase strategies exposed to plugins, derived host-side by the engine's decideStrategy.

Value	Description
'DirectDelete'	Drops the single mass behind an external boundary edge
'DirectUnion'	Merges the two masses adjacent to an internal edge
'SplitAndUnion'	Enumerable but NOT committable via edge() — it needs an interactive screen-space re-pick

SplitAndDelete is reserved in the engine and intentionally omitted.

ErasableEdgeRef

A transient reference to one erasable edge in the current plan's bottom-adjacency graph.

Lifetime

Valid ONLY until the next geometry-modifying operation. Any mutation (erase, boolean, transform, create, delete, …) rebuilds the adjacency graph and invalidates every previously-returned ref. Passing a stale ref to edge() throws NO_STRATEGY_FOR_PICK_INFO. Always re-list after a mutation.

This is a by-value record (round-trip it back to edge() unmodified), NOT a registry handle. components and snapPoint are the marshalled public forms of the engine's raw mesh.uniqueId numbers / by-value point.

Property	Type	Description
id	string	Opaque bottom-graph edge id (engine form "e-<n>"). Do not mutate; pass verbatim to edge()
strategy	EraseStrategy	What erasing this edge would do: DirectDelete drops a mass; DirectUnion merges two adjacent masses
edgeWeight	number	Bottom-graph edge weight: 1 = external boundary edge, >=2 = internal edge shared between components
components	ComponentHandle[]	The components this edge is incident to — one for external (DirectDelete), two for internal (DirectUnion)
snapPoint	Vec3Handle	A representative point on the edge (its head endpoint). Diagnostic only

PluginDesignEraseEdgeResult

Result of edge() — a success sentinel; the engine yields no survivor id.

Property	Type	Description
ok	true	Always true on success

Functions

listErasableEdges(options?)

Enumerate every erasable edge in the current plan's bottom-adjacency graph (one ErasableEdgeRef per edge). Pure read — no scene mutation, no command, not undoable. Erase-ineligible components (locked, hidden, off-storey) are filtered out.

Returned refs are transient — see ErasableEdgeRef. Re-list after any geometry mutation.

• Parameters:
  • options: object (optional) — Filters:
    • options.components: ComponentHandle[] (optional) — Restrict to edges adjacent to at least one of these entities
    • options.strategies: EraseStrategy[] (optional, default ["DirectDelete", "DirectUnion"]) — Restrict to these strategies. The default hides the interactive-only SplitAndUnion
• Returns: ErasableEdgeRef[] — The erasable edges ([] when none) — never null

const edges = await snaptrude.design.erase.listErasableEdges();
const union = edges.find((e) => e.strategy === "DirectUnion");
if (union) await snaptrude.design.erase.edge(union);

---

edge(edge)

Commit the erase for one edge. DirectUnion merges the two adjacent masses; DirectDelete drops the single mass behind the boundary edge. Single undo entry.

Pass an ErasableEdgeRef from listErasableEdges unmodified. A stale ref (graph rebuilt by a prior mutation) or a SplitAndUnion edge throws.

• Parameters:
  • edge: ErasableEdgeRef — The ref to commit, exactly as returned by listErasableEdges
• Returns: PluginDesignEraseEdgeResult — { ok: true } on success (the engine yields no survivor id today)
• Throws: when the ref is stale, its components are all erase-ineligible, or the strategy is not committable via the scripted path

// Refs are invalidated by any geometry mutation — re-list before each commit
const edges = await snaptrude.design.erase.listErasableEdges({
  strategies: ["DirectDelete"]
});
if (edges.length > 0) {
  const result = await snaptrude.design.erase.edge(edges[0]);
  console.log(result.ok); // true
}

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	listErasableEdges	A handle in options.components cannot be resolved	—
OPERATION_FAILED	edge	The engine rejects the commit — most commonly a stale ref (the graph was rebuilt by a mutation since listErasableEdges), an edge whose strategy is not committable via the scripted path, or an all-ineligible component set	engineCode — the engine's code, e.g. NO_STRATEGY_FOR_PICK_INFO for a stale/non-committable ref

Apart from handle resolution, listErasableEdges never throws — it is a pure read that returns [] when nothing is erasable.