@snaptrude/plugin-core 0.9.1 → 0.9.3

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

@@ -389,9 +389,15 @@ export abstract class PluginDesignCreateApi {
    *   Drives the wall's construction layers and default material, and — when
    *   `thickness` is omitted — its total layer thickness. Default: the engine's
    *   generic wall.
+   * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
+   *   basement — same convention as `design.create.space`). The walls are
+   *   assigned to it and lifted to its base elevation, all inside the same
+   *   single undo entry. The storey must already exist
+   *   (`core.storeys.create` first). Default: geometry-derived — a profile
+   *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
-   *   project, or wall creation fails
+   *   project, `storey` does not exist, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
@@ -422,6 +428,7 @@ export abstract class PluginDesignCreateApi {
     height?: number,
     thickness?: number,
     wallType?: string,
+    storey?: number,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -429,12 +436,17 @@ export abstract class PluginDesignCreateApi {
    *
    * Geometry is procedurally generated from the chosen `preset`; there is no
    * footprint input. Placed on the active structure/story unless overridden.
+   * The promise resolves only after the staircase's asynchronous geometry union
+   * and creation-command capture settle; a union failure rejects the call.
    *
    * @param preset - The parametric preset to generate
    * @param position - Placement point
    * @param label - Optional label
    * @param structureId - Target structure (default active)
    * @param level - Target level name (default active/`"01"`)
+   * @param dimensions - Optional positive dimension overrides in Snaptrude engine
+   *   units, plus a placement angle in 90-degree increments. Overrides are
+   *   applied to the staircase parameters before the creation command runs.
    * @returns the {@linkcode ComponentHandle} of the created staircase
    * @throws if the preset is unknown or placement fails
    *
@@ -458,6 +470,7 @@ export abstract class PluginDesignCreateApi {
     label?: string,
     structureId?: string,
     level?: string,
+    dimensions?: PluginStaircaseDimensions,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -517,7 +530,11 @@ export abstract class PluginDesignCreateApi {
    * entry). To rotate an existing instance instead, use `design.transform.rotate`.
    *
    * @param catalogId - Library id: team `_id` or general `fullName`
-   * @param position - Absolute world placement point
+   * @param position - Absolute world placement point. `position.y` is the REST
+   *   elevation: the item is grounded so its bounding-box base sits exactly at
+   *   `position.y` (the same surface-flush contract as interactive drag-drop) —
+   *   pass the floor/storey elevation to stand furniture on it; never add half
+   *   the item's height yourself.
    * @param options - Optional placement options: `label` — instance name
    *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
    *   source-mesh creation command (default `true`)
@@ -665,6 +682,43 @@ export abstract class PluginDesignCreateApi {
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
+  /**
+   * Place a catalog **door or window** into a host wall with optional size overrides.
+   *
+   * The world `position` is projected onto the host wall to locate the opening.
+   * All supplied dimensions use Snaptrude engine units. Window `sillHeight` is
+   * measured from the host wall base to the bottom of the window, not to
+   * its center. Placement is asynchronous and committed as one undoable creation.
+   *
+   * @param options - Opening kind, catalog and host references, placement, and
+   *   optional facing, label, and dimensions
+   * @returns the {@linkcode ComponentHandle} of the placed door or window
+   * @throws if the options are invalid, the catalog id is unknown, the host is
+   *   not a wall, loading fails, or the opening cannot be placed on the host
+   *
+   * @examplePrompt Add a 1m wide door to this wall here
+   * @examplePrompt Place a window with a 0.9m sill height on the selected wall
+   *
+   * @performance Single-opening creator — use it for one hosted opening. A plural
+   *   API is intentionally unavailable until host placement can be atomic.
+   *
+   * # Example
+   * ```ts
+   * const opening = await snaptrude.design.create.opening({
+   *   kind: "window",
+   *   catalogId: windowType.id,
+   *   hostWall: wall,
+   *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   width: 1.2,
+   *   height: 1.5,
+   *   sillHeight: 0.9,
+   * })
+   * ```
+   */
+  public abstract opening(
+    options: PluginDesignCreateOpeningOptions,
+  ): PluginApiReturn<ComponentHandle>
+
   /**
    * Place a **smart layout** — clone an in-scene template cluster (walls,
    * furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT
@@ -908,6 +962,24 @@ export const PluginStaircasePreset = z.enum([
 ])
 export type PluginStaircasePreset = z.infer<typeof PluginStaircasePreset>
 
+/**
+ * Optional staircase dimension overrides. Lengths use Snaptrude engine units
+ * and must be positive. `angleInDegrees` controls placement about the vertical
+ * axis and must be a multiple of 90 degrees.
+ */
+export const PluginStaircaseDimensions = z
+  .object({
+    width: z.number().finite().positive().optional(),
+    tread: z.number().finite().positive().optional(),
+    riser: z.number().finite().positive().optional(),
+    landingWidth: z.number().finite().positive().optional(),
+    angleInDegrees: z.number().finite().multipleOf(90).optional(),
+  })
+  .strict()
+export type PluginStaircaseDimensions = z.infer<
+  typeof PluginStaircaseDimensions
+>
+
 // ---------------------------------------------------------------------------
 // space
 // ---------------------------------------------------------------------------
@@ -1135,18 +1207,20 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `height` | `number`? | Wall height (default engine default) |
  * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
  * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
   wallType: z.string().min(1).optional(),
+  storey: z.number().int().optional(),
 })
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs
 >
-// TRANSPORT: positional signature shipped — wallType is the trailing 4th arg:
-//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string)
+// TRANSPORT: positional signature shipped — storey is the trailing 5th arg:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number)
 
 // ---------------------------------------------------------------------------
 // staircase
@@ -1162,6 +1236,7 @@ export type PluginDesignCreateWallsArgs = z.infer<
  * | `label` | `string`? | Optional label |
  * | `structureId` | `string`? | Target structure (default active) |
  * | `level` | `string`? | Target level name (default active/`"01"`) |
+ * | `dimensions` | {@linkcode PluginStaircaseDimensions}? | Positive dimension overrides in engine units, applied before creation |
  */
 export const PluginDesignCreateStaircaseArgs = z.object({
   preset: PluginStaircasePreset,
@@ -1169,6 +1244,7 @@ export const PluginDesignCreateStaircaseArgs = z.object({
   label: z.string().optional(),
   structureId: z.string().optional(),
   level: z.string().optional(),
+  dimensions: PluginStaircaseDimensions.optional(),
 })
 export type PluginDesignCreateStaircaseArgs = z.infer<
   typeof PluginDesignCreateStaircaseArgs
@@ -1258,6 +1334,45 @@ export type PluginDesignCreateWindowArgs = z.infer<
 // TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
 //   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
 
+// ---------------------------------------------------------------------------
+// opening
+// ---------------------------------------------------------------------------
+
+const PluginOpeningBaseOptions = {
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  facing: Vec3Handle.optional(),
+  label: z.string().optional(),
+  width: z.number().finite().positive().optional(),
+  height: z.number().finite().positive().optional(),
+}
+
+/**
+ * Options for {@linkcode PluginDesignCreateApi.opening}, discriminated by
+ * `kind`. Width and height are positive Snaptrude engine-unit values.
+ * `sillHeight` is available only for windows, is nonnegative, and is precisely
+ * the distance from the host wall base to the bottom of the window.
+ */
+export const PluginDesignCreateOpeningOptions = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("door"),
+      ...PluginOpeningBaseOptions,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("window"),
+      ...PluginOpeningBaseOptions,
+      sillHeight: z.number().finite().nonnegative().optional(),
+    })
+    .strict(),
+])
+export type PluginDesignCreateOpeningOptions = z.infer<
+  typeof PluginDesignCreateOpeningOptions
+>
+
 // ---------------------------------------------------------------------------
 // smartLayout
 // ---------------------------------------------------------------------------

