@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/dist/api/design/family.d.ts

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
 import { BrepHandle, ComponentHandle } from "../../handles";
+import { NetworkFamilyContract } from "./networks";
 /**
  * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
  *
@@ -11,19 +12,53 @@ import { BrepHandle, ComponentHandle } from "../../handles";
  * compiles that into a live parametric definition the user can place, flex and
  * save to their library.
  *
- * ## Workflow
+ * ## Generic component workflow
  *
  * ```
- * getReference()        read the spec DSL once — grammar, ops, expressions, example
- * prepare({ bundle })   validate + compile + show a live ghost; nothing committed
+ * 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 user's personal library, so it
- * survives reload with no extra step; finish on `place`, not on `create`.
+ * `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
  *
@@ -70,6 +105,8 @@ export declare abstract class PluginDesignFamilyApi {
      * 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?
@@ -80,7 +117,53 @@ export declare abstract class PluginDesignFamilyApi {
      * const { reference } = await snaptrude.design.family.getReference()
      * ```
      */
-    abstract getReference(): PluginApiReturn<PluginFamilyReference>;
+    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 })
+     * ```
+     */
+    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 } })
+     */
+    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
@@ -118,7 +201,8 @@ export declare abstract class PluginDesignFamilyApi {
      * 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
+     * @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
@@ -130,22 +214,44 @@ export declare abstract class PluginDesignFamilyApi {
      * console.log(`removed ${changed.removed}, rebuilt ${changed.rebuilt}`)
      * ```
      */
-    abstract flex(args: PluginDesignFamilyFlexArgs): PluginApiReturn<PluginFamilyFlexResult>;
+    abstract flex(args?: PluginDesignFamilyFlexArgs): PluginApiReturn<PluginFamilyFlexResult>;
     /**
-     * The prepared family's spec bundle, or `null` when nothing is prepared.
+     * 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.
      *
-     * @returns The draft bundle, or `null`
+     * @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 bundle = await snaptrude.design.family.get()
+     * const draft = await snaptrude.design.family.get()
+     * const family = await snaptrude.design.family.get({ component })
+     * // family.editing → { familyId, version, name, library }
      * ```
      */
-    abstract get(): PluginApiReturn<PluginFamilyBundle | null>;
+    abstract get(args?: PluginDesignFamilyGetArgs | string): PluginApiReturn<PluginFamilyGetResult | null>;
     /**
-     * Every parametric family registered in this session — native and imported.
+     * Every available parametric family, merging the session registry and catalog.
      *
-     * @returns One summary per family
+     * @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?
      *
@@ -154,13 +260,37 @@ export declare abstract class PluginDesignFamilyApi {
      * const families = await snaptrude.design.family.list()
      * ```
      */
-    abstract list(): PluginApiReturn<PluginFamilySummary[]>;
+    abstract list(args: PluginDesignFamilyListArgs & {
+        compact: true;
+    }): PluginApiReturn<string[]>;
+    abstract list(args?: PluginDesignFamilyListArgs & {
+        compact?: false;
+    }): PluginApiReturn<PluginFamilySummary[]>;
+    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 })
+     */
+    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 user's personal library first,
-     * so its instances survive reload.
+     * 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`:
      *
@@ -177,6 +307,13 @@ export declare abstract class PluginDesignFamilyApi {
      * 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
      *
@@ -194,8 +331,14 @@ export declare abstract class PluginDesignFamilyApi {
      * })
      * 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 } })
      * ```
      */
     abstract place(args?: PluginDesignFamilyPlaceArgs): PluginApiReturn<PluginFamilyPlaceResult>;
@@ -232,6 +375,34 @@ export declare abstract class PluginDesignFamilyApi {
      * 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
@@ -246,18 +417,40 @@ export declare abstract class PluginDesignFamilyApi {
      * # 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" } }] },
+     * })
      * ```
      */
     abstract setParameters(args: PluginDesignFamilySetParametersArgs): PluginApiReturn<PluginFamilyInstanceParameters>;
     /**
-     * Save the prepared bundle to the library — the user's personal library
-     * unless `teamId` is given. {@linkcode PluginDesignFamilyApi.place} already
-     * saves, so `create` is for sharing with a team. When nothing of the family is
-     * in the model yet, one instance is also dropped at the centre of the current
-     * view on the active storey (`placed: true`), so a save is never invisible.
+     * 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
+     * @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
@@ -290,7 +483,42 @@ export declare abstract class PluginDesignFamilyApi {
      * await snaptrude.design.family.delete({ id: "revit:steel-bollard~bef047", instances: true })
      * ```
      */
