@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

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

@@ -1,273 +1,273 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle } from "../../../handles"
-import { PluginDesignChangeResult } from "../lock"
-
-/**
- * The entity kinds {@linkcode PluginDesignSelectionApi.setByFilter} can select —
- * the union of the editor's "Filter selection" menus (Design tab + BIM tab).
- * Tokens mirror {@linkcode PluginEntityType} where a kind exists on the query
- * surface; the rest are selection-only kinds the query surface cannot reach
- * (layer-backed and annotation objects).
- *
- * | Value | Entity (menu label) |
- * |---|---|
- * | `"wall"` | Wall |
- * | `"slab"` | Floor slab |
- * | `"floor"` | Flooring |
- * | `"door"` | Door |
- * | `"window"` | Window |
- * | `"beam"` | Beam |
- * | `"column"` | Column |
- * | `"ceiling"` | Ceiling |
- * | `"roof"` | Roof |
- * | `"staircase"` | Staircase |
- * | `"furniture"` | Furniture |
- * | `"pergola"` | Pergola |
- * | `"sunshade"` | Sunshade |
- * | `"referenceLine"` | Reference line |
- * | `"space"` | Space (room mass) |
- * | `"site"` | Site |
- * | `"terrain"` | Terrain |
- * | `"cad"` | CAD import |
- * | `"pdf"` | PDF import |
- * | `"image"` | Image import |
- * | `"dimensionLine"` | Dimension line |
- * | `"model3d"` | Imported 3D model |
- * | `"neighborhoodBuilding"` | Neighborhood building |
- * | `"programBlock"` | Program block (department mass) |
- */
-export const PluginSelectionEntityType = z.enum([
-  "wall",
-  "slab",
-  "floor",
-  "door",
-  "window",
-  "beam",
-  "column",
-  "ceiling",
-  "roof",
-  "staircase",
-  "furniture",
-  "pergola",
-  "sunshade",
-  "referenceLine",
-  "space",
-  "site",
-  "terrain",
-  "cad",
-  "pdf",
-  "image",
-  "dimensionLine",
-  "model3d",
-  "neighborhoodBuilding",
-  "programBlock",
-])
-export type PluginSelectionEntityType = z.infer<typeof PluginSelectionEntityType>
-
-/**
- * The filter for {@linkcode PluginDesignSelectionApi.setByFilter}. At least one
- * field must be non-empty (to empty the selection use
- * {@linkcode PluginDesignSelectionApi.clear}). Fields **AND**-combine; values
- * within a field **OR**-combine — `{ storeys: [2], types: ["furniture"] }`
- * selects only the furniture on storey 2.
- *
- * | Field | Type | Selects entities where |
- * |---|---|---|
- * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
- * | `types` | {@linkcode PluginSelectionEntityType}`[]` | entity kind ∈ `types` |
- */
-export const PluginSelectionFilter = z
-  .object({
-    storeys: z.array(z.number()).optional(),
-    types: z.array(PluginSelectionEntityType).optional(),
-  })
-  .refine((f) => (f.storeys?.length ?? 0) + (f.types?.length ?? 0) > 0, {
-    message:
-      "PluginSelectionFilter requires at least one non-empty field (storeys or types); use design.selection.clear() to deselect everything",
-  })
-export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>
-
-/**
- * `snaptrude.design.selection` — read and mutate the current scene selection.
- *
- * Selection targets are {@linkcode ComponentHandle}s. `get` is the one sanctioned
- * `get`-returns-array accessor (§4.1(3)). The mutators (`set`/`add`/`remove`/`clear`)
- * change the live selection and return the resulting selection snapshot — they are
- * **not undoable** (the engine fires a selection listener, no command), so the
- * returned {@linkcode PluginDesignChangeResult} is a committed-state snapshot.
- */
-export abstract class PluginDesignSelectionApi {
-  constructor() {}
-
-  /**
-   * Read the current scene selection — the entities the user (or a previous
-   * call) has selected, returned as handles you can pass straight into other
-   * API calls.
-   *
-   * @returns The selection as {@linkcode ComponentHandle}`[]` (`[]` when nothing is selected)
-   *
-   * @examplePrompt What do I have selected right now?
-   * @examplePrompt List the currently selected objects
-   * @examplePrompt Which rooms are selected in the scene?
-   * @examplePrompt Get the ids of everything I've selected
-   * @examplePrompt Is anything selected?
-   *
-   * # Example
-   * ```ts
-   * // Selection handles feed straight into other API calls
-   * const selection = await snaptrude.design.selection.get()
-   * if (selection.length > 0) {
-   *   const props = await snaptrude.design.query.getProperties(selection[0])
-   * }
-   * ```
-   */
-  public abstract get(): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * Replace the selection with exactly the given entities — anything
-   * previously selected is deselected first, so afterwards only these
-   * entities are selected.
-   *
-   * @param components The entities to select
-   * @returns The resulting selection snapshot
-   *
-   * @examplePrompt Select these three walls
-   * @examplePrompt Select only the kitchen and deselect everything else
-   * @examplePrompt Change the selection to just these rooms
-   * @examplePrompt Highlight the spaces on the second storey
-   *
-   * # Example
-   * ```ts
-   * // Select only the ground-storey walls (replaces the previous selection)
-   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
-   * const { affected } = await snaptrude.design.selection.set(walls)
-   * ```
-   */
-  public abstract set(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * Add entities to the current selection without deselecting anything — the
-   * selection grows to include the given entities alongside whatever was
-   * already selected.
-   *
-   * @param components The entities to add to the selection
-   * @returns The resulting selection snapshot
-   *
-   * @examplePrompt Add the corridor to my current selection
-   * @examplePrompt Select these columns too, keeping what's already selected
-   * @examplePrompt Also select the roof
-   * @examplePrompt Extend the selection to include all the doors on this floor
-   *
-   * # Example
-   * ```ts
-   * // Grow the selection to include every roof, keeping what's already selected
-   * const roofs = await snaptrude.design.query.listRoofs()
-   * await snaptrude.design.selection.add(roofs)
-   * ```
-   */
-  public abstract add(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * Remove entities from the current selection — the given entities are
-   * deselected while everything else stays selected.
-   *
-   * @param components The entities to remove from the selection
-   * @returns The resulting selection snapshot
-   *
-   * @examplePrompt Deselect the stair core but keep the rest selected
-   * @examplePrompt Remove these walls from my selection
-   * @examplePrompt Take the furniture out of the current selection
-   * @examplePrompt Unselect the two smaller rooms
-   *
-   * # Example
-   * ```ts
-   * // Deselect the furniture while keeping everything else selected
-   * const furniture = await snaptrude.design.query.listFurniture({ isSelected: true })
-   * await snaptrude.design.selection.remove(furniture)
-   * ```
-   */
-  public abstract remove(
-    components: ComponentHandle[]
-  ): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * Clear the selection so nothing is selected (equivalent to `set([])`).
-   *
-   * @returns The resulting (empty) selection snapshot
-   *
-   * @examplePrompt Deselect everything
-   * @examplePrompt Clear my current selection
-   * @examplePrompt Unselect all objects in the scene
-   * @examplePrompt Make sure nothing is selected before we start
-   *
-   * # Example
-   * ```ts
-   * const { affected } = await snaptrude.design.selection.clear()
-   * // affected is the resulting selection — always [] here
-   * ```
-   */
-  public abstract clear(): PluginApiReturn<PluginDesignChangeResult>
-
-  /**
-   * Replace the selection with every visible entity of the active building that
-   * matches the filter — the programmatic equivalent of the editor's
-   * **Story selection** (`storeys`) and **Filter selection** (`types`) menus
-   * under the select tool, including their combination (fields AND, values
-   * within a field OR). Reaches selection-only kinds the query surface cannot
-   * (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models,
-   * neighborhood buildings) and selects whole groups the way the editor does.
-   *
-   * This is a one-shot bulk select, not a persistent mode: the user's next
-   * canvas click resets the underlying filter state (the selection it made
-   * stays until changed). Results honor the ambient view — active building,
-   * hidden objects/buckets, and in 2D the active storey.
-   *
-   * @param filter Which entities to select — {@linkcode PluginSelectionFilter};
-   *   at least one field must be non-empty
-   * @returns The resulting selection snapshot
-   *
-   * @examplePrompt Select everything on storey 2
-   * @examplePrompt Select all the walls and doors
-   * @examplePrompt Story selection: select the ground floor and first floor
-   * @examplePrompt Filter selection: select all furniture in the model
-   * @examplePrompt Select only the furniture on the second storey
-   * @examplePrompt Select all the spaces so I can recolor them
-   *
-   * # Example
-   * ```ts
-   * // "Story selection": everything on storeys 1 and 2
-   * await snaptrude.design.selection.setByFilter({ storeys: [1, 2] })
-   *
-   * // "Filter selection": all walls and doors
-   * await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] })
-   *
-   * // Combined: only the furniture on storey 2
-   * const { affected } = await snaptrude.design.selection.setByFilter({
-   *   storeys: [2],
-   *   types: ["furniture"],
-   * })
-   * ```
-   */
-  public abstract setByFilter(
-    filter: PluginSelectionFilter
-  ): PluginApiReturn<PluginDesignChangeResult>
-}
-
-/**
- * Arguments for {@linkcode PluginDesignSelectionApi.set}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | The entities to select |
- */
-export const PluginDesignSelectionSetArgs = z.object({
-  components: z.array(ComponentHandle),
-})
-export type PluginDesignSelectionSetArgs = z.infer<typeof PluginDesignSelectionSetArgs>
-
-export const PluginDesignSelectionAddArgs = PluginDesignSelectionSetArgs
-export type PluginDesignSelectionAddArgs = z.infer<typeof PluginDesignSelectionAddArgs>
-
-export const PluginDesignSelectionRemoveArgs = PluginDesignSelectionSetArgs
-export type PluginDesignSelectionRemoveArgs = z.infer<typeof PluginDesignSelectionRemoveArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * The entity kinds {@linkcode PluginDesignSelectionApi.setByFilter} can select —
+ * the union of the editor's "Filter selection" menus (Design tab + BIM tab).
+ * Tokens mirror {@linkcode PluginEntityType} where a kind exists on the query
+ * surface; the rest are selection-only kinds the query surface cannot reach
+ * (layer-backed and annotation objects).
+ *
+ * | Value | Entity (menu label) |
+ * |---|---|
+ * | `"wall"` | Wall |
+ * | `"slab"` | Floor slab |
+ * | `"floor"` | Flooring |
+ * | `"door"` | Door |
+ * | `"window"` | Window |
+ * | `"beam"` | Beam |
+ * | `"column"` | Column |
+ * | `"ceiling"` | Ceiling |
+ * | `"roof"` | Roof |
+ * | `"staircase"` | Staircase |
+ * | `"furniture"` | Furniture |
+ * | `"pergola"` | Pergola |
+ * | `"sunshade"` | Sunshade |
+ * | `"referenceLine"` | Reference line |
+ * | `"space"` | Space (room mass) |
+ * | `"site"` | Site |
+ * | `"terrain"` | Terrain |
+ * | `"cad"` | CAD import |
+ * | `"pdf"` | PDF import |
+ * | `"image"` | Image import |
+ * | `"dimensionLine"` | Dimension line |
+ * | `"model3d"` | Imported 3D model |
+ * | `"neighborhoodBuilding"` | Neighborhood building |
+ * | `"programBlock"` | Program block (department mass) |
+ */
+export const PluginSelectionEntityType = z.enum([
+  "wall",
+  "slab",
+  "floor",
+  "door",
+  "window",
+  "beam",
+  "column",
+  "ceiling",
+  "roof",
+  "staircase",
+  "furniture",
+  "pergola",
+  "sunshade",
+  "referenceLine",
+  "space",
+  "site",
+  "terrain",
+  "cad",
+  "pdf",
+  "image",
+  "dimensionLine",
+  "model3d",
+  "neighborhoodBuilding",
+  "programBlock",
+])
+export type PluginSelectionEntityType = z.infer<typeof PluginSelectionEntityType>
+
+/**
+ * The filter for {@linkcode PluginDesignSelectionApi.setByFilter}. At least one
+ * field must be non-empty (to empty the selection use
+ * {@linkcode PluginDesignSelectionApi.clear}). Fields **AND**-combine; values
+ * within a field **OR**-combine — `{ storeys: [2], types: ["furniture"] }`
+ * selects only the furniture on storey 2.
+ *
+ * | Field | Type | Selects entities where |
+ * |---|---|---|
+ * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
+ * | `types` | {@linkcode PluginSelectionEntityType}`[]` | entity kind ∈ `types` |
+ */
+export const PluginSelectionFilter = z
+  .object({
+    storeys: z.array(z.number()).optional(),
+    types: z.array(PluginSelectionEntityType).optional(),
+  })
+  .refine((f) => (f.storeys?.length ?? 0) + (f.types?.length ?? 0) > 0, {
+    message:
+      "PluginSelectionFilter requires at least one non-empty field (storeys or types); use design.selection.clear() to deselect everything",
+  })
+export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>
+
+/**
+ * `snaptrude.design.selection` — read and mutate the current scene selection.
+ *
+ * Selection targets are {@linkcode ComponentHandle}s. `get` is the one sanctioned
+ * `get`-returns-array accessor (§4.1(3)). The mutators (`set`/`add`/`remove`/`clear`)
+ * change the live selection and return the resulting selection snapshot — they are
+ * **not undoable** (the engine fires a selection listener, no command), so the
+ * returned {@linkcode PluginDesignChangeResult} is a committed-state snapshot.
+ */
+export abstract class PluginDesignSelectionApi {
+  constructor() {}
+
+  /**
+   * Read the current scene selection — the entities the user (or a previous
+   * call) has selected, returned as handles you can pass straight into other
+   * API calls.
+   *
+   * @returns The selection as {@linkcode ComponentHandle}`[]` (`[]` when nothing is selected)
+   *
+   * @examplePrompt What do I have selected right now?
+   * @examplePrompt List the currently selected objects
+   * @examplePrompt Which rooms are selected in the scene?
+   * @examplePrompt Get the ids of everything I've selected
+   * @examplePrompt Is anything selected?
+   *
+   * # Example
+   * ```ts
+   * // Selection handles feed straight into other API calls
+   * const selection = await snaptrude.design.selection.get()
+   * if (selection.length > 0) {
+   *   const props = await snaptrude.design.query.getProperties(selection[0])
+   * }
+   * ```
+   */
+  public abstract get(): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Replace the selection with exactly the given entities — anything
+   * previously selected is deselected first, so afterwards only these
+   * entities are selected.
+   *
+   * @param components The entities to select
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Select these three walls
+   * @examplePrompt Select only the kitchen and deselect everything else
+   * @examplePrompt Change the selection to just these rooms
+   * @examplePrompt Highlight the spaces on the second storey
+   *
+   * # Example
+   * ```ts
+   * // Select only the ground-storey walls (replaces the previous selection)
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.selection.set(walls)
+   * ```
+   */
+  public abstract set(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Add entities to the current selection without deselecting anything — the
+   * selection grows to include the given entities alongside whatever was
+   * already selected.
+   *
+   * @param components The entities to add to the selection
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Add the corridor to my current selection
+   * @examplePrompt Select these columns too, keeping what's already selected
+   * @examplePrompt Also select the roof
+   * @examplePrompt Extend the selection to include all the doors on this floor
+   *
+   * # Example
+   * ```ts
+   * // Grow the selection to include every roof, keeping what's already selected
+   * const roofs = await snaptrude.design.query.listRoofs()
+   * await snaptrude.design.selection.add(roofs)
+   * ```
+   */
+  public abstract add(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Remove entities from the current selection — the given entities are
+   * deselected while everything else stays selected.
+   *
+   * @param components The entities to remove from the selection
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Deselect the stair core but keep the rest selected
+   * @examplePrompt Remove these walls from my selection
+   * @examplePrompt Take the furniture out of the current selection
+   * @examplePrompt Unselect the two smaller rooms
+   *
+   * # Example
+   * ```ts
+   * // Deselect the furniture while keeping everything else selected
+   * const furniture = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * await snaptrude.design.selection.remove(furniture)
+   * ```
+   */
+  public abstract remove(
+    components: ComponentHandle[]
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Clear the selection so nothing is selected (equivalent to `set([])`).
+   *
+   * @returns The resulting (empty) selection snapshot
+   *
+   * @examplePrompt Deselect everything
+   * @examplePrompt Clear my current selection
+   * @examplePrompt Unselect all objects in the scene
+   * @examplePrompt Make sure nothing is selected before we start
+   *
+   * # Example
+   * ```ts
+   * const { affected } = await snaptrude.design.selection.clear()
+   * // affected is the resulting selection — always [] here
+   * ```
+   */
+  public abstract clear(): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Replace the selection with every visible entity of the active building that
+   * matches the filter — the programmatic equivalent of the editor's
+   * **Story selection** (`storeys`) and **Filter selection** (`types`) menus
+   * under the select tool, including their combination (fields AND, values
+   * within a field OR). Reaches selection-only kinds the query surface cannot
+   * (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models,
+   * neighborhood buildings) and selects whole groups the way the editor does.
+   *
+   * This is a one-shot bulk select, not a persistent mode: the user's next
+   * canvas click resets the underlying filter state (the selection it made
+   * stays until changed). Results honor the ambient view — active building,
+   * hidden objects/buckets, and in 2D the active storey.
+   *
+   * @param filter Which entities to select — {@linkcode PluginSelectionFilter};
+   *   at least one field must be non-empty
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Select everything on storey 2
+   * @examplePrompt Select all the walls and doors
+   * @examplePrompt Story selection: select the ground floor and first floor
+   * @examplePrompt Filter selection: select all furniture in the model
+   * @examplePrompt Select only the furniture on the second storey
+   * @examplePrompt Select all the spaces so I can recolor them
+   *
+   * # Example
+   * ```ts
+   * // "Story selection": everything on storeys 1 and 2
+   * await snaptrude.design.selection.setByFilter({ storeys: [1, 2] })
+   *
+   * // "Filter selection": all walls and doors
+   * await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] })
+   *
+   * // Combined: only the furniture on storey 2
+   * const { affected } = await snaptrude.design.selection.setByFilter({
+   *   storeys: [2],
+   *   types: ["furniture"],
+   * })
+   * ```
+   */
+  public abstract setByFilter(
+    filter: PluginSelectionFilter
+  ): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignSelectionApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The entities to select |
+ */
+export const PluginDesignSelectionSetArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignSelectionSetArgs = z.infer<typeof PluginDesignSelectionSetArgs>
+
+export const PluginDesignSelectionAddArgs = PluginDesignSelectionSetArgs
+export type PluginDesignSelectionAddArgs = z.infer<typeof PluginDesignSelectionAddArgs>
+
+export const PluginDesignSelectionRemoveArgs = PluginDesignSelectionSetArgs
+export type PluginDesignSelectionRemoveArgs = z.infer<typeof PluginDesignSelectionRemoveArgs>

package/src/api/design/shared.ts

@@ -1,40 +1,40 @@
-import * as z from "zod"
-import { ComponentHandle } from "../../handles"
-
-/**
- * Shared `design.*` operation return records (LLD Part A.3).
- *
- * `PluginDesignChangeResult` (`{ affected }`) is NOT here — it already lives in
- * `./lock` and is reused verbatim by the transform/delete mutators.
- *
- * NOTE: `PluginMirrorAxis` currently lives in `./doors`; its relocation into this
- * shared module is deferred to the transform wave (avoids a doors edit + a
- * double-export while `design.transform` is unwired).
- */
-
-/**
- * Result of a CSG boolean op (`design.boolean.union/subtract/intersect`). Grounded
- * in the engine `Boolean3dOperation.resultComponents { toCreate; toDelete }`:
- * `created` are the result masses, `deleted` is every consumed input (for
- * `subtract` this includes BOTH the target AND the tools). Errors throw (RPC
- * rejects); no `Result<>` crosses the boundary.
- */
-export const BooleanOutcome = z.object({
-  created: z.array(ComponentHandle),
-  deleted: z.array(ComponentHandle),
-})
-export type BooleanOutcome = z.infer<typeof BooleanOutcome>
-
-/**
- * Result of `design.edit.offsetSplit` (migrated from `tools.offset`). `createdIds`
- * are the components the offset produced; `deletedIds` are those a split-style
- * offset removed. `offsetValue` is the engine's POST-clamp / post-sign applied
- * distance — the only way a caller learns the actually-applied clamped distance
- * (the shipped `tools.offset` result dropped it).
- */
-export const OffsetSplitOutcome = z.object({
-  createdIds: z.array(ComponentHandle),
-  deletedIds: z.array(ComponentHandle),
-  offsetValue: z.number(),
-})
-export type OffsetSplitOutcome = z.infer<typeof OffsetSplitOutcome>
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Shared `design.*` operation return records (LLD Part A.3).
+ *
+ * `PluginDesignChangeResult` (`{ affected }`) is NOT here — it already lives in
+ * `./lock` and is reused verbatim by the transform/delete mutators.
+ *
+ * NOTE: `PluginMirrorAxis` currently lives in `./doors`; its relocation into this
+ * shared module is deferred to the transform wave (avoids a doors edit + a
+ * double-export while `design.transform` is unwired).
+ */
+
+/**
+ * Result of a CSG boolean op (`design.boolean.union/subtract/intersect`). Grounded
+ * in the engine `Boolean3dOperation.resultComponents { toCreate; toDelete }`:
+ * `created` are the result masses, `deleted` is every consumed input (for
+ * `subtract` this includes BOTH the target AND the tools). Errors throw (RPC
+ * rejects); no `Result<>` crosses the boundary.
+ */
+export const BooleanOutcome = z.object({
+  created: z.array(ComponentHandle),
+  deleted: z.array(ComponentHandle),
+})
+export type BooleanOutcome = z.infer<typeof BooleanOutcome>
+
+/**
+ * Result of `design.edit.offsetSplit` (migrated from `tools.offset`). `createdIds`
+ * are the components the offset produced; `deletedIds` are those a split-style
+ * offset removed. `offsetValue` is the engine's POST-clamp / post-sign applied
+ * distance — the only way a caller learns the actually-applied clamped distance
+ * (the shipped `tools.offset` result dropped it).
+ */
+export const OffsetSplitOutcome = z.object({
+  createdIds: z.array(ComponentHandle),
+  deletedIds: z.array(ComponentHandle),
+  offsetValue: z.number(),
+})
+export type OffsetSplitOutcome = z.infer<typeof OffsetSplitOutcome>