package/src/api/program/index.ts

@@ -23,7 +23,7 @@ import { PluginProgramAreasApi } from "./areas"
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
- * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
+ * - {@linkcode PluginProgramApi.site} — Read site/plot context and read/update Site Analysis
  * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
@@ -42,7 +42,7 @@ export abstract class PluginProgramApi {
   public abstract areas: PluginProgramAreasApi
   /** Spreadsheet reports — render tables to sheets, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
   public abstract spreadsheet: PluginProgramSpreadsheetApi
-  /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
+  /** Site/plot context and persisted Site Analysis. See {@linkcode PluginProgramSiteApi}. */
   public abstract site: PluginProgramSiteApi
   /** Vertical-circulation cores — read & predicate (reads only). See {@linkcode PluginProgramCoresApi}. */
   public abstract cores: PluginProgramCoresApi

package/src/api/program/site.ts

@@ -10,14 +10,17 @@ import { PluginAreaUnit } from "./metrics"
  * in Snaptrude units — the same plan space as a space's `planPoints`), and —
  * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
- * zoning numbers (FAR/FSI, height limits) live in the site-analysis sheet and
- * are not read here — with one exception: `listEdges` reads each parcel's
- * per-edge front/side/rear classification and effective base setbacks, the
- * same resolution the buildable-envelope setback pills show on canvas.
+ * zoning numbers (FAR/FSI, height limits) live in the Site Analysis sheet and
+ * are available through `getSiteAnalysis`, not the site-context reads. One
+ * context exception is `listEdges`: it reads each parcel's per-edge
+ * front/side/rear classification and effective base setbacks, the same
+ * resolution the buildable-envelope setback pills show on canvas.
  *
- * All methods are reads: they return plain records and never throw — `get`
- * returns an empty snapshot (zero totals) when there is no site, and the `list`
- * methods return `[]`.
+ * Site context methods are total reads: they return plain records and never
+ * throw — `get` returns an empty snapshot (zero totals) when there is no site,
+ * and the `list` methods return `[]`. Site Analysis is the exception:
+ * `getSiteAnalysis` reads the active proposal's persisted analysis sheet and
+ * `updateSiteAnalysis` performs a safe merge/append write to that sheet.
  *
  * Accessed via `snaptrude.program.site`.
  */
@@ -279,8 +282,126 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>
+
+  /**
+   * Read the persisted Site Analysis sheet for the active proposal.
+   *
+   * The read works without Program mode open. When a Program tab is open, the
+   * host first makes a best-effort attempt to flush its pending edits. The
+   * active proposal's sheet is preferred, with the base `"Site Analysis"`
+   * sheet as fallback. Returns `null` when no parseable sheet is persisted.
+   *
+   * @returns The persisted site location, polygon, and constraint rows, or
+   *   `null` when no Site Analysis data exists. This read never throws.
+   *
+   * @examplePrompt Read the current Site Analysis sheet
+   * @examplePrompt What zoning constraints are recorded for this proposal?
+   *
+   * # Example
+   * ```ts
+   * const analysis = await snaptrude.program.site.getSiteAnalysis()
+   * if (analysis) console.log(analysis.sheetName, analysis.rows)
+   * ```
+   */
+  public abstract getSiteAnalysis(): PluginApiReturn<PluginProgramSiteAnalysisResult>
+
+  /**
+   * Merge sourced site/zoning constraints into the active proposal's persisted
+   * Site Analysis sheet.
+   *
+   * Rows match by trimmed, case-insensitive Category + Description. Matched
+   * rows update only Quantity/Unit; unmatched rows append. Existing labels,
+   * formatting, and unrelated rows remain intact. There is deliberately no
+   * replace/reset mode — an appended duplicate row can NEVER be removed, so
+   * there is no "write now, fix later". Send only the rows that were actually
+   * sourced, ALWAYS call `getSiteAnalysis` first and reuse the sheet's exact
+   * labels, and never use `program.spreadsheet.setValues` for Site Analysis
+   * data — this method is the only correct writer. Check the result:
+   * `updatedRows` should account for every row that had a template match; an
+   * unexpected `appendedRows` usually means a label did not match the read's
+   * vocabulary.
+   *
+   * When Program mode is open, the host writes through the live sheet. Without
+   * a live tab it safely merges the persisted document. The call rejects rather
+   * than risk overwriting unflushed live edits or an unparseable existing sheet.
+   *
+   * @param rows - One or more sourced constraint rows to merge or append.
+   * @param options - Optional site location and JSON-encoded site polygon.
+   * @returns The target sheet name and merge counts.
+   * @throws PRECONDITION_FAILED when proposals exist but none is active, or
+   *   when live Program edits cannot be flushed safely.
+   *
+   * @examplePrompt Save these zoning constraints to Site Analysis
+   * @examplePrompt Update the FAR and setbacks in the Site Analysis sheet
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.program.site.updateSiteAnalysis([
+   *   { category: "FAR", description: "Floor Area Ratio", quantity: 3.5, unit: "ratio" },
+   *   { category: "Set backs", description: "Front setbacks", quantity: 6, unit: "m" },
+   * ])
+   * console.log(result.sheetName, result.updatedRows, result.appendedRows)
+   * ```
+   */
+  public abstract updateSiteAnalysis(
+    rows: PluginSiteAnalysisRow[],
+    options?: PluginSiteAnalysisUpdateOptions,
+  ): PluginApiReturn<PluginProgramSiteAnalysisUpdateResult>
 }
 
