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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.0.0-dev-20260827135706",
+  "version": "0.0.0-dev-20260827194031",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/design/family.ts

@@ -1,5 +1,6 @@
 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.
@@ -142,23 +143,96 @@ export abstract class PluginDesignFamilyApi {
   public abstract list(): PluginApiReturn<PluginFamilySummary[]>
 
   /**
-   * Arm placement with the prepared family.
+   * Put a family into the model — either the prepared draft or any family from
+   * {@linkcode PluginDesignFamilyApi.list}.
    *
-   * This does **not** create geometry. It puts the editor into placement mode
-   * with a ghost on the cursor; the user clicks in the canvas to drop it, the
-   * same as for any other family. Tell the user to click.
+   * Two modes, chosen by whether you pass `position`:
    *
-   * @returns Which family was armed
+   * **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 Let me put this on the facade
+   * @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(): PluginApiReturn<PluginFamilyPlaceResult>
+  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,
@@ -301,7 +375,7 @@ export interface PluginFamilyFlexResult {
   error?: string
 }
 
-/** One registered parametric family. */
+/** One family available to place — from the session registry or the catalog. */
 export interface PluginFamilySummary {
   id: string
   version: number
@@ -309,6 +383,18 @@ export interface PluginFamilySummary {
   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. */
@@ -316,9 +402,27 @@ 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
@@ -386,3 +490,55 @@ export const PluginDesignFamilyCreateArgs = z.object({
   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
+>

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

@@ -41,6 +41,7 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"curtainWall"` | Parametric curtain wall |
  * | `"mullion"` | Curtain-wall mullion |
  * | `"panel"` | Curtain-wall panel |
+ * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
  */
 export const PluginEntityType = z.enum([
   "wall",
@@ -60,6 +61,7 @@ export const PluginEntityType = z.enum([
   "curtainWall",
   "mullion",
   "panel",
+  "parametricComponent",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>