@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/design/erase/index.ts

@@ -0,0 +1,151 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+
+/**
+ * The erase strategies exposed to plugins. `SplitAndUnion` is *enumerable* but
+ * NOT committable via {@linkcode PluginDesignEraseApi.edge} (it needs an
+ * interactive screen-space re-pick); `SplitAndDelete` is reserved in the engine
+ * and intentionally omitted. Derived host-side by the engine's `decideStrategy`.
+ */
+export const EraseStrategy = z.enum(["DirectDelete", "DirectUnion", "SplitAndUnion"])
+export type EraseStrategy = z.infer<typeof EraseStrategy>
+
+/** Default enumerated strategies — the two the scripted `edge()` can commit. */
+export const DEFAULT_ERASE_STRATEGIES: readonly EraseStrategy[] = ["DirectDelete", "DirectUnion"]
+
+/**
+ * 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
+ * {@linkcode PluginDesignEraseApi.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.
+ */
+export const ErasableEdgeRef = z.object({
+  /** Opaque bottom-graph edge id (engine form `"e-<n>"`). Do not mutate. Pass verbatim to {@linkcode PluginDesignEraseApi.edge}. */
+  id: z.string().min(1),
+  /** What erasing this edge would do: `DirectDelete` drops a mass; `DirectUnion` merges two adjacent masses. */
+  strategy: EraseStrategy,
+  /** Bottom-graph edge weight: `1` = external boundary edge, `>=2` = internal edge shared between components. */
+  edgeWeight: z.number(),
+  /** The components this edge is incident to — one for external (DirectDelete); two or more for internal (DirectUnion; 3+ at T-junctions where several masses share the edge). */
+  components: z.array(ComponentHandle),
+  /** A representative point on the edge (its head endpoint). Diagnostic only. */
+  snapPoint: Vec3Handle,
+})
+export type ErasableEdgeRef = z.infer<typeof ErasableEdgeRef>
+
+/**
+ * Options for {@linkcode PluginDesignEraseApi.listErasableEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]?` | Restrict to edges adjacent to at least one of these entities |
+ * | `strategies` | {@linkcode EraseStrategy}`[]?` | Restrict to these strategies. Default `["DirectDelete","DirectUnion"]` (hides interactive-only `SplitAndUnion`) |
+ *
+ * TRANSPORT: positional now — `listErasableEdges(options?)`; this schema is
+ * retained for host-side validation.
+ */
+export const PluginDesignListErasableEdgesArgs = z.object({
+  components: z.array(ComponentHandle).optional(),
+  strategies: z.array(EraseStrategy).optional(),
+})
+export type PluginDesignListErasableEdgesArgs = z.infer<typeof PluginDesignListErasableEdgesArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignEraseApi.edge}.
+ *
+ * TRANSPORT: positional now — `edge(edge: ErasableEdgeRef)`; this schema is
+ * retained for host-side validation.
+ */
+export const PluginDesignEraseEdgeArgs = z.object({
+  edge: ErasableEdgeRef,
+})
+export type PluginDesignEraseEdgeArgs = z.infer<typeof PluginDesignEraseEdgeArgs>
+
+/** Result of {@linkcode PluginDesignEraseApi.edge} — success sentinel; the engine yields no survivor id. */
+export const PluginDesignEraseEdgeResult = z.object({ ok: z.literal(true) })
+export type PluginDesignEraseEdgeResult = z.infer<typeof PluginDesignEraseEdgeResult>
+
+/**
+ * `snaptrude.design.erase` — **adjacency-edge erase** (plan-level topology op).
+ *
+ * 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`.
+ *
+ * Two-step: {@linkcode listErasableEdges} to enumerate, then {@linkcode edge} to
+ * commit one ref (single undo entry). Scoped to **2D plan adjacency edges** in v1.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignEraseApi {
+  constructor() {}
+
+  /**
+   * Enumerate every erasable edge in the current plan's bottom-adjacency graph
+   * (one {@linkcode 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 {@linkcode ErasableEdgeRef}. Re-list
+   * after any geometry mutation.
+   *
+   * @param options - {@linkcode PluginDesignListErasableEdgesArgs} — optional filters (`components`, `strategies`)
+   * @returns The erasable edges (`[]` when none) — never `null`.
+   *
+   * @examplePrompt Which edges in my floor plan can be erased?
+   * @examplePrompt List the erasable edges on this storey
+   * @examplePrompt Show me the shared edges I could erase to merge rooms
+   * @examplePrompt What edges between these two spaces can be removed?
+   *
+   * # Example
+   * ```ts
+   * const edges = await snaptrude.design.erase.listErasableEdges()
+   * const union = edges.find((e) => e.strategy === "DirectUnion")
+   * if (union) await snaptrude.design.erase.edge(union)
+   * ```
+   */
+  public abstract listErasableEdges(
+    options?: PluginDesignListErasableEdgesArgs,
+  ): PluginApiReturn<ErasableEdgeRef[]>
+
+  /**
+   * 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 {@linkcode ErasableEdgeRef} from {@linkcode listErasableEdges}
+   * unmodified. A stale ref (graph rebuilt by a prior mutation) or a `SplitAndUnion`
+   * edge throws.
+   *
+   * @param edge - The {@linkcode ErasableEdgeRef} to erase, from {@linkcode listErasableEdges} unmodified
+   * @returns `{ 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.
+   *
+   * @examplePrompt Erase the edge between these two rooms so they merge
+   * @examplePrompt Remove the shared boundary between the kitchen and the dining space
+   * @examplePrompt Merge the two adjacent rooms by erasing their common edge
+   * @examplePrompt Knock through the partition line between these spaces
+   * @examplePrompt Erase this boundary edge from the plan
+   *
+   * # Example
+   * ```ts
+   * // Merge two adjacent rooms by erasing an internal edge they share
+   * const edges = await snaptrude.design.erase.listErasableEdges({ strategies: ["DirectUnion"] })
+   * if (edges.length > 0) {
+   *   const { ok } = await snaptrude.design.erase.edge(edges[0])
+   * }
+   * ```
+   */
+  public abstract edge(edge: ErasableEdgeRef): PluginApiReturn<PluginDesignEraseEdgeResult>
+}