+/**
+ * A constraint row stored in the Site Analysis sheet. A `quantity` of `"-"`
+ * means the value is not recorded yet — never echo `"-"` back as a sourced
+ * value.
+ */
+export const PluginSiteAnalysisRow = z.object({
+  category: z.string().min(1),
+  description: z.string(),
+  quantity: z.union([z.string(), z.number()]),
+  unit: z.string(),
+})
+export type PluginSiteAnalysisRow = z.infer<typeof PluginSiteAnalysisRow>
+
+/**
+ * Optional site context persisted alongside Site Analysis constraint rows.
+ * `null` and `undefined` are both accepted as "no options".
+ */
+export const PluginSiteAnalysisUpdateOptions = z
+  .object({
+    siteLocation: z.object({ lat: z.number(), lng: z.number() }).optional(),
+    /** JSON-encoded polygon string written to the Site Polygon row. */
+    sitePolygon: z.string().optional(),
+  })
+  .nullish()
+export type PluginSiteAnalysisUpdateOptions = z.infer<
+  typeof PluginSiteAnalysisUpdateOptions
+>
+
+/** Persisted Site Analysis data for the active proposal. */
+export const PluginProgramSiteAnalysisResult = z
+  .object({
+    sheetName: z.string(),
+    siteLocation: z.object({ lat: z.number(), lng: z.number() }).nullable(),
+    sitePolygon: z.string().nullable(),
+    rows: z.array(PluginSiteAnalysisRow),
+  })
+  .nullable()
+export type PluginProgramSiteAnalysisResult = z.infer<
+  typeof PluginProgramSiteAnalysisResult
+>
+
+/** Result of a merge/append Site Analysis write. */
+export const PluginProgramSiteAnalysisUpdateResult = z.object({
+  sheetName: z.string(),
+  /** Constraint rows on the sheet after the write. */
+  rowCount: z.number(),
+  updatedRows: z.number(),
+  appendedRows: z.number(),
+})
+export type PluginProgramSiteAnalysisUpdateResult = z.infer<
+  typeof PluginProgramSiteAnalysisUpdateResult
+>
+
 /**
  * A 2D ground-plane point of a site parcel footprint, in world XZ plan
  * coordinates (Snaptrude units) — the same plan space as a space's
@@ -564,7 +685,9 @@ export type PluginProgramSiteWeatherResult = z.infer<
  * never appears — the backend synonym resolves to `front`.
  */
 export const PluginProgramSiteEdgeRole = z.enum(["front", "side", "rear"])
