@snaptrude/plugin-core 0.3.0 → 0.6.0

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"

package/src/api/analysis/shadows.ts

@@ -0,0 +1,183 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Analysis shadows — real-time sun shadows in the scene.
+ *
+ * Shadows are cast for the sun position at a specific date and time at the
+ * project's geographic location. The date-time crosses this API as an **ISO
+ * 8601 date-time string** in the project's local time (e.g.
+ * `"2026-06-21T14:30"`); the engine snaps the time **down** to its half-hour
+ * grid (`14:59` → `14:30`); seconds, if provided, are discarded. The
+ * timezone is derived from the site location by the engine — do not append
+ * a UTC offset.
+ *
+ * Methods that position the sun **throw** when the project has no geo-located
+ * site/terrain — there is no fallback location. Set the site location first;
+ * read it via `program.site.getLocation`.
+ *
+ * Accessed via `snaptrude.analysis.shadows`.
+ */
+export abstract class PluginAnalysisShadowsApi {
+  constructor() {}
+
+  /**
+   * Turn real-time sun shadows ON, optionally at a specific date and time.
+   *
+   * Without `options.dateTime` the shadows use the current stored sun
+   * position; with it, the sun is moved first (same as
+   * {@linkcode PluginAnalysisShadowsApi.setDateTime}). Enabling shadows
+   * resets any active heatmap analysis (`sunlightHours` / `illuminance`) —
+   * they are mutually exclusive in the product.
+   *
+   * @param options - Optional `dateTime`: ISO 8601 local date-time to
+   *   position the sun at (snapped to the engine's half-hour grid).
+   * @returns `true` — shadows are enabled after the call.
+   * @throws When the project has no geo-located site/terrain.
+   * @throws When `options.dateTime` is not a parseable ISO date-time.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Turn on shadows
+   * @examplePrompt Show the shadows at 3pm on June 21st
+   * @examplePrompt Enable sun shadows for the summer solstice afternoon
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.shadows.enable({ dateTime: "2026-06-21T15:00" })
+   * ```
+   */
+  public abstract enable(
+    options?: PluginAnalysisShadowsEnableOptions,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Turn real-time sun shadows OFF.
+   *
+   * A no-op (returns `false`) when shadows are already off. The stored sun
+   * date-time is kept for the next enable.
+   *
+   * @returns `false` — shadows are disabled after the call.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Turn off shadows
+   * @examplePrompt Hide the sun shadows
+   * @examplePrompt Disable shadow rendering in the scene
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.shadows.disable()
+   * ```
+   */
+  public abstract disable(): PluginApiReturn<boolean>
+
+  /**
+   * Whether real-time sun shadows are currently enabled.
+   *
+   * A pure read — never mutates, never throws.
+   *
+   * @returns `true` when shadows are rendering.
+   *
+   * @examplePrompt Are shadows on?
+   * @examplePrompt Check whether sun shadows are enabled
+   * @examplePrompt Is the scene showing shadows right now?
+   *
+   * # Example
+   * ```ts
+   * const on = await snaptrude.analysis.shadows.isEnabled()
+   * ```
+   */
+  public abstract isEnabled(): PluginApiReturn<boolean>
+
+  /**
+   * Move the sun to a specific date and time.
+   *
+   * Takes an ISO 8601 date-time string in the project's local time; the
+   * engine snaps the time down to its half-hour grid and re-renders the shadows
+   * (when they are enabled). The engine stores no year — only the month, day,
+   * and time are applied, and the returned date-time always carries the
+   * **current year** (setting `"2020-12-21T09:30"` returns
+   * `"2026-12-21T09:30"` in 2026). Paired with
+   * {@linkcode PluginAnalysisShadowsApi.getDateTime}.
+   *
+   * @param dateTime - ISO 8601 local date-time, e.g. `"2026-12-21T09:30"`.
+   * @returns A {@linkcode PluginAnalysisShadowsDateTimeResult} — the applied
+   *   ISO date-time after half-hour snapping.
+   * @throws When the project has no geo-located site/terrain.
+   * @throws When `dateTime` is not a parseable ISO date-time.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Set the shadow time to 9:30 am on the winter solstice
+   * @examplePrompt Move the sun to noon on March 1st
+   * @examplePrompt Change the shadow study date to December 21
+   *
+   * # Example
+   * ```ts
+   * const applied = await snaptrude.analysis.shadows.setDateTime("2026-12-21T09:30")
+   * console.log(applied) // "2026-12-21T09:30" (snapped to the half-hour grid)
+   * ```
+   */
+  public abstract setDateTime(
+    dateTime: string,
+  ): PluginApiReturn<PluginAnalysisShadowsDateTimeResult>
+
+  /**
+   * Get the sun's current date and time.
+   *
+   * Returns the stored sun position as an ISO 8601 local date-time string —
+   * the value shadows render at (whether or not they are enabled). The engine
+   * stores no year, so the returned string always carries the **current
+   * year**, whatever year was passed to
+   * {@linkcode PluginAnalysisShadowsApi.setDateTime} (its pair).
+   *
+   * @returns A {@linkcode PluginAnalysisShadowsDateTimeResult} — the current
+   *   ISO local date-time of the sun.
+   *
+   * @examplePrompt What date and time are the shadows set to?
+   * @examplePrompt Get the current sun position date
+   * @examplePrompt Which time of day is the shadow study showing?
+   *
+   * # Example
+   * ```ts
+   * const dateTime = await snaptrude.analysis.shadows.getDateTime()
+   * ```
+   */
+  public abstract getDateTime(): PluginApiReturn<PluginAnalysisShadowsDateTimeResult>
+}
+
+/**
+ * Options for {@linkcode PluginAnalysisShadowsApi.enable}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dateTime` | `string \| undefined` | ISO 8601 local date-time to position the sun at (snapped to the half-hour grid) |
+ */
+export const PluginAnalysisShadowsEnableOptions = z.object({
+  dateTime: z.string().optional(),
+})
+export type PluginAnalysisShadowsEnableOptions = z.infer<
+  typeof PluginAnalysisShadowsEnableOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginAnalysisShadowsApi.setDateTime}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dateTime` | `string` | ISO 8601 local date-time, e.g. `"2026-06-21T14:30"` |
+ */
+export const PluginAnalysisShadowsSetDateTimeArgs = z.object({
+  dateTime: z.string(),
+})
+export type PluginAnalysisShadowsSetDateTimeArgs = z.infer<
+  typeof PluginAnalysisShadowsSetDateTimeArgs
+>
+
+/**
+ * Result of {@linkcode PluginAnalysisShadowsApi.setDateTime} /
+ * {@linkcode PluginAnalysisShadowsApi.getDateTime} — the sun's ISO 8601
+ * local date-time (minute precision, on the engine's half-hour grid).
+ */
+export const PluginAnalysisShadowsDateTimeResult = z.string()
+export type PluginAnalysisShadowsDateTimeResult = z.infer<
+  typeof PluginAnalysisShadowsDateTimeResult
+>

package/src/api/analysis/sunlightHours.ts

@@ -0,0 +1,211 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Analysis sunlightHours — the direct-sunlight-hours heatmap study.
+ *
+ * Computes, for every space surface (Room or Department Mass — generic
+ * Masses are not enough), how many hours of direct sunlight
+ * it receives over a date range, and renders the result as a heatmap on the
+ * scene. The computation is an **asynchronous backend job**:
+ *
+ * 1. {@linkcode PluginAnalysisSunlightHoursApi.compute} starts the job and
+ *    returns immediately.
+ * 2. Poll {@linkcode PluginAnalysisSunlightHoursApi.get} until `status` is
+ *    `"active"` (heatmap rendered) — a run typically takes minutes. There is
+ *    no completion event; polling is the pattern.
+ * 3. {@linkcode PluginAnalysisSunlightHoursApi.cancel} aborts an in-flight
+ *    run; {@linkcode PluginAnalysisSunlightHoursApi.reset} clears a rendered
+ *    heatmap.
+ *
+ * Heatmaps are invalidated by scene-mutating edits — re-run the study after
+ * changing the model. Dates cross as ISO 8601 date strings (`"YYYY-MM-DD"`).
+ *
+ * Accessed via `snaptrude.analysis.sunlightHours`.
+ */
+export abstract class PluginAnalysisSunlightHoursApi {
+  constructor() {}
+
+  /**
+   * Start a direct-sunlight-hours run for a date range.
+   *
+   * Starts the backend job and **returns immediately** — it does not wait
+   * for the heatmap. Poll {@linkcode PluginAnalysisSunlightHoursApi.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 PluginAnalysisIlluminanceApi} (`analysis.illuminance`)
+   * 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 project has no geo-located site/terrain (no location to
+   *   compute sun exposure for — there is no fallback location).
+   * @throws When the scene has no space (Room or Department Mass) to analyse
+   *   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 sunlight hours analysis for June
+   * @examplePrompt Compute direct sunlight hours between March and September
+   * @examplePrompt How much sun does my building get over the summer?
+   *
+   * # Example
+   * ```ts
+   * const { success } = await snaptrude.analysis.sunlightHours.compute(
+   *   "2026-06-01",
+   *   "2026-06-30",
+   * )
+   * // poll until the heatmap is rendered
+   * let job = await snaptrude.analysis.sunlightHours.get()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.analysis.sunlightHours.get()
+   * }
+   * ```
+   */
+  public abstract compute(
+    startDate: string,
+    endDate: string,
+  ): PluginApiReturn<PluginAnalysisComputeResult>
+
+  /**
+   * Get the state of the sunlight-hours study.
+   *
+   * The polling read for the async job started by
+   * {@linkcode PluginAnalysisSunlightHoursApi.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 sunlight analysis done?
+   * @examplePrompt Check the status of the sunlight hours run
+   * @examplePrompt What date range was the sunlight heatmap computed for?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.analysis.sunlightHours.get()
+   * if (job?.status === "active") console.log(job.startDate, job.endDate)
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginAnalysisJobStateResult>
+
+  /**
+   * Cancel the in-flight sunlight-hours 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 sunlight analysis
+   * @examplePrompt Stop the running sunlight hours computation
+   * @examplePrompt Abort the sun study
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.sunlightHours.cancel()
+   * ```
+   */
+  public abstract cancel(): PluginApiReturn<boolean>
+
+  /**
+   * Clear the sunlight-hours 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 PluginAnalysisSunlightHoursApi.cancel}.
+   *
+   * @returns `true` when a heatmap was cleared, `false` when none was
+   *   showing.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Clear the sunlight heatmap
+   * @examplePrompt Remove the sun hours colours from the model
+   * @examplePrompt Reset the sunlight analysis view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.sunlightHours.reset()
+   * ```
+   */
+  public abstract reset(): PluginApiReturn<boolean>
+}
+
+/**
+ * Result of starting an analysis job
+ * ({@linkcode PluginAnalysisSunlightHoursApi.compute} /
+ * {@linkcode PluginAnalysisIlluminanceApi.compute}).
+ *
+ * The `success: false` arm is **reserved — not yet emitted**: the current
+ * host always returns `{ success: true }` (start failures throw instead); a
+ * failure indicator may be added additively later.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | `true` when the backend job was started |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` (reserved — not yet emitted) |
+ */
+export const PluginAnalysisComputeResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginAnalysisComputeResult = z.infer<
+  typeof PluginAnalysisComputeResult
+>
+
+/**
+ * The status of an analysis heatmap job.
+ *
+ * | Value | 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 |
+ */
+export const PluginAnalysisJobStatus = z.enum([
+  "running",
+  "active",
+  "inactive",
+])
+export type PluginAnalysisJobStatus = z.infer<typeof PluginAnalysisJobStatus>
+
+/**
+ * The state of an analysis heatmap job.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginAnalysisJobStatus} | `"running"` \| `"active"` \| `"inactive"` |
+ * | `startDate` | `string` | ISO date (`"YYYY-MM-DD"`) the run was computed from |
+ * | `endDate` | `string` | ISO date (`"YYYY-MM-DD"`) the run was computed to |
+ */
+export const PluginAnalysisJobState = z.object({
+  status: PluginAnalysisJobStatus,
+  startDate: z.string(),
+  endDate: z.string(),
+})
+export type PluginAnalysisJobState = z.infer<typeof PluginAnalysisJobState>
+
+/**
+ * Result of {@linkcode PluginAnalysisSunlightHoursApi.get} /
+ * {@linkcode PluginAnalysisIlluminanceApi.get} — the job state, or `null`
+ * when no run result is available (the study never ran, was cancelled, or
+ * the last run failed).
+ */
+export const PluginAnalysisJobStateResult = PluginAnalysisJobState.nullable()
+export type PluginAnalysisJobStateResult = z.infer<
+  typeof PluginAnalysisJobStateResult
+>