-    abstract delete(args?: PluginDesignFamilyDeleteArgs): PluginApiReturn<PluginFamilyDeleteResult>;
+    abstract delete(args?: PluginDesignFamilyDeleteArgs | string): PluginApiReturn<PluginFamilyDeleteResult>;
+}
+/** Optional reference sections keep unrelated grammar out of the core response. */
+export declare const PluginFamilyReferenceSection: z.ZodEnum<{
+    architectural: "architectural";
+    networks: "networks";
+    relations: "relations";
+}>;
+export type PluginFamilyReferenceSection = z.infer<typeof PluginFamilyReferenceSection>;
+/** Omit section for the core grammar, workflow and example catalogue. */
+export declare const PluginDesignFamilyGetReferenceArgs: z.ZodObject<{
+    section: z.ZodOptional<z.ZodEnum<{
+        architectural: "architectural";
+        networks: "networks";
+        relations: "relations";
+    }>>;
+}, z.core.$strip>;
+export type PluginDesignFamilyGetReferenceArgs = z.infer<typeof PluginDesignFamilyGetReferenceArgs>;
+/** Compact output is opt-in: existing object consumers must retain their metadata. */
+export declare const PluginDesignFamilyListArgs: z.ZodObject<{
+    compact: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginDesignFamilyListArgs = z.infer<typeof PluginDesignFamilyListArgs>;
+/** 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 {
@@ -309,6 +537,31 @@ export interface PluginFamilyReference {
 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 {
@@ -342,7 +595,11 @@ export interface PluginFamilyParameter {
 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";
+    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;
 }
@@ -422,6 +679,13 @@ export interface PluginFamilySummary {
     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;
     /**
@@ -437,6 +701,93 @@ export interface PluginFamilySummary {
      */
     kind: "native" | "revit";
 }
