@snaptrude/plugin-core 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -32,6 +32,7 @@
     "build": "tsup --clean",
     "dev": "tsup --watch",
     "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
     "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.test.mjs

@@ -48,10 +48,7 @@ test("all 4 Phase-1 slice methods are present with intent + prompts", () => {
 })
 
 test("departments.get carries its args type; list takes no args", () => {
-  assert.equal(
-    byPath.get("program.departments.get").argsType,
-    "PluginProgramDepartmentsGetArgs",
-  )
+  assert.equal(byPath.get("program.departments.get").argsType, "string")
   assert.equal(byPath.get("program.departments.list").argsType, null)
 })
 
@@ -109,6 +106,37 @@ test("promoted methods are present in the manifest", () => {
     "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",
+    // 2026-07-09 promotion — program.layout became an async-job family (was
+    // author-ahead optional `arrange`/`pack`; now required + getState/cancel):
+    "program.layout.arrange",
+    "program.layout.pack",
+    "program.layout.getState",
+    "program.layout.cancel",
   ]
   for (const p of promoted) {
     assert.ok(
@@ -191,3 +219,74 @@ test("v2 family writes are IN the discovery manifest (hosts landed, promoted)",
     )
   }
 })
+
+test("0.7.0 batch — new families & methods present with intent + prompts", () => {
+  // The 0.7.0 wave: core.proposals, the program.layout async-job family,
+  // door/window catalogs + placement, furniture categories, smart layout,
+  // align, per-face materials, staircase read/write, footprint-area lock,
+  // storey duplicate, SVG import, and view display settings. Every entry is a
+  // required `abstract` member (react hosts landed), so each must be in the
+  // discovery manifest with a summary, >= 3 example prompts, and a result type.
+  const batch = [
+    // core.proposals — design-option infrastructure
+    "core.proposals.list",
+    "core.proposals.get",
+    "core.proposals.getActive",
+    "core.proposals.listForComponent",
+    "core.proposals.isActive",
+    "core.proposals.create",
+    "core.proposals.rename",
+    "core.proposals.setActive",
+    "core.proposals.delete",
+    // program.layout — async space-solver job family
+    "program.layout.arrange",
+    "program.layout.pack",
+    "program.layout.getState",
+    "program.layout.cancel",
+    // door / window catalogs (shared DTOs) + placement creators
+    "design.doors.listCatalogGroups",
+    "design.doors.listCatalog",
+    "design.doors.getCatalogItem",
+    "design.doors.exists",
+    "design.windows.listCatalogGroups",
+    "design.windows.listCatalog",
+    "design.windows.getCatalogItem",
+    "design.windows.exists",
+    "design.create.door",
+    "design.create.window",
+    // furniture categories + smart layout
+    "design.furniture.listCategories",
+    "design.create.smartLayout",
+    // align
+    "design.transform.align",
+    // per-face materials
+    "design.materials.applyToFaces",
+    "design.materials.resetFaces",
+    "design.materials.getByFace",
+    "design.materials.listByFace",
+    // staircase read/write
+    "design.query.getStaircaseParams",
+    "design.update.staircase",
+    // footprint-area lock
+    "design.lockArea",
+    "design.unlockArea",
+    "design.isAreaLocked",
+    "design.listAreaLocked",
+    // storey duplicate
+    "entity.story.duplicate",
+    // present-canvas SVG import + view display settings
+    "presentation.import.svg",
+    "presentation.views.getSettings",
+    "presentation.views.updateSettings",
+  ]
+  for (const p of batch) {
+    const m = byPath.get(p)
+    assert.ok(m, `missing 0.7.0 batch 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`,
+    )
+  }
+})

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
+>

package/src/api/analysis/illuminance.ts

