@snaptrude/plugin-core 0.8.0 → 0.9.0

package/dist/api/analysis/heatmaps.d.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
-import { ComponentHandle } from "../../handles";
+import { ComponentHandle, Vec3Components } from "../../handles";
 /**
  * Analysis heatmaps — render plugin-computed scalar data as a heatmap.
  *
@@ -15,15 +15,25 @@ import { ComponentHandle } from "../../handles";
  * - {@linkcode PluginAnalysisHeatmapsApi.renderGrid} — a coloured grid mesh
  *   from point samples in world coordinates (wind, noise, microclimate — any
  *   field sampled over an area).
+ * - {@linkcode PluginAnalysisHeatmapsApi.renderField} — arbitrary planar
+ *   polygon cells (or pre-tessellated meshes), one scalar value each — for
+ *   non-square analysis meshes straight from a solver.
  *
  * Shared semantics:
  *
- * - **Single active heatmap** — a render call **replaces** whatever heatmap
- *   is currently showing (from either mode).
+ * - **Named overlays** — every render call targets a named overlay
+ *   (`options.name`; a shared default overlay when omitted). Rendering an
+ *   existing name replaces that overlay only; the newly rendered overlay
+ *   becomes the visible one — **exactly one overlay is visible at a time**.
+ *   Up to 16 overlays can be registered; manage them (list / show / hide /
+ *   remove) via {@linkcode PluginAnalysisHeatmapsApi.overlays}.
  * - **Legend** — the host renders a legend card from
  *   {@linkcode PluginAnalysisHeatmapOptions} (title, unit, min/max, colour
  *   segments). Values outside `[min, max]` **clamp to the end colours** and
  *   the legend shows `<` / `>` markers at the clamped ends.
+ * - **Hover tooltip** — pass `options.hover: true` to any render call and,
+ *   while that overlay is visible, hovering a cell shows a tooltip with the
+ *   cell's `value` (and its `meta` payload, when the cell carries one).
  * - **Ephemeral** — the heatmap is a transient overlay: never persisted,
  *   never saved with views, and auto-cleared when a scene-mutating edit
  *   invalidates it. Re-render after changing the model.
@@ -31,14 +41,21 @@ import { ComponentHandle } from "../../handles";
  * Accessed via `snaptrude.analysis.heatmaps`.
  */
 export declare abstract class PluginAnalysisHeatmapsApi {
+    /**
+     * Manage the named heatmap overlays created by the render calls —
+     * list / show / hide / remove. See
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi}.
+     */
+    abstract overlays: PluginAnalysisHeatmapOverlaysApi;
     constructor();
     /**
      * Render a per-space heatmap — one flat colour per space's top face.
      *
      * Each entry maps a space to a scalar value; the value is mapped through
      * the colour ramp (see {@linkcode PluginAnalysisHeatmapOptions}) and the
-     * space's top face is painted that single flat colour. Replaces any
-     * heatmap currently showing (single active heatmap). Spaces whose top
+     * space's top face is painted that single flat colour. Renders into the
+     * overlay named `options.name` (the default overlay when omitted),
+     * replacing that overlay only and making it the visible one. Spaces whose top
      * face is not flat (pitched/sloped tops) are **skipped with a console
      * warning** — the rest of the heatmap still renders.
      *
@@ -57,6 +74,8 @@ export declare abstract class PluginAnalysisHeatmapsApi {
      *   skipped).
      * @throws When `options.min` is greater than `options.max`.
      * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Color each room by its occupancy count
@@ -83,8 +102,9 @@ export declare abstract class PluginAnalysisHeatmapsApi {
      * {@linkcode PluginUnitsApi.convert}) — coloured by mapping the value
      * through the colour ramp
      * (see {@linkcode PluginAnalysisHeatmapOptions}). This is the mode for
-     * field data — wind, noise, microclimate — sampled over an area. Replaces
-     * any heatmap currently showing (single active heatmap).
+     * field data — wind, noise, microclimate — sampled over an area. Renders
+     * into the overlay named `options.name` (the default overlay when
+     * omitted), replacing that overlay only and making it the visible one.
      *
      * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
      * and is never persisted or saved with views.
@@ -102,6 +122,8 @@ export declare abstract class PluginAnalysisHeatmapsApi {
      * @throws When `cells` is empty or `cellSize` is not a positive, finite number.
      * @throws When `options.min` is greater than `options.max`.
      * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Overlay my CFD wind simulation results on the site
@@ -120,15 +142,142 @@ export declare abstract class PluginAnalysisHeatmapsApi {
      */
     abstract renderGrid(cells: PluginAnalysisHeatmapGridCell[], cellSize: number, options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
     /**
-     * Clear the plugin heatmap from the scene.
+     * Render a grid heatmap on an **arbitrarily oriented plane** — a façade,
+     * a section cut, any flat surface.
+     *
+     * The same point-sample model as
+     * {@linkcode PluginAnalysisHeatmapsApi.renderGrid}, generalised: cells lie
+     * on the plane whose direction is given by `normal` (for a façade, the
+     * outward wall normal). Each cell is a square of edge `cellSize` centred
+     * on its **world-coordinate** `position` and oriented in that plane; the
+     * host derives the in-plane axes from the normal and offsets each cell a
+     * hair along it so the heatmap never z-fights the surface it annotates.
+     * Cell positions should lie on (or very near) the surface being
+     * annotated — the host does not project them. Renders into the overlay
+     * named `options.name` (the default overlay when omitted), replacing
+     * that overlay only and making it the visible one.
      *
-     * Un-applies the rendered heatmap (either mode) and removes its legend.
-     * A no-op (returns `false`) when no plugin heatmap is showing. Does not
-     * touch the built-in study heatmaps (`sunlightHours` / `illuminance`) —
-     * they have their own `reset`.
+     * This is the mode for per-façade data — solar irradiance, glare, panel
+     * yield, wind pressure — sampled over a vertical or sloped face. For
+     * horizontal ground fields prefer
+     * {@linkcode PluginAnalysisHeatmapsApi.renderGrid}, which is this call
+     * with `normal = { x: 0, y: 1, z: 0 }`.
      *
-     * @returns `true` when a heatmap was cleared, `false` when none was
-     *   showing.
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param cells - One {@linkcode PluginAnalysisHeatmapGridCell} per
+     *   sample: a world-coordinate `position` on the surface plane (y up)
+     *   and its scalar `value`.
+     * @param cellSize - Edge length of each (square) cell, in the same
+     *   Snaptrude internal units as `position` (see
+     *   {@linkcode PluginUnitsApi.convert}). Must be a positive, finite number.
+     * @param normal - The plane's normal direction as `{ x, y, z }` (for a
+     *   façade, the outward wall normal — read it via
+     *   `core.geom.query.face.getNormal` on the wall's face). Any non-zero
+     *   length; the host normalises it.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, explicit min/max range (auto-derived from the data when
+     *   omitted), and the colour ramp.
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `cells` is empty, `cellSize` is not a positive finite
+     *   number, or `normal` has zero length.
+     * @throws When `options.min` is greater than `options.max`.
+     * @throws When a colour in `options.colors` is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Paint the solar irradiance results on the south façade
+     * @examplePrompt Show my daylight values as a heatmap on this wall
+     * @examplePrompt Render panel-level PV yield on the building face
+     * @examplePrompt Overlay wind pressure on the tower's west elevation
+     *
+     * # Example
+     * ```ts
+     * // Samples lie on a wall plane facing +X; colour each 1-unit cell by irradiance.
+     * await snaptrude.analysis.heatmaps.renderSurfaceGrid(
+     *   samples.map((s) => ({ position: { x: wallX, y: s.y, z: s.z }, value: s.irradiance })),
+     *   1,
+     *   { x: 1, y: 0, z: 0 }, // façade normal
+     *   { title: "Irradiance", unit: "kWh/m²", colors: ["#0000ff", "#ffff00", "#ff0000"] },
+     * )
+     * ```
+     */
+    abstract renderSurfaceGrid(cells: PluginAnalysisHeatmapGridCell[], cellSize: number, normal: Vec3Components, options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Render a heatmap from **arbitrary cell geometry** — planar polygons or
+     * pre-tessellated meshes, one scalar value each.
+     *
+     * The free-form sibling of the grid calls: instead of square cells, each
+     * {@linkcode PluginAnalysisHeatmapFieldCell} brings its own footprint in
+     * **world coordinates** (y up) — either a planar `polygon` ring (3+
+     * points, any orientation; the host triangulates it) or a pre-tessellated
+     * `vertices` + `indices` mesh (triangle list). This is the mode for
+     * analysis meshes straight from a solver: FEA/CFD cells, Voronoi regions,
+     * per-panel façade patches — anything not on a square grid. Each cell's
+     * `value` is mapped through the colour scale
+     * (see {@linkcode PluginAnalysisHeatmapOptions}, including
+     * `options.scale`); an optional `meta` payload is stored with the overlay
+     * for later features. Renders into the overlay named `options.name` (the
+     * default overlay when omitted), replacing that overlay only and making
+     * it the visible one.
+     *
+     * Degenerate polygon cells (collinear points, zero area) are **skipped
+     * with a console warning** — the rest of the heatmap still renders.
+     *
+     * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+     * and is never persisted or saved with views.
+     *
+     * @param cells - One {@linkcode PluginAnalysisHeatmapFieldCell} per cell:
+     *   a planar `polygon` ring OR a `vertices`/`indices` triangle mesh, plus
+     *   its scalar `value` and optional `meta`.
+     * @param options - {@linkcode PluginAnalysisHeatmapOptions} — legend
+     *   title/unit, min/max range, colour ramp, and the colour `scale`
+     *   (bands / threshold / categorical).
+     * @returns A {@linkcode PluginAnalysisHeatmapsRenderResult} —
+     *   `{ success: true }` once the heatmap is rendered.
+     * @throws When `cells` is empty, a polygon has fewer than 3 points, a
+     *   pre-tessellated cell's `indices` length is not a multiple of 3, or an
+     *   index is out of range of its `vertices`.
+     * @throws When every polygon cell was degenerate (nothing renderable).
+     * @throws When a `categorical` scale has no class for a cell's value.
+     * @throws When `options.min` is greater than `options.max`, or a colour
+     *   is not a 6-digit hex colour.
+     * @throws When `options.name` is a new overlay name and the 16-overlay
+     *   cap is reached.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Overlay my FEA stress results on their solver mesh
+     * @examplePrompt Color these Voronoi regions by footfall
+     * @examplePrompt Paint each façade panel polygon by its PV yield
+     * @examplePrompt Render pass/fail daylight compliance per zone polygon
+     *
+     * # Example
+     * ```ts
+     * // Two triangular cells at ground level, coloured pass/fail at 300 lux.
+     * await snaptrude.analysis.heatmaps.renderField(
+     *   [
+     *     { polygon: [{ x: 0, y: 0, z: 0 }, { x: 4, y: 0, z: 0 }, { x: 0, y: 0, z: 4 }], value: 420 },
+     *     { polygon: [{ x: 4, y: 0, z: 4 }, { x: 0, y: 0, z: 4 }, { x: 4, y: 0, z: 0 }], value: 180 },
+     *   ],
+     *   { title: "Daylight", unit: "lux", scale: { type: "threshold", threshold: 300 } },
+     * )
+     * ```
+     */
+    abstract renderField(cells: PluginAnalysisHeatmapFieldCell[], options?: PluginAnalysisHeatmapOptions): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>;
+    /**
+     * Clear every plugin heatmap overlay from the scene.
+     *
+     * Removes **all** registered overlays (equivalent to
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi.removeAll}) and closes the
+     * legend. A no-op (returns `false`) when no plugin heatmap exists. Does
+     * not touch the built-in study heatmaps (`sunlightHours` /
+     * `illuminance`) — they have their own `reset`.
+     *
+     * @returns `true` when at least one overlay was cleared, `false` when
+     *   none existed.
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Clear my custom heatmap
@@ -163,6 +312,132 @@ export declare abstract class PluginAnalysisHeatmapsApi {
      */
     abstract isActive(): PluginApiReturn<boolean>;
 }
+/**
+ * Heatmap overlay management — the named overlays created by the
+ * `analysis.heatmaps` render calls.
+ *
+ * Every render call registers (or replaces) an overlay under
+ * `options.name` — a shared default overlay when omitted. Overlays are
+ * in-session only: never persisted, never saved with views, and **all**
+ * of them are cleared together when a scene-mutating edit invalidates
+ * them. At most 16 overlays can be registered at once, and **exactly one
+ * overlay is visible at a time** — showing one hides the others, and the
+ * legend always describes the visible overlay.
+ *
+ * Accessed via `snaptrude.analysis.heatmaps.overlays`.
+ */
+export declare abstract class PluginAnalysisHeatmapOverlaysApi {
+    constructor();
+    /**
+     * List the registered heatmap overlays.
+     *
+     * Returns every overlay's `name`, `kind` (which render call produced
+     * it: `"spaces"`, `"grid"`, `"surfaceGrid"` or `"field"`) and whether it is the
+     * currently visible one. At most one overlay has `visible: true`.
+     *
+     * @returns A {@linkcode PluginAnalysisHeatmapOverlaysListResult} —
+     *   `{ overlays: [{ name, visible, kind }] }`, empty when nothing is
+     *   registered.
+     *
+     * @examplePrompt Which heatmap overlays do I have?
+     * @examplePrompt List my rendered analysis overlays
+     * @examplePrompt Check which heatmap is currently visible
+     *
+     * # Example
+     * ```ts
+     * const { overlays } = await snaptrude.analysis.heatmaps.overlays.list()
+     * const visible = overlays.find((o) => o.visible)
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginAnalysisHeatmapOverlaysListResult>;
+    /**
+     * Make a registered overlay the visible one.
+     *
+     * Enables the named overlay's meshes, hides whichever overlay was
+     * visible before, and swaps the legend to the shown overlay's. A no-op
+     * returning `false` when no overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay is now visible, `false` when no
+     *   overlay of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Switch back to my wind heatmap
+     * @examplePrompt Show the occupancy overlay
+     * @examplePrompt Flip between my two analysis overlays
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.show("wind")
+     * ```
+     */
+    abstract show(name: string): PluginApiReturn<boolean>;
+    /**
+     * Hide an overlay without removing it.
+     *
+     * Disables the named overlay's meshes; when it was the visible one its
+     * legend closes too (nothing visible → no legend). The overlay stays
+     * registered and can be brought back with
+     * {@linkcode PluginAnalysisHeatmapOverlaysApi.show}. A no-op returning
+     * `false` when no overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay exists (and is now hidden), `false`
+     *   when no overlay of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Hide the wind overlay but keep it around
+     * @examplePrompt Temporarily hide my heatmap
+     * @examplePrompt Turn off the occupancy colours without deleting them
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.hide("wind")
+     * ```
+     */
+    abstract hide(name: string): PluginApiReturn<boolean>;
+    /**
+     * Remove an overlay — dispose its meshes and forget it.
+     *
+     * Frees the overlay's slot toward the 16-overlay cap; when it was the
+     * visible one its legend closes. A no-op returning `false` when no
+     * overlay of that name exists.
+     *
+     * @param name - The overlay's name (`options.name` at render time).
+     * @returns `true` when the overlay was removed, `false` when no overlay
+     *   of that name exists.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Delete the wind overlay
+     * @examplePrompt Remove my occupancy heatmap for good
+     * @examplePrompt Free up an overlay slot
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.analysis.heatmaps.overlays.remove("wind")
+     * ```
+     */
+    abstract remove(name: string): PluginApiReturn<boolean>;
+    /**
+     * Remove every registered overlay and close the legend.
+     *
+     * The bulk form of {@linkcode PluginAnalysisHeatmapOverlaysApi.remove};
+     * `analysis.heatmaps.reset()` is this call under its historical name.
+     *
+     * @returns The number of overlays removed (`0` when none existed).
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Clear all my heatmap overlays
+     * @examplePrompt Remove every analysis overlay from the scene
+     * @examplePrompt Start over with a clean set of overlays
+     *
+     * # Example
+     * ```ts
+     * const removed = await snaptrude.analysis.heatmaps.overlays.removeAll()
+     * ```
+     */
+    abstract removeAll(): PluginApiReturn<number>;
+}
 /**
  * One space's entry in {@linkcode PluginAnalysisHeatmapsApi.renderSpaces}.
  *
@@ -183,6 +458,7 @@ export type PluginAnalysisHeatmapSpaceEntry = z.infer<typeof PluginAnalysisHeatm
  * |---|---|---|
  * | `position` | `{ x, y, z }` | Cell centre in **world coordinates** (y is up) |
  * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay — shown in the hover tooltip when `options.hover` is on |
  */
 export declare const PluginAnalysisHeatmapGridCell: z.ZodObject<{
     position: z.ZodObject<{
@@ -191,8 +467,93 @@ export declare const PluginAnalysisHeatmapGridCell: z.ZodObject<{
         z: z.ZodNumber;
     }, z.core.$strip>;
     value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 export type PluginAnalysisHeatmapGridCell = z.infer<typeof PluginAnalysisHeatmapGridCell>;
+/**
+ * One cell in {@linkcode PluginAnalysisHeatmapsApi.renderField} — either a
+ * planar polygon ring the host triangulates, or a pre-tessellated triangle
+ * mesh. All coordinates are **world coordinates** (y up).
+ *
+ * Polygon form:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `polygon` | `{ x, y, z }[]` | Planar ring of 3+ points (any orientation; no self-intersections) |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay |
+ *
+ * Pre-tessellated form:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `vertices` | `{ x, y, z }[]` | Mesh vertices (3+) |
+ * | `indices` | `number[]` | Triangle list into `vertices` — length a multiple of 3, every index in range |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ * | `meta` | `unknown \| undefined` | Optional payload stored with the overlay |
+ */
+export declare const PluginAnalysisHeatmapFieldCell: z.ZodUnion<readonly [z.ZodObject<{
+    polygon: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>>;
+    value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    vertices: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>>;
+    indices: z.ZodArray<z.ZodNumber>;
+    value: z.ZodNumber;
+    meta: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>]>;
+export type PluginAnalysisHeatmapFieldCell = z.infer<typeof PluginAnalysisHeatmapFieldCell>;
+/**
+ * The colour scale for a heatmap render — how values become colours and how
+ * the legend reads. Three kinds (discriminated by `type`):
+ *
+ * - **`bands`** — the default: the colour ramp quantised into `count`
+ *   discrete bands (2–64, default 11). The rendered mesh and legend always
+ *   use discrete bands; "continuous" is simply a high `count`.
+ * - **`threshold`** — binary pass/fail at a cut-off `threshold`: values
+ *   `>= threshold` get `passColor`, the rest `failColor`; the legend shows
+ *   the two labelled swatches.
+ * - **`categorical`** — exact-match classes: every cell value must equal
+ *   one class's `value` (anything else is a validation error); the legend
+ *   shows one labelled swatch per class.
+ *
+ * | Kind | Property | Type | Description |
+ * |---|---|---|---|
+ * | `bands` | `count` | `number \| undefined` | Number of discrete bands, 2–64 (default 11) |
+ * | `threshold` | `threshold` | `number` | Values `>= threshold` pass |
+ * | `threshold` | `passColor` | `string \| undefined` | Hex colour for passing values (host default green) |
+ * | `threshold` | `failColor` | `string \| undefined` | Hex colour for failing values (host default red) |
+ * | `threshold` | `passLabel` | `string \| undefined` | Legend label for the pass swatch (default `≥ threshold`) |
+ * | `threshold` | `failLabel` | `string \| undefined` | Legend label for the fail swatch (default `< threshold`) |
+ * | `categorical` | `classes` | `{ value, label, color }[]` | Exact-match classes: scalar `value`, legend `label`, hex `color` |
+ */
+export declare const PluginAnalysisHeatmapScale: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"bands">;
+    count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"threshold">;
+    threshold: z.ZodNumber;
+    passColor: z.ZodOptional<z.ZodString>;
+    failColor: z.ZodOptional<z.ZodString>;
+    passLabel: z.ZodOptional<z.ZodString>;
+    failLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"categorical">;
+    classes: z.ZodArray<z.ZodObject<{
+        value: z.ZodNumber;
+        label: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+export type PluginAnalysisHeatmapScale = z.infer<typeof PluginAnalysisHeatmapScale>;
 /**
  * Display options shared by both heatmap render modes.
  *
@@ -204,18 +565,41 @@ export type PluginAnalysisHeatmapGridCell = z.infer<typeof PluginAnalysisHeatmap
  *
  * | Property | Type | Description |
  * |---|---|---|
+ * | `name` | `string \| undefined` | Overlay name to render into (see {@linkcode PluginAnalysisHeatmapOverlaysApi}); a shared default overlay when omitted |
  * | `title` | `string \| undefined` | Legend title |
  * | `unit` | `string \| undefined` | Unit label shown on the legend (e.g. `"m/s"`) |
  * | `min` | `number \| undefined` | Value mapped to the first colour stop; data minimum when omitted |
  * | `max` | `number \| undefined` | Value mapped to the last colour stop; data maximum when omitted |
  * | `colors` | `string[] \| undefined` | Ordered 6-digit hex colour stops (e.g. `"#0000ff"`), low → high; host blue → cyan → green → yellow → red default |
+ * | `scale` | {@linkcode PluginAnalysisHeatmapScale}` \| undefined` | Colour scale: discrete `bands` (count 2–64, default 11), binary `threshold`, or exact-match `categorical` |
+ * | `hover` | `boolean \| undefined` | Show a tooltip with the hovered cell's `value` (+ its `meta`, when given) while this overlay is visible. Default `false` |
  */
 export declare const PluginAnalysisHeatmapOptions: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     unit: z.ZodOptional<z.ZodString>;
     min: z.ZodOptional<z.ZodNumber>;
     max: z.ZodOptional<z.ZodNumber>;
     colors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scale: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"bands">;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"threshold">;
+        threshold: z.ZodNumber;
+        passColor: z.ZodOptional<z.ZodString>;
+        failColor: z.ZodOptional<z.ZodString>;
+        passLabel: z.ZodOptional<z.ZodString>;
+        failLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"categorical">;
+        classes: z.ZodArray<z.ZodObject<{
+            value: z.ZodNumber;
+            label: z.ZodString;
+            color: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "type">>;
+    hover: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type PluginAnalysisHeatmapOptions = z.infer<typeof PluginAnalysisHeatmapOptions>;
 /**
@@ -231,4 +615,44 @@ export declare const PluginAnalysisHeatmapsRenderResult: z.ZodObject<{
     success: z.ZodLiteral<true>;
 }, z.core.$strip>;
 export type PluginAnalysisHeatmapsRenderResult = z.infer<typeof PluginAnalysisHeatmapsRenderResult>;
+/**
+ * One overlay row in {@linkcode PluginAnalysisHeatmapOverlaysApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The overlay's name (`options.name` at render time) |
+ * | `visible` | `boolean` | Whether this is the (single) visible overlay |
+ * | `kind` | `"spaces" \| "grid" \| "surfaceGrid" \| "field"` | Which render call produced it |
+ */
+export declare const PluginAnalysisHeatmapOverlayInfo: z.ZodObject<{
+    name: z.ZodString;
+    visible: z.ZodBoolean;
+    kind: z.ZodEnum<{
+        spaces: "spaces";
+        grid: "grid";
+        surfaceGrid: "surfaceGrid";
+        field: "field";
+    }>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapOverlayInfo = z.infer<typeof PluginAnalysisHeatmapOverlayInfo>;
+/**
+ * Result of {@linkcode PluginAnalysisHeatmapOverlaysApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `overlays` | {@linkcode PluginAnalysisHeatmapOverlayInfo}`[]` | Every registered overlay; at most one has `visible: true` |
+ */
+export declare const PluginAnalysisHeatmapOverlaysListResult: z.ZodObject<{
+    overlays: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        visible: z.ZodBoolean;
+        kind: z.ZodEnum<{
+            spaces: "spaces";
+            grid: "grid";
+            surfaceGrid: "surfaceGrid";
+            field: "field";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginAnalysisHeatmapOverlaysListResult = z.infer<typeof PluginAnalysisHeatmapOverlaysListResult>;
 //# sourceMappingURL=heatmaps.d.ts.map

package/dist/api/analysis/heatmaps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heatmaps.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/heatmaps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8BAAsB,yBAAyB;;IAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;aACa,YAAY,CAC1B,OAAO,EAAE,+BAA+B,EAAE,EAC1C,OAAO,CAAC,EAAE,4BAA4B,GACrC,eAAe,CAAC,kCAAkC,CAAC;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;aACa,UAAU,CACxB,KAAK,EAAE,6BAA6B,EAAE,EACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,4BAA4B,GACrC,eAAe,CAAC,kCAAkC,CAAC;IAEtD;;;;;;;;;;;;;;;;;;;;OAoBG;aACa,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,QAAQ,IAAI,eAAe,CAAC,OAAO,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B;;;iBAG1C,CAAA;AACF,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACnD,OAAO,+BAA+B,CACvC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B;;;;;;;iBAGxC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,6BAA6B,CACrC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,4BAA4B;;;;;;iBASvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC;;iBAE7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA"}
+{"version":3,"file":"heatmaps.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/heatmaps.ts"],"names":[],"mappings":"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"}

package/dist/api/analysis/index.d.ts

@@ -3,6 +3,9 @@ import { PluginAnalysisShadowsApi } from "./shadows";
 import { PluginAnalysisSunlightHoursApi } from "./sunlightHours";
 import { PluginAnalysisIlluminanceApi } from "./illuminance";
 import { PluginAnalysisHeatmapsApi } from "./heatmaps";
+import { PluginAnalysisWeatherApi } from "./weather";
+import { PluginAnalysisSolarApi } from "./solar";
+import { PluginAnalysisDaylightApi } from "./daylight";
 /**
  * Sustainability-analysis APIs.
  *
@@ -20,6 +23,9 @@ import { PluginAnalysisHeatmapsApi } from "./heatmaps";
  * - {@linkcode PluginAnalysisApi.sunlightHours} — Direct-sunlight-hours heatmap job (start / poll / cancel / clear)
  * - {@linkcode PluginAnalysisApi.illuminance} — Daylight-illuminance heatmap job, Pro-gated (start / poll / cancel / clear)
  * - {@linkcode PluginAnalysisApi.heatmaps} — Render plugin-computed scalar data as a heatmap (per-space / grid)
+ * - {@linkcode PluginAnalysisApi.weather} — Read the site's typical-year weather series (numeric, paged)
+ * - {@linkcode PluginAnalysisApi.solar} — Sample solar exposure at caller-chosen points (numeric)
+ * - {@linkcode PluginAnalysisApi.daylight} — Standards-grade annual daylight metrics (IES LM-83, numeric)
  *
  * Accessed via `snaptrude.analysis`.
  */
@@ -34,6 +40,12 @@ export declare abstract class PluginAnalysisApi {
     abstract illuminance: PluginAnalysisIlluminanceApi;
     /** Plugin-supplied scalar-data heatmaps. See {@linkcode PluginAnalysisHeatmapsApi}. */
     abstract heatmaps: PluginAnalysisHeatmapsApi;
+    /** Site typical-year weather series (numeric, paged). See {@linkcode PluginAnalysisWeatherApi}. */
+    abstract weather: PluginAnalysisWeatherApi;
+    /** Per-point solar exposure sampling (numeric). See {@linkcode PluginAnalysisSolarApi}. */
+    abstract solar: PluginAnalysisSolarApi;
+    /** IES LM-83 annual daylight metrics (numeric). See {@linkcode PluginAnalysisDaylightApi}. */
+    abstract daylight: PluginAnalysisDaylightApi;
     constructor();
 }
 export * from "./sunpath";
@@ -41,4 +53,7 @@ export * from "./shadows";
 export * from "./sunlightHours";
 export * from "./illuminance";
 export * from "./heatmaps";
+export * from "./weather";
+export * from "./solar";
+export * from "./daylight";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/analysis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,iBAAiB;IACrC,oGAAoG;IACpG,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,uFAAuF;IACvF,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,yFAAyF;IACzF,SAAgB,aAAa,EAAE,8BAA8B,CAAA;IAC7D,4FAA4F;IAC5F,SAAgB,WAAW,EAAE,4BAA4B,CAAA;IACzD,uFAAuF;IACvF,SAAgB,QAAQ,EAAE,yBAAyB,CAAA;;CAGpD;AAED,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,iBAAiB;IACrC,oGAAoG;IACpG,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,uFAAuF;IACvF,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,yFAAyF;IACzF,SAAgB,aAAa,EAAE,8BAA8B,CAAA;IAC7D,4FAA4F;IAC5F,SAAgB,WAAW,EAAE,4BAA4B,CAAA;IACzD,uFAAuF;IACvF,SAAgB,QAAQ,EAAE,yBAAyB,CAAA;IACnD,mGAAmG;IACnG,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,2FAA2F;IAC3F,SAAgB,KAAK,EAAE,sBAAsB,CAAA;IAC7C,8FAA8F;IAC9F,SAAgB,QAAQ,EAAE,yBAAyB,CAAA;;CAGpD;AAED,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA"}