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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "1.0.2-plainpoint-20261026.2",
+  "version": "1.0.2-plainpoint-20261102.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/core/camera/index.ts

@@ -30,12 +30,14 @@ export abstract class PluginCameraApi {
    * Point the camera: place its eye at `eye` looking toward `target` (world
    * coordinates, internal `babylon` units). View-state only — not undoable.
    *
+   * From a 2D plan the camera first switches to 3D (a plan's camera is pinned
+   * top-down, so an eye there would be ignored); read `getPose().mode` after.
    * While Present is open this sets the Design frame a view saved in Present
    * is taken from; it never moves the Present sheet canvas; use
    * `presentation.camera` for that.
    *
-   * @param eye - Camera position as a {@linkcode Vec3Handle}
-   * @param target - Point the camera looks at as a {@linkcode Vec3Handle}
+   * @param eye - Camera position: a {@linkcode Vec3Handle} or a plain `{ x, y, z }`
+   * @param target - Point the camera looks at: a {@linkcode Vec3Handle} or a plain `{ x, y, z }`
    * @returns `true` once the camera has been positioned.
    *
    * @examplePrompt Look at the model from above the north-east corner

package/src/api/core/storeys/index.ts

@@ -101,6 +101,11 @@ export abstract class PluginCoreStoreysApi {
    * The new storey is inserted at the position specified by `storyValue`. This
    * operation is undoable.
    *
+   * Storeys are added at the ends of the stack only. A value above the top (or below the
+   * bottom) also creates every storey in between at the default height — `create(5)` on a
+   * stack of 1–2 adds 3, 4 and 5 and returns only 5 — and a value inside a gap of the
+   * stack is refused (PRECONDITION_FAILED). Read the stack back with `list` afterwards.
+   *
    * @param storyValue - Integer storey number
    *   to create (e.g. `3` to add a third floor)
    * @param height - Optional height in Babylon

package/src/api/design/create/bulk-items.ts

@@ -38,6 +38,10 @@ export type PluginWallTopProfilePoint = z.infer<
 >
 
 /**
+ * Current hosts refuse a non-null top profile (`PRECONDITION_FAILED`, "Walls have one
+ * height: sloped or stepped tops are not supported") and create nothing; the shape is
+ * kept for compatibility. The description below is the original contract.
+ *
  * The top edge of ONE wall as a polyline over its centerline: at least two
  * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
  * straight segments between them. Two points give a single slope (a raked

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

@@ -497,10 +497,10 @@ export abstract class PluginDesignCreateApi {
    *   single undo entry. The storey must already exist
    *   (`core.storeys.create` first). Default: geometry-derived — a profile
    *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
-   * @param topProfiles - Optional top edge per curve of `profile` (same order):
-   *   a {@linkcode PluginWallTopProfile} makes that wall raked / gabled; `null`
-   *   or a missing entry keeps it flat at `height`. Straight curves only. Such
-   *   walls are non-parametric (see {@linkcode PluginWallTopProfile}).
+   * @param topProfiles - Top edge per curve of `profile` (same order). Current
+   *   hosts build walls with one height: any non-null entry is refused with
+   *   `PRECONDITION_FAILED` ("sloped or stepped tops are not supported") and
+   *   nothing is created. Pass `null` entries or omit it.
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
    *   project, `storey` does not exist, `topProfiles` has more entries than the
@@ -514,9 +514,6 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add walls with mitred corners along the path
    * @examplePrompt Draw brick walls with plaster along this outline
    * @examplePrompt Build the perimeter in exposed concrete walls
-   * @examplePrompt Create a raked wall that slopes from 3m to 5m
-   * @examplePrompt Build a gable end wall with the ridge in the middle
-   * @examplePrompt Draw a wall with a sloped top edge
    *
    * # Example
    * ```ts
@@ -532,13 +529,6 @@ export abstract class PluginDesignCreateApi {
    * const brickWalls = await snaptrude.design.create.walls(
    *   centerlines, 3, undefined, brick.label,
    * )
-   * // …a raked wall (3m at the start, 5m at the end) on a single centerline:
-   * const run = await snaptrude.core.geom.create.profileFromCurves([
-   *   await snaptrude.core.geom.create.line(await v.new(0, 0, 10), await v.new(8, 0, 10)),
-   * ])
-   * const [raked] = await snaptrude.design.create.walls(run, undefined, 0.2, undefined, undefined, [
-   *   [{ along: 0, height: 3 }, { along: 1, height: 5 }],
-   * ])
    * ```
    *
    * @performance For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one
@@ -561,8 +551,9 @@ export abstract class PluginDesignCreateApi {
    * item's profile chain, mitred at shared endpoints. Junctions resolve within a
    * run, not between runs. Each item carries its own
    * dimensions, `wallType` and `storey`, so a single call can build a whole
-   * floor plate or several storeys at once. Per-curve `topProfiles` make raked
-   * or gabled walls (see {@linkcode PluginWallTopProfile}). Validate-all-or-throw;
+   * floor plate or several storeys at once. Walls have one height: a non-null
+   * `topProfiles` entry is refused with `PRECONDITION_FAILED` (`details.itemIndex`
+   * names the item) and nothing is created. Validate-all-or-throw;
    * one command.
    *
    * @param items - One {@linkcode PluginCreateWallRunItem} per run to create
@@ -583,7 +574,6 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Bulk create wall runs from these centerlines
    * @examplePrompt Create the walls for both storeys in a single undo step
    * @examplePrompt Turn these polylines into 200mm brick walls together
-   * @examplePrompt Import these raked walls with their top profiles in one go
    *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over calling `design.create.walls` in a loop: build the
@@ -604,9 +594,6 @@ export abstract class PluginDesignCreateApi {
    * const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([
    *   { profile: ground, height: 3, thickness: 0.2 },
    *   { profile: upper, height: 3, storey: 2 },
-   *   // one gable wall: 3m at both ends, 5m ridge in the middle
-   *   { profile: upper, thickness: 0.2, storey: 3,
-   *     topProfiles: [[{ along: 0, height: 3 }, { along: 0.5, height: 5 }, { along: 1, height: 3 }]] },
    * ])
    * console.log(groundWalls.length, "walls on the ground floor")
    * ```

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

@@ -1,5 +1,5 @@
 import * as z from "zod"
-import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { ComponentHandle, Vec3Input } from "../../../handles"
 
 /**
  * The shared field bag every hosted opening (door / window) carries — used by
@@ -17,9 +17,9 @@ import { ComponentHandle, Vec3Handle } from "../../../handles"
  * | `version` | `number`? | Exact family version; newest known by default |
  * | `values` | `Record<string, number \| string>`? | Authored instance parameters; numeric lengths use Snaptrude units |
  * | `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 swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires the recipe's hand parameter |
+ * | `position` | {@linkcode Vec3Input} | World point projected onto the wall (a vec3 handle or a plain `{ x, y, z }`) |
+ * | `facing` | {@linkcode Vec3Input}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Input}? | World point near the hinged jamb; requires the recipe's hand parameter |
  * | `label` | `string`? | Instance name (optional) |
  * | `width` | `number`? | Sets the declared width parameter, not the opening's evaluated envelope |
  * | `height` | `number`? | Sets the declared height parameter |
@@ -31,9 +31,9 @@ export const PluginOpeningBaseOptions = {
     .record(z.string(), z.union([z.number().finite(), z.string()]))
     .optional(),
   hostWall: ComponentHandle,
-  position: Vec3Handle,
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
+  position: Vec3Input,
+  facing: Vec3Input.optional(),
+  hinge: Vec3Input.optional(),
   label: z.string().optional(),
   width: z.number().finite().positive().optional(),
   height: z.number().finite().positive().optional(),

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/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/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/entity/story.ts

@@ -88,6 +88,10 @@ export abstract class PluginStoryApi {
    * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
    * @throws If a story with the given value already exists or creation fails
    *
+   * Storeys are added at the ends of the stack only: a value above the top also creates
+   * every storey in between (returning only the requested one), and a value inside a gap
+   * is refused.
+   *
    * @examplePrompt Add a third floor to the building
    * @examplePrompt Create a new storey above the second floor
    * @examplePrompt Add a basement level to this project

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<

package/src/api/presentation/placedViews.ts

@@ -820,6 +820,8 @@ export const PluginViewSettingCategory = z.enum([
   "Reference Line",
   "Adjacency Line",
   "Landscape elements",
+  "Text",
+  "Annotation",
 ])
 export type PluginViewSettingCategory = z.infer<
   typeof PluginViewSettingCategory
@@ -864,6 +866,10 @@ export type PluginViewLineStyle = z.infer<typeof PluginViewLineStyle>
  * | `viewStyle` | `"NONE" \| "FILLET" \| "BUBBLE"`? | Shape restyle: block / rounded corner / bubble |
  * | `radius` | `number`? | Corner radius for `FILLET` (feet) |
  * | `inset` | `number`? | Shape inset/offset |
+ * | `textColor` | `string`? | Dimension / Text / Annotation: `#rrggbb`, or `inherit` (each text keeps its own) |
+ * | `textFontFamily` | `string`? | Text / Annotation: one font family for every text, or `inherit` |
+ * | `textFontStyle` | `"inherit" \| "Regular" \| "Bold" \| "Italic" \| "Bold Italic"`? | Text / Annotation: one font style, or `inherit` (a family without it draws Regular) |
+ * | `leaderVisible` | `boolean`? | Annotation: draw the leaders (line, landing, arrowhead) |
  */
 export const PluginPlacedViewStylePatch = z
   .object({
@@ -921,6 +927,12 @@ export const PluginPlacedViewStylePatch = z
       .regex(/^#[0-9a-fA-F]{6}$/)
       .optional(),
     textMaskPadding: z.number().finite().min(0).max(5).optional(),
+    // Text and Annotation rows: one font for every authored text, or `inherit`.
+    textFontFamily: z.string().trim().min(1).optional(),
+    textFontStyle: z
+      .enum(["inherit", "Regular", "Bold", "Italic", "Bold Italic"])
+      .optional(),
+    leaderVisible: z.boolean().optional(),
   })
   .strict()
   .refine((p) => Object.keys(p).length > 0, {