@snaptrude/plugin-core 0.10.0 → 1.0.0

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
+>

package/src/api/entity/buildableEnvelope.ts

@@ -1,5 +1,9 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import {
+  PluginProgramSiteEdgeRole,
+  PluginProgramSiteEdgesEntry,
+} from "../program/site"
 
 /**
  * Buildable Envelope management — create and update parametric zoning envelopes.
@@ -72,6 +76,11 @@ export abstract class PluginBuildableEnvelopeApi {
    * volume from a revised site polygon, setbacks, vertical cap, or FAR and
    * lot-coverage limits, keeping the same envelope id.
    *
+   * 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.
@@ -82,9 +91,15 @@ export abstract class PluginBuildableEnvelopeApi {
    * @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
@@ -312,11 +327,71 @@ export type PluginBuildableEnvelopeUpdateArgs = z.infer<
  * | Property | Type | Description |
  * |---|---|---|
  * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
+ * | `clearedEdgeSetbacks` | `number[]` | `edgeIndex` of every edge whose own custom distance was cleared because its type's (front/side/rear) value changed; empty when none |
  */
 export const PluginBuildableEnvelopeUpdateResult = z.object({
   buildableEnvelopeId: z.string().min(1),
+  clearedEdgeSetbacks: z.array(z.number().int().nonnegative()),
 }).strict()
 
 export type PluginBuildableEnvelopeUpdateResult = z.infer<
   typeof PluginBuildableEnvelopeUpdateResult
 >
+
+/**
+ * Patch for one site edge, as taken by `design.update.siteEdge`.
+ *
+ * Strict schema. Provide `role`, `setback`, or both. A numeric `setback`
+ * requires `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | `"front" \| "side" \| "rear"`? | New edge type. Setting it clears the edge's own distance |
+ * | `setback` | `number \| null`? | This edge's own setback distance in `lengthUnit` (finite, nonnegative); `null` clears it so the edge falls back to its type's distance |
+ * | `lengthUnit` | `"m" \| "ft"`? | Unit of `setback`; required when `setback` is a number |
+ */
+export const PluginSiteEdgePatch = z
+  .object({
+    role: PluginProgramSiteEdgeRole.optional(),
+    // null = clear this edge's own distance
+    setback: z.number().finite().nonnegative().nullable().optional(),
+    lengthUnit: z.enum(["m", "ft"]).optional(),
+  })
+  .strict()
+  .refine(
+    (p) => p.role !== undefined || p.setback !== undefined,
+    "patch must set role and/or setback"
+  )
+  .refine(
+    (p) => typeof p.setback !== "number" || p.lengthUnit !== undefined,
+    "lengthUnit is required with a numeric setback"
+  )
+
+export type PluginSiteEdgePatch = z.infer<typeof PluginSiteEdgePatch>
+
+/**
+ * Result of `design.update.siteEdge` — the refreshed edge entry for the
+ * site, exactly as `program.site.listEdges()` returns it.
+ */
+export const PluginDesignUpdateSiteEdgeResult = PluginProgramSiteEdgesEntry
+
+export type PluginDesignUpdateSiteEdgeResult = z.infer<
+  typeof PluginDesignUpdateSiteEdgeResult
+>
+
+/**
+ * Result of `design.create.buildableEnvelopeFromSite`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | ID of the created buildable envelope |
+ */
+export const PluginDesignCreateBuildableEnvelopeFromSiteResult = z
+  .object({
+    buildableEnvelopeId: z.string(),
+  })
+  .strict()
+
+export type PluginDesignCreateBuildableEnvelopeFromSiteResult = z.infer<
+  typeof PluginDesignCreateBuildableEnvelopeFromSiteResult
+>

package/src/api/entity/referenceLine.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { ProfileHandle, CurveHandle } from "../../handles"
+import { PluginGraphicsLineStyleId } from "../presentation/graphics"
 
 /**
  * Reference line management — create, query, and delete reference lines.
@@ -53,7 +54,7 @@ export abstract class PluginReferenceLineApi {
    * @deprecated Use `design.create.referenceLines`
    */
   public abstract createMulti(
-    profile: ProfileHandle
+    profile: ProfileHandle,
   ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
 
   /**
@@ -85,7 +86,7 @@ export abstract class PluginReferenceLineApi {
    */
   public abstract get(
     referenceLineId: string,
-    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[],
   ): PluginApiReturn<PluginReferenceLineGetResult>
 
   /**
@@ -135,7 +136,7 @@ export abstract class PluginReferenceLineApi {
    * @deprecated Use `design.delete.entities`
    */
   public abstract delete(
-    referenceLineId: string
+    referenceLineId: string,
   ): PluginApiReturn<PluginReferenceLineDeleteResult>
 }
 
@@ -150,7 +151,9 @@ export const PluginReferenceLineCreateMultiArgs = z.object({
   profile: ProfileHandle,
 })
 
-export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
+export type PluginReferenceLineCreateMultiArgs = z.infer<
+  typeof PluginReferenceLineCreateMultiArgs
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.createMulti}.
@@ -163,7 +166,9 @@ export const PluginReferenceLineCreateMultiResult = z.object({
   referenceLineIds: z.array(z.string()),
 })
 
-export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
+export type PluginReferenceLineCreateMultiResult = z.infer<
+  typeof PluginReferenceLineCreateMultiResult
+>
 
 /**
  * Available properties that can be queried on a reference line.
@@ -171,10 +176,9 @@ export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenc
  * | Value | Return Type | Description |
  * |---|---|---|
  * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
+ * | `"styleId"` | `PluginGraphicsLineStyleId \| null` | Project style, or null for an unstyled legacy line |
  */
-export const PluginReferenceLineGetProperty = z.enum([
-  "curve",
-])
+export const PluginReferenceLineGetProperty = z.enum(["curve", "styleId"])
 
 /**
  * Arguments for {@linkcode PluginReferenceLineApi.get}.
@@ -189,7 +193,9 @@ export const PluginReferenceLineGetArgs = z.object({
   properties: z.array(PluginReferenceLineGetProperty),
 })
 
-export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
+export type PluginReferenceLineGetArgs = z.infer<
+  typeof PluginReferenceLineGetArgs
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.get}.
@@ -200,10 +206,13 @@ export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetAr
 export const PluginReferenceLineGetResult = z
   .object({
     curve: CurveHandle,
+    styleId: PluginGraphicsLineStyleId.nullable(),
   })
   .partial()
 
-export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
+export type PluginReferenceLineGetResult = z.infer<
+  typeof PluginReferenceLineGetResult
+>
 
 /**
  * Result of {@linkcode PluginReferenceLineApi.getAll}.
@@ -216,7 +225,9 @@ export const PluginReferenceLineGetAllResult = z.object({
   referenceLineIds: z.array(z.string()),
 })
 
-export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
+export type PluginReferenceLineGetAllResult = z.infer<
+  typeof PluginReferenceLineGetAllResult
+>
 
 /**
  * Arguments for {@linkcode PluginReferenceLineApi.delete}.
@@ -229,7 +240,9 @@ export const PluginReferenceLineDeleteArgs = z.object({
   referenceLineId: z.string(),
 })
 
-export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
+export type PluginReferenceLineDeleteArgs = z.infer<
+  typeof PluginReferenceLineDeleteArgs
+>
 
 /** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
 export type PluginReferenceLineDeleteResult = void