@snaptrude/plugin-core 0.9.2 → 0.9.4

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.
  */