@@ -0,0 +1,155 @@
+import { PluginApiReturn } from "../../types"
+import {
+  PluginAnalysisComputeResult,
+  PluginAnalysisJobStateResult,
+} from "./sunlightHours"
+
+/**
+ * Analysis illuminance — the daylight illuminance (lux) heatmap study.
+ *
+ * Computes interior daylight illuminance over a date range and renders the
+ * result as a heatmap on the scene. **Pro-gated**: every method that starts
+ * a run throws when the workspace is not on a Pro plan.
+ *
+ * Like {@linkcode PluginAnalysisSunlightHoursApi} (`analysis.sunlightHours`),
+ * this is an **asynchronous backend job**:
+ *
+ * 1. {@linkcode PluginAnalysisIlluminanceApi.compute} starts the job and
+ *    returns immediately.
+ * 2. Poll {@linkcode PluginAnalysisIlluminanceApi.get} until `status` is
+ *    `"active"` (heatmap rendered) — a run typically takes minutes. There is
+ *    no completion event; polling is the pattern.
+ * 3. {@linkcode PluginAnalysisIlluminanceApi.cancel} aborts an in-flight
+ *    run; {@linkcode PluginAnalysisIlluminanceApi.reset} clears a rendered
+ *    heatmap.
+ *
+ * Illuminance analyses BIM slab and roof objects (floors, roofs, …) — walls
+ * or bare Masses are not enough — and requires the 3D view. Heatmaps are invalidated by
+ * scene-mutating edits. Dates cross as ISO 8601 date strings
+ * (`"YYYY-MM-DD"`).
+ *
+ * Accessed via `snaptrude.analysis.illuminance`.
+ */
+export abstract class PluginAnalysisIlluminanceApi {
+  constructor() {}
+
+  /**
+   * Start a daylight-illuminance run for a date range.
+   *
+   * Starts the backend job and **returns immediately** — it does not wait
+   * for the heatmap. Poll {@linkcode PluginAnalysisIlluminanceApi.get} until
+   * `status` is `"active"`. Starting a new run while one is in flight
+   * replaces it. Shadows and the heatmap analyses are mutually exclusive in
+   * the product: starting a run disables real-time shadows and resets/cancels
+   * any {@linkcode PluginAnalysisSunlightHoursApi}
+   * (`analysis.sunlightHours`) study.
+   *
+   * @param startDate - Start of the study range, ISO date `"YYYY-MM-DD"`.
+   * @param endDate - End of the study range, ISO date `"YYYY-MM-DD"` (on or
+   *   after `startDate`).
+   * @returns A {@linkcode PluginAnalysisComputeResult} — `{ success: true }`
+   *   when the job was started. The `{ success: false, error }` arm is
+   *   reserved — not yet emitted (start failures currently throw).
+   * @throws When the workspace is not on a **Pro** plan (illuminance is a
+   *   Pro feature).
+   * @throws When the project has no geo-located site/terrain (no location to
+   *   compute daylight for — there is no fallback location).
+   * @throws When the scene has no slab or roof BIM object to analyse (walls
+   *   or bare Masses are not enough) or the editor is not in the 3D view.
+   * @throws When a date is not a parseable ISO date or the range is inverted.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Run a daylight illuminance analysis for December
+   * @examplePrompt Compute the lux levels inside the building for winter
+   * @examplePrompt How much daylight do the interior floors get?
+   *
+   * # Example
+   * ```ts
+   * const { success } = await snaptrude.analysis.illuminance.compute(
+   *   "2026-12-01",
+   *   "2026-12-31",
+   * )
+   * // poll until the heatmap is rendered
+   * let job = await snaptrude.analysis.illuminance.get()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.analysis.illuminance.get()
+   * }
+   * ```
+   */
+  public abstract compute(
+    startDate: string,
+    endDate: string,
+  ): PluginApiReturn<PluginAnalysisComputeResult>
+
+  /**
+   * Get the state of the illuminance study.
+   *
+   * The polling read for the async job started by
+   * {@linkcode PluginAnalysisIlluminanceApi.compute}. `status` values:
+   *
+   * | Status | Meaning |
+   * |---|---|
+   * | `"running"` | A run is in flight — keep polling |
+   * | `"active"` | The heatmap is rendered on the scene |
+   * | `"inactive"` | A previous run exists but its heatmap is not showing |
+   *
+   * @returns A {@linkcode PluginAnalysisJobStateResult} with the `status` and
+   *   the run's ISO `startDate`/`endDate`, or `null` when no run result is
+   *   available (the study never ran, was cancelled, or the last run failed).
+   *
+   * @examplePrompt Is the illuminance analysis done?
+   * @examplePrompt Check the status of the daylight lux run
+   * @examplePrompt What date range was the illuminance heatmap computed for?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.analysis.illuminance.get()
+   * if (job?.status === "active") console.log(job.startDate, job.endDate)
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginAnalysisJobStateResult>
+
+  /**
+   * Cancel the in-flight illuminance run.
+   *
+   * Aborts the backend job. A no-op (returns `false`) when nothing is
+   * running.
+   *
+   * @returns `true` when a run was cancelled, `false` when nothing was
+   *   running.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Cancel the illuminance analysis
+   * @examplePrompt Stop the running daylight computation
+   * @examplePrompt Abort the lux study
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.illuminance.cancel()
+   * ```
+   */
+  public abstract cancel(): PluginApiReturn<boolean>
+
+  /**
+   * Clear the illuminance heatmap from the scene.
+   *
+   * Un-applies the rendered heatmap and restores the normal material view.
+   * A no-op (returns `false`) when no heatmap is showing. Does not cancel an
+   * in-flight run — use {@linkcode PluginAnalysisIlluminanceApi.cancel}.
+   *
+   * @returns `true` when a heatmap was cleared, `false` when none was
+   *   showing.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Clear the illuminance heatmap
+   * @examplePrompt Remove the daylight lux colours from the model
+   * @examplePrompt Reset the illuminance analysis view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.illuminance.reset()
+   * ```
+   */
+  public abstract reset(): PluginApiReturn<boolean>
+}

