@snaptrude/plugin-core 0.0.0-dev-20260911064951 → 0.0.0-dev-20260921132444

package/src/api/design/grids.ts

@@ -0,0 +1,237 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginGridStyleOptions } from "./create/grids"
+
+/**
+ * Tag policy for structural line removal (mirrors the engine
+ * `GridLineTagPolicy` values verbatim): `"rewrite"` renumbers each affected
+ * wing's tag sequence after removal; `"preserve"` keeps the surviving lines'
+ * tags unchanged.
+ */
+export const PluginGridLineTagPolicy = z.enum(["rewrite", "preserve"])
+export type PluginGridLineTagPolicy = z.infer<typeof PluginGridLineTagPolicy>
+
+/** A positional grid-line address — indices into `design.query.grids.get`'s `wings` arrays. */
+export const PluginGridLineAddress = z.object({
+  wing: z.number().int().nonnegative(),
+  line: z.number().int().nonnegative(),
+})
+export type PluginGridLineAddress = z.infer<typeof PluginGridLineAddress>
+
+/**
+ * One per-wing entry of {@linkcode PluginDesignGridsApi.updateWings} —
+ * addressed by wing index. `spanMin`/`spanMax` move the family's length
+ * handles (Snaptrude units).
+ */
+export const PluginGridWingEntry = z.object({
+  wing: z.number().int().nonnegative(),
+  spacing: z.number().positive().finite().optional(),
+  count: z.number().int().min(1).optional(),
+  spanMin: z.number().finite().optional(),
+  spanMax: z.number().finite().optional(),
+})
+export type PluginGridWingEntry = z.infer<typeof PluginGridWingEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateWings}. */
+export const PluginDesignGridsUpdateWingsArgs = z.object({
+  grid: ComponentHandle,
+  wings: z.array(PluginGridWingEntry).min(1),
+})
+export type PluginDesignGridsUpdateWingsArgs = z.infer<
+  typeof PluginDesignGridsUpdateWingsArgs
+>
+
+/**
+ * One per-line entry of {@linkcode PluginDesignGridsApi.updateLines} —
+ * addressed positionally by `{ wing, line }` indices (invalidated by
+ * structural edits; re-query after mutating). `distanceToPrevious` /
+ * `distanceToNext` set the typed distance to the adjacent line on that side
+ * and are mutually exclusive.
+ *
+ * `visible` is **hide-only** (`false`), mirroring the product: per-line show
+ * does not exist — showing the GROUP (`design.visibility.show`) restores all
+ * of its lines, exactly like the native Show All.
+ */
+export const PluginGridLineEntry = z
+  .object({
+    wing: z.number().int().nonnegative(),
+    line: z.number().int().nonnegative(),
+    tag: z.string().min(1).optional(),
+    distanceToPrevious: z.number().positive().finite().optional(),
+    distanceToNext: z.number().positive().finite().optional(),
+    props: PluginGridStyleOptions.optional(),
+    visible: z.literal(false).optional(),
+  })
+  .superRefine((entry, ctx) => {
+    if (entry.distanceToPrevious !== undefined && entry.distanceToNext !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "distanceToPrevious and distanceToNext are mutually exclusive on one line entry",
+      })
+    }
+  })
+export type PluginGridLineEntry = z.infer<typeof PluginGridLineEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateLines}. */
+export const PluginDesignGridsUpdateLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineEntry).min(1),
+})
+export type PluginDesignGridsUpdateLinesArgs = z.infer<
+  typeof PluginDesignGridsUpdateLinesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.addLine}. */
+export const PluginDesignGridsAddLineArgs = z.object({
+  grid: ComponentHandle,
+  wing: z.number().int().nonnegative(),
+  position: z.number().finite(),
+})
+export type PluginDesignGridsAddLineArgs = z.infer<typeof PluginDesignGridsAddLineArgs>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.removeLines}. */
+export const PluginDesignGridsRemoveLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineAddress).min(1),
+  tagPolicy: PluginGridLineTagPolicy.optional(),
+})
+export type PluginDesignGridsRemoveLinesArgs = z.infer<
+  typeof PluginDesignGridsRemoveLinesArgs
+>
+
+/**
+ * `design.grids.*` — structural edits on a grid's line structure (the
+ * entity-family home for grid-specific operations, like `design.doors`).
+ *
+ * Lines are addressed positionally as `{ wing, line }` index pairs into the
+ * `wings` arrays returned by `design.query.grids.get`. Adding, removing, or
+ * re-counting lines re-indexes the wing — re-query after every structural edit.
+ *
+ * Group-level edits (default styling, angle, storey visibility) live on
+ * `design.update.grid`; creation lives on `design.create.grid*`.
+ *
+ * Accessed via `snaptrude.design.grids`.
+ */
+export abstract class PluginDesignGridsApi {
+  constructor() {}
+
+  /**
+   * Update one or more **wings** of a grid with sparse per-wing entries —
+   * `spacing` (uniform re-space), `count` (grow/truncate + tag renumber),
+   * `spanMin`/`spanMax` (family length handles). Every change routes through
+   * the exact setters the native panel uses — each changed field commits its
+   * own undoable command, identical to editing that field in the panel.
+   *
+   * A `count` change re-indexes the wing's lines — positional `{ wing, line }`
+   * addresses held from before the call are stale afterwards; re-query.
+   *
+   * @param grid - The grid group
+   * @param wings - Sparse {@linkcode PluginGridWingEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Change this grid's spacing to 8 metres
+   * @examplePrompt Make this grid 10 by 12 lines
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateWings(grid, [{ wing: 0, spacing: 8, count: 10 }])
+   * ```
+   */
+  public abstract updateWings(
+    grid: ComponentHandle,
+    wings: PluginGridWingEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Update one or more **lines** of a grid with sparse per-line entries —
+   * `tag`, `distanceToPrevious`/`distanceToNext` (typed distance to the
+   * neighbour on that side; mutually exclusive), `props` (per-line style
+   * overrides), and `visible: false` (hide). Every change routes through the
+   * exact setters the native panel uses — each changed field commits its own
+   * undoable command, identical to editing that field in the panel.
+   *
+   * Visibility mirrors the product exactly: `visible` accepts only `false` —
+   * per-line show does not exist. Hiding lines that would leave NO visible
+   * line hides the whole GROUP instead (the native last-line rule; those line
+   * flags stay untouched). To bring hidden lines back, show the group
+   * (`design.visibility.show([grid])`) — it restores ALL of its lines, like
+   * the native Show All.
+   *
+   * @param grid - The grid group
+   * @param lines - Sparse {@linkcode PluginGridLineEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rename grid line 2 to "B"
+   * @examplePrompt Move this grid line 4 metres from its neighbour
+   * @examplePrompt Hide grid line 3 on this grid
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateLines(grid, [
+   *   { wing: 0, line: 1, tag: "B", distanceToPrevious: 4 },
+   * ])
+   * ```
+   */
+  public abstract updateLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Insert a parallel grid line into a wing at an explicit position along the
+   * wing's spacing axis (Snaptrude units, wing-local — line 0's position can
+   * be read from its curve). Sibling lines do not shift; the wing's tag
+   * sequence is renumbered. Undoable.
+   *
+   * @param grid - The grid group
+   * @param wing - Wing index
+   * @param position - Position along the wing's spacing axis (Snaptrude units)
+   * @returns `true` once inserted
+   * @throws `VALIDATION` on a bad wing index or non-finite position
+   *
+   * @examplePrompt Add a grid line between lines 2 and 3
+   * @examplePrompt Insert an extra grid line 4 metres from line A
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.addLine(grid, 0, 12.5)
+   * ```
+   */
+  public abstract addLine(
+    grid: ComponentHandle,
+    wing: number,
+    position: number,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Remove grid lines by positional address, as ONE undoable step. With
+   * `tagPolicy: "rewrite"` (default) each affected wing renumbers its tag
+   * sequence; `"preserve"` keeps surviving tags unchanged. A wing emptied of
+   * lines is dropped from the group.
+   *
+   * Removing EVERY line of the group is rejected — delete the group instead
+   * (`design.delete.entities`).
+   *
+   * @param grid - The grid group
+   * @param lines - Positional addresses to remove (see `design.query.grids.get`)
+   * @param tagPolicy - `"rewrite"` (default) or `"preserve"`
+   * @returns `true` once removed
+   * @throws `VALIDATION` on out-of-range addresses; `OPERATION_FAILED` when the
+   *   removal would delete the group's last line
+   *
+   * @examplePrompt Delete grid line B
+   * @examplePrompt Remove the last two lines of this grid without renumbering
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.removeLines(grid, [{ wing: 0, line: 2 }], "preserve")
+   * ```
+   */
+  public abstract removeLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineAddress[],
+    tagPolicy?: PluginGridLineTagPolicy,
+  ): PluginApiReturn<boolean>
+}

package/src/api/design/index.ts

@@ -17,6 +17,7 @@ import { PluginDesignVisibilityApi } from "./visibility"
 import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
 import { PluginDesignFamilyApi } from "./family"
+import { PluginDesignGridsApi } from "./grids"
 import { PluginDesignChangeResult } from "./lock"
 
 /**
@@ -76,6 +77,9 @@ export abstract class PluginDesignApi {
   /** Author parametric families from a JSON spec. See {@linkcode PluginDesignFamilyApi}. */
   public abstract family: PluginDesignFamilyApi
 
+  /** Structural edits on a grid's line structure. See {@linkcode PluginDesignGridsApi}. */
+  public abstract grids: PluginDesignGridsApi
+
   /**
    * Lock entities so they cannot be edited. Undoable. Cascades to void/door/window
    * children, stacked-wall companions, and terrain neighborhood; skips
@@ -267,3 +271,4 @@ export * from "./visibility"
 export * from "./dimensions"
 export * from "./types"
 export * from "./family"
+export * from "./grids"

package/src/api/design/query/grids.ts

@@ -0,0 +1,197 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { CurveHandle, BBoxComponents } from "../../../handles"
+import { PluginReferenceLineStyle } from "../create"
+
+// ---------------------------------------------------------------------------
+// Records
+// ---------------------------------------------------------------------------
+
+/**
+ * Visual properties of grid lines — the group's defaults and any per-line
+ * overrides share this shape (values mirror the engine's `GridLineProps`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
+ * | `weight` | `number` | Line weight |
+ * | `color` | `string` | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
+ * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
+ */
+export const PluginGridLineProps = z.object({
+  style: PluginReferenceLineStyle,
+  weight: z.number(),
+  color: z.string(),
+  showStart: z.boolean(),
+  showEnd: z.boolean(),
+})
+export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
+
+/**
+ * One grid line within a wing.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
+ * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
+ * | `visible` | `boolean` | Persisted per-line visibility |
+ * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
+ * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
+ */
+export const PluginGridLineRecord = z.object({
+  curve: CurveHandle,
+  tag: z.string(),
+  visible: z.boolean(),
+  props: PluginGridLineProps,
+  overrides: PluginGridLineProps.partial().optional(),
+})
+export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
+
+/**
+ * One wing of a grid — a family of parallel lines sharing a local frame.
+ * `spacing` and `span` are measured along the wing's local axes in
+ * Snaptrude units; line addresses used by mutating APIs are
+ * `{ wing, line }` index pairs into these arrays.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
+ * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
+ * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
+ * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
+ */
+export const PluginGridWingRecord = z.object({
+  spacing: z.number(),
+  tagStart: z.string(),
+  span: z.object({ min: z.number(), max: z.number() }).optional(),
+  lines: z.array(PluginGridLineRecord),
+})
+export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
+
+/**
+ * Per-storey 2D-plan visibility of a grid.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `activeStorey` | `number` | The storey the grid belongs to |
+ * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
+ */
+export const PluginGridStoreyVisibility = z.object({
+  activeStorey: z.number(),
+  disabledOnStoreys: z.array(z.number()),
+})
+export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
+
+// ---------------------------------------------------------------------------
+// get — args & result
+// ---------------------------------------------------------------------------
+
+/**
+ * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"angle"` | World rotation about +Y, in **degrees** |
+ * | `"props"` | Group-level default line properties |
+ * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
+ * | `"wings"` | Full wing/line structure with world-space curve handles |
+ * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
+ */
+export const PluginGridGetProperty = z.enum([
+  "angle",
+  "props",
+  "storeyVisibility",
+  "wings",
+  "bounds",
+])
+export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `gridId` | `string` | The grid group ID to query |
+ * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginGridGetArgs = z.object({
+  gridId: z.string(),
+  properties: z.array(PluginGridGetProperty),
+})
+export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
+ * properties are present.
+ */
+export const PluginGridGetResult = z
+  .object({
+    angle: z.number(),
+    props: PluginGridLineProps,
+    storeyVisibility: PluginGridStoreyVisibility,
+    wings: z.array(PluginGridWingRecord),
+    bounds: BBoxComponents,
+  })
+  .partial()
+export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
+
+// ---------------------------------------------------------------------------
+// Abstract API
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.grids.*` — structural-grid-specific reads.
+ *
+ * A **grid** (grid group) is a structural/documentation grid: one or more
+ * *wings* (families of parallel lines with a shared local frame), each holding
+ * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
+ * `design.query.listGrids`; read an individual grid's structure here.
+ *
+ * Lines have no stable identity of their own — mutating APIs address them
+ * positionally as `{ wing, line }` index pairs into the `wings` arrays
+ * returned by {@linkcode get}. Structural edits (adding/removing lines,
+ * count changes) re-index lines; re-query after mutating.
+ *
+ * Accessed via `snaptrude.design.query.grids`.
+ */
+export abstract class PluginDesignQueryGridsApi {
+  constructor() {}
+
+  /**
+   * Get properties of a grid by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. `wings` is the heavy
+   * read (it registers a world-space {@linkcode CurveHandle} per line);
+   * request it only when the geometry is needed.
+   *
+   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
+   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
+   * world space.
+   *
+   * @param gridId - The unique grid group ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginGridGetProperty}.
+   * @returns A partial {@linkcode PluginGridGetResult} containing only the
+   *   requested properties
+   * @throws If the grid does not exist
+   *
+   * @examplePrompt What is the spacing of this grid?
+   * @examplePrompt Read the grid line tags on this structural grid
+   * @examplePrompt Get the geometry of every line in this grid
+   * @examplePrompt Which storeys is this grid hidden on?
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
+   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
+   * // read its coordinates via `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    gridId: string,
+    properties: z.infer<typeof PluginGridGetProperty>[],
+  ): PluginApiReturn<PluginGridGetResult>
+}

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

@@ -11,6 +11,7 @@ import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
 import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
+import { PluginDesignQueryGridsApi } from "./grids"
 
 // ---------------------------------------------------------------------------
 // Entity type vocabulary
@@ -42,6 +43,7 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"mullion"` | Curtain-wall mullion |
  * | `"panel"` | Curtain-wall panel |
  * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
+ * | `"grid"` | Structural grid group |
  */
 export const PluginEntityType = z.enum([
   "wall",
@@ -62,6 +64,7 @@ export const PluginEntityType = z.enum([
   "mullion",
   "panel",
   "parametricComponent",
+  "grid",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>
 
@@ -306,6 +309,8 @@ export abstract class PluginDesignQueryApi {
   public abstract spaces: PluginDesignQuerySpacesApi
   /** Reference-line-specific reads. See {@linkcode PluginDesignQueryReferenceLinesApi}. */
   public abstract referenceLines: PluginDesignQueryReferenceLinesApi
+  /** Structural-grid-specific reads. See {@linkcode PluginDesignQueryGridsApi}. */
+  public abstract grids: PluginDesignQueryGridsApi
 
   constructor() {}
 
@@ -723,6 +728,27 @@ export abstract class PluginDesignQueryApi {
     filter?: PluginEntityFilter,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * List all the structural grids (grid groups) in the project, optionally
+   * filtered by storey, building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns grid-group {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the structural grids in the model
+   * @examplePrompt How many grids are on the ground floor?
+   * @examplePrompt Show the grids on this storey
+   * @examplePrompt Which grids are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })
+   * ```
+   */
+  public abstract listGrids(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
   // ── single-entity access & identity ─────────────────────────────────────────
 
   /**
@@ -1147,3 +1173,4 @@ export type PluginStoreyOutlineResult = z.infer<
 export * from "./geometry"
 export * from "./spaces"
 export * from "./referenceLines"
+export * from "./grids"

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

@@ -15,6 +15,7 @@ import {
   PluginBuildableEnvelopeVerticalCap,
   PluginBuildableEnvelopeUpdateResult,
 } from "../../entity/buildableEnvelope"
+import { PluginGridStyleOptions } from "../create/grids"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -238,6 +239,27 @@ export type PluginDesignSetStoreyArgs = z.infer<
   typeof PluginDesignSetStoreyArgs
 >
 
+/**
+ * The sparse GROUP-LEVEL patch accepted by {@linkcode PluginDesignUpdateApi.grid}.
+ * Only provided fields change. Wing- and line-level updates live on the grids
+ * entity family: `design.grids.updateWings` / `design.grids.updateLines`.
+ */
+export const PluginGridPatch = z.object({
+  angle: z.number().finite().optional(),
+  props: PluginGridStyleOptions.optional(),
+  storeyVisibility: z
+    .array(z.object({ storey: z.number().int(), visible: z.boolean() }))
+    .optional(),
+})
+export type PluginGridPatch = z.infer<typeof PluginGridPatch>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
+export const PluginDesignUpdateGridArgs = z.object({
+  grid: ComponentHandle,
+  patch: PluginGridPatch,
+})
+export type PluginDesignUpdateGridArgs = z.infer<typeof PluginDesignUpdateGridArgs>
+
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
@@ -290,6 +312,37 @@ export abstract class PluginDesignUpdateApi {
     label: string,
   ): PluginApiReturn<boolean>
 
+  /**
+   * Update a structural grid's **group-level** fields with a sparse patch —
+   * default line styling, absolute angle, and per-storey 2D visibility. Only
+   * provided fields change. Wing- and line-level updates live on the grids
+   * entity family: {@linkcode PluginDesignGridsApi.updateWings} /
+   * {@linkcode PluginDesignGridsApi.updateLines}.
+   *
+   * Every change routes through the exact setters the native panel uses —
+   * each changed field commits its own undoable command, identical to editing
+   * that field in the panel. `angle` is an absolute target in degrees (CCW
+   * about +Y).
+   *
+   * @param grid - The grid group to update
+   * @param patch - The sparse {@linkcode PluginGridPatch}
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rotate the grid to 45 degrees
+   * @examplePrompt Make this grid's lines dashed and grey
+   * @examplePrompt Hide this grid on storey 3's plan
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * await snaptrude.design.update.grid(grid, { angle: 45, props: { style: "DASHED" } })
+   * ```
+   */
+  public abstract grid(
+    grid: ComponentHandle,
+    patch: PluginGridPatch,
+  ): PluginApiReturn<boolean>
+
   /**
    * Update a single space (room) — change its properties (room label, space
    * type, mass type, area class, department) and/or replace its geometry by

package/src/api/program/departments.ts

@@ -7,7 +7,7 @@ import { ComponentHandle } from "../../handles"
  * Program departments — read the department groupings of the active program.
  *
  * In program mode a **department** is a named, colored grouping of spaces with an
- * optional area **target**. This is the program-planning view of departments
+ * optional gross area **target** and a unit **count** target. This is the program-planning view of departments
  * (their identity, color, and target area); the underlying space geometry is read
  * and edited through the geometry namespaces, not here.
  *
@@ -203,6 +203,33 @@ export abstract class PluginProgramDepartmentsApi {
     units?: PluginAreaUnit,
   ): PluginApiReturn<PluginProgramDepartmentsSetTargetAreaResult>
 
+  /**
+   * Set a department's target unit count.
+   *
+   * The number of units (program blocks) the department is planned for — the
+   * count twin of {@linkcode PluginProgramDepartmentsApi.setTargetArea}, stored
+   * beside the gross area target on the department. Read it back from
+   * {@linkcode PluginProgramDepartmentsApi.get} (`targetCount`).
+   *
+   * @param departmentId - The id of the department whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department unit count to 12
+   * @examplePrompt The program needs 4 clinic blocks — update the department count
+   * @examplePrompt Update the target count for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetCount("dep_123", 12)
+   * ```
+   */
+  public abstract setTargetCount(
+    departmentId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetCountResult>
+
   /**
    * Delete a department.
    *
@@ -239,13 +266,15 @@ export abstract class PluginProgramDepartmentsApi {
  * | `id` | `string` | Unique department id |
  * | `name` | `string` | Display name |
  * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
- * | `targetArea` | `number \| null` | Target area in the response's `units`, or `null` if no target is set |
+ * | `targetArea` | `number \| null` | Gross target area in the response's `units`, or `null` if no target is set |
+ * | `targetCount` | `number` | Target number of units / program blocks (`0` when unset) |
  */
 export const PluginProgramDepartment = z.object({
   id: z.string(),
   name: z.string(),
   color: z.string(),
   targetArea: z.number().nullable(),
+  targetCount: z.number(),
 })
 export type PluginProgramDepartment = z.infer<typeof PluginProgramDepartment>
 
@@ -434,6 +463,29 @@ export type PluginProgramDepartmentsSetTargetAreaResult = z.infer<
   typeof PluginProgramDepartmentsSetTargetAreaResult
 >
 
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramDepartmentsSetTargetCountArgs = z.object({
+  departmentId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramDepartmentsSetTargetCountArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramDepartmentsSetTargetCountResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetCountResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountResult
+>
+
 /**
  * Arguments for {@linkcode PluginProgramDepartmentsApi.delete}.
  *