+/** Exact catalog pin. Unsaved session definitions are not catalog inventory. */
+export declare const PluginDesignFamilyGetDefinitionArgs: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDesignFamilyGetDefinitionArgs = z.infer<typeof PluginDesignFamilyGetDefinitionArgs>;
+/** Saved-family metadata. Physical lengths use mm; angle entries retain degrees. */
+export declare const PluginFamilyDefinitionParameter: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<{
+        boolean: "boolean";
+        enum: "enum";
+        length: "length";
+        text: "text";
+        integer: "integer";
+    }>;
+    unit: z.ZodOptional<z.ZodEnum<{
+        mm: "mm";
+        degrees: "degrees";
+    }>>;
+    default: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    drivesGeometry: z.ZodBoolean;
+    readOnly: z.ZodBoolean;
+    formulaDriven: z.ZodBoolean;
+    isInstance: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginFamilyDefinitionParameter = z.infer<typeof PluginFamilyDefinitionParameter>;
+/** Read-only catalog inventory. Boolean defaults retain the family DSL's Yes/No strings. */
+export declare const PluginFamilyDefinition: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+    label: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    lengthUnit: z.ZodLiteral<"mm">;
+    parameters: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            enum: "enum";
+            length: "length";
+            text: "text";
+            integer: "integer";
+        }>;
+        unit: z.ZodOptional<z.ZodEnum<{
+            mm: "mm";
+            degrees: "degrees";
+        }>>;
+        default: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        drivesGeometry: z.ZodBoolean;
+        readOnly: z.ZodBoolean;
+        formulaDriven: z.ZodBoolean;
+        isInstance: z.ZodBoolean;
+    }, z.core.$strip>>;
+    network: z.ZodOptional<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        role: z.ZodEnum<{
+            pipe: "pipe";
+            duct: "duct";
+            wire: "wire";
+            cable: "cable";
+            conduit: "conduit";
+            cableDuct: "cableDuct";
+            cableTray: "cableTray";
+            connector: "connector";
+            equipment: "equipment";
+        }>;
+        lengthParameter: z.ZodOptional<z.ZodString>;
+        ports: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            position: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+            direction: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+            size: z.ZodString;
+            height: z.ZodOptional<z.ZodString>;
+            widthDirection: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
+            systems: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type PluginFamilyDefinition = z.infer<typeof PluginFamilyDefinition>;
 /** What `place` reports. */
 export interface PluginFamilyPlaceResult {
     ok: boolean;
@@ -464,6 +815,108 @@ export interface PluginFamilyInstanceParameters {
     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 {
@@ -475,6 +928,36 @@ export interface PluginFamilyCreateResult {
     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. */
@@ -497,6 +980,30 @@ export interface PluginFamilyDeleteResult {
 export declare const PluginFamilyBundleSchema: z.ZodObject<{
     root: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     deps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    network: z.ZodOptional<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        role: z.ZodEnum<{
+            pipe: "pipe";
+            duct: "duct";
+            wire: "wire";
+            cable: "cable";
+            conduit: "conduit";
+            cableDuct: "cableDuct";
+            cableTray: "cableTray";
+            connector: "connector";
+            equipment: "equipment";
+        }>;
+        lengthParameter: z.ZodOptional<z.ZodString>;
+        ports: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            position: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+            direction: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+            size: z.ZodString;
+            height: z.ZodOptional<z.ZodString>;
+            widthDirection: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
+            systems: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.prepare}.
@@ -517,7 +1024,42 @@ export declare const PluginFamilyBundleSchema: z.ZodObject<{
  * 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 declare const PluginFamilySnapshotFocus: z.ZodUnion<readonly [z.ZodObject<{
+    parts: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    box: z.ZodObject<{
+        min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type PluginFamilySnapshotFocus = z.infer<typeof PluginFamilySnapshotFocus>;
+/** One close-up tile; omission of view uses the sheet's first view. */
+export declare const PluginFamilySnapshotCloseUp: z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+    parts: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    box: z.ZodObject<{
+        min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>;
+}, z.core.$strip>]>, z.ZodObject<{
+    view: z.ZodOptional<z.ZodEnum<{
+        top: "top";
+        front: "front";
+        right: "right";
+        iso: "iso";
+    }>>;
+}, z.core.$strip>>;
+export type PluginFamilySnapshotCloseUp = z.infer<typeof PluginFamilySnapshotCloseUp>;
 export declare const PluginFamilySnapshotOption: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
     views: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         top: "top";
@@ -526,6 +1068,28 @@ export declare const PluginFamilySnapshotOption: z.ZodUnion<readonly [z.ZodBoole
         iso: "iso";
     }>>>;
     tileSize: z.ZodOptional<z.ZodNumber>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+        parts: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        box: z.ZodObject<{
+            min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>, z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+        parts: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        box: z.ZodObject<{
+            min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>, z.ZodObject<{
+        view: z.ZodOptional<z.ZodEnum<{
+            top: "top";
+            front: "front";
+            right: "right";
+            iso: "iso";
+        }>>;
+    }, z.core.$strip>>>]>>;
 }, z.core.$strip>]>;
 export type PluginFamilySnapshotOption = z.infer<typeof PluginFamilySnapshotOption>;
 /** The picture block on prepare / flex / getParameters results when `snapshot` was asked for. */
@@ -534,9 +1098,18 @@ export interface PluginFamilySnapshot {
     /** PNG data URL of the composed sheet. */
     image?: string;
     views?: ("iso" | "front" | "right" | "top")[];
-    /** [width, height, depth] in Snaptrude units. */
+    /** [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;
 }
@@ -544,10 +1117,58 @@ export declare const PluginDesignFamilyPrepareArgs: z.ZodObject<{
     bundle: z.ZodOptional<z.ZodObject<{
         root: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         deps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        network: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            role: z.ZodEnum<{
+                pipe: "pipe";
+                duct: "duct";
+                wire: "wire";
+                cable: "cable";
+                conduit: "conduit";
+                cableDuct: "cableDuct";
+                cableTray: "cableTray";
+                connector: "connector";
+                equipment: "equipment";
+            }>;
+            lengthParameter: z.ZodOptional<z.ZodString>;
+            ports: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                position: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+                direction: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+                size: z.ZodString;
+                height: z.ZodOptional<z.ZodString>;
+                widthDirection: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
+                systems: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spec: z.ZodOptional<z.ZodObject<{
         root: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         deps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        network: z.ZodOptional<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            role: z.ZodEnum<{
+                pipe: "pipe";
+                duct: "duct";
+                wire: "wire";
+                cable: "cable";
+                conduit: "conduit";
+                cableDuct: "cableDuct";
+                cableTray: "cableTray";
+                connector: "connector";
+                equipment: "equipment";
+            }>;
+            lengthParameter: z.ZodOptional<z.ZodString>;
+            ports: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                position: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+                direction: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
+                size: z.ZodString;
+                height: z.ZodOptional<z.ZodString>;
+                widthDirection: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
+                systems: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     snapshot: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         views: z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -557,6 +1178,28 @@ export declare const PluginDesignFamilyPrepareArgs: z.ZodObject<{
             iso: "iso";
         }>>>;
         tileSize: z.ZodOptional<z.ZodNumber>;
+        focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodObject<{
+            view: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                front: "front";
+                right: "right";
+                iso: "iso";
+            }>>;
+        }, z.core.$strip>>>]>>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
 export type PluginDesignFamilyPrepareArgs = z.infer<typeof PluginDesignFamilyPrepareArgs>;
@@ -565,11 +1208,11 @@ export type PluginDesignFamilyPrepareArgs = z.infer<typeof PluginDesignFamilyPre
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `values` | `Record<string, number \| string>` | Parameter values to change (partial) |
+ * | `values` | `Record<string, number \| string>` | Optional sparse changes; omission does not rebuild |
  * | `snapshot` | {@linkcode PluginFamilySnapshotOption} | Also return a picture of the flexed family |
  */
 export declare const PluginDesignFamilyFlexArgs: z.ZodObject<{
-    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     snapshot: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         views: z.ZodOptional<z.ZodArray<z.ZodEnum<{
             top: "top";
@@ -578,20 +1221,121 @@ export declare const PluginDesignFamilyFlexArgs: z.ZodObject<{
             iso: "iso";
         }>>>;
         tileSize: z.ZodOptional<z.ZodNumber>;
+        focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodObject<{
+            view: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                front: "front";
+                right: "right";
+                iso: "iso";
+            }>>;
+        }, z.core.$strip>>>]>>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
 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 declare const PluginDesignFamilyGetArgs: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNumber>;
+    component: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+}, z.core.$strip>;
+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 declare const PluginDesignFamilyGetExamplesArgs: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    discipline: z.ZodOptional<z.ZodEnum<{
+        architecture: "architecture";
+        structure: "structure";
+        mep: "mep";
+        furniture: "furniture";
+    }>>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginDesignFamilyGetTemplateArgs: z.ZodObject<{
+    kind: z.ZodEnum<{
+        door: "door";
+        window: "window";
+    }>;
+    subType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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` | Team library to save into; omit for personal |
+ * | `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 declare const PluginDesignFamilyCreateArgs: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
-    teamId: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type PluginDesignFamilyCreateArgs = z.infer<typeof PluginDesignFamilyCreateArgs>;
 /**
@@ -614,22 +1358,25 @@ export type PluginDesignFamilyDeleteArgs = z.infer<typeof PluginDesignFamilyDele
  * |---|---|---|
  * | `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 |
+ * | `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` | Storey to place on; defaults to the active one |
+ * | `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 declare const PluginDesignFamilyPlaceArgs: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodNumber>;
-    position: z.ZodOptional<z.ZodObject<{
+    position: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../..").Handle<"vec3">, string>>, z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
         z: z.ZodNumber;
-    }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
     rotation: z.ZodOptional<z.ZodNumber>;
     values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     storey: z.ZodOptional<z.ZodNumber>;
+    host: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    teamId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type PluginDesignFamilyPlaceArgs = z.infer<typeof PluginDesignFamilyPlaceArgs>;
 /**
@@ -649,6 +1396,28 @@ export declare const PluginDesignFamilyGetParametersArgs: z.ZodObject<{
             iso: "iso";
         }>>>;
         tileSize: z.ZodOptional<z.ZodNumber>;
+        focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+            parts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            box: z.ZodObject<{
+                min: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                max: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>, z.ZodObject<{
+            view: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                front: "front";
+                right: "right";
+                iso: "iso";
+            }>>;
+        }, z.core.$strip>>>]>>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
 export type PluginDesignFamilyGetParametersArgs = z.infer<typeof PluginDesignFamilyGetParametersArgs>;
@@ -662,7 +1431,16 @@ export type PluginDesignFamilyGetParametersArgs = z.infer<typeof PluginDesignFam
  */
 export declare const PluginDesignFamilySetParametersArgs: z.ZodObject<{
     component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
-    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    values: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
+    children: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        from: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        expr: z.ZodString;
+    }, z.core.$strip>, z.ZodNull]>>>;
+    relations: z.ZodOptional<z.ZodObject<{
+        add: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        remove: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginDesignFamilySetParametersArgs = z.infer<typeof PluginDesignFamilySetParametersArgs>;
 //# sourceMappingURL=family.d.ts.map