@snaptrude/plugin-core 0.8.0 → 0.9.0

package/src/api/analysis/heatmaps.ts

@@ -16,15 +16,25 @@ import { ComponentHandle, Vec3Components } 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.
@@ -32,6 +42,13 @@ import { ComponentHandle, Vec3Components } from "../../handles"
  * Accessed via `snaptrude.analysis.heatmaps`.
  */
 export abstract class PluginAnalysisHeatmapsApi {
+  /**
+   * Manage the named heatmap overlays created by the render calls —
+   * list / show / hide / remove. See
+   * {@linkcode PluginAnalysisHeatmapOverlaysApi}.
+   */
+  public abstract overlays: PluginAnalysisHeatmapOverlaysApi
+
   constructor() {}
 
   /**
@@ -39,8 +56,9 @@ export abstract class PluginAnalysisHeatmapsApi {
    *
    * 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.
    *
@@ -59,6 +77,8 @@ export 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
@@ -89,8 +109,9 @@ export 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.
@@ -108,6 +129,8 @@ export 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
@@ -131,15 +154,152 @@ export abstract class PluginAnalysisHeatmapsApi {
   ): 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.
+   *
+   * 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 }`.
    *
-   * 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`.
+   * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+   * and is never persisted or saved with views.
    *
-   * @returns `true` when a heatmap was cleared, `false` when none was
-   *   showing.
+   * @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"] },
+   * )
+   * ```
+   */
+  public 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 } },
+   * )
+   * ```
+   */
+  public 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
@@ -176,6 +336,138 @@ export abstract class PluginAnalysisHeatmapsApi {
   public 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 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)
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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")
+   * ```
+   */
+  public 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()
+   * ```
+   */
+  public abstract removeAll(): PluginApiReturn<number>
+}
+
 /**
  * One space's entry in {@linkcode PluginAnalysisHeatmapsApi.renderSpaces}.
  *
@@ -199,15 +491,115 @@ export type PluginAnalysisHeatmapSpaceEntry = z.infer<
  * |---|---|---|
  * | `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 const PluginAnalysisHeatmapGridCell = z.object({
   position: Vec3Components,
   value: z.number().finite(),
+  meta: z.unknown().optional(),
 })
 export type PluginAnalysisHeatmapGridCell = z.infer<
   typeof PluginAnalysisHeatmapGridCell
 >
 
+/** A 6-digit hex colour like `"#0000ff"` (the `#` is optional). */
+const HexColor = z
+  .string()
+  .regex(/^#?[0-9a-fA-F]{6}$/, 'expected a 6-digit hex colour like "#0000ff"')
+
+/**
+ * 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 const PluginAnalysisHeatmapFieldCell = z.union([
+  z.object({
+    polygon: z.array(Vec3Components).min(3),
+    value: z.number().finite(),
+    meta: z.unknown().optional(),
+  }),
+  z.object({
+    vertices: z.array(Vec3Components).min(3),
+    indices: z.array(z.number().int().nonnegative()).min(3),
+    value: z.number().finite(),
+    meta: z.unknown().optional(),
+  }),
+])
+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 const PluginAnalysisHeatmapScale = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("bands"),
+    count: z.number().int().min(2).max(64).optional(),
+  }),
+  z.object({
+    type: z.literal("threshold"),
+    threshold: z.number().finite(),
+    passColor: HexColor.optional(),
+    failColor: HexColor.optional(),
+    passLabel: z.string().optional(),
+    failLabel: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("categorical"),
+    classes: z
+      .array(
+        z.object({
+          value: z.number().finite(),
+          label: z.string(),
+          color: HexColor,
+        }),
+      )
+      .min(1),
+  }),
+])
+export type PluginAnalysisHeatmapScale = z.infer<
+  typeof PluginAnalysisHeatmapScale
+>
+
 /**
  * Display options shared by both heatmap render modes.
  *
@@ -219,21 +611,24 @@ export type PluginAnalysisHeatmapGridCell = z.infer<
  *
  * | 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 const PluginAnalysisHeatmapOptions = z.object({
+  name: z.string().min(1).max(64).optional(),
   title: z.string().optional(),
   unit: z.string().optional(),
   min: z.number().finite().optional(),
   max: z.number().finite().optional(),
-  colors: z
-    .array(z.string().regex(/^#?[0-9a-fA-F]{6}$/, "expected a 6-digit hex colour like \"#0000ff\""))
-    .min(1)
-    .optional(),
+  colors: z.array(HexColor).min(1).optional(),
+  scale: PluginAnalysisHeatmapScale.optional(),
+  hover: z.boolean().optional(),
 })
 export type PluginAnalysisHeatmapOptions = z.infer<
   typeof PluginAnalysisHeatmapOptions
@@ -254,3 +649,35 @@ export const PluginAnalysisHeatmapsRenderResult = z.object({
 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 const PluginAnalysisHeatmapOverlayInfo = z.object({
+  name: z.string(),
+  visible: z.boolean(),
+  kind: z.enum(["spaces", "grid", "surfaceGrid", "field"]),
+})
+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 const PluginAnalysisHeatmapOverlaysListResult = z.object({
+  overlays: z.array(PluginAnalysisHeatmapOverlayInfo),
+})
+export type PluginAnalysisHeatmapOverlaysListResult = z.infer<
+  typeof PluginAnalysisHeatmapOverlaysListResult
+>

package/src/api/analysis/index.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.
@@ -21,6 +24,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`.
  */
@@ -35,6 +41,12 @@ export abstract class PluginAnalysisApi {
   public abstract illuminance: PluginAnalysisIlluminanceApi
   /** Plugin-supplied scalar-data heatmaps. See {@linkcode PluginAnalysisHeatmapsApi}. */
   public abstract heatmaps: PluginAnalysisHeatmapsApi
+  /** Site typical-year weather series (numeric, paged). See {@linkcode PluginAnalysisWeatherApi}. */
+  public abstract weather: PluginAnalysisWeatherApi
+  /** Per-point solar exposure sampling (numeric). See {@linkcode PluginAnalysisSolarApi}. */
+  public abstract solar: PluginAnalysisSolarApi
+  /** IES LM-83 annual daylight metrics (numeric). See {@linkcode PluginAnalysisDaylightApi}. */
+  public abstract daylight: PluginAnalysisDaylightApi
 
   constructor() {}
 }
@@ -44,3 +56,6 @@ export * from "./shadows"
 export * from "./sunlightHours"
 export * from "./illuminance"
 export * from "./heatmaps"
+export * from "./weather"
+export * from "./solar"
+export * from "./daylight"