@snaptrude/plugin-core 1.0.2-plainpoint-20261026.2 → 1.0.2

package/src/api/design/dimensions.ts

@@ -5,7 +5,6 @@ import {
   DimensionHandle,
   Vec3Components,
   Vec3Handle,
-  Vec3Input,
 } from "../../handles"
 
 /**
@@ -95,8 +94,8 @@ export abstract class PluginDesignDimensionsApi {
    * ```
    */
   public abstract create(
-    from: Vec3Input,
-    to: Vec3Input,
+    from: Vec3Handle,
+    to: Vec3Handle,
     anchor: ComponentHandle,
     options?: { anchorTo?: ComponentHandle; offset?: number },
   ): PluginApiReturn<DimensionHandle>
@@ -363,8 +362,8 @@ export type PluginDimensionsChangeResult = z.infer<
  * TRANSPORT: positional args — validated host-side as this object.
  */
 export const PluginDesignDimensionsCreateArgs = z.object({
-  from: Vec3Input,
-  to: Vec3Input,
+  from: Vec3Handle,
+  to: Vec3Handle,
   anchor: ComponentHandle,
   anchorTo: ComponentHandle.optional(),
   offset: z.number().finite().optional(),

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 import { OffsetSplitOutcome } from "../shared"
 
 /**
@@ -41,7 +41,7 @@ export abstract class PluginDesignEditApi {
   public abstract offsetSplit(
     component: ComponentHandle,
     offsetDistance: number,
-    options?: { profilePickPoint?: Vec3Input },
+    options?: { profilePickPoint?: Vec3Handle },
   ): PluginApiReturn<OffsetSplitOutcome>
 }
 
@@ -49,6 +49,6 @@ export abstract class PluginDesignEditApi {
 export const PluginDesignOffsetSplitArgs = z.object({
   component: ComponentHandle,
   offsetDistance: z.number(),
-  profilePickPoint: Vec3Input.optional(),
+  profilePickPoint: Vec3Handle.optional(),
 })
 export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 
 /**
  * The erase strategies exposed to plugins. `SplitAndUnion` is *enumerable* but
@@ -38,7 +38,7 @@ export const ErasableEdgeRef = z.object({
   /** 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: Vec3Input,
+  snapPoint: Vec3Handle,
 })
 export type ErasableEdgeRef = z.infer<typeof ErasableEdgeRef>
 

package/src/api/design/family.ts

@@ -5,7 +5,6 @@ import {
   ComponentHandle,
   Vec3Components,
   Vec3Handle,
-  Vec3Input,
 } from "../../handles"
 import { NetworkFamilyContract } from "./networks"
 
@@ -1320,7 +1319,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
 export const PluginDesignFamilyPlaceArgs = z.object({
   id: z.string().optional(),
   version: z.number().int().positive().optional(),
-  position: z.union([Vec3Input, Vec3Components]).optional(),
+  position: z.union([Vec3Handle, Vec3Components]).optional(),
   rotation: z.number().optional(),
   values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   storey: z.number().int().optional(),

package/src/api/design/index.ts

@@ -15,6 +15,7 @@ import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
 import { PluginDesignDimensionsApi } from "./dimensions"
+import { PluginDesignTextApi } from "./text"
 import { PluginDesignTypesApi } from "./types"
 import { PluginDesignFamilyApi } from "./family"
 import { PluginDesignGridsApi } from "./grids"
@@ -41,6 +42,7 @@ import {
  * - {@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.text} — authored text and annotations (Text / Annotate tools): create / list / get / update / setLeader
  * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
  * - {@linkcode PluginDesignApi.family} — author parametric families from a JSON spec
  * - {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock} / {@linkcode PluginDesignApi.isLocked} / {@linkcode PluginDesignApi.listLocked} — lock state (top-level design verbs, §2A.1)
@@ -79,6 +81,8 @@ export abstract class PluginDesignApi {
   public abstract visibility: PluginDesignVisibilityApi
   /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
   public abstract dimensions: PluginDesignDimensionsApi
+  /** Authored text and annotations (Text / Annotate tools). See {@linkcode PluginDesignTextApi}. */
+  public abstract text: PluginDesignTextApi
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
   /** Author parametric families from a JSON spec. See {@linkcode PluginDesignFamilyApi}. */
@@ -296,6 +300,7 @@ export * from "./edit"
 export * from "./update"
 export * from "./visibility"
 export * from "./dimensions"
+export * from "./text"
 export * from "./types"
 export * from "./family"
 export * from "./grids"

package/src/api/design/lock.ts

@@ -9,12 +9,6 @@ import { ComponentHandle } from "../../handles"
  */
 export const PluginDesignChangeResult = z.object({
   affected: z.array(ComponentHandle),
-  /** Derived BIM (walls/floors/slabs) the parametric engine removed with its host. Delete only. */
-  cascaded: z.array(ComponentHandle).optional(),
-  /** Handles that no longer resolved when the call ran and were skipped. Delete only. */
-  missing: z.array(ComponentHandle).optional(),
-  /** Handles the engine accepted but left standing; delete them again or report them. Delete only. */
-  rejected: z.array(ComponentHandle).optional(),
 })
 export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
 

package/src/api/design/text.ts

@@ -0,0 +1,394 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle, Vec3Components, Vec3Handle } from "../../handles"
+
+/**
+ * Authored text — what the Text and Annotate tools place on a drawing.
+ *
+ * A text is a single line of words drawn flat in its drawing: a **plain text**
+ * is centred on its position; an **annotation** is the same text with a leader,
+ * a line from an arrowhead (the point it labels) to the text's position, then a
+ * short landing to where the words start. Texts are scene components, so their
+ * id is a {@linkcode ComponentHandle} and the generic component APIs work on
+ * them:
+ *
+ * - delete: `design.delete.entities`
+ * - move / rotate / mirror: `design.transform.*` (the leader travels with the text)
+ * - copy: `design.create.copy`
+ * - hide / show / isolate: `design.visibility.*`
+ * - lock / unlock: `design.lock` / `design.unlock`
+ * - select: `design.selection.*`
+ *
+ * **Where a text lives.** Plan text belongs to one storey and is drawn only in
+ * that storey's plan (never in 3D). Text placed while a section or elevation is
+ * open belongs to that drawing and is drawn only there. The record's `drawing`
+ * and `drawingId` say which.
+ *
+ * **Size and pens.** A text has no size of its own: every text draws at the
+ * project's Text size (Object Styles → Text, `presentation.standards`
+ * `annotation.Text.textMm`, paper mm) at the active view scale, and the leader
+ * draws with the Text category's projection pen
+ * (`presentation.graphics` / `presentation.standards` `objectStyles.Text`).
+ * Present sheets restyle all texts of a placed view at once through the
+ * `"Text"` and `"Annotation"` categories of
+ * `presentation.placedViews.updateStyles` (colour, font, leader visibility).
+ *
+ * **Fonts.** `fontFamily` is a Google Fonts family (`"Inter"`, `"Roboto"`,
+ * `"Open Sans"`, …) or one of the built-ins `"Arial"`, `"Helvetica"`,
+ * `"Times New Roman"`, `"Courier New"`, matched case-insensitively and stored
+ * in its canonical spelling; an unknown family is refused (`VALIDATION`). A
+ * font style the family does not have falls back to `"Regular"`, as in the
+ * Properties panel, so read back the style that applied.
+ *
+ * **Units.** Positions are world points in Babylon units (1 BU = 0.254 m).
+ *
+ * Every mutator here commits through the engine's command manager: one undo
+ * entry per call, autosaved, replayed to collaborators.
+ *
+ * Accessed via `snaptrude.design.text`.
+ */
+export abstract class PluginDesignTextApi {
+  constructor() {}
+
+  /**
+   * Place a text, or an annotation when `options.arrowhead` is given.
+   *
+   * Where it goes:
+   * - `options.storey` given → plan text on that storey, at its floor level
+   *   (the `y` of `position` is ignored).
+   * - otherwise, with a section or elevation open on the canvas → that
+   *   drawing; `position` (and `arrowhead`) are projected onto its plane.
+   * - otherwise → plan text on the active storey.
+   *
+   * The text is created unrotated (it reads along +X in plan); rotate it with
+   * `design.transform.rotate`. The font style falls back to `"Regular"` when the
+   * family has no such style.
+   *
+   * @param position - World point the text is placed at: the centre of a plain
+   *   text, or the leader's text end (where the landing starts) of an
+   *   annotation.
+   * @param content - The words, one line (no line breaks), not blank.
+   * @param options - `arrowhead` (world point the leader points at; makes an
+   *   annotation), `color` (`#rrggbb`, default `#000000`), `fontFamily`
+   *   (see **Fonts** above, default `"Inter"`), `fontStyle` (default
+   *   `"Regular"`), `storey` (plan text on this storey).
+   * @returns The new text's {@linkcode ComponentHandle}.
+   * @throws `VALIDATION` for malformed arguments, blank or multi-line
+   *   `content`, an unknown `fontFamily`, or an `arrowhead` on top of
+   *   `position`; `PRECONDITION_FAILED`
+   *   when `storey` does not exist or the editor is not mounted;
+   *   `METHOD_NOT_PERMITTED` when plugin writes are disabled.
+   *
+   * @examplePrompt Label the living room "LIVING" on the plan
+   * @examplePrompt Add an annotation pointing at this column saying "RCC 300x300"
+   * @examplePrompt Write "NORTH ENTRY" in red bold text at the entrance on level 2
+   *
+   * # Example
+   * ```ts
+   * const { design, core } = snaptrude
+   * const v = core.math.vec3
+   * // A plain label on storey 1.
+   * await design.text.create(await v.new(10, 0, 20), "LIVING", { storey: 1 })
+   * // An annotation whose leader points at a wall corner.
+   * await design.text.create(await v.new(30, 0, 40), "Shear wall", {
+   *   arrowhead: await v.new(22, 0, 32),
+   *   color: "#c62828",
+   *   fontStyle: "Bold",
+   * })
+   * ```
+   */
+  public abstract create(
+    position: Vec3Handle,
+    content: string,
+    options?: {
+      arrowhead?: Vec3Handle
+      color?: string
+      fontFamily?: string
+      fontStyle?: PluginTextFontStyle
+      storey?: number
+    },
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * List the texts and annotations of every building in the active design
+   * option as full records (each carries its `buildingId`).
+   *
+   * Filters combine with AND: `storeys` keeps texts on those storeys (plan
+   * text, and texts of a section or elevation, carry the storey they were
+   * placed from), `kind` keeps only plain texts or only annotations,
+   * `isHidden` only the ones whose user Hide flag equals the value given.
+   *
+   * @param options - `storeys`, `kind`, `isHidden` filters (all optional,
+   *   ANDed).
+   * @returns The matching {@linkcode PluginText} records (`[]` when nothing
+   *   matches).
+   * @throws `VALIDATION` for malformed filters.
+   *
+   * @examplePrompt List all the text labels on level 1
+   * @examplePrompt Which annotations are in this model?
+   * @examplePrompt Find the text that says "LOBBY"
+   *
+   * @performance Array read — one host round-trip returns every record.
+   *   Filter in one call rather than calling `get` per text.
+   *
+   * # Example
+   * ```ts
+   * const texts = await snaptrude.design.text.list({ storeys: [1] })
+   * const lobby = texts.find((t) => t.content === "LOBBY")
+   * ```
+   */
+  public abstract list(options?: {
+    storeys?: number[]
+    kind?: PluginTextKind
+    isHidden?: boolean
+  }): PluginApiReturn<PluginText[]>
+
+  /**
+   * Read one text by handle.
+   *
+   * Returns `null` — rather than throwing — when the id is not a live text
+   * (deleted, undone, or another kind of component), so a handle kept across a
+   * delete or an undo can be polled safely.
+   *
+   * @param text - The text to read.
+   * @returns Its {@linkcode PluginText} record, or `null`.
+   * @throws `VALIDATION` if `text` is not a non-empty id string.
+   *
+   * @examplePrompt What does this text say?
+   * @examplePrompt Read the annotation I just placed
+   *
+   * # Example
+   * ```ts
+   * const t = await snaptrude.design.text.get(handle)
+   * if (t?.leader) console.log(t.content, "points at", t.leader.arrowhead)
+   * ```
+   */
+  public abstract get(text: ComponentHandle): PluginApiReturn<PluginText | null>
+
+  /**
+   * Change the words, colour or font of one or more texts — the same edit as
+   * the Properties panel. Fields left out keep each text's own value. A font
+   * style the (new) family does not have falls back to `"Regular"`, as in the
+   * panel. One undo entry for the whole batch.
+   *
+   * @param texts - The texts to change (at least one).
+   * @param patch - `content`, `color`, `fontFamily`, `fontStyle` (at least
+   *   one).
+   * @returns The texts that actually changed, as
+   *   {@linkcode PluginTextChangeResult} — texts already matching the patch
+   *   are omitted.
+   * @throws `VALIDATION` for malformed arguments, blank / multi-line
+   *   `content` or an unknown `fontFamily`; `HANDLE_INVALID` if any handle
+   *   is not a live text (the whole call rejects before anything changes);
+   *   `PRECONDITION_FAILED` if any text is locked or outside the active
+   *   design option; `METHOD_NOT_PERMITTED`
+   *   when plugin writes are disabled.
+   *
+   * @examplePrompt Make all the room labels bold
+   * @examplePrompt Change this annotation to read "Fire exit"
+   * @examplePrompt Use Roboto in blue for every text on level 2
+   *
+   * @performance Array API — pass the whole set in one call (one host
+   *   round-trip, one undo entry). Never loop this per text.
+   *
+   * # Example
+   * ```ts
+   * const text = snaptrude.design.text
+   * const level2 = await text.list({ storeys: [2] })
+   * await text.update(level2.map((t) => t.id), { fontFamily: "Roboto", color: "#1565c0" })
+   * ```
+   */
+  public abstract update(
+    texts: ComponentHandle[],
+    patch: PluginTextPatch,
+  ): PluginApiReturn<PluginTextChangeResult>
+
+  /**
+   * Point a text's leader at a new place — the same edit as dragging an
+   * annotation's arrowhead with the Edit tool. Passing `null` removes the
+   * leader (the annotation becomes a plain text); giving a plain text an
+   * arrowhead turns it into an annotation. The text itself does not move. To
+   * move the text while its arrowhead stays put, move it with
+   * `design.transform.move`, then call this with the old `leader.arrowhead`.
+   *
+   * @param text - The text to change.
+   * @param arrowhead - World point the leader points at (projected onto the
+   *   text's drawing plane), or `null` to remove the leader.
+   * @returns The updated {@linkcode PluginText} record.
+   * @throws `VALIDATION` for malformed arguments or an arrowhead on top of the
+   *   text's position; `HANDLE_INVALID` if `text` is not a live text;
+   *   `PRECONDITION_FAILED` if it is locked or outside the active design
+   *   option; `METHOD_NOT_PERMITTED` when plugin writes are disabled.
+   *
+   * @examplePrompt Point this annotation at the door instead
+   * @examplePrompt Remove the leader from this label
+   *
+   * # Example
+   * ```ts
+   * const { design, core } = snaptrude
+   * await design.text.setLeader(handle, await core.math.vec3.new(12, 0, 8))
+   * ```
+   */
+  public abstract setLeader(
+    text: ComponentHandle,
+    arrowhead: Vec3Handle | null,
+  ): PluginApiReturn<PluginText>
+}
+
+/** The four font styles a text can use (the Properties panel's Style list). */
+export const PluginTextFontStyle = z.enum([
+  "Regular",
+  "Bold",
+  "Italic",
+  "Bold Italic",
+])
+export type PluginTextFontStyle = z.infer<typeof PluginTextFontStyle>
+
+/** `"text"` — a plain text; `"annotation"` — a text with a leader. */
+export const PluginTextKind = z.enum(["text", "annotation"])
+export type PluginTextKind = z.infer<typeof PluginTextKind>
+
+/**
+ * The drawing a text belongs to: `"plan"` (its storey's plan), `"section"`,
+ * `"elevation"`, or `"view"` (a saved 2D view).
+ */
+export const PluginTextDrawing = z.enum(["plan", "section", "elevation", "view"])
+export type PluginTextDrawing = z.infer<typeof PluginTextDrawing>
+
+const TextContent = z
+  .string()
+  .refine((s) => s.trim().length > 0, { message: "content must not be blank" })
+  .refine((s) => !/[\r\n]/.test(s), {
+    message: "content must be one line (no line breaks)",
+  })
+const TextColor = z
+  .string()
+  .regex(/^#[0-9a-fA-F]{6}$/, "color must be a #rrggbb hex color")
+const TextFontFamily = z
+  .string()
+  .refine((s) => s.trim().length > 0, { message: "fontFamily must not be blank" })
+
+/**
+ * One text or annotation. Positions are world points in Babylon units.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | {@linkcode ComponentHandle} | The text's handle |
+ * | `kind` | {@linkcode PluginTextKind} | `"text"` or `"annotation"` (has a leader) |
+ * | `content` | `string` | The words |
+ * | `color` | `string` | `#rrggbb` |
+ * | `fontFamily` | `string` | Font family |
+ * | `fontStyle` | {@linkcode PluginTextFontStyle} | Font style |
+ * | `position` | {@linkcode Vec3Components} | Centre of a plain text; the leader's text end of an annotation |
+ * | `rotation` | `number` | Rotation in its drawing in degrees, positive clockwise as seen on screen — in plan, the sense a positive `design.transform.rotate` angle turns it (0 = reads along +X) |
+ * | `leader` | `{ arrowhead: Vec3Components } \| null` | Where the leader points; `null` for plain text |
+ * | `storey` | `number` | Storey it belongs to |
+ * | `buildingId` | `string \| null` | Building it belongs to |
+ * | `drawing` | {@linkcode PluginTextDrawing} | The drawing it is drawn in |
+ * | `drawingId` | `string \| null` | The section id, elevation preset or view id; `null` for plan text |
+ * | `isHidden` | `boolean` | The user Hide flag (`design.visibility.hide` / `show`) |
+ * | `isLocked` | `boolean` | Locked against edits — its own lock (`design.lock` / `unlock`) or a locked group or design option, as `design.isLocked` reports |
+ */
+export const PluginText = z.object({
+  id: ComponentHandle,
+  kind: PluginTextKind,
+  content: z.string(),
+  color: z.string(),
+  fontFamily: z.string(),
+  fontStyle: PluginTextFontStyle,
+  position: Vec3Components,
+  rotation: z.number(),
+  leader: z.object({ arrowhead: Vec3Components }).nullable(),
+  storey: z.number(),
+  buildingId: z.string().nullable(),
+  drawing: PluginTextDrawing,
+  drawingId: z.string().nullable(),
+  isHidden: z.boolean(),
+  isLocked: z.boolean(),
+})
+export type PluginText = z.infer<typeof PluginText>
+
+/**
+ * A sparse edit for {@linkcode PluginDesignTextApi.update} — at least one
+ * field.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `content` | `string`? | New words (one line, not blank) |
+ * | `color` | `string`? | `#rrggbb` |
+ * | `fontFamily` | `string`? | Google Fonts family (`"Inter"`, `"Roboto"`, …) or `"Arial"` / `"Helvetica"` / `"Times New Roman"` / `"Courier New"` |
+ * | `fontStyle` | {@linkcode PluginTextFontStyle}? | Falls back to `"Regular"` when the family lacks it |
+ */
+export const PluginTextPatch = z
+  .object({
+    content: TextContent.optional(),
+    color: TextColor.optional(),
+    fontFamily: TextFontFamily.optional(),
+    fontStyle: PluginTextFontStyle.optional(),
+  })
+  .strict()
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one field",
+  })
+export type PluginTextPatch = z.infer<typeof PluginTextPatch>
+
+/**
+ * Result of {@linkcode PluginDesignTextApi.update}: the texts the call
+ * changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `affected` | {@linkcode ComponentHandle}`[]` | The texts the call changed |
+ */
+export const PluginTextChangeResult = z.object({
+  affected: z.array(ComponentHandle),
+})
+export type PluginTextChangeResult = z.infer<typeof PluginTextChangeResult>
+
+/**
+ * Arguments for {@linkcode PluginDesignTextApi.create} (options flattened).
+ *
+ * TRANSPORT: positional args — validated host-side as this object.
+ */
+export const PluginDesignTextCreateArgs = z.object({
+  position: Vec3Handle,
+  content: TextContent,
+  arrowhead: Vec3Handle.optional(),
+  color: TextColor.optional(),
+  fontFamily: TextFontFamily.optional(),
+  fontStyle: PluginTextFontStyle.optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginDesignTextCreateArgs = z.infer<
+  typeof PluginDesignTextCreateArgs
+>
+
+/** Arguments for {@linkcode PluginDesignTextApi.list} (options flattened). */
+export const PluginDesignTextListArgs = z.object({
+  storeys: z.array(z.number()).optional(),
+  kind: PluginTextKind.optional(),
+  isHidden: z.boolean().optional(),
+})
+export type PluginDesignTextListArgs = z.infer<typeof PluginDesignTextListArgs>
+
+/** Arguments for {@linkcode PluginDesignTextApi.get}. */
+export const PluginDesignTextGetArgs = z.object({ text: ComponentHandle })
+export type PluginDesignTextGetArgs = z.infer<typeof PluginDesignTextGetArgs>
+
+/** Arguments for {@linkcode PluginDesignTextApi.update}. */
+export const PluginDesignTextUpdateArgs = z.object({
+  texts: z.array(ComponentHandle).min(1),
+  patch: PluginTextPatch,
+})
+export type PluginDesignTextUpdateArgs = z.infer<
+  typeof PluginDesignTextUpdateArgs
+>
+
+/** Arguments for {@linkcode PluginDesignTextApi.setLeader}. */
+export const PluginDesignTextSetLeaderArgs = z.object({
+  text: ComponentHandle,
+  arrowhead: Vec3Handle.nullable(),
+})
+export type PluginDesignTextSetLeaderArgs = z.infer<
+  typeof PluginDesignTextSetLeaderArgs
+>

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Handle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 
 /**
@@ -22,17 +22,9 @@ export abstract class PluginDesignTransformApi {
    * component's absolute position as the anchor). Undoable.
    *
    * @param components - Entities to move
-   * @param displacement - Relative translation as a {@linkcode Vec3Handle}. A displacement
-   *   shorter than 1e-6 is a no-op that succeeds (hosts before Oct 2026 throw
-   *   `OPERATION_FAILED` "No movement occurred" instead, so skip the call when nothing moves).
+   * @param displacement - Relative translation as a {@linkcode Vec3Handle}
    * @param options - `is2D`, `trackParentChange`
    * @returns {@linkcode PluginDesignChangeResult}
-   * @throws `OPERATION_FAILED` when the engine drops the whole move. A single connected
-   *   parametric wall moves only across its own line: the vertical part and the part along
-   *   the line are dropped. Move the whole connected run in one call to lift walls; to slide
-   *   or lengthen one wall, delete it and create it again on the new line. Graph-bound walls
-   *   made by Sketch-to-BIM refuse `move` outright (`TOPOLOGY_ERROR` / `ZERO_MOVEMENT`):
-   *   adjust the room boundary that owns the wall instead.
    *
    * @examplePrompt Move the selected room 5 metres to the right
    * @examplePrompt Shift these walls 3m along the x axis
@@ -51,7 +43,7 @@ export abstract class PluginDesignTransformApi {
    */
   public abstract move(
     components: ComponentHandle[],
-    displacement: Vec3Input,
+    displacement: Vec3Handle,
     options?: { is2D?: boolean; trackParentChange?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
@@ -89,7 +81,7 @@ export abstract class PluginDesignTransformApi {
   public abstract rotate(
     components: ComponentHandle[],
     angleInDegrees: number,
-    options?: { axis?: Vec3Input; pivot?: Vec3Input; is2D?: boolean },
+    options?: { axis?: Vec3Handle; pivot?: Vec3Handle; is2D?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -213,7 +205,7 @@ export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
  */
 export const PluginDesignMoveArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Input,
+  displacement: Vec3Handle,
   is2D: z.boolean().optional(),
   trackParentChange: z.boolean().optional(),
 })
@@ -225,9 +217,9 @@ export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
 export const PluginDesignRotateArgs = z.object({
   components: z.array(ComponentHandle).min(1),
   angleInDegrees: z.number(),
-  axis: Vec3Input.optional(),
+  axis: Vec3Handle.optional(),
   is2D: z.boolean().optional(),
-  pivot: Vec3Input.optional(),
+  pivot: Vec3Handle.optional(),
 })
 export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>
 

package/src/api/entity/space.ts

@@ -6,7 +6,6 @@ import * as z from "zod"
 import {
   ProfileHandle,
   Vec3Handle,
-  Vec3Input,
   Vec3Components,
   QuatComponents,
   CurveHandle,
@@ -22,7 +21,7 @@ import {
  * | `dimensions` | `{ width, height, depth }` | Box dimensions in Babylon units |
  */
 export const PluginSpaceCreateRectangularArgs = z.object({
-  position: Vec3Input,
+  position: Vec3Handle,
   dimensions: z.object({
     width: z.number(),
     height: z.number(),
@@ -63,7 +62,7 @@ export const PluginSpaceCreateFromProfileArgs = z.object({
   profile: ProfileHandle,
   innerProfiles: z.array(ProfileHandle).optional(),
   extrudeHeight: z.number(),
-  position: Vec3Input,
+  position: Vec3Handle,
 })
 
 export type PluginSpaceCreateFromProfileArgs = z.infer<
@@ -467,7 +466,7 @@ export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>
 export const PluginSpaceBulkCreateItem = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("rectangular"),
-    position: Vec3Input,
+    position: Vec3Handle,
     dimensions: z.object({
       width: z.number(),
       height: z.number(),
@@ -483,7 +482,7 @@ export const PluginSpaceBulkCreateItem = z.discriminatedUnion("kind", [
     profile: ProfileHandle,
     innerProfiles: z.array(ProfileHandle).optional(),
     extrudeHeight: z.number(),
-    position: Vec3Input,
+    position: Vec3Handle,
     room_type: z.string().optional(),
     spaceType: PluginSpaceType.optional(),
     massType: PluginMassType.optional(),

package/src/api/presentation/graphics.ts

@@ -41,17 +41,20 @@ export const PluginGraphicsModelCategory = z.enum([
   "Walls",
   "Windows",
 ])
+/** Text is authored text and annotations; its projection pen draws their leader lines. */
 export const PluginGraphicsAnnotationCategory = z.enum([
   "Dimension",
   "Grids",
   "Sections",
+  "Text",
 ])
 export const PluginGraphicsCategory = z.enum([
   ...PluginGraphicsModelCategory.options,
   ...PluginGraphicsAnnotationCategory.options,
 ])
+/** Text has no view override: its meshes are not hidden or halftoned by category. */
 export const PluginGraphicsOverrideCategory = z.enum([
-  ...PluginGraphicsCategory.options,
+  ...PluginGraphicsCategory.exclude(["Text"]).options,
   "Lines",
 ])
 export type PluginGraphicsOverrideCategory = z.infer<