-export type PluginProgramSiteEdgeRole = z.infer<typeof PluginProgramSiteEdgeRole>
+export type PluginProgramSiteEdgeRole = z.infer<
+  typeof PluginProgramSiteEdgeRole
+>
 
 /**
  * One boundary edge of a site parcel, as {@linkcode PluginProgramSiteApi.listEdges}

package/src/handles.ts

@@ -22,7 +22,7 @@ import type { ArenaKind } from "./api/core/handles"
  * handle eventually releases its host registry entry. Deterministic release is
  * still preferred: `core.handles.release/releaseAll` or scopes.
  *
- * Crossing non-RPC boundaries (popup UI postMessage, persistence, logging):
+ * Crossing non-RPC boundaries (UI postMessage, persistence, logging):
  * send {@linkcode Handle.id} — structured clone strips the class prototype.
  */
 export class Handle<K extends string> {
@@ -173,7 +173,7 @@ export type BBoxComponents = { min: Vec3Components; max: Vec3Components }
  *  - the bare id string (the wire form — the client unwraps args to ids)
  *  - a live `Handle` instance (host-internal re-parse, direct host callers)
  *  - `{ __h: string }` (the tagged result form, echoed back as an arg)
- *  - `{ id: string }` (a Handle stripped by structured clone at the popup-UI boundary)
+ *  - `{ id: string }` (a Handle stripped by structured clone at the UI boundary)
  * Shape checking stays prefix-only; existence, kind, and ownership are enforced
  * host-side by the HandleRegistry (§9.7) — no existence oracle.
  */