@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/api/design/erase/index.d.ts

@@ -0,0 +1,160 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import { ComponentHandle } 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 declare const EraseStrategy: z.ZodEnum<{
+    DirectDelete: "DirectDelete";
+    DirectUnion: "DirectUnion";
+    SplitAndUnion: "SplitAndUnion";
+}>;
+export type EraseStrategy = z.infer<typeof EraseStrategy>;
+/** Default enumerated strategies — the two the scripted `edge()` can commit. */
+export declare const DEFAULT_ERASE_STRATEGIES: readonly EraseStrategy[];
+/**
+ * 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 declare const ErasableEdgeRef: z.ZodObject<{
+    id: z.ZodString;
+    strategy: z.ZodEnum<{
+        DirectDelete: "DirectDelete";
+        DirectUnion: "DirectUnion";
+        SplitAndUnion: "SplitAndUnion";
+    }>;
+    edgeWeight: z.ZodNumber;
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    snapPoint: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
+}, z.core.$strip>;
+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 declare const PluginDesignListErasableEdgesArgs: z.ZodObject<{
+    components: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+    strategies: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        DirectDelete: "DirectDelete";
+        DirectUnion: "DirectUnion";
+        SplitAndUnion: "SplitAndUnion";
+    }>>>;
+}, z.core.$strip>;
+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 declare const PluginDesignEraseEdgeArgs: z.ZodObject<{
+    edge: z.ZodObject<{
+        id: z.ZodString;
+        strategy: z.ZodEnum<{
+            DirectDelete: "DirectDelete";
+            DirectUnion: "DirectUnion";
+            SplitAndUnion: "SplitAndUnion";
+        }>;
+        edgeWeight: z.ZodNumber;
+        components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+        snapPoint: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginDesignEraseEdgeArgs = z.infer<typeof PluginDesignEraseEdgeArgs>;
+/** Result of {@linkcode PluginDesignEraseApi.edge} — success sentinel; the engine yields no survivor id. */
+export declare const PluginDesignEraseEdgeResult: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+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 declare 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)
+     * ```
+     */
+    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])
+     * }
+     * ```
+     */
+    abstract edge(edge: ErasableEdgeRef): PluginApiReturn<PluginDesignEraseEdgeResult>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/api/design/erase/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/erase/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAc,MAAM,kBAAkB,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;EAA2D,CAAA;AACrF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEzD,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,EAAE,SAAS,aAAa,EAAoC,CAAA;AAEjG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;iBAW1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC;;;;;;;iBAG5C,CAAA;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAA;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;iBAEpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAEjF,4GAA4G;AAC5G,eAAO,MAAM,2BAA2B;;iBAAoC,CAAA;AAC5E,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;;;;;;;GAaG;AACH,8BAAsB,oBAAoB;;IAGxC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,iBAAiB,CAC/B,OAAO,CAAC,EAAE,iCAAiC,GAC1C,eAAe,CAAC,eAAe,EAAE,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;aACa,IAAI,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC,2BAA2B,CAAC;CAC1F"}