@snaptrude/plugin-core 0.9.6 → 0.9.7

package/src/api/design/create/opening-fields.ts

@@ -0,0 +1,29 @@
+import * as z from "zod"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+
+/**
+ * The shared field bag every hosted opening (door / window) carries — used by
+ * {@linkcode PluginDesignCreateOpeningOptions} and by the bulk item schemas in
+ * `bulk-items.ts`, so singular and plural openings validate identically.
+ *
+ * `facing` is a WORLD POINT on the desired side of the wall, not a direction.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the opening |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the opening faces (default engine-chosen) |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
+ * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ */
+export const PluginOpeningBaseOptions = {
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  facing: Vec3Handle.optional(),
+  label: z.string().optional(),
+  width: z.number().finite().positive().optional(),
+  height: z.number().finite().positive().optional(),
+}

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

@@ -39,6 +39,10 @@ export abstract class PluginDesignDeleteApi {
    * children are removed and linked-list neighbours are fixed up — not caller-tunable
    * in v1. Undoable — commits as a **single** undo entry.
    *
+   * Dimension lines anchored to a deleted entity are removed with it, in the same undo
+   * entry, exactly as the editor's Delete key does — see `design.dimensions`. They are
+   * NOT listed in `affected`, which reports component handles only.
+   *
    * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
    * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
    *   (echoed host-side from the resolved+deleted set — the engine returns no ids).

package/src/api/design/dimensions.ts

@@ -0,0 +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
+>

package/src/api/design/index.ts

@@ -14,6 +14,7 @@ import { PluginDesignTransformApi } from "./transform"
 import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
+import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
 import { PluginDesignChangeResult } from "./lock"
 
@@ -30,6 +31,7 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
  * - {@linkcode PluginDesignApi.visibility} — hide / isolate / reveal entities
+ * - {@linkcode PluginDesignApi.dimensions} — dimension lines (Measuring Tape): create / list / delete / hide
  * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
  * - {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock} / {@linkcode PluginDesignApi.isLocked} / {@linkcode PluginDesignApi.listLocked} — lock state (top-level design verbs, §2A.1)
  * - {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea} / {@linkcode PluginDesignApi.isAreaLocked} / {@linkcode PluginDesignApi.listAreaLocked} — footprint-area lock for Room/Department spaces
@@ -65,6 +67,8 @@ export abstract class PluginDesignApi {
   public abstract update: PluginDesignUpdateApi
   /** Hide / isolate / reveal entities. See {@linkcode PluginDesignVisibilityApi}. */
   public abstract visibility: PluginDesignVisibilityApi
+  /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
+  public abstract dimensions: PluginDesignDimensionsApi
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
 
@@ -256,4 +260,5 @@ export * from "./transform"
 export * from "./edit"
 export * from "./update"
 export * from "./visibility"
+export * from "./dimensions"
 export * from "./types"

package/src/handles.ts

@@ -115,6 +115,19 @@ export type UnderlayHandle = EntityId<"underlay">
  */
 export type TerrainHandle = EntityId<"terrain">
 
+/**
+ * A **dimension line** — one measurement annotation left behind by the Measuring
+ * Tape tool (NOT a width/height/depth property; see `design.dimensions`).
+ * Entity-style: the token IS the raw engine dimension id (`dim_…`), resolved live
+ * host-side from the dimension-line registry (`getDimensionLineMap()`) — not via
+ * `ComponentUtility.FindComponentById`, which does not index dimension lines (a
+ * dimension line is not a Component). No arena, no quota, stable across
+ * undo/redo and across reloads (the record persists with the project). Returned
+ * by `design.dimensions.create` and consumed by every other
+ * `design.dimensions.*` method.
+ */
+export type DimensionHandle = EntityId<"dimension">
+
 /**
  * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
  * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
@@ -233,6 +246,17 @@ export const ImportJobHandle = z
   .min(1)
   .transform((s) => s as ImportJobHandle)
 
+/**
+ * {@linkcode DimensionHandle} is an entity-style handle — the raw `dim_…` engine
+ * id, validated only as a non-empty string (no `"<kind>_"` prefix enforcement),
+ * resolved live host-side against the dimension-line registry (existence
+ * enforced there, as `HANDLE_INVALID`).
+ */
+export const DimensionHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as DimensionHandle)
+
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")