@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827194031

package/src/api/analysis/heatmaps.ts

@@ -0,0 +1,683 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle, Vec3Components } from "../../handles"
+
+/**
+ * Analysis heatmaps — render plugin-computed scalar data as a heatmap.
+ *
+ * Unlike the built-in studies ({@linkcode PluginAnalysisSunlightHoursApi},
+ * {@linkcode PluginAnalysisIlluminanceApi}) where the host computes the
+ * values, here the **plugin brings its own numbers** and the host renders
+ * them. Two render modes:
+ *
+ * - {@linkcode PluginAnalysisHeatmapsApi.renderSpaces} — one flat colour per
+ *   space, painted on the space's top face (occupancy, energy use, any
+ *   per-room metric).
+ * - {@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:
+ *
+ * - **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.
+ *
+ * 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() {}
+
+  /**
+   * 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. 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.
+   *
+   * The heatmap is ephemeral: it is auto-cleared by scene-mutating edits
+   * and is never persisted or saved with views.
+   *
+   * @param entries - One {@linkcode PluginAnalysisHeatmapSpaceEntry} per
+   *   space: the space's handle and its scalar value.
+   * @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 `entries` is empty or a handle does not resolve to a space.
+   * @throws When no space had a flat top face to paint (every entry was
+   *   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
+   * @examplePrompt Show my energy simulation results as a heatmap per space
+   * @examplePrompt Paint the rooms red to blue by temperature
+   *
+   * # Example
+   * ```ts
+   * const spaces = await snaptrude.design.query.listSpaces()
+   * await snaptrude.analysis.heatmaps.renderSpaces(
+   *   spaces.map((space) => ({ space, value: occupancy[space] ?? 0 })),
+   *   { title: "Occupancy", unit: "people", min: 0, max: 50 },
+   * )
+   * ```
+   */
+  public abstract renderSpaces(
+    entries: PluginAnalysisHeatmapSpaceEntry[],
+    options?: PluginAnalysisHeatmapOptions,
+  ): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>
+
+  /**
+   * Render a grid heatmap — a coloured mesh from point samples.
+   *
+   * Each cell is a scalar sample at a **world-coordinate** position
+   * (**y is up** — a ground-level field sits at `y = 0`); the host builds
+   * one square cell of edge `cellSize` per sample — in the same Snaptrude
+   * internal units as `position` (convert real-world lengths via
+   * {@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. 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.
+   *
+   * @param cells - One {@linkcode PluginAnalysisHeatmapGridCell} per
+   *   sample: a world-coordinate `position` (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 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 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
+   * @examplePrompt Render a noise-level grid around the building
+   * @examplePrompt Show these sampled microclimate values as a colored grid
+   *
+   * # Example
+   * ```ts
+   * // World coordinates are y-up: a ground-level field varies in x/z at y = 0.
+   * await snaptrude.analysis.heatmaps.renderGrid(
+   *   samples.map((s) => ({ position: { x: s.x, y: 0, z: s.z }, value: s.windSpeed })),
+   *   2, // 2-unit square cells
+   *   { title: "Wind speed", unit: "m/s", colors: ["#0000ff", "#00ff00", "#ff0000"] },
+   * )
+   * ```
+   */
+  public abstract renderGrid(
+    cells: PluginAnalysisHeatmapGridCell[],
+    cellSize: number,
+    options?: PluginAnalysisHeatmapOptions,
+  ): PluginApiReturn<PluginAnalysisHeatmapsRenderResult>
+
+  /**
+   * 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 }`.
+   *
+   * 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"] },
+   * )
+   * ```
+   */
+  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
+   * @examplePrompt Remove the wind overlay from the model
+   * @examplePrompt Reset the plugin heatmap view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.heatmaps.reset()
+   * ```
+   */
+  public abstract reset(): PluginApiReturn<boolean>
+
+  /**
+   * Is a plugin heatmap currently showing?
+   *
+   * `true` between a successful render and the next
+   * {@linkcode PluginAnalysisHeatmapsApi.reset} — or the scene-mutating
+   * edit that auto-clears it (heatmaps are ephemeral).
+   *
+   * @returns `true` when a plugin heatmap is rendered on the scene.
+   *
+   * @examplePrompt Is my heatmap still showing?
+   * @examplePrompt Check whether the custom heatmap is active
+   * @examplePrompt Do I need to re-render the wind overlay?
+   *
+   * # Example
+   * ```ts
+   * if (!(await snaptrude.analysis.heatmaps.isActive())) {
+   *   await snaptrude.analysis.heatmaps.renderGrid(cells, 2)
+   * }
+   * ```
+   */
+  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}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | Handle of the space to colour |
+ * | `value` | `number` | The scalar value mapped to a colour |
+ */
+export const PluginAnalysisHeatmapSpaceEntry = z.object({
+  space: ComponentHandle,
+  value: z.number().finite(),
+})
+export type PluginAnalysisHeatmapSpaceEntry = z.infer<
+  typeof PluginAnalysisHeatmapSpaceEntry
+>
+
+/**
+ * One grid sample in {@linkcode PluginAnalysisHeatmapsApi.renderGrid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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.
+ *
+ * The colour ramp maps values to colours: `colors` is an **ordered list of
+ * hex colour stops, low → high** (e.g. `["#0000ff", "#ff0000"]`). When
+ * omitted, the host's default blue → cyan → green → yellow → red ramp is used. Values outside
+ * `[min, max]` clamp to the end colours; the legend marks the clamped ends
+ * with `<` / `>`. `min`/`max` are auto-derived from the data when omitted.
+ *
+ * | 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(HexColor).min(1).optional(),
+  scale: PluginAnalysisHeatmapScale.optional(),
+  hover: z.boolean().optional(),
+})
+export type PluginAnalysisHeatmapOptions = z.infer<
+  typeof PluginAnalysisHeatmapOptions
+>
+
+/**
+ * Result of {@linkcode PluginAnalysisHeatmapsApi.renderSpaces} /
+ * {@linkcode PluginAnalysisHeatmapsApi.renderGrid} — render failures throw,
+ * so a returned value always carries `success: true`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `true` | The heatmap is rendered on the scene |
+ */
+export const PluginAnalysisHeatmapsRenderResult = z.object({
+  success: z.literal(true),
+})
+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
+>