package/src/api/analysis/sunpath.ts

@@ -0,0 +1,83 @@
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Analysis sunpath — the sun-path diagram overlay.
+ *
+ * The sun-path diagram draws the sun's annual/daily trajectory arcs over the
+ * scene for the project's geographic location, so daylight behaviour can be
+ * read directly off the model. Toggling it is an **undoable** action (it goes
+ * through the command stack, so `core.history.undo` reverts it).
+ *
+ * The overlay is computed for the project's geo-location. Enabling **throws**
+ * when the project has no geo-located site/terrain — there is no fallback
+ * location. Set the site location first (Import terrain / site context);
+ * read it via `program.site.getLocation`.
+ *
+ * Accessed via `snaptrude.analysis.sunpath`.
+ */
+export abstract class PluginAnalysisSunpathApi {
+  constructor() {}
+
+  /**
+   * Turn the sun-path diagram overlay ON.
+   *
+   * Undoable: the toggle is committed through the command stack. A no-op
+   * (returns `true`) when the overlay is already active.
+   *
+   * @returns `true` — the overlay is active after the call.
+   * @throws When the project has no geo-located site/terrain (no location to
+   *   compute the sun trajectory for).
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Show the sun path diagram
+   * @examplePrompt Turn on the sunpath overlay
+   * @examplePrompt Visualize the sun's trajectory over my building
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.sunpath.enable()
+   * const active = await snaptrude.analysis.sunpath.isActive() // true
+   * ```
+   */
+  public abstract enable(): PluginApiReturn<boolean>
+
+  /**
+   * Turn the sun-path diagram overlay OFF.
+   *
+   * Undoable: the toggle is committed through the command stack. A no-op
+   * (returns `false`) when the overlay is already off.
+   *
+   * @returns `false` — the overlay is inactive after the call.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Hide the sun path diagram
+   * @examplePrompt Turn off the sunpath overlay
+   * @examplePrompt Remove the sun trajectory arcs from the scene
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.analysis.sunpath.disable()
+   * ```
+   */
+  public abstract disable(): PluginApiReturn<boolean>
+
+  /**
+   * Whether the sun-path diagram overlay is currently active.
+   *
+   * A pure read — never mutates, never throws.
+   *
+   * @returns `true` when the overlay is showing.
+   *
+   * @examplePrompt Is the sun path diagram on?
+   * @examplePrompt Check whether the sunpath overlay is active
+   * @examplePrompt Am I looking at the sun trajectory right now?
+   *
+   * # Example
+   * ```ts
+   * if (!(await snaptrude.analysis.sunpath.isActive())) {
+   *   await snaptrude.analysis.sunpath.enable()
+   * }
+   * ```
+   */
+  public abstract isActive(): PluginApiReturn<boolean>
+}