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

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 } from "../../../handles"
+import { ComponentHandle, Vec3Handle, Vec3Input } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 
 /**
@@ -22,9 +22,17 @@ 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}
+   * @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 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
@@ -43,7 +51,7 @@ export abstract class PluginDesignTransformApi {
    */
   public abstract move(
     components: ComponentHandle[],
-    displacement: Vec3Handle,
+    displacement: Vec3Input,
     options?: { is2D?: boolean; trackParentChange?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
@@ -81,7 +89,7 @@ export abstract class PluginDesignTransformApi {
   public abstract rotate(
     components: ComponentHandle[],
     angleInDegrees: number,
-    options?: { axis?: Vec3Handle; pivot?: Vec3Handle; is2D?: boolean },
+    options?: { axis?: Vec3Input; pivot?: Vec3Input; is2D?: boolean },
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -205,7 +213,7 @@ export type PluginAlignEdge = z.infer<typeof PluginAlignEdge>
  */
 export const PluginDesignMoveArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Handle,
+  displacement: Vec3Input,
   is2D: z.boolean().optional(),
   trackParentChange: z.boolean().optional(),
 })
@@ -217,9 +225,9 @@ export type PluginDesignMoveArgs = z.infer<typeof PluginDesignMoveArgs>
 export const PluginDesignRotateArgs = z.object({
   components: z.array(ComponentHandle).min(1),
   angleInDegrees: z.number(),
-  axis: Vec3Handle.optional(),
+  axis: Vec3Input.optional(),
   is2D: z.boolean().optional(),
-  pivot: Vec3Handle.optional(),
+  pivot: Vec3Input.optional(),
 })
 export type PluginDesignRotateArgs = z.infer<typeof PluginDesignRotateArgs>
 

package/src/api/entity/space.ts

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

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, {

package/src/api/presentation/standards.ts

@@ -82,6 +82,7 @@ const StoredText = z
       })
       .strict()
       .optional(),
+    Text: z.object({ textMm: TextSize.optional() }).strict().optional(),
   })
   .strict()
 const StoredDimension = z
@@ -226,6 +227,10 @@ export const PluginGraphicStandardPatch = z
           })
           .strict()
           .optional(),
+        Text: z
+          .object({ textMm: TextSize.nullable().optional() })
+          .strict()
+          .optional(),
       })
       .strict()
       .optional(),
@@ -329,6 +334,7 @@ export const PluginResolvedGraphicStandard = z.object({
     gridBubbleRadiusMm: HeadRadius,
     sectionTextMm: TextSize,
     sectionHeadRadiusMm: HeadRadius,
+    annotationMm: TextSize,
   }),
   dimension: z.object({
     tickMm: TickLength,

package/src/api/presentation/views.ts

@@ -522,8 +522,13 @@ export type PluginPresentationViewsCreateArgs = z.infer<
   typeof PluginPresentationViewsCreateArgs
 >
 
-/** Result of {@linkcode PluginPresentationViewsApi.create} — the saved view. */
-export const PluginPresentationViewsCreateResult = PluginPresentationView
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.create} — the saved view, plus `framed`:
+ * whether the view was framed on the given elements or bounds (always `false` without `frame`).
+ */
+export const PluginPresentationViewsCreateResult = PluginPresentationView.extend({
+  framed: z.boolean().optional(),
+})
 export type PluginPresentationViewsCreateResult = z.infer<
   typeof PluginPresentationViewsCreateResult
 >

package/src/handles.ts

@@ -288,6 +288,17 @@ export const EdgeHandle = handleSchema("edge")
 export const HalfEdgeHandle = handleSchema("halfedge")
 export const VertexHandle = handleSchema("vertex")
 export const Vec3Components = z.object({ x: z.number(), y: z.number(), z: z.number() })
+/**
+ * A vec3 ARGUMENT: a {@linkcode Vec3Handle} in any inbound form, or a plain finite
+ * `{ x, y, z }` point. Geometry reads return plain points, and callers pass them straight
+ * back where a vec3 is expected; the host resolves the point as a vector. Returns stay
+ * {@linkcode Vec3Handle}. Explicitly typed to keep handles.d.ts inside its size budget.
+ */
+export type Vec3Input = Handle<"vec3"> | Vec3Components
+export const Vec3Input: z.ZodUnion<readonly [typeof Vec3Handle, typeof Vec3Components]> = z.union(
+  [Vec3Handle, Vec3Components],
+  { error: 'expected a "vec3" handle or a plain { x, y, z } point' }
+)
 export const QuatComponents = z.object({
   x: z.number(),
   y: z.number(),