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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.0.0-dev-20260911064951",
+  "version": "0.0.0-dev-20260921132444",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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/core/tags.ts

@@ -163,6 +163,40 @@ export abstract class PluginCoreTagsApi {
     componentId: ComponentHandle,
   ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
 
+  /**
+   * List the tags carried by many components in one call.
+   *
+   * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+   * `componentIds` to read specific components (unknown ids are skipped), or
+   * omit it to read **every** taggable component (Mass/Floor space) in the
+   * project. Each entry carries the component id and its tags — one per tagged
+   * category, with the tag's `color` — so a plugin can color every space by a
+   * chosen category's tag in a single round-trip.
+   *
+   * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+   * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+   *   `components` array, one entry per component (in input order when
+   *   `componentIds` is given).
+   *
+   * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+   *
+   * @examplePrompt Get the tags of every space with their colors
+   * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+   * @examplePrompt Which tag does each selected space carry?
+   *
+   * # Example
+   * ```ts
+   * const { components } = await snaptrude.core.tags.listForComponents()
+   * for (const c of components) {
+   *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+   *   if (occupancy) paint(c.componentId, occupancy.color)
+   * }
+   * ```
+   */
+  public abstract listForComponents(
+    componentIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsListForComponentsResult>
+
   /**
    * List the components carrying a given tag or category.
    *
@@ -588,6 +622,48 @@ export type PluginCoreTagsGetTagsForComponentResult = z.infer<
   typeof PluginCoreTagsGetTagsForComponentResult
 >
 
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export const PluginCoreTagsListForComponentsArgs = z.object({
+  componentIds: z.array(ComponentHandle).optional(),
+})
+export type PluginCoreTagsListForComponentsArgs = z.infer<
+  typeof PluginCoreTagsListForComponentsArgs
+>
+
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreComponentTags = z.object({
+  componentId: ComponentHandle,
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export const PluginCoreTagsListForComponentsResult = z.object({
+  components: z.array(PluginCoreComponentTags),
+})
+export type PluginCoreTagsListForComponentsResult = z.infer<
+  typeof PluginCoreTagsListForComponentsResult
+>
+
 /**
  * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
  * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.

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/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