@snaptrude/plugin-core 0.3.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -17,6 +17,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.5.4"
   },
@@ -30,6 +31,9 @@
     "check-types": "tsc --noEmit",
     "build": "tsup --clean",
     "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist"
+    "clean-dist": "rm -rf dist",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all"
   }
 }

package/scripts/generate-manifest.mjs

@@ -0,0 +1,193 @@
+// Discovery-manifest generator.
+//
+// The plugin API surface is a tree of abstract `Plugin*Api` classes; the wire
+// method map (`PluginApiMethodMap`) is TYPE-LEVEL ONLY and cannot be enumerated
+// at runtime. This script statically walks the abstract+Zod source with ts-morph
+// and emits a flat, machine-readable manifest of every leaf method:
+//
+//   { path, namespace, summary, examplePrompts[], argsType, resultType }
+//
+// The manifest is the substrate the discovery server (plugin-mcp-server) and the
+// retrieval-accuracy eval harness key on. Authors only ever write the abstract
+// class + Zod schemas + JSDoc + `@examplePrompt` lines — this regenerates the rest.
+//
+// Run: `pnpm --filter @snaptrude/plugin-core generate:manifest`
+//      add `--check` to assert the on-disk manifest is up-to-date (CI gate);
+//      exits non-zero without writing if regeneration would change it.
+import { Project } from "ts-morph"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+import { writeFileSync, readFileSync, existsSync } from "node:fs"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = resolve(here, "..")
+const apiGlob = resolve(pkgRoot, "src/api/**/*.ts")
+const outFile = resolve(pkgRoot, "api-manifest.json")
+
+const ROOT_CLASS = "PluginApi"
+const RETURN_WRAPPER = "PluginApiReturn"
+
+/** First paragraph of a JSDoc description, whitespace-collapsed. */
+function summaryOf(jsDoc) {
+  if (!jsDoc) return ""
+  const desc = (jsDoc.getDescription() ?? "").trim()
+  const firstPara = desc.split(/\n\s*\n/)[0] ?? ""
+  return firstPara.replace(/\s+/g, " ").trim()
+}
+
+/** All `@examplePrompt` comment strings on a method's JSDoc. */
+function examplePromptsOf(jsDoc) {
+  if (!jsDoc) return []
+  return jsDoc
+    .getTags()
+    .filter((t) => t.getTagName() === "examplePrompt")
+    .map((t) => (t.getCommentText() ?? "").trim())
+    .filter(Boolean)
+}
+
+/** Strip the `PluginApiReturn<...>` wrapper to the inner result type text. */
+function unwrapReturn(text) {
+  if (!text) return "void"
+  const m = text.match(new RegExp(`^${RETURN_WRAPPER}<([\\s\\S]*)>$`))
+  return (m ? m[1] : text).trim()
+}
+
+/**
+ * Statically walk the abstract `PluginApi` class tree and return one flat,
+ * sorted manifest entry per leaf method. Pure (no side effects) so it is unit
+ * testable; the CLI below adds the write + report.
+ */
+export function buildManifest({ includeOptional = false } = {}) {
+  const project = new Project({ skipAddingFilesFromTsConfig: true })
+  project.addSourceFilesAtPaths(apiGlob)
+
+  // className -> ClassDeclaration, for every abstract Plugin*Api class.
+  const classes = new Map()
+  for (const sf of project.getSourceFiles()) {
+    for (const cls of sf.getClasses()) {
+      const name = cls.getName()
+      if (name && name.startsWith("Plugin") && name.endsWith("Api")) {
+        classes.set(name, cls)
+      }
+    }
+  }
+
+  const leaves = []
+
+  function walk(className, pathPrefix) {
+    const cls = classes.get(className)
+    if (!cls) return
+
+    // Leaf methods on this namespace.
+    for (const method of cls.getMethods()) {
+      const name = method.getName()
+      const jsDoc = method.getJsDocs().at(-1) ?? null
+      const param = method.getParameters()[0]
+      leaves.push({
+        path: `${pathPrefix}${name}`,
+        namespace: pathPrefix.replace(/\.$/, ""),
+        summary: summaryOf(jsDoc),
+        examplePrompts: examplePromptsOf(jsDoc),
+        argsType: param?.getTypeNode()?.getText() ?? null,
+        resultType: unwrapReturn(method.getReturnTypeNode()?.getText()),
+      })
+    }
+
+    // Sub-namespaces are abstract properties typed as another Plugin*Api class.
+    //
+    // Author-ahead discipline: a member declared optional (`?`) is authored
+    // BEFORE the host implements it — present in the type tree (so plugins and
+    // codegen see the shape) but kept OUT of the discovery manifest until it is
+    // promoted to a required `abstract` member in the wave the host lands it.
+    // The default (discovery) build skips optional members; the authored-surface
+    // build (`includeOptional`, used by the retrieval eval) includes them — both
+    // the optional sub-namespaces and the optional function-property leaves.
+    for (const prop of cls.getProperties()) {
+      const optional = prop.hasQuestionToken()
+      if (optional && !includeOptional) continue
+      const typeNode = prop.getTypeNode()
+      const childType = typeNode?.getText()
+      if (childType && classes.has(childType)) {
+        walk(childType, `${pathPrefix}${prop.getName()}.`)
+      } else if (
+        includeOptional &&
+        typeNode &&
+        typeNode.getKindName() === "FunctionType"
+      ) {
+        // An optional author-ahead leaf, written as a function-property.
+        const jsDoc = prop.getJsDocs().at(-1) ?? null
+        const param = typeNode.getParameters()[0]
+        leaves.push({
+          path: `${pathPrefix}${prop.getName()}`,
+          namespace: pathPrefix.replace(/\.$/, ""),
+          summary: summaryOf(jsDoc),
+          examplePrompts: examplePromptsOf(jsDoc),
+          argsType: param?.getTypeNode()?.getText() ?? null,
+          resultType: unwrapReturn(typeNode.getReturnTypeNode()?.getText()),
+        })
+      }
+    }
+  }
+
+  walk(ROOT_CLASS, "")
+  leaves.sort((a, b) => a.path.localeCompare(b.path))
+  return leaves
+}
+
+// --- CLI: write + report (skipped when imported, e.g. by tests) ------------
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  // `--all` builds the AUTHORED-surface manifest (includes optional author-ahead
+  // members) to a separate file, for the retrieval eval. Default builds the
+  // discovery manifest (required/host-landed members only).
+  const all = process.argv.includes("--all")
+  const check = process.argv.includes("--check")
+  const target = all ? resolve(pkgRoot, "api-manifest.full.json") : outFile
+  const leaves = buildManifest({ includeOptional: all })
+  const json = JSON.stringify(leaves, null, 2) + "\n"
+
+  if (check) {
+    // Determinism / staleness gate: regenerate and compare, never write.
+    const current = existsSync(target) ? readFileSync(target, "utf8") : ""
+    if (current !== json) {
+      console.error(
+        `${target} is STALE or non-deterministic — run \`generate:manifest${all ? " --all" : ""}\` and commit the result.`,
+      )
+      process.exit(1)
+    }
+    console.log(
+      `manifest up-to-date & deterministic (${leaves.length} methods)`,
+    )
+    process.exit(0)
+  }
+
+  writeFileSync(target, json)
+
+  const missingPrompts = leaves.filter((l) => l.examplePrompts.length === 0)
+  console.log(
+    `manifest${all ? " (authored surface)" : ""}: ${leaves.length} methods -> ${target}`,
+  )
+  console.log(
+    `coverage: ${leaves.length - missingPrompts.length}/${leaves.length} methods have @examplePrompt lines`,
+  )
+  if (missingPrompts.length) {
+    console.log(
+      `  (no @examplePrompt yet: ${missingPrompts.map((l) => l.path).join(", ")})`,
+    )
+  }
+  const slice = [
+    "program.departments.list",
+    "program.departments.get",
+    "program.metrics.get",
+    "presentation.views.list",
+  ]
+  console.log("slice methods present:")
+  for (const p of slice) {
+    const hit = leaves.find((l) => l.path === p)
+    console.log(
+      `  ${hit ? "OK " : "MISS"} ${p}${hit ? ` (${hit.examplePrompts.length} prompts)` : ""}`,
+    )
+  }
+}

