@snaptrude/plugin-core 0.9.11 → 0.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.11",
+  "version": "0.9.12",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/design/family.ts

@@ -0,0 +1,591 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle, Vec3Components } from "../../handles"
+
+/**
+ * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
+ *
+ * A parametric family is a reusable, parameter-driven building component: a
+ * curtain-wall panel, a louvre screen, a balustrade, a shading fin. Unlike the
+ * rest of `design.*`, you do not build one out of geometry calls — you write a
+ * JSON **spec** describing its parameters and its geometry rules, and the host
+ * compiles that into a live parametric definition the user can place, flex and
+ * save to their library.
+ *
+ * ## Workflow
+ *
+ * ```
+ * getReference()        read the spec DSL once — grammar, ops, expressions, example
+ * prepare({ bundle })   validate + compile + show a live ghost; nothing committed
+ * flex({ values })      re-run at new values; returns the geometry delta
+ * place()               arm placement — the USER clicks to drop it
+ * create({ name })      commit it to the project's family library
+ * ```
+ *
+ * ## Read getReference() first
+ *
+ * The spec DSL is a closed expression language with its own op set, coordinate
+ * 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
+ * documentation cannot drift from what the compiler accepts.
+ *
+ * ## The repair contract
+ *
+ * {@linkcode PluginDesignFamilyApi.prepare} does **not** throw on an invalid
+ * spec — it returns `{ ok: false, errors }` where each error carries a JSON
+ * pointer into the bundle you sent (e.g. `"/root/geometry/2/body/0/w"`). Read
+ * `errors[0].path`, fix that node, and call `prepare` again. A failed `prepare`
+ * leaves the previous good draft standing, so it costs nothing but the node you
+ * broke. Re-authoring from scratch throws away everything already correct.
+ *
+ * Accessed via `snaptrude.design.family`.
+ */
+export abstract class PluginDesignFamilyApi {
+  constructor() {}
+
+  /**
+   * Read the family-spec DSL reference: grammar, the op table, the expression
+   * whitelist, the coordinate convention, the repair contract, and a worked
+   * example taken from a registered family.
+   *
+   * Read this before authoring a family for the first time in a session. The
+   * DSL is a closed language — a guessed op or function is a rejected spec.
+   *
+   * @returns The reference text
+   *
+   * @examplePrompt How do I write a parametric family spec?
+   * @examplePrompt Show me the family DSL
+   *
+   * # Example
+   * ```ts
+   * const { reference } = await snaptrude.design.family.getReference()
+   * ```
+   */
+  public abstract getReference(): PluginApiReturn<PluginFamilyReference>
+
+  /**
+   * Validate, compile and preview a family spec. Nothing is committed to the
+   * model or the library — call {@linkcode PluginDesignFamilyApi.place} or
+   * {@linkcode PluginDesignFamilyApi.create} for that.
+   *
+   * Safe to call repeatedly while iterating. On success, check `partCount` and
+   * `bbox` against what you intended before treating the family as correct — a
+   * facade that built 3 parts, or a 3 m screen reporting 40 m of height, is a
+   * visible bug the validator cannot catch.
+   *
+   * @param args The spec bundle, as `{ bundle }` or `{ spec }`
+   * @returns Build report, or `{ ok: false, errors }` with JSON-pointer paths
+   *
+   * @examplePrompt Make a louvre screen with adjustable blade count and tilt
+   * @examplePrompt Design a curtain wall panel family with 8 bays
+   * @examplePrompt Create a railing family I can adjust
+   *
+   * # Example
+   * ```ts
+   * const r = await snaptrude.design.family.prepare({ bundle })
+   * if (!r.ok) console.error(r.errors[0].path, r.errors[0].message)
+   * ```
+   */
+  public abstract prepare(
+    args: PluginDesignFamilyPrepareArgs,
+  ): PluginApiReturn<PluginFamilyPrepareResult>
+
+  /**
+   * Re-run the prepared family's recipe at new parameter values.
+   *
+   * Values are merged over the current ones and clamped to the parameter
+   * sheet's min/max, so a partial `{ bays: 6 }` is fine. The returned `changed`
+   * buckets are the host's own diff of what the geometry did — flexing a
+   * driving parameter and reporting them demonstrates the family is parametric.
+   *
+   * @param args The parameter values to change
+   * @returns The new build plus the geometry delta
+   *
+   * @examplePrompt Change it to 6 bays
+   * @examplePrompt Show me what happens with 20 blades
+   *
+   * # Example
+   * ```ts
+   * const { changed } = await snaptrude.design.family.flex({ values: { bays: 6 } })
+   * console.log(`removed ${changed.removed}, rebuilt ${changed.rebuilt}`)
+   * ```
+   */
+  public abstract flex(
+    args: PluginDesignFamilyFlexArgs,
+  ): PluginApiReturn<PluginFamilyFlexResult>
+
+  /**
+   * The prepared family's spec bundle, or `null` when nothing is prepared.
+   *
+   * @returns The draft bundle, or `null`
+   *
+   * # Example
+   * ```ts
+   * const bundle = await snaptrude.design.family.get()
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginFamilyBundle | null>
+
+  /**
+   * Every parametric family registered in this session — native and imported.
+   *
+   * @returns One summary per family
+   *
+   * @examplePrompt What families are available?
+   *
+   * # Example
+   * ```ts
+   * const families = await snaptrude.design.family.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginFamilySummary[]>
+
+  /**
+   * Put a family into the model — either the prepared draft or any family from
+   * {@linkcode PluginDesignFamilyApi.list}.
+   *
+   * Two modes, chosen by whether you pass `position`:
+   *
+   * **With `position`** the component is created there and then, undoably. Use
+   * this when you know where it goes — you were given coordinates, or you are
+   * copying an existing instance. The returned `component` handle works with
+   * `design.transform.move` / `.rotate` and with
+   * {@linkcode PluginDesignFamilyApi.setParameters}.
+   *
+   * **Without `position`** it arms placement mode with a ghost on the cursor
+   * and returns immediately — no geometry yet. The USER clicks to drop it, so
+   * tell them to. Prefer this when the location is a judgement call.
+   *
+   * To COPY a placed component, place its family again at the new position with
+   * the same `values` — there is no separate copy call.
+   *
+   * @param args Which family, where, and at what parameter values
+   * @returns What was placed; `component` is present only in positioned mode
+   *
+   * @examplePrompt Place it in the model
+   * @examplePrompt Put a louvre screen at the origin
+   * @examplePrompt Copy that table two metres to the right
+   *
+   * # Example
+   * ```ts
+   * // positioned — geometry exists when this resolves
+   * const { component } = await snaptrude.design.family.place({
+   *   id: "revit:gypsum-stud-partition~90ad72",
+   *   position: { x: 0, y: 0, z: 0 },
+   *   rotation: 90,
+   * })
+   * await snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })
+   *
+   * // interactive — the user clicks
+   * await snaptrude.design.family.place()
+   * ```
+   */
+  public abstract place(
+    args?: PluginDesignFamilyPlaceArgs,
+  ): PluginApiReturn<PluginFamilyPlaceResult>
+
+  /**
+   * Read a placed component's current parameter values and its sheet.
+   *
+   * Use before {@linkcode PluginDesignFamilyApi.setParameters} so you change
+   * what is actually there: parameter KEYS are the family's own, not the
+   * label the user says, and a Revit-imported family carries parameters that
+   * do not drive geometry at all.
+   *
+   * @param args The component to read
+   * @returns Its definition, current values, and the parameter sheet
+   *
+   * @examplePrompt What size is that table?
+   * @examplePrompt Show me the parameters on this partition
+   *
+   * # Example
+   * ```ts
+   * const { values, parameters } = await snaptrude.design.family.getParameters({ component })
+   * ```
+   */
+  public abstract getParameters(
+    args: PluginDesignFamilyGetParametersArgs,
+  ): PluginApiReturn<PluginFamilyInstanceParameters | null>
+
+  /**
+   * Change a placed component's parameters and rebuild its geometry in place.
+   *
+   * Partial: pass only what changes. The component keeps its position,
+   * rotation and identity — this is an edit, not a replace, and it is undoable.
+   *
+   * Only parameters with `drivesGeometry` actually move the mesh. Setting one
+   * that does not is accepted and stored (it round-trips to Revit) but nothing
+   * visible happens — say so rather than claiming a change the user cannot see.
+   *
+   * @param args The component and the values to change
+   * @returns The values now in effect
+   *
+   * @examplePrompt Make that table seat 8
+   * @examplePrompt Change the stud spacing to 400
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.family.setParameters({ component, values: { seats: 8 } })
+   * ```
+   */
+  public abstract setParameters(
+    args: PluginDesignFamilySetParametersArgs,
+  ): PluginApiReturn<PluginFamilyInstanceParameters>
+
+  /**
+   * Commit the prepared bundle to the project's parametric-definition library,
+   * so it survives the session and appears in the Families panel.
+   *
+   * @param args Optional library name and team scope
+   * @returns The catalogued definition's id and version
+   *
+   * @examplePrompt Save this as a family called Vertical Louvre
+   * @examplePrompt Add it to my library
+   *
+   * # Example
+   * ```ts
+   * const { definitionId } = await snaptrude.design.family.create({ name: "Louvre Screen" })
+   * ```
+   */
+  public abstract create(
+    args?: PluginDesignFamilyCreateArgs,
+  ): PluginApiReturn<PluginFamilyCreateResult>
+}
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/** The family-spec DSL reference returned by `getReference`. */
+export interface PluginFamilyReference {
+  /** Grammar, op table, expression whitelist, repair contract, worked example. */
+  reference: string
+}
+
+/**
+ * A family spec bundle. `root` is the family; `deps` carries every spec
+ * reachable through an `instance` op, keyed by spec id, so a saved family is
+ * self-contained and reloads anywhere.
+ *
+ * The internal shape of a spec is documented by
+ * {@linkcode PluginDesignFamilyApi.getReference}, not by these types — it is a
+ * data DSL whose grammar changes independently of this API surface.
+ */
+export interface PluginFamilyBundle {
+  root: Record<string, unknown>
+  deps?: Record<string, Record<string, unknown>>
+}
+
+/** 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 Snaptrude units — convert with `core.units.convert` for display. */
+  size: [number, number, number]
+}
+
+/** One row of a family's parameter sheet. */
+export interface PluginFamilyParameter {
+  key: string
+  label: string
+  type: "length" | "integer" | "enum" | "text" | "boolean"
+  /** Current value. `length`/`integer` are numbers; the rest are strings. */
+  value: string | number
+  default: string | number
+  /**
+   * Whether this parameter actually drives geometry — INFERRED by the host from
+   * which names the spec's expressions reference. `false` means the value is
+   * stored and round-tripped but moves nothing.
+   */
+  drivesGeometry: boolean
+  min?: number
+  max?: number
+  options?: readonly string[]
+}
+
+/**
+ * A validation diagnostic. `path` is a JSON pointer into the submitted bundle —
+ * fix that node and re-`prepare`.
+ */
+export interface PluginFamilyDiagnostic {
+  /** JSON pointer, e.g. `"/root/geometry/2/body/0/w"`. */
+  path: string
+  code:
+    | "schema"
+    | "bad-expression"
+    | "unknown-name"
+    | "unknown-def"
+    | "cycle"
+    | "duplicate-name"
+    | "unbounded-repeat"
+    | "depth"
+    | "bad-dimension"
+    | "proportion"
+  message: string
+  hint?: string
+}
+
+/** What `prepare` reports. */
+export interface PluginFamilyPrepareResult {
+  /** `false` means the spec was rejected — read `errors`, fix, re-prepare. */
+  ok: boolean
+  familyId?: string
+  version?: number
+  label?: string
+  /** How many parts the family built. Sanity-check against intent. */
+  partCount?: number
+  /** Extents in Snaptrude units. Sanity-check against intent. */
+  bbox?: PluginFamilyBBox
+  evalMs?: number
+  parameters?: PluginFamilyParameter[]
+  /** Computed quantities, when the spec declares a `takeoff` block. */
+  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. */
+  error?: string
+}
+
+/**
+ * The host's diff of what a flex did to the geometry. This is the evidence that
+ * a family is parametric.
+ */
+export interface PluginFamilyChangeBuckets {
+  added: number
+  removed: number
+  moved: number
+  rebuilt: number
+  addedNames: string[]
+  removedNames: string[]
+}
+
+/** What `flex` reports. */
+export interface PluginFamilyFlexResult {
+  ok: boolean
+  /** The RESOLVED values after merge + clamping — not necessarily what was sent. */
+  values?: Record<string, number | string>
+  partCount?: number
+  bbox?: PluginFamilyBBox
+  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
+}
+
+/** One family available to place — from the session registry or the catalog. */
+export interface PluginFamilySummary {
+  id: string
+  version: number
+  label: string
+  category?: string
+  /** Number of rows on the family's parameter sheet. */
+  parameters: number
+  /**
+   * Where the family came from, which decides how far you can edit it.
+   *
+   * `"native"` — authored from a JSON spec through this API. Its recipe is
+   * data, so every parameter genuinely re-runs the geometry.
+   *
+   * `"revit"` — imported from a Revit family. Parameters exist and are
+   * editable, but only those the importer could bind to geometry actually
+   * change the mesh; the rest are carried for round-tripping. Check
+   * `drivesGeometry` on the parameter before promising the user a change.
+   */
+  kind: "native" | "revit"
+}
+
+/** What `place` reports. */
+export interface PluginFamilyPlaceResult {
+  ok: boolean
+  familyId?: string
+  version?: number
+  /**
+   * The created component — present ONLY when `position` was given. In
+   * interactive mode nothing exists yet, so there is nothing to hand back;
+   * the user has not clicked.
+   */
+  component?: ComponentHandle
+  error?: string
+}
+
+/** A placed component's parameter state, from `getParameters` / `setParameters`. */
+export interface PluginFamilyInstanceParameters {
+  /** The definition this instance is pinned to. */
+  familyId: string
+  version: number
+  label: string
+  /** Current values, keyed by parameter key. */
+  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. */
+export interface PluginFamilyCreateResult {
+  ok: boolean
+  definitionId?: string
+  version?: number
+  guid?: string
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// Argument schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * A spec bundle as it crosses the boundary: `root` plus optional `deps`.
+ *
+ * Loose by design — the spec grammar is a data DSL validated by the host's own
+ * validator, which returns JSON-pointer diagnostics far more useful than a Zod
+ * shape error. This schema only guarantees the envelope is an object.
+ */
+export const PluginFamilyBundleSchema = z.object({
+  root: z.record(z.string(), z.unknown()),
+  deps: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+})
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.prepare}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.flex}.
+ *
+ * | 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>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Library name; defaults to the spec's own label |
+ * | `teamId` | `string` | Team library to save into; omit for personal |
+ */
+export const PluginDesignFamilyCreateArgs = z.object({
+  name: z.string().optional(),
+  teamId: z.string().optional(),
+})
+export type PluginDesignFamilyCreateArgs = z.infer<typeof PluginDesignFamilyCreateArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Family to place, from {@linkcode PluginDesignFamilyApi.list}. Omit to place the prepared draft |
+ * | `version` | `number` | Exact version; defaults to the newest known |
+ * | `position` | `{ x, y, z }` | Place HERE, without user interaction. Omit to arm the cursor instead |
+ * | `rotation` | `number` | Yaw in degrees about +Y. Only with `position` |
+ * | `values` | `Record<string, number \| string>` | Parameter values for THIS instance |
+ * | `storey` | `number` | Storey to place on; defaults to the active one |
+ */
+export const PluginDesignFamilyPlaceArgs = z.object({
+  id: z.string().optional(),
+  version: z.number().int().positive().optional(),
+  position: Vec3Components.optional(),
+  rotation: z.number().optional(),
+  values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginDesignFamilyPlaceArgs = z.infer<typeof PluginDesignFamilyPlaceArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.getParameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | A placed parametric component |
+ */
+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
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.setParameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | A placed parametric component |
+ * | `values` | `Record<string, number \| string>` | Values to change (partial) |
+ */
+export const PluginDesignFamilySetParametersArgs = z.object({
+  component: ComponentHandle,
+  values: z.record(z.string(), z.union([z.number(), z.string()])),
+})
+export type PluginDesignFamilySetParametersArgs = z.infer<
+  typeof PluginDesignFamilySetParametersArgs
+>

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 { PluginDesignFamilyApi } from "./family"
 import { PluginDesignGridsApi } from "./grids"
 import { PluginDesignChangeResult } from "./lock"
 
@@ -34,6 +35,7 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@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)
  * - {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea} / {@linkcode PluginDesignApi.isAreaLocked} / {@linkcode PluginDesignApi.listAreaLocked} — footprint-area lock for Room/Department spaces
  *
@@ -72,6 +74,8 @@ export abstract class PluginDesignApi {
   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
@@ -266,4 +270,5 @@ export * from "./update"
 export * from "./visibility"
 export * from "./dimensions"
 export * from "./types"
+export * from "./family"
 export * from "./grids"

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

@@ -42,6 +42,7 @@ import { PluginDesignQueryGridsApi } from "./grids"
  * | `"curtainWall"` | Parametric curtain wall |
  * | `"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([
@@ -62,6 +63,7 @@ export const PluginEntityType = z.enum([
   "curtainWall",
   "mullion",
   "panel",
+  "parametricComponent",
   "grid",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>