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

package/src/api/design/family.ts

@@ -25,7 +25,8 @@ import { ComponentHandle, Vec3Components } from "../../handles"
  * ## Read getReference() first
  *
  * The spec DSL is a closed expression language with its own op set, coordinate
- * convention (**+Y up, integer millimetres** — not Snaptrude's babylon units)
+ * convention (**+Y up, Snaptrude units** — the scene's own unit, 1 SU = 254 mm;
+ * literals may carry a unit suffix such as `600mm` or `2ft`)
  * and part-naming law. It is deliberately NOT duplicated in these types:
  * {@linkcode PluginDesignFamilyApi.getReference} returns the whole reference,
  * generated from a family that is actually registered in the host, so the
@@ -278,11 +279,11 @@ export interface PluginFamilyBundle {
   deps?: Record<string, Record<string, unknown>>
 }
 
-/** Axis-aligned extents of a built family. Integer millimetres, +Y up. */
+/** Axis-aligned extents of a built family. Snaptrude units (1 SU = 254 mm), +Y up. */
 export interface PluginFamilyBBox {
   min: [number, number, number]
   max: [number, number, number]
-  /** `[width, height, depth]` in millimetres. */
+  /** `[width, height, depth]` in Snaptrude units — convert with `core.units.convert` for display. */
   size: [number, number, number]
 }
 
@@ -322,6 +323,7 @@ export interface PluginFamilyDiagnostic {
     | "unbounded-repeat"
     | "depth"
     | "bad-dimension"
+    | "proportion"
   message: string
   hint?: string
 }
@@ -335,7 +337,7 @@ export interface PluginFamilyPrepareResult {
   label?: string
   /** How many parts the family built. Sanity-check against intent. */
   partCount?: number
-  /** Extents in millimetres. Sanity-check against intent. */
+  /** Extents in Snaptrude units. Sanity-check against intent. */
   bbox?: PluginFamilyBBox
   evalMs?: number
   parameters?: PluginFamilyParameter[]
@@ -343,6 +345,8 @@ export interface PluginFamilyPrepareResult {
   takeoff?: Record<string, number | string>
   /** The first few part names — enough to check the naming came out right. */
   sampleParts?: string[]
+  /** Present when `snapshot` was asked for. */
+  snapshot?: PluginFamilySnapshot
   errors: PluginFamilyDiagnostic[]
   warnings: PluginFamilyDiagnostic[]
   /** Set when the bundle validated but threw while building. */
@@ -372,6 +376,10 @@ export interface PluginFamilyFlexResult {
   evalMs?: number
   changed?: PluginFamilyChangeBuckets
   takeoff?: Record<string, number | string>
+  /** Proportion warnings at the flexed values (code `proportion`): a part thinner than 0.5 mm, a part or family over 50 m, a family under 10 mm — the signature of a unit slip. */
+  warnings?: PluginFamilyDiagnostic[]
+  /** Present when `snapshot` was asked for. */
+  snapshot?: PluginFamilySnapshot
   error?: string
 }
 
@@ -421,6 +429,8 @@ export interface PluginFamilyInstanceParameters {
   values: Record<string, number | string>
   /** The sheet: what each key means, its bounds, and whether it moves geometry. */
   parameters: PluginFamilyParameter[]
+  /** Present when `getParameters` was asked for a `snapshot`. */
+  snapshot?: PluginFamilySnapshot
 }
 
 /** What `create` reports. */
@@ -455,13 +465,46 @@ export const PluginFamilyBundleSchema = z.object({
  * |---|---|---|
  * | `bundle` | {@linkcode PluginFamilyBundle} | The family spec bundle |
  * | `spec` | {@linkcode PluginFamilyBundle} | Alias for `bundle` |
+ * | `snapshot` | {@linkcode PluginFamilySnapshotOption} | Also return a picture of the built family |
  *
  * Exactly one of `bundle` / `spec` is required. A bare `FamilySpec` (no `root`
  * wrapper) is also accepted by the host and wrapped for the caller.
  */
+/**
+ * Ask for a picture with the result: `true` for the default sheet (iso, front,
+ * right and top tiles with a dimension line), or an object to choose views and
+ * tile size. The picture is an isolated offscreen render of the family alone —
+ * the viewport is not moved — and comes back as a PNG data URL in the result's
+ * `snapshot.image`. Through the agent's `run_worker`, return the result and the
+ * image reaches the model as an image.
+ */
+export const PluginFamilySnapshotOption = z.union([
+  z.boolean(),
+  z.object({
+    views: z.array(z.enum(["iso", "front", "right", "top"])).optional(),
+    /** Pixels per tile (square), 64–2048; default 512. */
+    tileSize: z.number().optional(),
+  }),
+])
+export type PluginFamilySnapshotOption = z.infer<typeof PluginFamilySnapshotOption>
+
+/** The picture block on prepare / flex / getParameters results when `snapshot` was asked for. */
+export interface PluginFamilySnapshot {
+  ok: boolean
+  /** PNG data URL of the composed sheet. */
+  image?: string
+  views?: ("iso" | "front" | "right" | "top")[]
+  /** [width, height, depth] in Snaptrude units. */
+  size?: [number, number, number]
+  ms?: number
+  /** Set when the picture could not be taken (e.g. the legacy renderer); the call itself still succeeded. */
+  error?: string
+}
+
 export const PluginDesignFamilyPrepareArgs = z.object({
   bundle: PluginFamilyBundleSchema.optional(),
   spec: PluginFamilyBundleSchema.optional(),
+  snapshot: PluginFamilySnapshotOption.optional(),
 })
 export type PluginDesignFamilyPrepareArgs = z.infer<typeof PluginDesignFamilyPrepareArgs>
 
@@ -471,9 +514,11 @@ export type PluginDesignFamilyPrepareArgs = z.infer<typeof PluginDesignFamilyPre
  * | Property | Type | Description |
  * |---|---|---|
  * | `values` | `Record<string, number \| string>` | Parameter values to change (partial) |
+ * | `snapshot` | {@linkcode PluginFamilySnapshotOption} | Also return a picture of the flexed family |
  */
 export const PluginDesignFamilyFlexArgs = z.object({
   values: z.record(z.string(), z.union([z.number(), z.string()])),
+  snapshot: PluginFamilySnapshotOption.optional(),
 })
 export type PluginDesignFamilyFlexArgs = z.infer<typeof PluginDesignFamilyFlexArgs>
 
@@ -522,6 +567,8 @@ export type PluginDesignFamilyPlaceArgs = z.infer<typeof PluginDesignFamilyPlace
  */
 export const PluginDesignFamilyGetParametersArgs = z.object({
   component: ComponentHandle,
+  /** Also return a picture of this instance (its recipe re-run at its values, with its paint). */
+  snapshot: PluginFamilySnapshotOption.optional(),
 })
 export type PluginDesignFamilyGetParametersArgs = z.infer<
   typeof PluginDesignFamilyGetParametersArgs

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

@@ -14,8 +14,10 @@ import { PluginDesignTransformApi } from "./transform"
 import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
+import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
 import { PluginDesignFamilyApi } from "./family"
+import { PluginDesignGridsApi } from "./grids"
 import { PluginDesignChangeResult } from "./lock"
 
 /**
@@ -31,6 +33,7 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
  * - {@linkcode PluginDesignApi.visibility} — hide / isolate / reveal entities
+ * - {@linkcode PluginDesignApi.dimensions} — dimension lines (Measuring Tape): create / list / delete / hide
  * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
  * - {@linkcode PluginDesignApi.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)
@@ -67,11 +70,16 @@ export abstract class PluginDesignApi {
   public abstract update: PluginDesignUpdateApi
   /** Hide / isolate / reveal entities. See {@linkcode PluginDesignVisibilityApi}. */
   public abstract visibility: PluginDesignVisibilityApi
+  /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
+  public abstract dimensions: PluginDesignDimensionsApi
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
   /** 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
@@ -260,5 +268,7 @@ export * from "./transform"
 export * from "./edit"
 export * from "./update"
 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>
+}