package/scripts/generate-manifest.test.mjs

@@ -0,0 +1,215 @@
+// Unit tests for the discovery-manifest generator (pure codegen logic).
+// Run: `node --test scripts/generate-manifest.test.mjs` (from packages/plugin-core)
+import { test } from "node:test"
+import assert from "node:assert/strict"
+import { buildManifest } from "./generate-manifest.mjs"
+
+const manifest = buildManifest()
+const byPath = new Map(manifest.map((m) => [m.path, m]))
+
+test("every entry has a dotted path and a namespace", () => {
+  for (const m of manifest) {
+    assert.match(m.path, /^[a-z][a-zA-Z0-9.]*$/, `bad path: ${m.path}`)
+    assert.equal(typeof m.namespace, "string")
+    assert.ok(
+      Array.isArray(m.examplePrompts),
+      `${m.path} examplePrompts not array`,
+    )
+  }
+})
+
+test("output is sorted and unique by path", () => {
+  const paths = manifest.map((m) => m.path)
+  assert.deepEqual(
+    paths,
+    [...paths].sort((a, b) => a.localeCompare(b)),
+    "not sorted",
+  )
+  assert.equal(new Set(paths).size, paths.length, "duplicate paths")
+})
+
+test("all 4 Phase-1 slice methods are present with intent + prompts", () => {
+  const slice = [
+    "program.departments.list",
+    "program.departments.get",
+    "program.metrics.get",
+    "presentation.views.list",
+  ]
+  for (const p of slice) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing slice method: ${p}`)
+    assert.ok(m.summary.length > 0, `${p} has no intent summary`)
+    assert.ok(m.examplePrompts.length >= 3, `${p} has < 3 example prompts`)
+    assert.ok(
+      m.resultType && m.resultType !== "void",
+      `${p} has no result type`,
+    )
+  }
+})
+
+test("departments.get carries its args type; list takes no args", () => {
+  assert.equal(byPath.get("program.departments.get").argsType, "string")
+  assert.equal(byPath.get("program.departments.list").argsType, null)
+})
+
+test("return-type wrapper PluginApiReturn<...> is unwrapped", () => {
+  for (const m of manifest) {
+    assert.ok(
+      !/^PluginApiReturn</.test(m.resultType ?? ""),
+      `${m.path} not unwrapped`,
+    )
+  }
+})
+
+test("author-ahead (optional) members are kept OUT of the manifest", () => {
+  // Optional sub-namespaces (`aiInspiration?`) and optional leaf methods
+  // (`departments.delete?`, `cores.create?`) are authored ahead of the host and
+  // must not appear in the discovery manifest until promoted to required
+  // `abstract` members. (See the discipline note in generate-manifest.mjs.)
+  const authoredAhead = [
+    "presentation.aiInspiration.listModels",
+    "program.departments.delete",
+    "program.cores.create",
+  ]
+  for (const p of authoredAhead) {
+    assert.ok(
+      !byPath.has(p),
+      `optional author-ahead member leaked into manifest: ${p}`,
+    )
+  }
+})
+
+test("promoted methods are present in the manifest", () => {
+  // Methods whose react host bodies have landed and been verified, flipped from
+  // optional author-ahead to required `abstract`.
+  const promoted = [
+    "program.departments.create",
+    "program.departments.setTargetArea",
+    "program.site.get",
+    "program.site.getContext",
+    "presentation.import.image",
+    "presentation.import.pdf",
+    "presentation.sheets.list",
+    "presentation.sheets.place",
+    "presentation.diagrams.place",
+    // 2026-07-02 promotions — react hosts landed and verified:
+    "program.spreadsheet.render",
+    "program.adjacency.getMatrix",
+    "program.adjacency.compute",
+    "program.spreadsheet.getTakeoff",
+    "program.spreadsheet.runScript",
+    "presentation.views.get",
+    "presentation.views.getActive",
+    "presentation.views.capture",
+    "presentation.views.setActive",
+    "presentation.views.create",
+    "core.layers.setActive",
+    "core.layers.update",
+    "program.areas.update",
+    // 2026-07-06 promotions — analysis namespace + program.site geo reads,
+    // react hosts landed:
+    "analysis.sunpath.enable",
+    "analysis.sunpath.disable",
+    "analysis.sunpath.isActive",
+    "analysis.shadows.enable",
+    "analysis.shadows.disable",
+    "analysis.shadows.isEnabled",
+    "analysis.shadows.setDateTime",
+    "analysis.shadows.getDateTime",
+    "analysis.sunlightHours.compute",
+    "analysis.sunlightHours.get",
+    "analysis.sunlightHours.cancel",
+    "analysis.sunlightHours.reset",
+    "analysis.illuminance.compute",
+    "analysis.illuminance.get",
+    "analysis.illuminance.cancel",
+    "analysis.illuminance.reset",
+    "program.site.getLocation",
+    "program.site.getNorthAngle",
+    // 2026-07-07 promotion — analysis.heatmaps, react host landed:
+    "analysis.heatmaps.renderSpaces",
+    "analysis.heatmaps.renderGrid",
+    "analysis.heatmaps.reset",
+    "analysis.heatmaps.isActive",
+  ]
+  for (const p of promoted) {
+    assert.ok(
+      byPath.has(p),
+      `expected promoted method missing from manifest: ${p}`,
+    )
+  }
+})
+
+test("v2 family reads (all 5 families) are present with intent + prompts", () => {
+  // All 22 reads of the five landed families. Every sub-api mount is now required
+  // `abstract` (the react hosts have landed), so each read is in the discovery
+  // manifest with a summary, >= 3 example prompts, and a result type.
+  const reads = [
+    "core.groups.list",
+    "core.groups.get",
+    "core.groups.getForComponent",
+    "core.groups.listMembers",
+    "core.groups.isLocked",
+    "core.groups.getBounds",
+    "core.buildings.list",
+    "core.buildings.get",
+    "core.buildings.listStoreys",
+    "core.buildings.getActive",
+    "core.layers.list",
+    "core.layers.get",
+    "core.layers.getActive",
+    "core.tags.listCategories",
+    "core.tags.getCategory",
+    "core.tags.list",
+    "core.tags.get",
+    "core.tags.getTagsForComponent",
+    "core.tags.listComponents",
+    "program.areas.get",
+    "program.areas.list",
+    "program.areas.listMembers",
+  ]
+  for (const p of reads) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing v2 family read: ${p}`)
+    assert.ok(m.summary.length > 0, `${p} has no intent summary`)
+    assert.ok(m.examplePrompts.length >= 3, `${p} has < 3 example prompts`)
+    assert.ok(
+      m.resultType && m.resultType !== "void",
+      `${p} has no result type`,
+    )
+  }
+})
+
+test("v2 family writes are IN the discovery manifest (hosts landed, promoted)", () => {
+  // 2026-07-02: every v2 family write's react host body has landed, so the
+  // contract members were promoted from optional `foo?: (args) => ...`
+  // fn-properties to required `abstract` methods — they now appear in the
+  // discovery build.
+  const promotedWrites = [
+    "core.groups.create",
+    "core.groups.update",
+    "core.groups.delete",
+    "core.buildings.setActive",
+    "core.buildings.create",
+    "core.buildings.update",
+    "core.buildings.copy",
+    "core.buildings.delete",
+    "core.layers.setActive",
+    "core.layers.update",
+    "core.tags.createCategory",
+    "core.tags.updateCategory",
+    "core.tags.deleteCategory",
+    "core.tags.create",
+    "core.tags.update",
+    "core.tags.delete",
+    "core.tags.assign",
+    "core.tags.unassign",
+    "program.areas.update",
+  ]
+  for (const p of promotedWrites) {
+    assert.ok(
+      byPath.has(p),
+      `promoted v2 family write missing from manifest: ${p}`,
+    )
+  }
+})

package/src/api/analysis/heatmaps.ts

@@ -0,0 +1,256 @@
+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).
+ *
+ * Shared semantics:
+ *
+ * - **Single active heatmap** — a render call **replaces** whatever heatmap
+ *   is currently showing (from either mode).
+ * - **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.
+ * - **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 {
+  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
+   * 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 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. Replaces
+   * any heatmap currently showing (single active heatmap).
+   *
+   * 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 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>
+
+  /**
+   * Clear the plugin heatmap from the scene.
+   *
+   * 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`.
+   *
+   * @returns `true` when a heatmap was cleared, `false` when none was
+   *   showing.
+   * @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>
+}
+
+/**
+ * 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 |
+ */
+export const PluginAnalysisHeatmapGridCell = z.object({
+  position: Vec3Components,
+  value: z.number().finite(),
+})
+export type PluginAnalysisHeatmapGridCell = z.infer<
+  typeof PluginAnalysisHeatmapGridCell
+>
+
+/**
+ * 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 |
+ * |---|---|---|
+ * | `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 |
+ */
+export const PluginAnalysisHeatmapOptions = z.object({
+  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(),
+})
+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
+>