@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/api/analysis/illuminance.ts

@@ -1,155 +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>
-}
+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

@@ -1,61 +1,61 @@
-import { PluginAnalysisSunpathApi } from "./sunpath"
-import { PluginAnalysisShadowsApi } from "./shadows"
-import { PluginAnalysisSunlightHoursApi } from "./sunlightHours"
-import { PluginAnalysisIlluminanceApi } from "./illuminance"
-import { PluginAnalysisHeatmapsApi } from "./heatmaps"
-import { PluginAnalysisWeatherApi } from "./weather"
-import { PluginAnalysisSolarApi } from "./solar"
-import { PluginAnalysisDaylightApi } from "./daylight"
-
-/**
- * Sustainability-analysis APIs.
- *
- * 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)
- * - {@linkcode PluginAnalysisApi.weather} — Read the site's typical-year weather series (numeric, paged)
- * - {@linkcode PluginAnalysisApi.solar} — Sample solar exposure at caller-chosen points (numeric)
- * - {@linkcode PluginAnalysisApi.daylight} — Standards-grade annual daylight metrics (IES LM-83, numeric)
- *
- * Accessed via `snaptrude.analysis`.
- */
-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
-  /** Site typical-year weather series (numeric, paged). See {@linkcode PluginAnalysisWeatherApi}. */
-  public abstract weather: PluginAnalysisWeatherApi
-  /** Per-point solar exposure sampling (numeric). See {@linkcode PluginAnalysisSolarApi}. */
-  public abstract solar: PluginAnalysisSolarApi
-  /** IES LM-83 annual daylight metrics (numeric). See {@linkcode PluginAnalysisDaylightApi}. */
-  public abstract daylight: PluginAnalysisDaylightApi
-
-  constructor() {}
-}
-
-export * from "./sunpath"
-export * from "./shadows"
-export * from "./sunlightHours"
-export * from "./illuminance"
-export * from "./heatmaps"
-export * from "./weather"
-export * from "./solar"
-export * from "./daylight"
+import { PluginAnalysisSunpathApi } from "./sunpath"
+import { PluginAnalysisShadowsApi } from "./shadows"
+import { PluginAnalysisSunlightHoursApi } from "./sunlightHours"
+import { PluginAnalysisIlluminanceApi } from "./illuminance"
+import { PluginAnalysisHeatmapsApi } from "./heatmaps"
+import { PluginAnalysisWeatherApi } from "./weather"
+import { PluginAnalysisSolarApi } from "./solar"
+import { PluginAnalysisDaylightApi } from "./daylight"
+
+/**
+ * Sustainability-analysis APIs.
+ *
+ * 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)
+ * - {@linkcode PluginAnalysisApi.weather} — Read the site's typical-year weather series (numeric, paged)
+ * - {@linkcode PluginAnalysisApi.solar} — Sample solar exposure at caller-chosen points (numeric)
+ * - {@linkcode PluginAnalysisApi.daylight} — Standards-grade annual daylight metrics (IES LM-83, numeric)
+ *
+ * Accessed via `snaptrude.analysis`.
+ */
+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
+  /** Site typical-year weather series (numeric, paged). See {@linkcode PluginAnalysisWeatherApi}. */
+  public abstract weather: PluginAnalysisWeatherApi
+  /** Per-point solar exposure sampling (numeric). See {@linkcode PluginAnalysisSolarApi}. */
+  public abstract solar: PluginAnalysisSolarApi
+  /** IES LM-83 annual daylight metrics (numeric). See {@linkcode PluginAnalysisDaylightApi}. */
+  public abstract daylight: PluginAnalysisDaylightApi
+
+  constructor() {}
+}
+
+export * from "./sunpath"
+export * from "./shadows"
+export * from "./sunlightHours"
+export * from "./illuminance"
+export * from "./heatmaps"
+export * from "./weather"
+export * from "./solar"
+export * from "./daylight"