@snaptrude/plugin-core 0.9.16-networks-20261012.1 → 0.9.17

package/src/api/design/family.ts

@@ -1,12 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import {
-  BrepHandle,
-  ComponentHandle,
-  Vec3Components,
-  Vec3Handle,
-} from "../../handles"
-import { NetworkFamilyContract } from "./networks"
+import { BrepHandle, ComponentHandle, Vec3Components } from "../../handles"
 
 /**
  * `snaptrude.design.family.*` — author NATIVE parametric families from a JSON spec.
@@ -18,52 +12,19 @@ import { NetworkFamilyContract } from "./networks"
  * compiles that into a live parametric definition the user can place, flex and
  * save to their library.
  *
- * ## Generic component workflow
+ * ## 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
+ * getReference()        read the spec DSL once — grammar, ops, expressions, example
+ * prepare({ bundle })   validate + compile + show a live ghost; nothing committed
  * flex({ values })      re-run at new values; returns the geometry delta
  * place({ 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 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`.
+ * survives reload with no extra step; finish on `place`, not on `create`.
  *
  * ## Read getReference() first
  *
@@ -111,8 +72,6 @@ export 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?
@@ -123,61 +82,7 @@ export abstract class PluginDesignFamilyApi {
    * 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>
+  public abstract getReference(): PluginApiReturn<PluginFamilyReference>
 
   /**
    * Validate, compile and preview a family spec. Nothing is committed to the
@@ -219,8 +124,7 @@ export 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. Omit values (or pass an empty
-   * record) to report or photograph the current draft without rebuilding it.
+   * @param args The parameter values to change
    * @returns The new build plus the geometry delta
    *
    * @examplePrompt Change it to 6 bays
@@ -233,49 +137,25 @@ export abstract class PluginDesignFamilyApi {
    * ```
    */
   public abstract flex(
-    args?: PluginDesignFamilyFlexArgs,
+    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.
+   * The prepared family's spec bundle, or `null` when nothing is prepared.
    *
-   * @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
+   * @returns The draft bundle, or `null`
    *
    * # Example
    * ```ts
-   * const draft = await snaptrude.design.family.get()
-   * const family = await snaptrude.design.family.get({ component })
-   * // family.editing → { familyId, version, name, library }
+   * const bundle = await snaptrude.design.family.get()
    * ```
    */
-  public abstract get(
-    args?: PluginDesignFamilyGetArgs | string,
-  ): PluginApiReturn<PluginFamilyGetResult | null>
+  public abstract get(): PluginApiReturn<PluginFamilyBundle | null>
 
   /**
-   * Every available parametric family, merging the session registry and catalog.
+   * Every parametric family registered in this session — native and imported.
    *
-   * @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.
+   * @returns One summary per family
    *
    * @examplePrompt What families are available?
    *
@@ -284,35 +164,7 @@ export abstract class PluginDesignFamilyApi {
    * 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>
+  public abstract list(): PluginApiReturn<PluginFamilySummary[]>
 
   /**
    * Put a family into the model — either the prepared draft or any family from
@@ -336,13 +188,6 @@ export 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
    *
@@ -362,9 +207,6 @@ export abstract class PluginDesignFamilyApi {
    *
    * // 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(
@@ -407,34 +249,6 @@ export 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
@@ -449,15 +263,6 @@ export 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" } }] },
-   * })
    * ```
    */
   public abstract setParameters(
@@ -467,24 +272,12 @@ export abstract class PluginDesignFamilyApi {
   /**
    * Save the prepared bundle to the library — the user's personal library
    * unless `teamId` is given. {@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.
+   * 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.
    *
    * @param args Optional library name and team scope
-   * @returns The catalogued definition's id and version, and what the user chose
+   * @returns The catalogued definition's id and version
    *
    * @examplePrompt Save this as a family called Vertical Louvre
    * @examplePrompt Add it to my library
@@ -521,56 +314,14 @@ export abstract class PluginDesignFamilyApi {
    * ```
    */
   public abstract delete(
-    args?: PluginDesignFamilyDeleteArgs | string,
+    args?: PluginDesignFamilyDeleteArgs,
   ): 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. */
@@ -589,34 +340,6 @@ 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. */
@@ -664,10 +387,6 @@ export interface PluginFamilyDiagnostic {
     | "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
 }
@@ -752,13 +471,6 @@ 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
   /**
@@ -775,49 +487,6 @@ export interface PluginFamilySummary {
   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
@@ -846,104 +515,6 @@ 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. */
@@ -956,26 +527,6 @@ 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
 }
 
@@ -1004,7 +555,6 @@ export interface PluginFamilyDeleteResult {
 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(),
 })
 
 /**
@@ -1026,71 +576,16 @@ export const PluginFamilyBundleSchema = z.object({
  * 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
->
+export type PluginFamilySnapshotOption = z.infer<typeof PluginFamilySnapshotOption>
 
 /** The picture block on prepare / flex / getParameters results when `snapshot` was asked for. */
 export interface PluginFamilySnapshot {
@@ -1098,18 +593,9 @@ export interface PluginFamilySnapshot {
   /** 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. */
+  /** [width, height, depth] in Snaptrude units. */
   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
 }
@@ -1119,105 +605,21 @@ export const PluginDesignFamilyPrepareArgs = z.object({
   spec: PluginFamilyBundleSchema.optional(),
   snapshot: PluginFamilySnapshotOption.optional(),
 })
-export type PluginDesignFamilyPrepareArgs = z.infer<
-  typeof PluginDesignFamilyPrepareArgs
->
+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 |
+ * | `values` | `Record<string, number \| string>` | Parameter values to change (partial) |
  * | `snapshot` | {@linkcode PluginFamilySnapshotOption} | Also return a picture of the flexed family |
  */
 export const PluginDesignFamilyFlexArgs = z.object({
-  values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
+  values: z.record(z.string(), z.union([z.number(), z.string()])),
   snapshot: PluginFamilySnapshotOption.optional(),
 })
-export type PluginDesignFamilyFlexArgs = z.infer<
-  typeof PluginDesignFamilyFlexArgs
->
-
-/**
- * Arguments for {@linkcode PluginDesignFamilyApi.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[] }>
-}
+export type PluginDesignFamilyFlexArgs = z.infer<typeof PluginDesignFamilyFlexArgs>
 
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.create}.
@@ -1231,9 +633,7 @@ export const PluginDesignFamilyCreateArgs = z.object({
   name: z.string().optional(),
   teamId: z.string().optional(),
 })
-export type PluginDesignFamilyCreateArgs = z.infer<
-  typeof PluginDesignFamilyCreateArgs
->
+export type PluginDesignFamilyCreateArgs = z.infer<typeof PluginDesignFamilyCreateArgs>
 
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.delete}.
@@ -1247,9 +647,7 @@ export const PluginDesignFamilyDeleteArgs = z.object({
   id: z.string().optional(),
   instances: z.boolean().optional(),
 })
-export type PluginDesignFamilyDeleteArgs = z.infer<
-  typeof PluginDesignFamilyDeleteArgs
->
+export type PluginDesignFamilyDeleteArgs = z.infer<typeof PluginDesignFamilyDeleteArgs>
 
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.place}.
@@ -1258,7 +656,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
  * |---|---|---|
  * | `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 |
+ * | `position` | `{ x, y, z }` | Place HERE, without user interaction. Omit to arm the cursor instead |
  * | `rotation` | `number` | Yaw in degrees about +Y. Only with `position` |
  * | `values` | `Record<string, number \| string>` | Parameter values for THIS instance |
  * | `storey` | `number` | Storey to place on; defaults to the active one |
@@ -1266,16 +664,12 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
 export const PluginDesignFamilyPlaceArgs = z.object({
   id: z.string().optional(),
   version: z.number().int().positive().optional(),
-  position: z.union([Vec3Handle, Vec3Components]).optional(),
+  position: Vec3Components.optional(),
   rotation: z.number().optional(),
   values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   storey: z.number().int().optional(),
-  /** Hosted families: wall or family host. Values apply before fit checks and cutting. */
-  host: ComponentHandle.optional(),
 })
-export type PluginDesignFamilyPlaceArgs = z.infer<
-  typeof PluginDesignFamilyPlaceArgs
->
+export type PluginDesignFamilyPlaceArgs = z.infer<typeof PluginDesignFamilyPlaceArgs>
 
 /**
  * Arguments for {@linkcode PluginDesignFamilyApi.getParameters}.
@@ -1303,31 +697,7 @@ export type PluginDesignFamilyGetParametersArgs = z.infer<
  */
 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(),
+  values: z.record(z.string(), z.union([z.number(), z.string()])),
 })
 export type PluginDesignFamilySetParametersArgs = z.infer<
   typeof PluginDesignFamilySetParametersArgs