@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827194031

package/src/api/design/family.ts

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