@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,54 +1,54 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
-import { OffsetSplitOutcome } from "../shared"
-
-/**
- * STAGED (LLD Wave 2) — abstract shell only. NOT yet wired into `PluginDesignApi`
- * and has no host implementation. `offsetSplit` migrates off `tools.offset` (adding
- * the previously-dropped `offsetValue` to the result).
- *
- * `snaptrude.design.edit` — non-create geometry edits (offset-split, and later
- * push-pull / topology edits). Undoable.
- *
- * TRANSPORT: positional args per method.
- */
-export abstract class PluginDesignEditApi {
-  constructor() {}
-
-  /**
-   * Offset the top profile of a component by a distance and split the face along
-   * the offset curve. Positive distances offset outward, negative inward.
-   * Single-component only (the engine rejects batches).
-   * @param component - The component whose top profile is offset-split.
-   * @param offsetDistance - Offset distance; positive = outward, negative = inward.
-   * @param options - Optional settings: `profilePickPoint` picks the profile when ambiguous.
-   * @returns {@linkcode OffsetSplitOutcome} `{ createdIds, deletedIds, offsetValue }`
-   *
-   * @examplePrompt Offset the top face of this mass inward by 2 metres and split it
-   * @examplePrompt Create a 1m setback border on top of the selected mass
-   * @examplePrompt Split the roof profile with a 500mm inward offset
-   * @examplePrompt Offset-split the slab's top profile outward by 3 feet
-   *
-   * # Example
-   * ```ts
-   * // Offset the top profile inward by 2 units and split the face along it
-   * const [mass] = await snaptrude.design.query.listMasses()
-   * const { createdIds, offsetValue } = await snaptrude.design.edit.offsetSplit(mass, -2)
-   * // offsetValue is the post-clamp distance the engine actually applied
-   * ```
-   */
-  public abstract offsetSplit(
-    component: ComponentHandle,
-    offsetDistance: number,
-    options?: { profilePickPoint?: Vec3Handle },
-  ): PluginApiReturn<OffsetSplitOutcome>
-}
-
-// Positional target: offsetSplit(component, offsetDistance, options?)
-export const PluginDesignOffsetSplitArgs = z.object({
-  component: ComponentHandle,
-  offsetDistance: z.number(),
-  profilePickPoint: Vec3Handle.optional(),
-})
-export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { OffsetSplitOutcome } from "../shared"
+
+/**
+ * STAGED (LLD Wave 2) — abstract shell only. NOT yet wired into `PluginDesignApi`
+ * and has no host implementation. `offsetSplit` migrates off `tools.offset` (adding
+ * the previously-dropped `offsetValue` to the result).
+ *
+ * `snaptrude.design.edit` — non-create geometry edits (offset-split, and later
+ * push-pull / topology edits). Undoable.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignEditApi {
+  constructor() {}
+
+  /**
+   * Offset the top profile of a component by a distance and split the face along
+   * the offset curve. Positive distances offset outward, negative inward.
+   * Single-component only (the engine rejects batches).
+   * @param component - The component whose top profile is offset-split.
+   * @param offsetDistance - Offset distance; positive = outward, negative = inward.
+   * @param options - Optional settings: `profilePickPoint` picks the profile when ambiguous.
+   * @returns {@linkcode OffsetSplitOutcome} `{ createdIds, deletedIds, offsetValue }`
+   *
+   * @examplePrompt Offset the top face of this mass inward by 2 metres and split it
+   * @examplePrompt Create a 1m setback border on top of the selected mass
+   * @examplePrompt Split the roof profile with a 500mm inward offset
+   * @examplePrompt Offset-split the slab's top profile outward by 3 feet
+   *
+   * # Example
+   * ```ts
+   * // Offset the top profile inward by 2 units and split the face along it
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const { createdIds, offsetValue } = await snaptrude.design.edit.offsetSplit(mass, -2)
+   * // offsetValue is the post-clamp distance the engine actually applied
+   * ```
+   */
+  public abstract offsetSplit(
+    component: ComponentHandle,
+    offsetDistance: number,
+    options?: { profilePickPoint?: Vec3Handle },
+  ): PluginApiReturn<OffsetSplitOutcome>
+}
+
+// Positional target: offsetSplit(component, offsetDistance, options?)
+export const PluginDesignOffsetSplitArgs = z.object({
+  component: ComponentHandle,
+  offsetDistance: z.number(),
+  profilePickPoint: Vec3Handle.optional(),
+})
+export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>

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

@@ -1,151 +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>
-}
+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>
+}