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

package/src/api/design/dimensions.ts

@@ -1,453 +1,453 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import {
-  ComponentHandle,
-  DimensionHandle,
-  Vec3Components,
-  Vec3Handle,
-} from "../../handles"
-
-/**
- * Dimension lines (Measuring Tape) — the measurement annotations the Measuring
- * Tape tool leaves in the 3D scene, NOT an entity's width/height/depth
- * properties (for those see `design.windows.getDimensions`,
- * `design.create.staircase`'s `dimensions`, or `design.query.measure`).
- *
- * A dimension line is a scene object: two endpoints anchored to the geometry
- * they were measured on, an offset that pushes the drawn line clear of the
- * span, and a label showing the distance in the project's units. Because the
- * endpoints are anchored, the line follows its host when the host is moved,
- * edited, or resized, and it is removed with the host when the host is deleted.
- * Dimension lines are storey-scoped, render in both plan and 3D, and are drawn
- * into Present-mode sheets (style them with
- * `presentation.placedViews.updateStyles(shapeId, "Dimension", …)`).
- *
- * **Units.** Every length here — `offset` and the record's `length` — is in
- * **Babylon units** (BU), the engine's storage unit: 1 BU = 10 in = 0.254 m.
- * Convert with `core.units.convert(value, from, await core.units.getBabylonType())`.
- *
- * **Offset convention.** `options.offset` is a **signed** distance in BU:
- * positive pushes the drawn line to the **left** of the `from` → `to`
- * direction in plan (`cross(up, direction)`), negative to the right. It
- * defaults to `3.937` BU (1 m). The placement mode is always `"across"` (the
- * tape tool's perpendicular mode), which re-perpendicularises when the host
- * geometry is edited.
- *
- * Every mutator here (`create`, `delete`, `hide`, `show`) commits through the
- * engine's command manager, so each call is a single undo entry, is autosaved,
- * and replays to collaborators.
- *
- * Accessed via `snaptrude.design.dimensions`.
- */
-export abstract class PluginDesignDimensionsApi {
-  constructor() {}
-
-  /**
-   * Draw one dimension line between two world points, anchored to a component.
-   *
-   * `anchor` is **required**: the endpoints are stored relative to the anchor's
-   * mesh, and only component-anchored dimension lines survive a reload. A
-   * free-point dimension anchors to a scene helper mesh whose id is not stable
-   * across reloads, so it is dropped or corrupted when the project is reopened
-   * — the host therefore rejects a non-component anchor rather than writing a
-   * record that silently disappears. Pass `options.anchorTo` to anchor the
-   * second endpoint to a different component (it defaults to `anchor`).
-   *
-   * The dimension is created flat (never plan-projected) so the same call
-   * produces the same record whatever the current camera; it still draws in
-   * plan.
-   *
-   * @param from - World-space first endpoint.
-   * @param to - World-space second endpoint.
-   * @param anchor - The component the first endpoint is anchored to (required).
-   * @param options - `anchorTo` (component for the second endpoint; defaults to
-   *   `anchor`), `offset` (signed perpendicular offset in Babylon units,
-   *   positive = left of the `from` → `to` direction in plan; default `3.937`
-   *   BU = 1 m).
-   * @returns The new dimension line's {@linkcode DimensionHandle}.
-   * @throws `VALIDATION` for malformed arguments or a degenerate span (`from`
-   *   and `to` closer than the engine's minimum); `HANDLE_INVALID` for an
-   *   unknown `anchor` / `anchorTo`; `PRECONDITION_FAILED` when the anchor is
-   *   outside the active proposal or the editor is not mounted;
-   *   `METHOD_NOT_PERMITTED` when plugin writes are disabled.
-   *
-   * @examplePrompt Dimension every wall on level 2
-   * @examplePrompt Add a dimension line along this wall
-   * @examplePrompt Measure the width of this room and label it on the plan
-   *
-   * # Example
-   * ```ts
-   * const { design, core } = snaptrude
-   * const v = core.math.vec3
-   * const curve = core.geom.query.curve
-   * for (const wall of await design.query.listWalls({ storeys: [2] })) {
-   *   const cl = await design.query.geometry.getCenterline(wall)
-   *   if (!cl) continue
-   *   const a = await curve.getStartPoint(cl)
-   *   const b = await curve.getEndPoint(cl)
-   *   await design.dimensions.create(
-   *     await v.new(a.x, a.y, a.z),
-   *     await v.new(b.x, b.y, b.z),
-   *     wall,
-   *   )
-   * }
-   * ```
-   */
-  public abstract create(
-    from: Vec3Handle,
-    to: Vec3Handle,
-    anchor: ComponentHandle,
-    options?: { anchorTo?: ComponentHandle; offset?: number },
-  ): PluginApiReturn<DimensionHandle>
-
-  /**
-   * List the dimension lines in the project as full records.
-   *
-   * Filters combine with AND. `storeys` keeps only the dimensions on those
-   * storey numbers, `anchors` only the ones anchored to those components
-   * (matching either endpoint, and matching an instanced anchor's source mesh
-   * too), `isHidden` only the ones whose user Hide flag equals the value given.
-   *
-   * Dimension lines drawn by the Measuring Tape onto a scene helper mesh rather
-   * than a component come back with `anchor: null` and are not proposal-scoped.
-   *
-   * @param options - `storeys`, `anchors`, `isHidden` filters (all optional,
-   *   ANDed).
-   * @returns The matching {@linkcode PluginDimensionLine} records (`[]` when
-   *   nothing matches).
-   * @throws `VALIDATION` for malformed filters; `HANDLE_INVALID` for an unknown
-   *   handle in `anchors`.
-   *
-   * @examplePrompt List all the dimension lines in this model
-   * @examplePrompt Which dimensions are on level 3?
-   * @examplePrompt Flag any dimension line shorter than 600 mm
-   *
-   * @performance Array read — one host round-trip returns every record. Filter
-   *   in one call rather than calling `get` per dimension.
-   *
-   * # Example
-   * ```ts
-   * const units = snaptrude.core.units
-   * const min = await units.convert(600, "millimeters", await units.getBabylonType())
-   * const short = (await snaptrude.design.dimensions.list()).filter(
-   *   (d) => d.length < min,
-   * )
-   * console.log(short.map((d) => `${d.label} on storey ${d.storey}`))
-   * ```
-   */
-  public abstract list(options?: {
-    storeys?: number[]
-    anchors?: ComponentHandle[]
-    isHidden?: boolean
-  }): PluginApiReturn<PluginDimensionLine[]>
-
-  /**
-   * Read one dimension line by handle.
-   *
-   * Returns `null` — rather than throwing — when the dimension no longer
-   * exists, so a handle kept across a delete or an undo can be polled safely.
-   *
-   * @param dimension - The dimension line to read.
-   * @returns Its {@linkcode PluginDimensionLine} record, or `null` if it is
-   *   gone.
-   * @throws `VALIDATION` if `dimension` is not a non-empty id string.
-   *
-   * @examplePrompt Read the dimension line I just created
-   * @examplePrompt How long is this dimension and what does its label say?
-   * @examplePrompt Check whether that dimension line still exists
-   *
-   * # Example
-   * ```ts
-   * const dim = await snaptrude.design.dimensions.get(handle)
-   * if (dim) console.log(dim.label, dim.length, dim.storey)
-   * ```
-   */
-  public abstract get(
-    dimension: DimensionHandle,
-  ): PluginApiReturn<PluginDimensionLine | null>
-
-  /**
-   * Delete dimension lines — the same hard removal as selecting them and
-   * pressing Delete. Undoable as a **single** entry for the whole batch.
-   *
-   * Deleted handles are stale afterwards: {@linkcode
-   * PluginDesignDimensionsApi.get} returns `null` for them and the other
-   * mutators throw `HANDLE_INVALID`.
-   *
-   * @param dimensions - The dimension lines to delete (at least one — an empty
-   *   array is a caller error, not a no-op).
-   * @returns The dimensions that were deleted, as
-   *   {@linkcode PluginDimensionsChangeResult}.
-   * @throws `VALIDATION` for an empty or malformed array; `HANDLE_INVALID` if
-   *   any handle is unknown (the whole call rejects before anything is
-   *   deleted); `PRECONDITION_FAILED` if any dimension's anchor is outside the
-   *   active proposal; `METHOD_NOT_PERMITTED` when plugin writes are disabled.
-   *
-   * @examplePrompt Remove all dimension lines
-   * @examplePrompt Delete the dimensions on this wall
-   * @examplePrompt Clear the measurements I added to level 2
-   *
-   * @performance Array API — pass the whole set in one call (one host
-   *   round-trip, one undo entry). Never loop this per dimension.
-   *
-   * # Example
-   * ```ts
-   * const dims = snaptrude.design.dimensions
-   * const onWall = await dims.list({ anchors: [wall] })
-   * if (onWall.length > 0) await dims.delete(onWall.map((d) => d.id))
-   * ```
-   */
-  public abstract delete(
-    dimensions: DimensionHandle[],
-  ): PluginApiReturn<PluginDimensionsChangeResult>
-
-  /**
-   * Hide dimension lines from the viewport — the same as the right-click "Hide"
-   * action (it sets the user Hide flag, `isHidden`). Undoable. Already-hidden
-   * dimensions are skipped and are not reported in `affected`.
-   *
-   * @param dimensions - The dimension lines to hide.
-   * @returns The dimensions actually hidden, as
-   *   {@linkcode PluginDimensionsChangeResult} — already-hidden inputs are
-   *   omitted, so `affected` can be shorter than the input.
-   * @throws `VALIDATION` for a malformed array; `HANDLE_INVALID` if any handle
-   *   is unknown; `PRECONDITION_FAILED` if any dimension's anchor is outside
-   *   the active proposal; `METHOD_NOT_PERMITTED` when plugin writes are
-   *   disabled.
-   *
-   * @examplePrompt Hide the dimensions on this storey
-   * @examplePrompt Hide every dimension line while I present
-   * @examplePrompt Temporarily hide the measurements on level 3
-   *
-   * @performance Array API — one host round-trip and one undo entry for the
-   *   whole set.
-   *
-   * # Example
-   * ```ts
-   * const dims = snaptrude.design.dimensions
-   * const onLevel3 = await dims.list({ storeys: [3] })
-   * const { affected } = await dims.hide(onLevel3.map((d) => d.id))
-   * ```
-   */
-  public abstract hide(
-    dimensions: DimensionHandle[],
-  ): PluginApiReturn<PluginDimensionsChangeResult>
-
-  /**
-   * Reveal hidden dimension lines — clear the user Hide flag, the inverse of
-   * {@linkcode PluginDesignDimensionsApi.hide}. Undoable. Already-visible
-   * dimensions are skipped and are not reported in `affected`.
-   *
-   * Clearing the flag does not guarantee the dimension is on screen: a
-   * dimension whose anchor component is itself hidden stays off screen with
-   * `isHidden: false` and `isVisible: false`.
-   *
-   * @param dimensions - The dimension lines to reveal.
-   * @returns The dimensions actually revealed, as
-   *   {@linkcode PluginDimensionsChangeResult} — already-visible inputs are
-   *   omitted, so `affected` can be shorter than the input.
-   * @throws `VALIDATION` for a malformed array; `HANDLE_INVALID` if any handle
-   *   is unknown; `PRECONDITION_FAILED` if any dimension's anchor is outside
-   *   the active proposal; `METHOD_NOT_PERMITTED` when plugin writes are
-   *   disabled.
-   *
-   * @examplePrompt Show the dimension lines again
-   * @examplePrompt Unhide all the hidden dimensions
-   * @examplePrompt Bring back the measurements I hid on this storey
-   *
-   * @performance Array API — one host round-trip and one undo entry for the
-   *   whole set.
-   *
-   * # Example
-   * ```ts
-   * const dims = snaptrude.design.dimensions
-   * const hidden = await dims.list({ isHidden: true })
-   * await dims.show(hidden.map((d) => d.id))
-   * ```
-   */
-  public abstract show(
-    dimensions: DimensionHandle[],
-  ): PluginApiReturn<PluginDimensionsChangeResult>
-}
-
-/**
- * How a dimension line's drawn offset is constrained.
- *
- * - `"across"` — perpendicular to the span (the tape tool's default, and what
- *   every plugin-created dimension uses); re-perpendicularises when the host
- *   geometry is edited.
- * - `"x"` / `"y"` / `"z"` — the offset is locked to that world axis.
- * - `"none"` — no placement mode recorded (a plain world-space offset).
- */
-export const PluginDimensionPlacement = z.enum([
-  "across",
-  "x",
-  "y",
-  "z",
-  "none",
-])
-export type PluginDimensionPlacement = z.infer<typeof PluginDimensionPlacement>
-
-/**
- * One dimension line (Measuring Tape annotation). Lengths are in **Babylon
- * units** (1 BU = 0.254 m — convert with `core.units.convert`).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | {@linkcode DimensionHandle} | The dimension line's handle |
- * | `from` | {@linkcode Vec3Components} | Live world position of the first endpoint |
- * | `to` | {@linkcode Vec3Components} | Live world position of the second endpoint |
- * | `length` | `number` | Straight-line distance between `from` and `to`, in Babylon units |
- * | `label` | `string` | The text drawn on the canvas, in the project's units (a bare number for metric/inch projects, `27' 7"` style for feet-inches). For a span whose x, y and z all differ the drawn line is the plan projection, so `label` reads the horizontal distance while `length` is the true 3D one |
- * | `offset` | {@linkcode Vec3Components} | World vector from the measured span to the drawn line |
- * | `placement` | {@linkcode PluginDimensionPlacement} | How that offset is constrained |
- * | `anchor` | {@linkcode ComponentHandle}` \| null` | Component the first endpoint is anchored to; `null` for a free point or a non-component host mesh |
- * | `anchorTo` | {@linkcode ComponentHandle}` \| null` | Component the second endpoint is anchored to; equals `anchor` when both endpoints share a host |
- * | `storey` | `number` | Storey the dimension belongs to |
- * | `buildingId` | `string \| null` | Building it belongs to, when it has one |
- * | `isHidden` | `boolean` | The user Hide flag (what `hide` / `show` toggle) |
- * | `isVisible` | `boolean` | Whether it is actually drawn — `false` when hidden, and also when an anchor component is hidden |
- * | `isPlanProjected` | `boolean` | Whether it is drawn flattened onto the storey base (Measuring Tape dimensions drawn in 2D are; plugin-created ones never are) |
- */
-export const PluginDimensionLine = z.object({
-  id: DimensionHandle,
-  from: Vec3Components,
-  to: Vec3Components,
-  length: z.number(),
-  label: z.string(),
-  offset: Vec3Components,
-  placement: PluginDimensionPlacement,
-  anchor: ComponentHandle.nullable(),
-  anchorTo: ComponentHandle.nullable(),
-  storey: z.number(),
-  buildingId: z.string().nullable(),
-  isHidden: z.boolean(),
-  isVisible: z.boolean(),
-  isPlanProjected: z.boolean(),
-})
-export type PluginDimensionLine = z.infer<typeof PluginDimensionLine>
-
-/**
- * Result of every `design.dimensions` mutation that takes a batch
- * ({@linkcode PluginDesignDimensionsApi.delete} /
- * {@linkcode PluginDesignDimensionsApi.hide} /
- * {@linkcode PluginDesignDimensionsApi.show}) — the dimensions actually
- * affected. `hide` / `show` skip dimensions already in the target state, so
- * `affected` can be shorter than the input; `delete` echoes the whole batch.
- * Failures throw (the RPC rejects); there is no `Result<>` monad in the SDK.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `affected` | {@linkcode DimensionHandle}`[]` | The dimension lines the call changed |
- */
-export const PluginDimensionsChangeResult = z.object({
-  affected: z.array(DimensionHandle),
-})
-export type PluginDimensionsChangeResult = z.infer<
-  typeof PluginDimensionsChangeResult
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.create} (options
- * flattened).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `from` | {@linkcode Vec3Handle} | World-space first endpoint |
- * | `to` | {@linkcode Vec3Handle} | World-space second endpoint |
- * | `anchor` | {@linkcode ComponentHandle} | Component the first endpoint anchors to (required — free-point dimensions do not survive a reload) |
- * | `anchorTo` | {@linkcode ComponentHandle}? | Component for the second endpoint (default: `anchor`) |
- * | `offset` | `number`? | Signed perpendicular offset in Babylon units, positive = left of the `from` → `to` direction in plan (default `3.937` BU = 1 m) |
- *
- * TRANSPORT: positional args — validated host-side as this object.
- */
-export const PluginDesignDimensionsCreateArgs = z.object({
-  from: Vec3Handle,
-  to: Vec3Handle,
-  anchor: ComponentHandle,
-  anchorTo: ComponentHandle.optional(),
-  offset: z.number().finite().optional(),
-})
-export type PluginDesignDimensionsCreateArgs = z.infer<
-  typeof PluginDesignDimensionsCreateArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.list} (options flattened).
- * Filters combine with AND; omitting all of them lists every dimension line.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `storeys` | `number[]`? | Only dimensions on these storey numbers |
- * | `anchors` | {@linkcode ComponentHandle}`[]`? | Only dimensions anchored to these components (either endpoint) |
- * | `isHidden` | `boolean`? | user-hidden flag === |
- */
-export const PluginDesignDimensionsListArgs = z.object({
-  storeys: z.array(z.number()).optional(),
-  anchors: z.array(ComponentHandle).optional(),
-  isHidden: z.boolean().optional(),
-})
-export type PluginDesignDimensionsListArgs = z.infer<
-  typeof PluginDesignDimensionsListArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `dimension` | {@linkcode DimensionHandle} | The dimension line to read |
- */
-export const PluginDesignDimensionsGetArgs = z.object({
-  dimension: DimensionHandle,
-})
-export type PluginDesignDimensionsGetArgs = z.infer<
-  typeof PluginDesignDimensionsGetArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.delete}.
- *
- * `.min(1)` mirrors {@linkcode PluginDesignDeleteEntitiesArgs}: an empty delete
- * is a caller error, not a no-op.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to delete. Unknown handles reject the whole call (fail-fast). |
- */
-export const PluginDesignDimensionsDeleteArgs = z.object({
-  dimensions: z.array(DimensionHandle).min(1),
-})
-export type PluginDesignDimensionsDeleteArgs = z.infer<
-  typeof PluginDesignDimensionsDeleteArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.hide}. An empty array is
- * allowed and is a no-op (mirroring {@linkcode PluginDesignVisibilityHideArgs}).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to hide |
- */
-export const PluginDesignDimensionsHideArgs = z.object({
-  dimensions: z.array(DimensionHandle),
-})
-export type PluginDesignDimensionsHideArgs = z.infer<
-  typeof PluginDesignDimensionsHideArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignDimensionsApi.show}. An empty array is
- * allowed and is a no-op.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to reveal |
- */
-export const PluginDesignDimensionsShowArgs = z.object({
-  dimensions: z.array(DimensionHandle),
-})
-export type PluginDesignDimensionsShowArgs = z.infer<
-  typeof PluginDesignDimensionsShowArgs
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import {
+  ComponentHandle,
+  DimensionHandle,
+  Vec3Components,
+  Vec3Handle,
+} from "../../handles"
+
+/**
+ * Dimension lines (Measuring Tape) — the measurement annotations the Measuring
+ * Tape tool leaves in the 3D scene, NOT an entity's width/height/depth
+ * properties (for those see `design.windows.getDimensions`,
+ * `design.create.staircase`'s `dimensions`, or `design.query.measure`).
+ *
+ * A dimension line is a scene object: two endpoints anchored to the geometry
+ * they were measured on, an offset that pushes the drawn line clear of the
+ * span, and a label showing the distance in the project's units. Because the
+ * endpoints are anchored, the line follows its host when the host is moved,
+ * edited, or resized, and it is removed with the host when the host is deleted.
+ * Dimension lines are storey-scoped, render in both plan and 3D, and are drawn
+ * into Present-mode sheets (style them with
+ * `presentation.placedViews.updateStyles(shapeId, "Dimension", …)`).
+ *
+ * **Units.** Every length here — `offset` and the record's `length` — is in
+ * **Babylon units** (BU), the engine's storage unit: 1 BU = 10 in = 0.254 m.
+ * Convert with `core.units.convert(value, from, await core.units.getBabylonType())`.
+ *
+ * **Offset convention.** `options.offset` is a **signed** distance in BU:
+ * positive pushes the drawn line to the **left** of the `from` → `to`
+ * direction in plan (`cross(up, direction)`), negative to the right. It
+ * defaults to `3.937` BU (1 m). The placement mode is always `"across"` (the
+ * tape tool's perpendicular mode), which re-perpendicularises when the host
+ * geometry is edited.
+ *
+ * Every mutator here (`create`, `delete`, `hide`, `show`) commits through the
+ * engine's command manager, so each call is a single undo entry, is autosaved,
+ * and replays to collaborators.
+ *
+ * Accessed via `snaptrude.design.dimensions`.
+ */
+export abstract class PluginDesignDimensionsApi {
+  constructor() {}
+
+  /**
+   * Draw one dimension line between two world points, anchored to a component.
+   *
+   * `anchor` is **required**: the endpoints are stored relative to the anchor's
+   * mesh, and only component-anchored dimension lines survive a reload. A
+   * free-point dimension anchors to a scene helper mesh whose id is not stable
+   * across reloads, so it is dropped or corrupted when the project is reopened
+   * — the host therefore rejects a non-component anchor rather than writing a
+   * record that silently disappears. Pass `options.anchorTo` to anchor the
+   * second endpoint to a different component (it defaults to `anchor`).
+   *
+   * The dimension is created flat (never plan-projected) so the same call
+   * produces the same record whatever the current camera; it still draws in
+   * plan.
+   *
+   * @param from - World-space first endpoint.
+   * @param to - World-space second endpoint.
+   * @param anchor - The component the first endpoint is anchored to (required).
+   * @param options - `anchorTo` (component for the second endpoint; defaults to
+   *   `anchor`), `offset` (signed perpendicular offset in Babylon units,
+   *   positive = left of the `from` → `to` direction in plan; default `3.937`
+   *   BU = 1 m).
+   * @returns The new dimension line's {@linkcode DimensionHandle}.
+   * @throws `VALIDATION` for malformed arguments or a degenerate span (`from`
+   *   and `to` closer than the engine's minimum); `HANDLE_INVALID` for an
+   *   unknown `anchor` / `anchorTo`; `PRECONDITION_FAILED` when the anchor is
+   *   outside the active proposal or the editor is not mounted;
+   *   `METHOD_NOT_PERMITTED` when plugin writes are disabled.
+   *
+   * @examplePrompt Dimension every wall on level 2
+   * @examplePrompt Add a dimension line along this wall
+   * @examplePrompt Measure the width of this room and label it on the plan
+   *
+   * # Example
+   * ```ts
+   * const { design, core } = snaptrude
+   * const v = core.math.vec3
+   * const curve = core.geom.query.curve
+   * for (const wall of await design.query.listWalls({ storeys: [2] })) {
+   *   const cl = await design.query.geometry.getCenterline(wall)
+   *   if (!cl) continue
+   *   const a = await curve.getStartPoint(cl)
+   *   const b = await curve.getEndPoint(cl)
+   *   await design.dimensions.create(
+   *     await v.new(a.x, a.y, a.z),
+   *     await v.new(b.x, b.y, b.z),
+   *     wall,
+   *   )
+   * }
+   * ```
+   */
+  public abstract create(
+    from: Vec3Handle,
+    to: Vec3Handle,
+    anchor: ComponentHandle,
+    options?: { anchorTo?: ComponentHandle; offset?: number },
+  ): PluginApiReturn<DimensionHandle>
+
+  /**
+   * List the dimension lines in the project as full records.
+   *
+   * Filters combine with AND. `storeys` keeps only the dimensions on those
+   * storey numbers, `anchors` only the ones anchored to those components
+   * (matching either endpoint, and matching an instanced anchor's source mesh
+   * too), `isHidden` only the ones whose user Hide flag equals the value given.
+   *
+   * Dimension lines drawn by the Measuring Tape onto a scene helper mesh rather
+   * than a component come back with `anchor: null` and are not proposal-scoped.
+   *
+   * @param options - `storeys`, `anchors`, `isHidden` filters (all optional,
+   *   ANDed).
+   * @returns The matching {@linkcode PluginDimensionLine} records (`[]` when
+   *   nothing matches).
+   * @throws `VALIDATION` for malformed filters; `HANDLE_INVALID` for an unknown
+   *   handle in `anchors`.
+   *
+   * @examplePrompt List all the dimension lines in this model
+   * @examplePrompt Which dimensions are on level 3?
+   * @examplePrompt Flag any dimension line shorter than 600 mm
+   *
+   * @performance Array read — one host round-trip returns every record. Filter
+   *   in one call rather than calling `get` per dimension.
+   *
+   * # Example
+   * ```ts
+   * const units = snaptrude.core.units
+   * const min = await units.convert(600, "millimeters", await units.getBabylonType())
+   * const short = (await snaptrude.design.dimensions.list()).filter(
+   *   (d) => d.length < min,
+   * )
+   * console.log(short.map((d) => `${d.label} on storey ${d.storey}`))
+   * ```
+   */
+  public abstract list(options?: {
+    storeys?: number[]
+    anchors?: ComponentHandle[]
+    isHidden?: boolean
+  }): PluginApiReturn<PluginDimensionLine[]>
+
+  /**
+   * Read one dimension line by handle.
+   *
+   * Returns `null` — rather than throwing — when the dimension no longer
+   * exists, so a handle kept across a delete or an undo can be polled safely.
+   *
+   * @param dimension - The dimension line to read.
+   * @returns Its {@linkcode PluginDimensionLine} record, or `null` if it is
+   *   gone.
+   * @throws `VALIDATION` if `dimension` is not a non-empty id string.
+   *
+   * @examplePrompt Read the dimension line I just created
+   * @examplePrompt How long is this dimension and what does its label say?
+   * @examplePrompt Check whether that dimension line still exists
+   *
+   * # Example
+   * ```ts
+   * const dim = await snaptrude.design.dimensions.get(handle)
+   * if (dim) console.log(dim.label, dim.length, dim.storey)
+   * ```
+   */
+  public abstract get(
+    dimension: DimensionHandle,
+  ): PluginApiReturn<PluginDimensionLine | null>
+
+  /**
+   * Delete dimension lines — the same hard removal as selecting them and
+   * pressing Delete. Undoable as a **single** entry for the whole batch.
+   *
+   * Deleted handles are stale afterwards: {@linkcode
+   * PluginDesignDimensionsApi.get} returns `null` for them and the other
+   * mutators throw `HANDLE_INVALID`.
+   *
+   * @param dimensions - The dimension lines to delete (at least one — an empty
+   *   array is a caller error, not a no-op).
+   * @returns The dimensions that were deleted, as
+   *   {@linkcode PluginDimensionsChangeResult}.
+   * @throws `VALIDATION` for an empty or malformed array; `HANDLE_INVALID` if
+   *   any handle is unknown (the whole call rejects before anything is
+   *   deleted); `PRECONDITION_FAILED` if any dimension's anchor is outside the
+   *   active proposal; `METHOD_NOT_PERMITTED` when plugin writes are disabled.
+   *
+   * @examplePrompt Remove all dimension lines
+   * @examplePrompt Delete the dimensions on this wall
+   * @examplePrompt Clear the measurements I added to level 2
+   *
+   * @performance Array API — pass the whole set in one call (one host
+   *   round-trip, one undo entry). Never loop this per dimension.
+   *
+   * # Example
+   * ```ts
+   * const dims = snaptrude.design.dimensions
+   * const onWall = await dims.list({ anchors: [wall] })
+   * if (onWall.length > 0) await dims.delete(onWall.map((d) => d.id))
+   * ```
+   */
+  public abstract delete(
+    dimensions: DimensionHandle[],
+  ): PluginApiReturn<PluginDimensionsChangeResult>
+
+  /**
+   * Hide dimension lines from the viewport — the same as the right-click "Hide"
+   * action (it sets the user Hide flag, `isHidden`). Undoable. Already-hidden
+   * dimensions are skipped and are not reported in `affected`.
+   *
+   * @param dimensions - The dimension lines to hide.
+   * @returns The dimensions actually hidden, as
+   *   {@linkcode PluginDimensionsChangeResult} — already-hidden inputs are
+   *   omitted, so `affected` can be shorter than the input.
+   * @throws `VALIDATION` for a malformed array; `HANDLE_INVALID` if any handle
+   *   is unknown; `PRECONDITION_FAILED` if any dimension's anchor is outside
+   *   the active proposal; `METHOD_NOT_PERMITTED` when plugin writes are
+   *   disabled.
+   *
+   * @examplePrompt Hide the dimensions on this storey
+   * @examplePrompt Hide every dimension line while I present
+   * @examplePrompt Temporarily hide the measurements on level 3
+   *
+   * @performance Array API — one host round-trip and one undo entry for the
+   *   whole set.
+   *
+   * # Example
+   * ```ts
+   * const dims = snaptrude.design.dimensions
+   * const onLevel3 = await dims.list({ storeys: [3] })
+   * const { affected } = await dims.hide(onLevel3.map((d) => d.id))
+   * ```
+   */
+  public abstract hide(
+    dimensions: DimensionHandle[],
+  ): PluginApiReturn<PluginDimensionsChangeResult>
+
+  /**
+   * Reveal hidden dimension lines — clear the user Hide flag, the inverse of
+   * {@linkcode PluginDesignDimensionsApi.hide}. Undoable. Already-visible
+   * dimensions are skipped and are not reported in `affected`.
+   *
+   * Clearing the flag does not guarantee the dimension is on screen: a
+   * dimension whose anchor component is itself hidden stays off screen with
+   * `isHidden: false` and `isVisible: false`.
+   *
+   * @param dimensions - The dimension lines to reveal.
+   * @returns The dimensions actually revealed, as
+   *   {@linkcode PluginDimensionsChangeResult} — already-visible inputs are
+   *   omitted, so `affected` can be shorter than the input.
+   * @throws `VALIDATION` for a malformed array; `HANDLE_INVALID` if any handle
+   *   is unknown; `PRECONDITION_FAILED` if any dimension's anchor is outside
+   *   the active proposal; `METHOD_NOT_PERMITTED` when plugin writes are
+   *   disabled.
+   *
+   * @examplePrompt Show the dimension lines again
+   * @examplePrompt Unhide all the hidden dimensions
+   * @examplePrompt Bring back the measurements I hid on this storey
+   *
+   * @performance Array API — one host round-trip and one undo entry for the
+   *   whole set.
+   *
+   * # Example
+   * ```ts
+   * const dims = snaptrude.design.dimensions
+   * const hidden = await dims.list({ isHidden: true })
+   * await dims.show(hidden.map((d) => d.id))
+   * ```
+   */
+  public abstract show(
+    dimensions: DimensionHandle[],
+  ): PluginApiReturn<PluginDimensionsChangeResult>
+}
+
+/**
+ * How a dimension line's drawn offset is constrained.
+ *
+ * - `"across"` — perpendicular to the span (the tape tool's default, and what
+ *   every plugin-created dimension uses); re-perpendicularises when the host
+ *   geometry is edited.
+ * - `"x"` / `"y"` / `"z"` — the offset is locked to that world axis.
+ * - `"none"` — no placement mode recorded (a plain world-space offset).
+ */
+export const PluginDimensionPlacement = z.enum([
+  "across",
+  "x",
+  "y",
+  "z",
+  "none",
+])
+export type PluginDimensionPlacement = z.infer<typeof PluginDimensionPlacement>
+
+/**
+ * One dimension line (Measuring Tape annotation). Lengths are in **Babylon
+ * units** (1 BU = 0.254 m — convert with `core.units.convert`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | {@linkcode DimensionHandle} | The dimension line's handle |
+ * | `from` | {@linkcode Vec3Components} | Live world position of the first endpoint |
+ * | `to` | {@linkcode Vec3Components} | Live world position of the second endpoint |
+ * | `length` | `number` | Straight-line distance between `from` and `to`, in Babylon units |
+ * | `label` | `string` | The text drawn on the canvas, in the project's units (a bare number for metric/inch projects, `27' 7"` style for feet-inches). For a span whose x, y and z all differ the drawn line is the plan projection, so `label` reads the horizontal distance while `length` is the true 3D one |
+ * | `offset` | {@linkcode Vec3Components} | World vector from the measured span to the drawn line |
+ * | `placement` | {@linkcode PluginDimensionPlacement} | How that offset is constrained |
+ * | `anchor` | {@linkcode ComponentHandle}` \| null` | Component the first endpoint is anchored to; `null` for a free point or a non-component host mesh |
+ * | `anchorTo` | {@linkcode ComponentHandle}` \| null` | Component the second endpoint is anchored to; equals `anchor` when both endpoints share a host |
+ * | `storey` | `number` | Storey the dimension belongs to |
+ * | `buildingId` | `string \| null` | Building it belongs to, when it has one |
+ * | `isHidden` | `boolean` | The user Hide flag (what `hide` / `show` toggle) |
+ * | `isVisible` | `boolean` | Whether it is actually drawn — `false` when hidden, and also when an anchor component is hidden |
+ * | `isPlanProjected` | `boolean` | Whether it is drawn flattened onto the storey base (Measuring Tape dimensions drawn in 2D are; plugin-created ones never are) |
+ */
+export const PluginDimensionLine = z.object({
+  id: DimensionHandle,
+  from: Vec3Components,
+  to: Vec3Components,
+  length: z.number(),
+  label: z.string(),
+  offset: Vec3Components,
+  placement: PluginDimensionPlacement,
+  anchor: ComponentHandle.nullable(),
+  anchorTo: ComponentHandle.nullable(),
+  storey: z.number(),
+  buildingId: z.string().nullable(),
+  isHidden: z.boolean(),
+  isVisible: z.boolean(),
+  isPlanProjected: z.boolean(),
+})
+export type PluginDimensionLine = z.infer<typeof PluginDimensionLine>
+
+/**
+ * Result of every `design.dimensions` mutation that takes a batch
+ * ({@linkcode PluginDesignDimensionsApi.delete} /
+ * {@linkcode PluginDesignDimensionsApi.hide} /
+ * {@linkcode PluginDesignDimensionsApi.show}) — the dimensions actually
+ * affected. `hide` / `show` skip dimensions already in the target state, so
+ * `affected` can be shorter than the input; `delete` echoes the whole batch.
+ * Failures throw (the RPC rejects); there is no `Result<>` monad in the SDK.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `affected` | {@linkcode DimensionHandle}`[]` | The dimension lines the call changed |
+ */
+export const PluginDimensionsChangeResult = z.object({
+  affected: z.array(DimensionHandle),
+})
+export type PluginDimensionsChangeResult = z.infer<
+  typeof PluginDimensionsChangeResult
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.create} (options
+ * flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `from` | {@linkcode Vec3Handle} | World-space first endpoint |
+ * | `to` | {@linkcode Vec3Handle} | World-space second endpoint |
+ * | `anchor` | {@linkcode ComponentHandle} | Component the first endpoint anchors to (required — free-point dimensions do not survive a reload) |
+ * | `anchorTo` | {@linkcode ComponentHandle}? | Component for the second endpoint (default: `anchor`) |
+ * | `offset` | `number`? | Signed perpendicular offset in Babylon units, positive = left of the `from` → `to` direction in plan (default `3.937` BU = 1 m) |
+ *
+ * TRANSPORT: positional args — validated host-side as this object.
+ */
+export const PluginDesignDimensionsCreateArgs = z.object({
+  from: Vec3Handle,
+  to: Vec3Handle,
+  anchor: ComponentHandle,
+  anchorTo: ComponentHandle.optional(),
+  offset: z.number().finite().optional(),
+})
+export type PluginDesignDimensionsCreateArgs = z.infer<
+  typeof PluginDesignDimensionsCreateArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.list} (options flattened).
+ * Filters combine with AND; omitting all of them lists every dimension line.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeys` | `number[]`? | Only dimensions on these storey numbers |
+ * | `anchors` | {@linkcode ComponentHandle}`[]`? | Only dimensions anchored to these components (either endpoint) |
+ * | `isHidden` | `boolean`? | user-hidden flag === |
+ */
+export const PluginDesignDimensionsListArgs = z.object({
+  storeys: z.array(z.number()).optional(),
+  anchors: z.array(ComponentHandle).optional(),
+  isHidden: z.boolean().optional(),
+})
+export type PluginDesignDimensionsListArgs = z.infer<
+  typeof PluginDesignDimensionsListArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dimension` | {@linkcode DimensionHandle} | The dimension line to read |
+ */
+export const PluginDesignDimensionsGetArgs = z.object({
+  dimension: DimensionHandle,
+})
+export type PluginDesignDimensionsGetArgs = z.infer<
+  typeof PluginDesignDimensionsGetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.delete}.
+ *
+ * `.min(1)` mirrors {@linkcode PluginDesignDeleteEntitiesArgs}: an empty delete
+ * is a caller error, not a no-op.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to delete. Unknown handles reject the whole call (fail-fast). |
+ */
+export const PluginDesignDimensionsDeleteArgs = z.object({
+  dimensions: z.array(DimensionHandle).min(1),
+})
+export type PluginDesignDimensionsDeleteArgs = z.infer<
+  typeof PluginDesignDimensionsDeleteArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.hide}. An empty array is
+ * allowed and is a no-op (mirroring {@linkcode PluginDesignVisibilityHideArgs}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to hide |
+ */
+export const PluginDesignDimensionsHideArgs = z.object({
+  dimensions: z.array(DimensionHandle),
+})
+export type PluginDesignDimensionsHideArgs = z.infer<
+  typeof PluginDesignDimensionsHideArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignDimensionsApi.show}. An empty array is
+ * allowed and is a no-op.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dimensions` | {@linkcode DimensionHandle}`[]` | Dimension lines to reveal |
+ */
+export const PluginDesignDimensionsShowArgs = z.object({
+  dimensions: z.array(DimensionHandle),
+})
+export type PluginDesignDimensionsShowArgs = z.infer<
+  typeof PluginDesignDimensionsShowArgs
+>