@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

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

@@ -9,12 +9,54 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
+import {
+  MassParametersPatch,
+  type MassParametersRecord,
+} from "../../../massParameters"
 import {
   PluginBuildableEnvelopePolygonVertex,
   PluginBuildableEnvelopeSetbackTier,
   PluginBuildableEnvelopeVerticalCap,
   PluginBuildableEnvelopeUpdateResult,
+  PluginSiteEdgePatch,
+  PluginDesignUpdateSiteEdgeResult,
 } from "../../entity/buildableEnvelope"
+import { PluginGridStyleOptions } from "../create/grids"
+import { PluginGraphicsLineStyleId } from "../../presentation/graphics"
+import { PluginEntityType } from "../query"
+import { PluginWallType } from "../types"
+import {
+  PluginConstructionType,
+  PluginFamilyValues,
+  type PluginFamilyUpdates,
+} from "../catalog"
+
+/** A project style; its pen/pattern and native legacy mirror change together. */
+export const PluginReferenceLineStylePatch = z
+  .object({
+    styleId: PluginGraphicsLineStyleId,
+  })
+  .strict()
+export type PluginReferenceLineStylePatch = z.infer<
+  typeof PluginReferenceLineStylePatch
+>
+
+/** Arguments for design.update.referenceLine. */
+export const PluginDesignUpdateReferenceLineArgs = z
+  .object({
+    referenceLineId: z.string().min(1),
+    patch: PluginReferenceLineStylePatch,
+  })
+  .strict()
+
+/** Styled line id and the applied project style. */
+export const PluginDesignUpdateReferenceLineResult = z.object({
+  referenceLineId: z.string(),
+  styleId: PluginGraphicsLineStyleId,
+})
+export type PluginDesignUpdateReferenceLineResult = z.infer<
+  typeof PluginDesignUpdateReferenceLineResult
+>
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -136,6 +178,22 @@ export type PluginDesignUpdateStaircaseArgs = z.infer<
   typeof PluginDesignUpdateStaircaseArgs
 >
 
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.parameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The parametric mass to edit |
+ * | `patch` | {@linkcode MassParametersPatch} | Partial `values` (+ optional `operations`), or the full edited record |
+ */
+export const PluginDesignUpdateParametersArgs = z.object({
+  component: ComponentHandle,
+  patch: MassParametersPatch,
+})
+export type PluginDesignUpdateParametersArgs = z.infer<
+  typeof PluginDesignUpdateParametersArgs
+>
+
 /**
  * Sparse edits for a wall (all optional; at least one required). Only the
  * fields you provide change. Dimensions are in **engine units** (the same
@@ -146,13 +204,14 @@ export type PluginDesignUpdateStaircaseArgs = z.infer<
  * |---|---|---|
  * | `thickness` | `number`? | Wall thickness, engine units (> 0) |
  * | `height` | `number`? | Wall height, engine units (> 0) |
- * | `type` | `string`? | Convert the wall to another wall type — a name (or `wall:`-prefixed id) from `design.types.list("wall")` |
+ * | `type` | {@linkcode PluginWallType}? | Legacy name/id or exact authorized native `{ id, version }` pin from `design.types.list("wall")` |
  */
 export const PluginWallUpdates = z
   .object({
     thickness: z.number().positive().optional(),
     height: z.number().positive().optional(),
-    type: z.string().trim().min(1).optional(),
+    type: PluginWallType.optional(),
+    values: PluginFamilyValues.optional(),
   })
   .refine((p) => Object.keys(p).length > 0, {
     message: "PluginWallUpdates requires at least one field to change",
@@ -177,6 +236,8 @@ export const PluginSlabUpdates = z
   .object({
     thickness: z.number().positive().optional(),
     overhang: z.number().optional(),
+    type: PluginConstructionType.optional(),
+    values: PluginFamilyValues.optional(),
   })
   .refine((p) => Object.keys(p).length > 0, {
     message: "PluginSlabUpdates requires at least one field to change",
@@ -238,15 +299,86 @@ export type PluginDesignSetStoreyArgs = z.infer<
   typeof PluginDesignSetStoreyArgs
 >
 
+/**
+ * Object types {@linkcode PluginDesignUpdateApi.setObjectType} can turn a mass
+ * into — the `design.query` `type` vocabulary.
+ */
+export const PluginObjectType = PluginEntityType.extract([
+  "wall",
+  "roof",
+  "slab",
+  "floor",
+])
+export type PluginObjectType = z.infer<typeof PluginObjectType>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.setObjectType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The masses to convert (>= 1) |
+ * | `objectType` | {@linkcode PluginObjectType} | Target object type (`"wall"`, `"roof"`, `"slab"`, `"floor"`) |
+ */
+export const PluginDesignSetObjectTypeArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  objectType: PluginObjectType,
+})
+export type PluginDesignSetObjectTypeArgs = z.infer<
+  typeof PluginDesignSetObjectTypeArgs
+>
+
+/**
+ * The sparse GROUP-LEVEL patch accepted by {@linkcode PluginDesignUpdateApi.grid}.
+ * Only provided fields change. Wing- and line-level updates live on the grids
+ * entity family: `design.grids.updateWings` / `design.grids.updateLines`.
+ */
+export const PluginGridPatch = z.object({
+  angle: z.number().finite().optional(),
+  props: PluginGridStyleOptions.optional(),
+  storeyVisibility: z
+    .array(z.object({ storey: z.number().int(), visible: z.boolean() }))
+    .optional(),
+})
+export type PluginGridPatch = z.infer<typeof PluginGridPatch>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
+export const PluginDesignUpdateGridArgs = z.object({
+  grid: ComponentHandle,
+  patch: PluginGridPatch,
+})
+export type PluginDesignUpdateGridArgs = z.infer<
+  typeof PluginDesignUpdateGridArgs
+>
+
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
  * Migrated from the removed `entity.space.{update, updateGeometryFromProfile, bulkUpdate}`.
  * Only provided fields change; each call is undoable. Failures throw (RPC rejects).
+ *
+ * Native family edits accept `type` and/or sparse `values` from `design.catalog`.
+ * Length overrides use mm; dimensional arguments use SU. Contours and axes stay unchanged.
+ * Shared/type overrides are refused. A thickness argument must agree with the layer values.
+ * Family roof overhang is unsupported; use the native slab path for family overhang edits.
  */
 export abstract class PluginDesignUpdateApi {
   constructor() {}
 
+  /**
+   * Apply a project style through the native reference-line property command.
+   * One saved undo step; no selection or tool preference changes. Saves the
+   * legacy thickness/mode mirror too. Requires Paper Pens and an editable line
+   * in the current proposal. A no-op creates no history entry.
+   * @param referenceLineId - Existing reference line id.
+   * @param patch - styleId from the project line-style catalog.
+   * @returns The line id and applied style id.
+   * @example await snaptrude.design.update.referenceLine(id, { styleId: "wide" })
+   */
+  public abstract referenceLine(
+    referenceLineId: string,
+    patch: PluginReferenceLineStylePatch,
+  ): PluginApiReturn<PluginDesignUpdateReferenceLineResult>
+
   /**
    * Set a component's **Label** — the same editable Label field the properties
    * panel shows (doors, windows, furniture, spaces, and every other labelled
@@ -290,6 +422,37 @@ export abstract class PluginDesignUpdateApi {
     label: string,
   ): PluginApiReturn<boolean>
 
+  /**
+   * Update a structural grid's **group-level** fields with a sparse patch —
+   * default line styling, absolute angle, and per-storey 2D visibility. Only
+   * provided fields change. Wing- and line-level updates live on the grids
+   * entity family: {@linkcode PluginDesignGridsApi.updateWings} /
+   * {@linkcode PluginDesignGridsApi.updateLines}.
+   *
+   * Every change routes through the exact setters the native panel uses —
+   * each changed field commits its own undoable command, identical to editing
+   * that field in the panel. `angle` is an absolute target in degrees (CCW
+   * about +Y).
+   *
+   * @param grid - The grid group to update
+   * @param patch - The sparse {@linkcode PluginGridPatch}
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rotate the grid to 45 degrees
+   * @examplePrompt Make this grid's lines dashed and grey
+   * @examplePrompt Hide this grid on storey 3's plan
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * await snaptrude.design.update.grid(grid, { angle: 45, props: { style: "DASHED" } })
+   * ```
+   */
+  public abstract grid(
+    grid: ComponentHandle,
+    patch: PluginGridPatch,
+  ): PluginApiReturn<boolean>
+
   /**
    * Update a single space (room) — change its properties (room label, space
    * type, mass type, area class, department) and/or replace its geometry by
@@ -299,6 +462,8 @@ export abstract class PluginDesignUpdateApi {
    * @param space - The space to update
    * @param options - `properties` (sparse) and/or `geometry` ({ profile, extrudeHeight })
    * @returns the updated space's echoed {@linkcode PluginSpaceUpdateResult}
+   * @throws PRECONDITION_FAILED for a void (a hole cut with `design.create.void`): delete it and
+   *   cut a new one
    *
    * @examplePrompt Rename this room to Office
    * @examplePrompt Change this space's room type to Meeting Room
@@ -332,6 +497,7 @@ export abstract class PluginDesignUpdateApi {
    *
    * @param items - One {@linkcode PluginUpdateSpaceItem} per space
    * @returns one {@linkcode PluginSpaceUpdateResult} per item, in input order
+   * @throws PRECONDITION_FAILED for a void, like {@linkcode space}
    *
    * @examplePrompt Label all the selected rooms as Bedrooms
    * @examplePrompt Change the room type of these five spaces at once
@@ -409,6 +575,98 @@ export abstract class PluginDesignUpdateApi {
     params: PluginStaircaseParamUpdates,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Edit a parametric mass by patching its creation recipe and rebuilding the
+   * solid in place — the mass keeps its id, storey, materials, position and
+   * linked copies; only the geometry changes. Read the current record with
+   * `design.query.getParameters` first.
+   *
+   * `patch` is a partial of `record.values` — or the whole record you read
+   * back, edited. A key you leave out is unchanged (that includes
+   * `operations`). Each key you send replaces that value whole — a scalar, a
+   * point, a list or a record (`contour`, `profile`, `sections`, `path`,
+   * `options`, `operations`) alike — so send the complete value you read,
+   * edited (a partial `options` drops the switches it leaves out);
+   * `{ operations: [] }` drops every operation. An optional key
+   * the record does not carry yet may be patched in when the kind allows it:
+   * a straight extrusion acquires `twistInDegrees` or `topScale`, an
+   * options-less loft or sweep acquires `options` (`levels` is not one — send
+   * the angle, not the section count). A patch that changes nothing
+   * returns the current record and records no edit (no undo step). `kind` and
+   * `version` are immutable: to change the kind, build a new mass. Keys are the
+   * record's `values` keys for its `kind` (sphere: `centre`, `radius`;
+   * cylinder: `base`, `axis`, `radius`, `height`; torus: `centre`, `axis`,
+   * `majorRadius`, `minorRadius`; …) plus `operations`. To change a fillet
+   * radius, edit `operations[i].radius` in the record you read and send
+   * `{ operations }` back. Points and axes are WORLD coordinates in internal
+   * units, exactly as `getParameters` reports them.
+   *
+   * Rebuilds in memory first, then swaps onto the SAME component; every linked
+   * copy regenerates together. One undo step; saves and syncs to collaborators
+   * like any geometry edit. Kernel kinds (revolution, sweep, loft, primitives,
+   * any `operations`) run on OpenCascade — expect a short pause.
+   *
+   * @param component - a mass whose `getParameters` is non-null
+   * @param patch - partial `values` (+ optional `operations`), or the full edited record
+   * @returns the complete post-edit record, world coordinates (what
+   *   `getParameters` now returns)
+   * @throws PRECONDITION_FAILED when the component is not a mass (a family
+   *   instance: use `design.family.setParameters`).
+   *   Also PRECONDITION_FAILED when the mass carries no live recipe — built
+   *   from a boolean, split, `brepFromFaces`/`brepFromMesh` or drawn; edited
+   *   free-form since (push/pull, move face, boolean); or scaled with the
+   *   transform tool. `getParameters` returns `null` for exactly these.
+   *   Do not retry — rebuild it with a recipe constructor and say so.
+   *   A scaled mass is the exception: undo the scale and call again.
+   *   Also PRECONDITION_FAILED when the mass (or a linked copy) is **locked**
+   *   (the message says so). Locking is invisible to `getParameters` — a
+   *   locked parametric mass still reads back a full record. Unlock it (and
+   *   every linked copy) and call again; never rebuild it, the recipe is intact.
+   *   Also PRECONDITION_FAILED when an `operations` entry's edge/face selectors
+   *   no longer resolve on the rebuilt base (the message names the operation
+   *   and edge): re-select the edges on the new shape and re-apply that
+   *   operation.
+   *   Also PRECONDITION_FAILED when the edit is the first twist or taper — or
+   *   the straightening — of an extrusion that carries a shell, fillet or
+   *   chamfer (the kernel numbers its faces differently): send the twist/taper
+   *   keys with `operations: []` first (the message names them), re-select on
+   *   the new shape, then send `{ operations }` back.
+   *   Graph-bound spaces accept amount-only extrusion edits. Footprint, twist,
+   *   taper and operation edits require the owning boundary tools, so generated
+   *   walls, junctions and hosted openings remain synchronized.
+   * @throws VALIDATION for a key the kind does not have (the message lists the
+   *   kind's keys), `kind` or `version` in a partial patch, or a value outside
+   *   the constructor's own rules (torus tube ≥ ring, revolution angle ∉
+   *   (0, 360], a profile crossing its axis, a spline with fewer than
+   *   degree + 1 poles).
+   * @throws OPERATION_FAILED when the kernel cannot build the edited recipe;
+   *   the model is left unchanged.
+   *
+   * @examplePrompt Make the dome's radius 8 metres
+   * @examplePrompt Raise the podium to 5 m
+   * @examplePrompt Widen the vase — move its profile points 20 cm outward
+   * @examplePrompt Change the fillet on the rounded column to 300 mm
+   *
+   * # Example
+   * ```ts
+   * // { kind: "sphere", values: { centre, radius: 19.685 }, … }
+   * const before = await snaptrude.design.query.getParameters(dome)
+   * const after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units
+   *
+   * // Fillet radius on a recorded result: read → edit → send the array back
+   * const rec = await snaptrude.design.query.getParameters(column)
+   * const operations = rec?.operations ?? []
+   * if (operations[0]?.op === "fillet") {
+   *   operations[0].radius = 1.181
+   *   await snaptrude.design.update.parameters(column, { operations })
+   * }
+   * ```
+   */
+  public abstract parameters(
+    component: ComponentHandle,
+    patch: MassParametersPatch,
+  ): PluginApiReturn<MassParametersRecord>
+
   /**
    * Edit a **wall** — its thickness and/or height (the same command the
    * properties panel's Thickness/Height fields drive) and/or its **wall type**
@@ -583,6 +841,24 @@ export abstract class PluginDesignUpdateApi {
     updates: PluginSlabUpdates,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /** Replace a native beam family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native beam. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract beam(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /** Replace a native column family while preserving its authored axis. Values use mm/degrees.
+   * @param component Native column. @param updates Saved family reference and optional instance values.
+   * @returns Affected component IDs. One undoable operation; unsupported geometry fails before mutation.
+   */
+  public abstract column(
+    component: ComponentHandle,
+    updates: PluginFamilyUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Set a component's **absolute world elevation** — moves it vertically so its
    * base (the bounding-box bottom, world Y) lands at `elevation`. Composed over
@@ -690,12 +966,65 @@ export abstract class PluginDesignUpdateApi {
     storey: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Change the **object type** of one or more masses — turn a mass into a real
+   * wall, roof, slab or floor: the properties panel's Object Type dropdown,
+   * headless. The geometry is kept exactly as it is (a wedge stays a wedge;
+   * nothing is flattened to a default thickness), so a sloped mass built with
+   * `design.create.massFromBrep` becomes a sloped roof or a raked wall. The
+   * component keeps its handle, label and storey; it gains the target type's
+   * construction layers and properties, and the type's default material when
+   * the mass still wore the default. One undoable operation for the whole
+   * list; undo turns them back into masses.
+   *
+   * Instances convert as a family: passing one instance (or the source) of an
+   * instanced mass converts its source and every sibling; `affected` echoes
+   * every visible member (the hidden instancing template converts too but is
+   * not listed). A converted component cannot be converted again (same rule
+   * as the panel). A converted wall has no parametric centerline: it hosts
+   * doors and windows and exports, but neighbours do not re-mitre against it.
+   *
+   * Throws before anything changes (all-or-nothing) when a component is not a
+   * mass, is a plinth, is locked or in a locked bucket, already had its type
+   * changed, or when a handle is gone/forged.
+   *
+   * @param components - The masses to convert
+   * @param objectType - Target type: `"wall"`, `"roof"`, `"slab"` or `"floor"`
+   *   (the `design.query.getEntityType` vocabulary)
+   * @returns the visible components converted — the same handles, plus any
+   *   instance siblings pulled in by family expansion
+   *
+   * @examplePrompt Convert this mass into a wall
+   * @examplePrompt Turn the sloped mass into a roof
+   * @examplePrompt Make these masses real slabs
+   * @examplePrompt Change the object type of the selection to wall
+   * @examplePrompt Convert the wedge I built into a raked wall
+   * @examplePrompt Turn this mass into a floor
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromFaces(wedgeFaces)
+   * const wedge = await snaptrude.design.create.massFromBrep(brep, "Gable end")
+   * const { affected } = await snaptrude.design.update.setObjectType([wedge], "wall")
+   * console.log(await snaptrude.design.query.getEntityType(affected[0])) // "wall"
+   * ```
+   */
+  public abstract setObjectType(
+    components: ComponentHandle[],
+    objectType: PluginObjectType,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Update an existing parametric buildable envelope — regenerate the zoning
    * volume from a revised site polygon, setbacks, vertical cap, or FAR and
    * lot-coverage limits, keeping the same envelope id. Canonical home of the
    * update formerly at `entity.buildableEnvelope.update` (now deprecated).
    *
+   * Edge state is preserved, like the right panel: every edge's type
+   * (front/side/rear) is kept. For each type whose value changed (by more than
+   * 2 mm), the per-edge custom distances on edges of that type are cleared;
+   * custom distances on types whose value did not change are kept.
+   *
    * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
    *   must match an existing envelope on the canvas.
    * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
@@ -706,9 +1035,15 @@ export abstract class PluginDesignUpdateApi {
    * @param farRatio - Optional FAR value, positive when provided.
    * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
    * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
-   *   `buildableEnvelopeId` of the updated envelope.
+   *   `buildableEnvelopeId` of the updated envelope and `clearedEdgeSetbacks`,
+   *   the `edgeIndex` of each edge that lost its custom distance (empty when
+   *   none). Tell the user about any cleared edges.
    * @throws If validation fails, the envelope does not exist, or generation
-   *   produces no renderable geometry.
+   *   produces no renderable geometry. Also throws `PRECONDITION_FAILED`
+   *   (`details.reason: "STALE_EDGE_SETTINGS"`, nothing changes) when the site
+   *   outline changed since the edge settings were made. Tell the user;
+   *   editing any edge on the canvas setback pills resets the edge settings
+   *   to the new outline (dropping the old ones), after which you can retry.
    *
    * @examplePrompt Change the envelope's height limit to 175 feet
    * @examplePrompt Update the setbacks on the buildable envelope
@@ -742,4 +1077,63 @@ export abstract class PluginDesignUpdateApi {
     farRatio?: number,
     lotCoverageMaxPct?: number,
   ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
+
+  /**
+   * Change one site edge's type (front / side / rear) and/or give that edge
+   * its own setback distance, the same as editing a setback pill on the
+   * canvas. One undo step; the pills and Site Analysis sheet refresh.
+   *
+   * Address the edge with `siteId` and `edgeIndex` from
+   * `program.site.listEdges()`. Setting `role` clears that edge's own
+   * distance. `setback: null` clears the edge's own distance and puts it back
+   * on its type's distance. When `role` and a numeric `setback` are both
+   * given, the role is applied first and then the setback, so the new distance
+   * wins. On the only edge of its type, a numeric setback becomes that type's
+   * value (like the canvas pills), so `null` afterwards has nothing to
+   * clear; set the type's value instead. Only call this when the user asks to
+   * change an edge.
+   *
+   * @param siteId - Site component id, from `program.site.listEdges()`.
+   * @param edgeIndex - Edge index from `program.site.listEdges()`; nonnegative
+   *   integer, upper bound checked by the host.
+   * @param patch - A {@linkcode PluginSiteEdgePatch}: `role`, `setback` (a
+   *   number in `lengthUnit`, or `null` to clear), and `lengthUnit` (required
+   *   with a numeric `setback`). Provide `role` and/or `setback`.
+   * @returns The refreshed {@linkcode PluginDesignUpdateSiteEdgeResult} for the
+   *   site, as `program.site.listEdges()` returns it.
+   * @throws
+   *   - `HANDLE_INVALID`: unknown `siteId` (invalid site handle).
+   *   - `VALIDATION`: `edgeIndex` is out of range or not a nonnegative
+   *     integer; when the index is out of range, `details` include `edgeCount`.
+   *   - `PRECONDITION_FAILED`, with `details.reason` one of:
+   *     - `NO_BUILDABLE_ENVELOPE`: the site has no envelope to store edge
+   *       settings on. Ask the user whether to create a default envelope with
+   *       `design.create.buildableEnvelopeFromSite(siteId)` or to create one
+   *       themselves; do not create one unasked.
+   *     - `MASSING_ENVELOPE`: the site's envelope is a massing envelope. Tell
+   *       the user; change nothing.
+   *     - `ENVELOPE_TRANSFORMED`: the envelope has been rotated or scaled, so
+   *       edge editing is unavailable. Tell the user.
+   *     - `STALE_EDGE_SETTINGS`: the site outline changed since the edge
+   *       settings were made. Tell the user; editing any edge on the canvas
+   *       setback pills resets the edge settings to the new outline (dropping
+   *       the old ones), after which you can retry.
+   *
+   * @examplePrompt Make edge 2 the front
+   * @examplePrompt Set just the north edge setback to 8 m
+   * @examplePrompt Remove the custom setback on edge 3
+   *
+   * # Example
+   * ```ts
+   * const [{ siteId }] = (await snaptrude.program.site.listEdges()).sites
+   * await snaptrude.design.update.siteEdge(siteId, 2, { role: "front" })
+   * await snaptrude.design.update.siteEdge(siteId, 3, { setback: 8, lengthUnit: "m" })
+   * await snaptrude.design.update.siteEdge(siteId, 3, { setback: null })
+   * ```
+   */
+  public abstract siteEdge(
+    siteId: string,
+    edgeIndex: number,
+    patch: PluginSiteEdgePatch,
+  ): PluginApiReturn<PluginDesignUpdateSiteEdgeResult>
 }

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

@@ -10,13 +10,14 @@ import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
  * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
  *
  * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
- * browse the placeable window library — plain value records keyed by a library id
- * (team `_id` or general `fullName`), NOT handles — and feed `design.create.window`.
- * They are network-backed but carry no `Async` suffix (§6.6) and never throw
- * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * browse saved hosted window families, keyed by definition ID, and feed design.create.window.
+ * They reject if saved definitions cannot be loaded completely. A missing item returns null.
+ * The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
  * DTOs are shared with `design.doors` (defined there, re-exported here).
  *
- * `getSillHeight` (bounds-derived) and the command-wired `mirror` land in a later pass.
+ * PC-only: dimensions read the evaluated opening and host thickness in SU. Setters
+ * write declared width/height parameters, never mesh scale. Missing or derived
+ * controls reject. Use design.family.setParameters for sill and other controls.
  */
 export abstract class PluginDesignWindowsApi {
   constructor() {}
@@ -40,7 +41,9 @@ export abstract class PluginDesignWindowsApi {
    * if (type) console.log("window type:", type)
    * ```
    */
-  public abstract getType(window: ComponentHandle): PluginApiReturn<string | null>
+  public abstract getType(
+    window: ComponentHandle,
+  ): PluginApiReturn<string | null>
 
   /**
    * Get the width of a window — how wide its opening is along the host wall.
@@ -60,7 +63,9 @@ export abstract class PluginDesignWindowsApi {
    * if (width !== null) console.log("window width:", width)
    * ```
    */
-  public abstract getWidth(window: ComponentHandle): PluginApiReturn<number | null>
+  public abstract getWidth(
+    window: ComponentHandle,
+  ): PluginApiReturn<number | null>
 
   /**
    * Get the height of a window — how tall its opening is on the host wall.
@@ -80,12 +85,13 @@ export abstract class PluginDesignWindowsApi {
    * if (height !== null) console.log("window height:", height)
    * ```
    */
-  public abstract getHeight(window: ComponentHandle): PluginApiReturn<number | null>
+  public abstract getHeight(
+    window: ComponentHandle,
+  ): PluginApiReturn<number | null>
 
   /**
-   * Get a window's full dimensions in one call — width along the wall, vertical
-   * height, and thickness through the wall — measured in the window's local
-   * oriented space.
+   * Get evaluated opening width/height and host thickness in Snaptrude units.
+   * The opening can differ from the width/height input parameters.
    *
    * @param window The window to query
    * @returns The dimensions, or `null`
@@ -104,7 +110,7 @@ export abstract class PluginDesignWindowsApi {
    * ```
    */
   public abstract getDimensions(
-    window: ComponentHandle
+    window: ComponentHandle,
   ): PluginApiReturn<PluginWindowDimensions | null>
 
   /**
@@ -129,7 +135,7 @@ export abstract class PluginDesignWindowsApi {
    */
   public abstract setWidth(
     window: ComponentHandle,
-    width: number
+    width: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -153,7 +159,7 @@ export abstract class PluginDesignWindowsApi {
    */
   public abstract setHeight(
     window: ComponentHandle,
-    height: number
+    height: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -174,7 +180,9 @@ export abstract class PluginDesignWindowsApi {
    * for (const g of groups) console.log(g.dbType, g.label, g.source)
    * ```
    */
-  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+  public abstract listCatalogGroups(): PluginApiReturn<
+    PluginObjectCatalogGroup[]
+  >
 
   /**
    * List the placeable window catalog (team + general libraries), optionally
@@ -196,7 +204,7 @@ export abstract class PluginDesignWindowsApi {
    * ```
    */
   public abstract listCatalog(
-    group?: string
+    group?: string,
   ): PluginApiReturn<PluginObjectCatalogItem[]>
 
   /**
@@ -218,7 +226,7 @@ export abstract class PluginDesignWindowsApi {
    * ```
    */
   public abstract getCatalogItem(
-    id: string
+    id: string,
   ): PluginApiReturn<PluginObjectCatalogItem | null>
 
   /**
@@ -282,7 +290,9 @@ export const PluginDesignWindowSetWidthArgs = z.object({
   window: ComponentHandle,
   width: z.number(),
 })
-export type PluginDesignWindowSetWidthArgs = z.infer<typeof PluginDesignWindowSetWidthArgs>
+export type PluginDesignWindowSetWidthArgs = z.infer<
+  typeof PluginDesignWindowSetWidthArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignWindowsApi.setHeight}.
@@ -296,7 +306,9 @@ export const PluginDesignWindowSetHeightArgs = z.object({
   window: ComponentHandle,
   height: z.number(),
 })
-export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>
+export type PluginDesignWindowSetHeightArgs = z.infer<
+  typeof PluginDesignWindowSetHeightArgs
+>
 
 // ---------------------------------------------------------------------------
 // catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
@@ -315,7 +327,9 @@ export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
 export const PluginDesignWindowListCatalogArgs = z.object({
   group: z.string().optional(),
 })
-export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindowListCatalogArgs>
+export type PluginDesignWindowListCatalogArgs = z.infer<
+  typeof PluginDesignWindowListCatalogArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
@@ -327,7 +341,11 @@ export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindo
 export const PluginDesignWindowGetCatalogItemArgs = z.object({
   id: z.string(),
 })
-export type PluginDesignWindowGetCatalogItemArgs = z.infer<typeof PluginDesignWindowGetCatalogItemArgs>
+export type PluginDesignWindowGetCatalogItemArgs = z.infer<
+  typeof PluginDesignWindowGetCatalogItemArgs
+>
 
 export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
-export type PluginDesignWindowExistsArgs = z.infer<typeof PluginDesignWindowExistsArgs>
+export type PluginDesignWindowExistsArgs = z.infer<
+  typeof PluginDesignWindowExistsArgs
+>