package/src/api/analysis/index.ts

@@ -0,0 +1,46 @@
+import { PluginAnalysisSunpathApi } from "./sunpath"
+import { PluginAnalysisShadowsApi } from "./shadows"
+import { PluginAnalysisSunlightHoursApi } from "./sunlightHours"
+import { PluginAnalysisIlluminanceApi } from "./illuminance"
+import { PluginAnalysisHeatmapsApi } from "./heatmaps"
+
+/**
+ * Sustainability-analysis APIs.
+ *
+ * Analysis is the environmental-performance layer: sun and daylight studies
+ * computed for the project's geo-located site. The synchronous visual
+ * overlays (sun-path diagram, real-time shadows) toggle instantly; the
+ * heatmap studies (direct sunlight hours, daylight illuminance) are
+ * asynchronous backend jobs — start them, poll their state, and cancel or
+ * clear them. Shadows and the heatmap analyses are **mutually exclusive**
+ * (enabling one resets the other), exactly as in the sustainability sidebar.
+ * Site inputs (location, true north) are read via `program.site`.
+ *
+ * - {@linkcode PluginAnalysisApi.sunpath} — Toggle & query the sun-path diagram overlay
+ * - {@linkcode PluginAnalysisApi.shadows} — Toggle real-time shadows and scrub the sun's date-time
+ * - {@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)
+ *
+ * Accessed via `snaptrude.analysis`.
+ */
+export abstract class PluginAnalysisApi {
+  /** Sun-path diagram overlay — enable/disable/isActive. See {@linkcode PluginAnalysisSunpathApi}. */
+  public abstract sunpath: PluginAnalysisSunpathApi
+  /** Real-time sun shadows + sun date-time. See {@linkcode PluginAnalysisShadowsApi}. */
+  public abstract shadows: PluginAnalysisShadowsApi
+  /** Direct-sunlight-hours heatmap job. See {@linkcode PluginAnalysisSunlightHoursApi}. */
+  public abstract sunlightHours: PluginAnalysisSunlightHoursApi
+  /** Daylight-illuminance heatmap job (Pro). See {@linkcode PluginAnalysisIlluminanceApi}. */
+  public abstract illuminance: PluginAnalysisIlluminanceApi
+  /** Plugin-supplied scalar-data heatmaps. See {@linkcode PluginAnalysisHeatmapsApi}. */
+  public abstract heatmaps: PluginAnalysisHeatmapsApi
+
+  constructor() {}
+}
+
+export * from "./sunpath"
+export * from "./shadows"
+export * from "./sunlightHours"
+export * from "./illuminance"
+export * from "./heatmaps"