@snaptrude/plugin-core 0.10.0 → 1.0.0

package/src/api/design/family.ts

@@ -0,0 +1,1342 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import {
+  BrepHandle,
+  ComponentHandle,
+  Vec3Components,
+  Vec3Handle,
+} from "../../handles"
+import { NetworkFamilyContract } from "./networks"
+
+/**
+ * `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.
+ *
+ * ## Generic component workflow
+ *
+ * ```
+ * getReference()        read the spec DSL once — grammar, ops, expressions, examples
+ * getExamples()         worked example families by discipline; getExamples({ id }) for one
+ * prepare({ bundle })   validate + compile; nothing committed, nothing in the viewport
+ * flex({ values })      re-run at new values; returns the geometry delta
+ * place({ position })   put it in the model — saves the family as the first instance drops
+ * place()               save the family, then arm placement — the USER clicks to drop it
+ * create()              save an EDIT of a saved family — the app asks the user
+ * create({ teamId })    share with a team; a save with nothing placed also drops one instance
+ * ```
+ *
+ * `place` saves the prepared family to the library, so it survives reload with no extra step:
+ * the open project's team library in a team project, else the user's personal library
+ * (`teamId` picks another: a team's id, or `null` for the personal library); finish a NEW generic component on
+ * `place`, not on `create` (`create` ends only an edit of a saved family, below).
+ *
+ * Architectural types use `create({ name })` to save the prepared recipe.
+ * Saving does not assign a family to a native host.
+ * Read `design.catalog` and pass the saved `{ id, version }` reference to the
+ * native `design.create` method with its contour, wall profile, or straight axis.
+ * Standalone placement does not create a native host. Selecting a Draw type
+ * does not register an API type. Native creator values use mm, while this
+ * generic family API uses SU. Read `family_authoring` for the full workflow.
+ *
+ * ## Door and window templates
+ *
+ * Start with `getTemplate({ kind: "door" | "window", subType? })`, edit the
+ * recipe's style while keeping its contract, then `prepare` → `flex` → `create`.
+ * Place the saved family with
+ * `design.create.door(familyId, hostWall, position, { version, values, hinge }, facing)`
+ * or `design.create.window` with the same positional signature. Positions,
+ * hinge and facing are vec3 handles; values use the authored parameter keys.
+ * Templates produce ParametricComponents, not separate OpeningComponents. Read
+ * and edit their instances through `getParameters` / `setParameters`.
+ * The contract maps opening dimensions to parameter keys; do not assume the
+ * recipe names its width parameter `width`. Generic family lengths use SU.
+ * Hosted door/window `create({ name })` saves without placing a standalone
+ * sample. Supply the host and position in a subsequent placement.
+ *
+ * ## Changing a saved family
+ *
+ * Open it with `get({ id })` or `get({ component })`, edit with `prepare` /
+ * `flex`, then `create()`. The app — not the agent — asks the user whether to
+ * update that family (this project's placed copies move to the new version) or
+ * save a new family. Do not ask this yourself; report the returned `decision`.
+ *
+ * ## 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,
+ * the same unit `core.units.getBabylonType()` names and every geometry API
+ * takes; literals inside spec expressions 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.
+ *
+ * ## Curved parts are exact
+ *
+ * A part whose sketch has a curved edge — any `revolve`, or an `extrude` /
+ * `sweep` / `loft` with an arc or circle in its profile (or an arc in a sweep
+ * path) — is built by the exact geometry kernel, the same one behind curved
+ * masses. Straight-edged parts keep the fast mesh builder. `getParameters` on a
+ * placed component reports which built each part in `parts[].engine`, and a
+ * kernel part carries a `brep`: read it with `core.geom.query.brep.*` and
+ * `core.geom.query.face.getSurfaceKind` — the same face-kind check as for a
+ * curved mass. If the kernel is unavailable a part falls back to the mesh
+ * builder (`engine: "mesh"`) rather than failing the family.
+ *
+ * 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.
+   *
+   * @param args Optional section, or its bare name. Omit for the core reference.
+   * Fetch architectural, networks or relations only when the family needs them.
+   * @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(
+    args?: PluginDesignFamilyGetReferenceArgs | PluginFamilyReferenceSection,
+  ): PluginApiReturn<PluginFamilyReference>
+
+  /**
+   * Worked example families to learn from: real, tested bundles by discipline
+   * (architecture, structure, MEP, furniture). With no `id`, returns the
+   * catalogue — each example's id, label, discipline and the patterns it
+   * teaches — filtered by `discipline` / `tag` when given. With an `id`,
+   * returns that example's full bundle. Fetch the one closest to the task
+   * before authoring and borrow its patterns; examples are patterns to
+   * combine, not templates to copy whole.
+   *
+   * @param args - `{ id }` for one bundle, or `{ discipline?, tag? }` to list
+   * @returns The catalogue, or one example with its bundle
+   *
+   * @examplePrompt Show me an example of a structural family
+   * @examplePrompt How is a hosted door family written?
+   *
+   * # Example
+   * ```ts
+   * const list = await snaptrude.design.family.getExamples({ discipline: "mep" })
+   * const ex = await snaptrude.design.family.getExamples({ id: list[0].id })
+   * ```
+   */
+  public abstract getExamples(
+    args?: PluginDesignFamilyGetExamplesArgs | string,
+  ): PluginApiReturn<PluginFamilyExampleSummary[] | PluginFamilyExample>
+
+  /**
+   * Get a validated starter recipe for a door or window, with an opening
+   * contract, host wall-thickness binding and role-named parts. Edit profiles,
+   * panels, glazing, hardware and materials while preserving the contract.
+   * Use `prepare` / `flex` to check the recipe, then `create` to save it and
+   * `design.create.door(familyId, hostWall, position, { version, values }, facing)`
+   * (or `window`) to place it. Edit the resulting ParametricComponent through
+   * `getParameters` / `setParameters`, not a separate opening API.
+   *
+   * `subType` defaults to `singleDoor` / `fixedWindow`. An unsupported subType
+   * returns the kind's default template, a note in `guidance`, and `available`
+   * templates. Start from the closest recipe and set `root.subType` to your token.
+   *
+   * @param args The opening kind and optional subtype token
+   * @returns The bundle, parameter-key contract, subtype, guidance and available templates
+   * @example
+   * const { bundle, contract } = await snaptrude.design.family.getTemplate({
+   *   kind: "door", subType: "doubleDoor",
+   * })
+   * // Flex the authored width key, not an assumed parameter name (lengths in SU).
+   * await snaptrude.design.family.prepare({ bundle })
+   * await snaptrude.design.family.flex({ values: { [contract.width]: 4 } })
+   */
+  public abstract getTemplate(
+    args: PluginDesignFamilyGetTemplateArgs,
+  ): PluginApiReturn<PluginFamilyTemplateResult>
+
+  /**
+   * Validate, compile and preview a family spec. Nothing is committed to the
+   * model or the library — call {@linkcode PluginDesignFamilyApi.place} to put
+   * it in the model, which also saves it.
+   *
+   * 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.
+   *
+   * Lengths — the spec's bare numbers, `bbox`, the sheet's `length` values — are
+   * Snaptrude units: the same 254 mm unit as the kernel's internal (`"babylon"`)
+   * unit. A unit suffix (`600mm`) is legal only inside a spec expression.
+   *
+   * @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
+   * @examplePrompt Make a pendant lamp family with a domed shade I can resize
+   *
+   * # 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. Omit values (or pass an empty
+   * record) to report or photograph the current draft without rebuilding it.
+   * @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>
+
+  /**
+   * A family's spec bundle: the prepared draft's, or — to CHANGE a saved
+   * family — that family's recipe, opened as the new draft.
+   *
+   * - No arguments: the prepared draft, or `null` when nothing is prepared.
+   * - `{ id, version? }`: open a saved family from the library (newest version
+   *   when `version` is omitted).
+   * - `{ component }`: open the family (at its version) of that placed copy.
+   *
+   * Opening makes the recipe the current draft and returns `editing` — which
+   * saved family it is. Edit it with `prepare` / `flex`, then call `create`.
+   * On that save the APP shows the user its own window asking whether to
+   * update the family (every placed copy in this project moves to the new
+   * version) or save it as a new family — "new family" is the default. Never
+   * ask the user this yourself, and never promise either outcome: report what
+   * `create` returns.
+   *
+   * @param args Optional: which saved family to open
+   * @returns The bundle (plus `editing` when it edits a saved family), or `null`
+   *
+   * @examplePrompt Make the chairs I placed 50 mm wider
+   * @examplePrompt Change the Louvre Screen family so its blades are deeper
+   *
+   * # Example
+   * ```ts
+   * const draft = await snaptrude.design.family.get()
+   * const family = await snaptrude.design.family.get({ component })
+   * // family.editing → { familyId, version, name, library }
+   * ```
+   */
+  public abstract get(
+    args?: PluginDesignFamilyGetArgs | string,
+  ): PluginApiReturn<PluginFamilyGetResult | null>
+
+  /**
+   * Every available parametric family, merging the session registry and catalog.
+   *
+   * @param args Opt into compact lines for generic discovery. The default stays
+   * object-shaped so existing callers retain version, openingKind and subType.
+   * @returns Summary objects, or `id | label | category | kind` lines when compact.
+   *
+   * @examplePrompt What families are available?
+   *
+   * # Example
+   * ```ts
+   * const families = await snaptrude.design.family.list()
+   * ```
+   */
+  public abstract list(
+    args: PluginDesignFamilyListArgs & { compact: true },
+  ): PluginApiReturn<string[]>
+  public abstract list(
+    args?: PluginDesignFamilyListArgs & { compact?: false },
+  ): PluginApiReturn<PluginFamilySummary[]>
+  public abstract list(
+    args?: PluginDesignFamilyListArgs,
+  ): PluginApiReturn<PluginFamilySummary[] | string[]>
+
+  /**
+   * Read one saved catalog definition without opening a draft or placing geometry.
+   * Both id and version are required. The catalog checks access on every read.
+   * Length defaults and bounds are in mm, ready for network graph overrides;
+   * angle parameters retain degrees, identified by each parameter's unit.
+   * existing getParameters/place/setParameters continue to use Snaptrude units.
+   * Defaults include current catalog overrides, which can change without a new version.
+   * No scene, registry, history, or persistence state is changed.
+   * Missing/inaccessible pins and invalid recipes fail; no latest-version fallback.
+   * This metadata does not certify connectors or engineering compatibility.
+   *
+   * @param args Exact saved catalog id and version, from list()
+   * @returns Compact parameter metadata, not geometry or the recipe bundle
+   * @example
+   * const definition = await snaptrude.design.family.getDefinition({ id, version })
+   */
+  public abstract getDefinition(
+    args: PluginDesignFamilyGetDefinitionArgs,
+  ): PluginApiReturn<PluginFamilyDefinition>
+
+  /**
+   * Put a family into the model — either the prepared draft or any family from
+   * {@linkcode PluginDesignFamilyApi.list}.
+   *
+   * Placing the prepared draft saves it to the library first, so its instances survive
+   * reload: the open project's team library in a team project, else the user's personal
+   * library. `teamId` picks another (`null` is the personal library).
+   *
+   * 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.
+   *
+   * HOSTED families (doors, windows — anything with an `opening`, a `host`
+   * block, or a void with `cuts: "host"`) take `host`: a wall or a placed
+   * family. The family is set into the host's face nearest `position` (the
+   * host's middle when omitted), and the host is cut — a system wall by the
+   * wall cutter, a family by its own recipe. Host-bound parameters then follow
+   * the host (a door's wall thickness follows the wall).
+   *
+   * @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 })
+   *
+   * // on the first floor — position.y is an offset above storey 2's base
+   * await snaptrude.design.family.place({ id: familyId, position: { x: 4, y: 0, z: 0 }, storey: 2 })
+   *
+   * // interactive — the user clicks
+   * await snaptrude.design.family.place()
+   *
+   * // hosted — a door in a wall, near a point along it
+   * await snaptrude.design.family.place({ id: doorId, host: wall, position: { x: 3, y: 0, z: 0 } })
+   * ```
+   */
+  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.
+   *
+   * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
+   * internal (`"babylon"`) unit — convert with `core.units.convert` to report.
+   *
+   * @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.
+   *
+   * NESTED children: `children: { "<path>": { key: value } }` sets a nested
+   * child's own values (every copy of it). A value its parent sets is sent up
+   * to what it follows when that is a plain relationship; otherwise it is
+   * refused with what to change instead (see `refused`).
+   *
+   * LINKS: `links: { key: { from, expr } }` makes this family's `key` follow
+   * another placed object — `from` is a family (it reports its parameters and
+   * outputs) or a wall (it reports thickness, length, height); `expr` is an
+   * expression over those reports. `null` removes a link. Links that would
+   * make objects follow each other in a loop are refused. Values accept unit
+   * literals ("600mm").
+   *
+   * RELATIONS: `relations: { add: [...], remove: ["r1"] }` sets how the family
+   * sits against other placed objects or cuts its host:
+   * - `attach` — `{ kind: "attach", side: "base" | "top", to: <object> | { level, face? }, offset? }`:
+   *   sits on a surface, or its top reaches one (reports `reach`, `gap`, `surface`).
+   * - `join` — `{ kind: "join", end, to: <family>, toEnd, bindOther? }`: its end moves onto
+   *   the other's end (reports `angle`, `absAngle`, `mitre`).
+   * - `span` — `{ kind: "span", from, to, at? }`: pinned between two objects, running along
+   *   its +X (reports `distance`, `run`, `rise`, `slope`, `from.*`, `to.*`).
+   * - `path` — `{ kind: "path", from? | points, closed? }`: follows a wall's centreline, a
+   *   family's run or given points (reports `length`; the recipe reads the path).
+   * - `cut` — `{ kind: "cut", to: "host" }`: applies recipe voids to the current host.
+   *   Removing it closes the opening without detaching or deleting the family.
+   *   Door/window placement adds it. Hosting alone does not cut. No parameter binds.
+   * Placement relations take `bind: { <param>: "<expression over its reports>" }`; bound
+   * parameters are read-only. A relation with an existing `id` replaces it.
+   *
+   * `length` values are Snaptrude units: the same 254 mm unit as the kernel's
+   * internal (`"babylon"`) unit — convert the user's number with
+   * `core.units.convert` first; a bare `400` is 400 SU, not 400 mm. Kernel part
+   * breps read before the edit are stale: re-read `getParameters`.
+   *
+   * @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 } })
+   * await snaptrude.design.family.setParameters({ component, children: { chair: { width: "380mm" } } })
+   * await snaptrude.design.family.setParameters({
+   *   component: railing,
+   *   links: { steps: { from: stair, expr: "steps" }, side: { from: stair, expr: "width - 40mm" } },
+   * })
+   * await snaptrude.design.family.setParameters({
+   *   component: post,
+   *   relations: { add: [{ kind: "attach", side: "top", to: slab, bind: { height: "reach" } }] },
+   * })
+   * ```
+   */
+  public abstract setParameters(
+    args: PluginDesignFamilySetParametersArgs,
+  ): PluginApiReturn<PluginFamilyInstanceParameters>
+
+  /**
+   * Save the prepared bundle to the library: the open project's team library in a team
+   * project, else the user's personal library. `teamId` picks another team, and `null` the
+   * personal library. {@linkcode PluginDesignFamilyApi.place} already
+   * saves generic components. Hosted doors/windows save without placement;
+   * they need a wall and position through `design.create.door` / `design.create.window`.
+   * For a non-hosted family with no placed instance, saving also drops one
+   * standalone sample at the current view centre on the active storey
+   * (`placed: true`). This includes architectural families: the sample does
+   * not assign a family to a native host.
+   *
+   * When the draft edits a saved family (opened with `get({ id })` /
+   * `get({ component })`), or its name is already taken in that library, the
+   * APP asks the user in its own window whether to save a new version of that
+   * family — every placed copy in this project moves to it, and families
+   * nesting it may be offered theirs — or a new family ("new family" is the
+   * default). The agent never asks this itself and cannot answer the window.
+   * `decision` reports what the user chose; `"cancelled"` means nothing was
+   * saved (`ok: false`) and nothing will auto-save until `create` is called again.
+   *
+   * @param args Optional library name and team scope
+   * @returns The catalogued definition's id and version, and what the user chose
+   *
+   * @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>
+
+  /**
+   * Remove a family from the library: its catalog row is archived, so it
+   * leaves the Families panel. Placed instances are untouched — in this
+   * project and every other — because archived pins keep resolving. Pass
+   * `instances: true` to ALSO delete this project's instances in one undoable
+   * command; do that only when the user asks for the instances to go.
+   *
+   * Omit `id` to target the prepared draft. `id` may be a draft id, a saved
+   * catalog id, or any family from `list()`.
+   *
+   * @param args Optional family id, and whether to delete instances too
+   * @returns Whether a library row was archived and how many instances were removed
+   *
+   * @examplePrompt Delete the Louvre Screen family from my library
+   * @examplePrompt Get rid of that bollard and every copy of it in here
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.family.delete({ id: "revit:steel-bollard~bef047" })
+   * await snaptrude.design.family.delete({ id: "revit:steel-bollard~bef047", instances: true })
+   * ```
+   */
+  public abstract delete(
+    args?: PluginDesignFamilyDeleteArgs | string,
+  ): PluginApiReturn<PluginFamilyDeleteResult>
+}
+
+/** Optional reference sections keep unrelated grammar out of the core response. */
+export const PluginFamilyReferenceSection = z.enum([
+  "architectural",
+  "networks",
+  "relations",
+])
+export type PluginFamilyReferenceSection = z.infer<
+  typeof PluginFamilyReferenceSection
+>
+
+/** Omit section for the core grammar, workflow and example catalogue. */
+export const PluginDesignFamilyGetReferenceArgs = z.object({
+  section: PluginFamilyReferenceSection.optional(),
+})
+export type PluginDesignFamilyGetReferenceArgs = z.infer<
+  typeof PluginDesignFamilyGetReferenceArgs
+>
+
+/** Compact output is opt-in: existing object consumers must retain their metadata. */
+export const PluginDesignFamilyListArgs = z.object({
+  compact: z.boolean().optional(),
+})
+export type PluginDesignFamilyListArgs = z.infer<
+  typeof PluginDesignFamilyListArgs
+>
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/** One worked example in the catalogue returned by `getExamples`. */
+export interface PluginFamilyExampleSummary {
+  id: string
+  label: string
+  discipline: "architecture" | "structure" | "mep" | "furniture"
+  /** The patterns it demonstrates, e.g. "nesting", "slot", "path", "union", "trim". */
+  teaches: string[]
+  /** Size of the bundle as compact JSON, kilobytes — what fetching it costs. */
+  sizeKB: number
+}
+
+/** One worked example with its full bundle, from `getExamples({ id })`. */
+export interface PluginFamilyExample extends PluginFamilyExampleSummary {
+  bundle: PluginFamilyBundle
+}
+
+/** 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>>
+  /** Connector metadata saved with the recipe; network placement evaluates these expressions. */
+  network?: NetworkFamilyContract
+}
+
+/** Which saved family a draft edits. */
+export interface PluginFamilyEditing {
+  /** Library id of the family being edited. */
+  familyId: string
+  /** The version that was opened. */
+  version: number
+  /** Its library name — an update saves under this name. */
+  name: string
+  /** "your library", or the team library's name. */
+  library: string
+}
+
+/** What `get` returns: the bundle, plus `editing` when the draft edits a saved family. */
+export interface PluginFamilyGetResult extends PluginFamilyBundle {
+  editing?: PluginFamilyEditing
+}
+
+/** A family at a version, as `create` reports parents it did or did not update. */
+export interface PluginFamilyVersionRef {
+  id: string
+  name: string
+  version: number
+  /** Set when the user chose to update it but the update failed. */
+  error?: string
+}
+
+/** 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` (Snaptrude units) and `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"
+    /** A part the geometry kernel could not build exactly; drawn approximately. */
+    | "kernel-fallback"
+    /** A part whose hole loop crosses its outline. */
+    | "profile-hole"
+  message: string
+  hint?: string
+}
+
+/**
+ * One placed part and which engine built it, from `getParameters`. `"kernel"` —
+ * a curved sketch built exactly; `"mesh"` — straight-edged, or the kernel
+ * fallback.
+ */
+export interface PluginFamilyPart {
+  name: string
+  engine: "kernel" | "mesh"
+  /**
+   * Kernel parts only: the part's exact solid, for `core.geom.query.brep.*` /
+   * `core.geom.query.face.getSurfaceKind`. READ-ONLY and PART-LOCAL — in the
+   * part's own frame, not where the component sits, so never pass it to a
+   * boolean or `design.create.massFromBrep` (a family changes only through
+   * `setParameters`). Valid until the next parameter change: re-read
+   * `getParameters` after `setParameters`.
+   */
+  brep?: BrepHandle
+}
+
+/** 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
+  /** The category's type token (`root.subType`), e.g. singleDoor or casementDouble. */
+  subType?: string
+  /**
+   * Opening contract kind, distinct from provenance (`kind`). Place with the
+   * positional `design.create.door` / `window` API and edit via family parameters.
+   */
+  openingKind?: "door" | "window"
+  /** 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"
+}
+
+/** Exact catalog pin. Unsaved session definitions are not catalog inventory. */
+export const PluginDesignFamilyGetDefinitionArgs = z.object({
+  id: z.string().min(1),
+  version: z.number().int().positive(),
+})
+export type PluginDesignFamilyGetDefinitionArgs = z.infer<
+  typeof PluginDesignFamilyGetDefinitionArgs
+>
+
+/** Saved-family metadata. Physical lengths use mm; angle entries retain degrees. */
+export const PluginFamilyDefinitionParameter = z.object({
+  key: z.string(),
+  label: z.string(),
+  type: z.enum(["length", "integer", "enum", "text", "boolean"]),
+  /** Angles use the legacy length type. Check unit before interpreting numeric values. */
+  unit: z.enum(["mm", "degrees"]).optional(),
+  default: z.union([z.number().finite(), z.string()]),
+  min: z.number().finite().optional(),
+  max: z.number().finite().optional(),
+  options: z.array(z.string()).optional(),
+  drivesGeometry: z.boolean(),
+  readOnly: z.boolean(),
+  formulaDriven: z.boolean(),
+  /** False means shared/type: placement cannot change it for one instance. */
+  isInstance: z.boolean(),
+})
+export type PluginFamilyDefinitionParameter = z.infer<
+  typeof PluginFamilyDefinitionParameter
+>
+
+/** Read-only catalog inventory. Boolean defaults retain the family DSL's Yes/No strings. */
+export const PluginFamilyDefinition = z.object({
+  id: z.string(),
+  version: z.number().int().positive(),
+  label: z.string(),
+  category: z.string().optional(),
+  lengthUnit: z.literal("mm"),
+  parameters: z.array(PluginFamilyDefinitionParameter),
+  /** Pinned connector metadata. Absence means this family cannot build a topology network. */
+  network: NetworkFamilyContract.optional(),
+})
+export type PluginFamilyDefinition = z.infer<typeof PluginFamilyDefinition>
+
+/** 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[]
+  /** The placed parts; kernel parts carry their exact `brep`. */
+  parts?: PluginFamilyPart[]
+  /** Present when `getParameters` was asked for a `snapshot`. */
+  snapshot?: PluginFamilySnapshot
+  /** The family's `outputs`, as last built. */
+  reports?: Record<string, number | string>
+  /** Every declared nested child, as last built. */
+  children?: PluginFamilyNestedChild[]
+  /** Parameters that follow another object (links) or the host. */
+  follows?: PluginFamilyFollow[]
+  /** Where a hosted family sits: a system wall, or a family by id. */
+  host?: ({ kind: "wall" } | { kind: "family"; id: string }) & {
+    /** True when the host no longer has room for it: it is out of the model until it fits again. */
+    parked?: boolean
+  }
+  /** Guests hosted in THIS family that no longer fit it (parked); they return when they fit. */
+  parkedGuests?: { id: string; family: string }[]
+  /** How it sits against other placed objects (attach, join, span, path), with current reports. */
+  relations?: PluginFamilyRelation[]
+  /** setParameters only: the edits refused, each with what to change instead. */
+  refused?: string[]
+}
+
+/** A nested child of a placed family. */
+export interface PluginFamilyNestedChild {
+  /** "chair", or "chair/cushion" for a child of a child — the key for `children` edits. */
+  path: string
+  label: string
+  /** The family it is now (a slot's current pick). */
+  family: string
+  familyLabel: string
+  /** How many copies the parent places. */
+  copies: number
+  slot?: { expr: string; options: string[] }
+  values: Record<string, number | string>
+  /** Values the parent sets, with the expression it sets them by. */
+  setBy: Record<string, string | undefined>
+  reports: Record<string, number | string>
+}
+
+/** A placed relation as stored, plus what it measures now. */
+export type PluginFamilyRelation = PluginFamilyRelationInput & {
+  id: string
+  /** "Attached to", "Joins", "Spans between", "Along a path", "Cuts host". */
+  label: string
+  summary: string
+  /** False when a target is gone: the family stayed where it was. */
+  live: boolean
+  reports: Record<string, number | string>
+}
+
+/** One relation to add (`relations.add`). Targets are handles, except a cut's symbolic "host". */
+export type PluginFamilyRelationInput = {
+  /** Replaces the relation with this id; a new one gets "r1", "r2"… */
+  id?: string
+  /** This family's parameter → an expression over the relation's reports and own parameters. */
+  bind?: Record<string, string>
+} & (
+  | {
+      kind: "attach"
+      side: "base" | "top"
+      to: ComponentHandle | { level: number; face?: "base" | "top" }
+      offset?: number
+    }
+  | {
+      kind: "join"
+      end: "start" | "end"
+      to: ComponentHandle
+      toEnd: "start" | "end"
+      /** The other family's parameters, over the same reports. */
+      bindOther?: Record<string, string>
+    }
+  | {
+      kind: "span"
+      from: ComponentHandle
+      to: ComponentHandle
+      at?: "top" | "centre" | "base"
+    }
+  | {
+      kind: "path"
+      from?: ComponentHandle
+      points?: [number, number, number][]
+      closed?: boolean
+    }
+  | {
+      /** Apply recipe voids to the existing host without adding another host ID. */
+      kind: "cut"
+      to: "host"
+      bind?: never
+    }
+)
+
+/** One parameter that follows something else. */
+export interface PluginFamilyFollow {
+  key: string
+  /** "relation": set by a placed relation — `from` is the relation's id. */
+  kind: "link" | "host" | "relation"
+  /** The source's id. */
+  from: string
+  fromLabel: string
+  /** The expression over the source's reports (for a host: the report name). */
+  expr: string
+}
+
+/** What `create` reports. */
+export interface PluginFamilyCreateResult {
+  ok: boolean
+  definitionId?: string
+  version?: number
+  guid?: string
+  /** True when the save also dropped one instance into the model (nothing was placed yet). */
+  placed?: boolean
+  /** Host guidance for the caller, e.g. that an instance was placed at the view centre. */
+  hint?: string
+  /**
+   * What the user chose in the app's window: `"version"` (a new version of
+   * the saved family), `"new"` (a new family), `"cancelled"` (nothing saved).
+   * `"saved"` = no question was needed.
+   */
+  decision?: "version" | "new" | "cancelled" | "saved"
+  /** The library name it was saved under. */
+  name?: string
+  /** Placed copies in this project moved to the new version (the family's and updated parents'). */
+  movedCopies?: number
+  /** What the moved copies lost because the new version no longer has it. */
+  dropped?: {
+    values: Array<{ copy: string; key: string }>
+    childValues: Array<{ copy: string; path: string }>
+    follows: Array<{ copy: string; key: string; kind: "link" | "relation" }>
+  }
+  /** Families nesting this one that the user chose to update, at their new versions. */
+  parentsUpdated?: PluginFamilyVersionRef[]
+  /** Families nesting this one that keep their version. */
+  parentsKept?: PluginFamilyVersionRef[]
+  error?: string
+}
+
+/** What `delete` reports. */
+export interface PluginFamilyDeleteResult {
+  ok: boolean
+  familyId?: string
+  /** Instances deleted from the scene (only with `instances: true`), in one undoable command. */
+  removedInstances?: number
+  /** True when a library row was archived; false for an unsaved draft. */
+  archived?: boolean
+  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(),
+  network: NetworkFamilyContract.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.
+ *
+ * `focus` makes it a close-up: `{ parts: ["seat", "back", "slat@*"] }` frames
+ * the joint where those groups meet (`*` matches any run of characters;
+ * nested names are `a/b`), or their full bounds if they do not meet. A margin
+ * of a quarter of their size (at least 50 mm) surrounds the joint.
+ * `{ box: { min, max } }` frames a region in family space
+ * (Snaptrude units, +Y up). Every other part is still drawn; the dimension line
+ * then gives the framed region and the result says `closeUp: true`. A part
+ * name that matches nothing fails the snapshot with a list of real names.
+ */
+export const PluginFamilySnapshotFocus = z.union([
+  z.object({ parts: z.array(z.string().min(1)).min(1) }),
+  z.object({
+    box: z
+      .object({
+        min: z.tuple([
+          z.number().finite(),
+          z.number().finite(),
+          z.number().finite(),
+        ]),
+        max: z.tuple([
+          z.number().finite(),
+          z.number().finite(),
+          z.number().finite(),
+        ]),
+      })
+      .refine(
+        ({ min, max }) => min.every((value, axis) => value <= max[axis]),
+        {
+          message: "Each minimum must be at or below its maximum",
+        },
+      ),
+  }),
+])
+export type PluginFamilySnapshotFocus = z.infer<
+  typeof PluginFamilySnapshotFocus
+>
+
+/** One close-up tile; omission of view uses the sheet's first view. */
+export const PluginFamilySnapshotCloseUp = z.intersection(
+  PluginFamilySnapshotFocus,
+  z.object({ view: z.enum(["iso", "front", "right", "top"]).optional() }),
+)
+export type PluginFamilySnapshotCloseUp = z.infer<
+  typeof PluginFamilySnapshotCloseUp
+>
+
+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(),
+    /** One focus across views, or 1–6 independent close-up tiles in one image. */
+    focus: z
+      .union([
+        PluginFamilySnapshotFocus,
+        z.array(PluginFamilySnapshotCloseUp).min(1).max(6),
+      ])
+      .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 SU. For a close-up list, this remains the whole family's size. */
+  size?: [number, number, number]
+  ms?: number
+  /** True when the sheet is a close-up (`focus`), not the whole family. */
+  closeUp?: boolean
+  /** Per-tile results for a focus list. One invalid target does not discard other tiles. */
+  closeUps?: Array<{
+    view: "iso" | "front" | "right" | "top"
+    label: string
+    size?: [number, number, number]
+    error?: string
+  }>
+  /** 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>` | Optional sparse changes; omission does not rebuild |
+ * | `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()])).optional(),
+  snapshot: PluginFamilySnapshotOption.optional(),
+})
+export type PluginDesignFamilyFlexArgs = z.infer<
+  typeof PluginDesignFamilyFlexArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.get}. All optional — no
+ * arguments returns the prepared draft.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | A saved family to open for editing, from {@linkcode PluginDesignFamilyApi.list} |
+ * | `version` | `number` | Exact version to open; defaults to the newest |
+ * | `component` | {@linkcode ComponentHandle} | Open the family of this placed copy, at its version |
+ */
+export const PluginDesignFamilyGetArgs = z.object({
+  id: z.string().optional(),
+  version: z.number().int().positive().optional(),
+  component: ComponentHandle.optional(),
+})
+export type PluginDesignFamilyGetArgs = z.infer<
+  typeof PluginDesignFamilyGetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.getExamples}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | One example's id — returns its bundle |
+ * | `discipline` | `string` | List only this discipline: architecture, structure, mep, furniture |
+ * | `tag` | `string` | List only examples teaching this pattern (e.g. "path", "union") |
+ */
+export const PluginDesignFamilyGetExamplesArgs = z.object({
+  id: z.string().optional(),
+  discipline: z
+    .enum(["architecture", "structure", "mep", "furniture"])
+    .optional(),
+  tag: z.string().optional(),
+})
+export type PluginDesignFamilyGetExamplesArgs = z.infer<
+  typeof PluginDesignFamilyGetExamplesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.getTemplate}.
+ * `kind` selects the opening contract. `subType` is a nonempty type token;
+ * omission selects singleDoor / fixedWindow. Unsupported tokens return the
+ * default template with guidance rather than preventing custom subtype authoring.
+ */
+export const PluginDesignFamilyGetTemplateArgs = z.object({
+  kind: z.enum(["door", "window"]),
+  subType: z.string().min(1).optional(),
+})
+export type PluginDesignFamilyGetTemplateArgs = z.infer<
+  typeof PluginDesignFamilyGetTemplateArgs
+>
+
+/**
+ * Maps opening dimensions to authored length parameter KEYS, not values.
+ * Width and height describe the wall hole; sill measures from the wall base
+ * to the hole bottom (windows). Wall thickness follows the host wall.
+ * The recipe and family parameter APIs use Snaptrude units (1 SU = 254 mm).
+ */
+export interface PluginFamilyOpeningContract {
+  kind: "door" | "window"
+  width: string
+  height: string
+  sill?: string
+  wallThickness?: string
+}
+
+/** Starter recipe metadata returned by `getTemplate`; instances are ParametricComponents. */
+export interface PluginFamilyTemplateResult {
+  /** Validated recipe bundle: edit its style while preserving the contract. */
+  bundle: PluginFamilyBundle
+  contract: PluginFamilyOpeningContract
+  /** Actual template subtype, including when an unsupported token used the default. */
+  subType: string
+  /** Authoring rules and any note about an unsupported requested subtype. */
+  guidance: string[]
+  /** Available starter templates for the requested kind. */
+  available: Array<{ subType: string; label: string; teaches: string[] }>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Library name; defaults to the spec's own label |
+ * | `teamId` | `string \| null` | Library to save into: a team's id, or `null` for the personal library. Omit for the open project's team library (personal in a personal project) |
+ */
+export const PluginDesignFamilyCreateArgs = z.object({
+  name: z.string().optional(),
+  teamId: z.string().nullable().optional(),
+})
+export type PluginDesignFamilyCreateArgs = z.infer<
+  typeof PluginDesignFamilyCreateArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFamilyApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Family to remove; omit for the prepared draft |
+ * | `instances` | `boolean` | Also delete this project's placed instances; default false |
+ */
+export const PluginDesignFamilyDeleteArgs = z.object({
+  id: z.string().optional(),
+  instances: z.boolean().optional(),
+})
+export type PluginDesignFamilyDeleteArgs = z.infer<
+  typeof PluginDesignFamilyDeleteArgs
+>
+
+/**
+ * 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` | `Vec3Handle` or `{ x, y, z }` | Place here in SU. Prefer a vec3 handle; coordinates remain for existing callers. Omit to arm the cursor |
+ * | `rotation` | `number` | Yaw in degrees about +Y. Only with `position` |
+ * | `values` | `Record<string, number \| string>` | Parameter values for THIS instance |
+ * | `storey` | `number` | Target storey (integer: 1 ground, 2 first floor, -1 basement; must already exist). The family is lifted to that storey's base and `position.y` is an offset above it, like `design.create.walls`. Without it, `position` is absolute and the storey is derived from where the family's geometry sits. Ignored with `host`: a hosted family follows its host |
+ * | `teamId` | `string \| null` | Library an unsaved draft saves to before it is placed: a team's id, or `null` for the personal library. Omit for the open project's team library (personal in a personal project). Ignored for a family already in a library |
+ */
+export const PluginDesignFamilyPlaceArgs = z.object({
+  id: z.string().optional(),
+  version: z.number().int().positive().optional(),
+  position: z.union([Vec3Handle, Vec3Components]).optional(),
+  rotation: z.number().optional(),
+  values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
+  storey: z.number().int().optional(),
+  /** Hosted families: wall or family host. Values apply before fit checks and cutting. */
+  host: ComponentHandle.optional(),
+  teamId: z.string().nullable().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()]))
+    .optional()
+    .default({}),
+  /** Nested children's own values: { "<path>": { key: value } }. */
+  children: z
+    .record(z.string(), z.record(z.string(), z.union([z.number(), z.string()])))
+    .optional(),
+  /** Links: { key: { from, expr } | null }. */
+  links: z
+    .record(
+      z.string(),
+      z.union([
+        z.object({ from: ComponentHandle, expr: z.string() }),
+        z.null(),
+      ]),
+    )
+    .optional(),
+  /** Placed relations: { add?: [{ kind, … }], remove?: ["r1"] } — checked by the host. */
+  relations: z
+    .object({
+      add: z.array(z.record(z.string(), z.unknown())).optional(),
+      remove: z.array(z.string()).optional(),
+    })
+    .optional(),
+})
+export type PluginDesignFamilySetParametersArgs = z.infer<
+  typeof PluginDesignFamilySetParametersArgs
+>