@snaptrude/plugin-core 0.9.9 → 0.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "check-types": "tsc --noEmit",
-    "build": "tsup --clean",
-    "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist",
-    "test": "node --test test/*.test.mjs",
-    "generate:manifest": "node scripts/generate-manifest.mjs",
-    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
-    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
-    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
-  },
   "devDependencies": {
     "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
@@ -37,5 +26,16 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
   }
-}
+}

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

@@ -29,10 +29,14 @@ export interface PluginCoreModeSetResult {
  * Not to be confused with the viewport's 2D/3D camera mode
  * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
  *
- * `set` covers `design`, `bim`, and `present` — in-page switches.
- * `program` opens in its own browser tab in the product, which a plugin worker
- * cannot do, so `set("program")` fails with `PRECONDITION_FAILED`; `get()`
- * still reports `"program"` for code running in the Program tab.
+ * `set` covers `design`, `bim`, and `present` — in-page switches — and
+ * `program`, which opens the Program tab (a paired browser window) through the
+ * same path as the top bar's Program button. Because the open happens outside a
+ * user gesture the browser may block the pop-up; the editor then shows its
+ * "Allow pop-up to continue" modal and the tab opens when the user confirms.
+ * `get()` reports `"program"` only for code running in the Program tab itself.
+ * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
+ * the tab is ready before calling `program.spreadsheet.*`.
  */
 export abstract class PluginCoreModeApi {
   constructor() {}
@@ -74,16 +78,24 @@ export abstract class PluginCoreModeApi {
    * Switch the editor to another application mode — the same action as
    * clicking that tab in the top menu bar.
    *
-   * Supported: `"design"`, `"bim"`, `"present"`. Switching to
-   * `"program"` is rejected with `PRECONDITION_FAILED` (the Program surface
-   * opens in its own browser tab in the product; a plugin cannot open one).
+   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
+   * the Program tab (a paired browser window) exactly as the top bar's Program
+   * button does, and resolves once that tab has connected to the editor (up to
+   * ~90s — the browser may block the pop-up, in which case the editor shows an
+   * "Allow pop-up to continue" modal and waits for the user to confirm).
+   * Idempotent when the Program tab is already open. Note `get()` in the model
+   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
+   * a separate window.
    *
    * @param mode - Target mode token from {@linkcode PluginAppMode}
    * @returns The committed `{ mode }` after the switch.
+   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
+   *   pop-up modal or the tab does not connect within the timeout.
    *
    * @examplePrompt Switch to present mode
    * @examplePrompt Open BIM mode
    * @examplePrompt Go back to design mode
+   * @examplePrompt Open program mode
    *
    * # Example
    * ```ts

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

@@ -0,0 +1,137 @@
+import * as z from "zod"
+import { ComponentHandle, CurveHandle, Vec3Handle } from "../../../handles"
+
+// ---------------------------------------------------------------------------
+// Shared grid style vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * Grid line style (mirrors the engine `LineMode` values verbatim — the same
+ * vocabulary as {@linkcode PluginReferenceLineStyle}).
+ */
+export const PluginGridLineStyle = z.enum(["SOLID", "DASHED", "DOT_DASH"])
+export type PluginGridLineStyle = z.infer<typeof PluginGridLineStyle>
+
+/**
+ * Optional visual styling shared by every grid creator (and reused as the
+ * patch shape by `design.update.grid`). All fields optional; engine defaults
+ * apply when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginGridLineStyle}? | Line style |
+ * | `weight` | `number`? | Line weight (> 0) |
+ * | `color` | `string`? | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean`? | Show the start-end tag bubble |
+ * | `showEnd` | `boolean`? | Show the end-end tag bubble |
+ */
+export const PluginGridStyleOptions = z.object({
+  style: PluginGridLineStyle.optional(),
+  weight: z.number().positive().optional(),
+  color: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "color must be a #rrggbb hex string")
+    .optional(),
+  showStart: z.boolean().optional(),
+  showEnd: z.boolean().optional(),
+})
+export type PluginGridStyleOptions = z.infer<typeof PluginGridStyleOptions>
+
+// ---------------------------------------------------------------------------
+// create.grid — free rectangular grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.grid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `linesX` | `number` | Line count of the first family (integer ≥ 1) |
+ * | `linesY` | `number` | Line count of the second family (integer ≥ 1) |
+ * | `spacingX` | `number` | Spacing of the first family (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Spacing of the second family (Snaptrude units, > 0) |
+ * | `angle` | `number`? | Rotation in degrees, CCW about +Y (default 0) |
+ * | `center` | {@linkcode Vec3Handle}? | Placement centre; defaults to the native viewport-centre behavior |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridArgs = z
+  .object({
+    linesX: z.number().int().min(1),
+    linesY: z.number().int().min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+    angle: z.number().finite().optional(),
+    center: Vec3Handle.optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridArgs = z.infer<typeof PluginDesignCreateGridArgs>
+
+// ---------------------------------------------------------------------------
+// create.gridFromCurve — single-curve grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridFromCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The grid line's geometry — a line or arc (circles are rejected) |
+ * | `tag` | `string`? | The line's grid tag (defaults to the draw tool's next tag) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridFromCurveArgs = z
+  .object({
+    curve: CurveHandle,
+    tag: z.string().min(1).optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridFromCurveArgs = z.infer<
+  typeof PluginDesignCreateGridFromCurveArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.gridsFromMasses — fitted grids
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridsFromMasses}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `masses` | {@linkcode ComponentHandle}`[]` | Masses whose footprints seat the grids |
+ * | `spacingX` | `number` | First-family spacing (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Second-family spacing (Snaptrude units, > 0) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridsFromMassesArgs = z
+  .object({
+    masses: z.array(ComponentHandle).min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridsFromMassesArgs = z.infer<
+  typeof PluginDesignCreateGridsFromMassesArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.columnsFromGrids — columns at line intersections
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.columnsFromGrids}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `grids` | {@linkcode ComponentHandle}`[]` | Grid groups whose line intersections seat the columns |
+ * | `width` | `number` | Column width (Snaptrude units, > 0) |
+ * | `depth` | `number` | Column depth (Snaptrude units, > 0) |
+ */
+export const PluginDesignCreateColumnsFromGridsArgs = z.object({
+  grids: z.array(ComponentHandle).min(1),
+  width: z.number().positive().finite(),
+  depth: z.number().positive().finite(),
+})
+export type PluginDesignCreateColumnsFromGridsArgs = z.infer<
+  typeof PluginDesignCreateColumnsFromGridsArgs
+>

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

@@ -4,9 +4,11 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  CurveHandle,
   ProfileHandle,
   Vec3Handle,
 } from "../../../handles"
+import { PluginGridStyleOptions } from "./grids"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -628,6 +630,134 @@ export abstract class PluginDesignCreateApi {
     gridTag?: string,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * Create a free rectangular **structural grid** — one grid group with two
+   * perpendicular line families (`linesX` lines spaced `spacingX` apart, and
+   * `linesY` lines spaced `spacingY` apart) on the active storey. One undoable
+   * creation.
+   *
+   * Units: spacings in Snaptrude units; `angle` in degrees (CCW about +Y,
+   * default 0). Without `center` the grid is centred on the current viewport
+   * (the native tool's behavior) — pass `center` for deterministic placement.
+   *
+   * @param linesX - Line count of the first family (integer ≥ 1)
+   * @param linesY - Line count of the second family (integer ≥ 1)
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - `angle`, `center`, and {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Create a 5 by 8 structural grid with 6 metre spacing
+   * @examplePrompt Add a column grid rotated 30 degrees
+   * @examplePrompt Set up a structural grid at the site origin
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const grid = await snaptrude.design.create.grid(5, 8, 6, 6, { center: centre })
+   * ```
+   */
+  public abstract grid(
+    linesX: number,
+    linesY: number,
+    spacingX: number,
+    spacingY: number,
+    options?: {
+      angle?: number
+      center?: Vec3Handle
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **structural grid from a single curve** — one grid group holding
+   * one wing with one line (the draw tool's output). The curve may be a line
+   * or an arc; circles are rejected with `VALIDATION`. Undoable.
+   *
+   * @param curve - The grid line's geometry ({@linkcode CurveHandle}, world space)
+   * @param options - `tag` (defaults to the draw tool's next tag) and
+   *   {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Draw a grid line from A to B
+   * @examplePrompt Add a curved grid line through these points
+   * @examplePrompt Create grid line "C" along this wall
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * const from = await vec3.new(0, 0, 0)
+   * const to = await vec3.new(30, 0, 0)
+   * const curve = await snaptrude.core.geom.create.line(from, to)
+   * const grid = await snaptrude.design.create.gridFromCurve(curve, { tag: "A" })
+   * ```
+   */
+  public abstract gridFromCurve(
+    curve: CurveHandle,
+    options?: {
+      tag?: string
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Generate **structural grids fitted to mass footprints** — one grid group
+   * per footprint cluster, with counts and orientation derived from each
+   * footprint's geometry and the given spacings. All created groups commit as
+   * ONE undoable unit.
+   *
+   * Lenient like the native tool: masses without an extractable footprint
+   * (no B-rep, degenerate top face) are skipped; throws `VALIDATION` only when
+   * NONE of the given masses yields a footprint.
+   *
+   * @param masses - Masses whose footprints seat the grids
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - {@linkcode PluginGridStyleOptions}
+   * @returns the created grid groups' {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt Generate grids for the selected masses
+   * @examplePrompt Auto-generate a 6m structural grid on this building
+   * @examplePrompt Fit column grids to every mass on this storey
+   *
+   * # Example
+   * ```ts
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const grids = await snaptrude.design.create.gridsFromMasses(masses, 6, 6)
+   * ```
+   */
+  public abstract gridsFromMasses(
+    masses: ComponentHandle[],
+    spacingX: number,
+    spacingY: number,
+    options?: PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create **columns at every grid-line intersection** of the given grid
+   * groups, sized `width` × `depth` and oriented to the grid axes, on the
+   * grids' storey. All columns commit as ONE undoable unit.
+   *
+   * @param grids - Grid groups whose intersections seat the columns
+   * @param width - Column width (Snaptrude units, > 0)
+   * @param depth - Column depth (Snaptrude units, > 0)
+   * @returns the created columns' {@linkcode ComponentHandle}`[]`
+   * @throws `VALIDATION` when an id does not resolve to a grid group;
+   *   `OPERATION_FAILED` when the grids have no line intersections
+   *
+   * @examplePrompt Generate columns on this grid
+   * @examplePrompt Place 450mm square columns at every grid intersection
+   *
+   * # Example
+   * ```ts
+   * const grids = await snaptrude.design.query.listGrids()
+   * const columns = await snaptrude.design.create.columnsFromGrids(grids, 0.45, 0.45)
+   * ```
+   */
+  public abstract columnsFromGrids(
+    grids: ComponentHandle[],
+    width: number,
+    depth: number,
+  ): PluginApiReturn<ComponentHandle[]>
+
   /**
    * Place a **furniture** item from the project library at a world position.
    *
@@ -1821,3 +1951,4 @@ export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
 
 export * from "./opening-fields"
 export * from "./bulk-items"
+export * from "./grids"

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

@@ -16,6 +16,7 @@ import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
 import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
+import { PluginDesignGridsApi } from "./grids"
 import { PluginDesignChangeResult } from "./lock"
 
 /**
@@ -72,6 +73,9 @@ export abstract class PluginDesignApi {
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
 
+  /** 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
@@ -262,3 +266,4 @@ export * from "./update"
 export * from "./visibility"
 export * from "./dimensions"
 export * from "./types"
+export * from "./grids"