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

package/dist/api/analysis/illuminance.d.ts

@@ -0,0 +1,145 @@
+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 declare 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()
+     * }
+     * ```
+     */
+    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)
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    abstract reset(): PluginApiReturn<boolean>;
+}
+//# sourceMappingURL=illuminance.d.ts.map

package/dist/api/analysis/illuminance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"illuminance.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/illuminance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,4BAA4B;;IAGhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;aACa,OAAO,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,2BAA2B,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;aACa,GAAG,IAAI,eAAe,CAAC,4BAA4B,CAAC;IAEpE;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;IAElD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC;CAClD"}

package/dist/api/analysis/index.d.ts

@@ -0,0 +1,59 @@
+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 declare abstract class PluginAnalysisApi {
+    /** Sun-path diagram overlay — enable/disable/isActive. See {@linkcode PluginAnalysisSunpathApi}. */
+    abstract sunpath: PluginAnalysisSunpathApi;
+    /** Real-time sun shadows + sun date-time. See {@linkcode PluginAnalysisShadowsApi}. */
+    abstract shadows: PluginAnalysisShadowsApi;
+    /** Direct-sunlight-hours heatmap job. See {@linkcode PluginAnalysisSunlightHoursApi}. */
+    abstract sunlightHours: PluginAnalysisSunlightHoursApi;
+    /** Daylight-illuminance heatmap job (Pro). See {@linkcode PluginAnalysisIlluminanceApi}. */
+    abstract illuminance: PluginAnalysisIlluminanceApi;
+    /** Plugin-supplied scalar-data heatmaps. See {@linkcode PluginAnalysisHeatmapsApi}. */
+    abstract heatmaps: PluginAnalysisHeatmapsApi;
+    /** Site typical-year weather series (numeric, paged). See {@linkcode PluginAnalysisWeatherApi}. */
+    abstract weather: PluginAnalysisWeatherApi;
+    /** Per-point solar exposure sampling (numeric). See {@linkcode PluginAnalysisSolarApi}. */
+    abstract solar: PluginAnalysisSolarApi;
+    /** IES LM-83 annual daylight metrics (numeric). See {@linkcode PluginAnalysisDaylightApi}. */
+    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";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,iBAAiB;IACrC,oGAAoG;IACpG,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,uFAAuF;IACvF,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,yFAAyF;IACzF,SAAgB,aAAa,EAAE,8BAA8B,CAAA;IAC7D,4FAA4F;IAC5F,SAAgB,WAAW,EAAE,4BAA4B,CAAA;IACzD,uFAAuF;IACvF,SAAgB,QAAQ,EAAE,yBAAyB,CAAA;IACnD,mGAAmG;IACnG,SAAgB,OAAO,EAAE,wBAAwB,CAAA;IACjD,2FAA2F;IAC3F,SAAgB,KAAK,EAAE,sBAAsB,CAAA;IAC7C,8FAA8F;IAC9F,SAAgB,QAAQ,EAAE,yBAAyB,CAAA;;CAGpD;AAED,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA"}

package/dist/api/analysis/shadows.d.ts

@@ -0,0 +1,165 @@
+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 declare 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" })
+     * ```
+     */
+    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()
+     * ```
+     */
+    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()
+     * ```
+     */
+    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)
+     * ```
+     */
+    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()
+     * ```
+     */
+    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 declare const PluginAnalysisShadowsEnableOptions: z.ZodObject<{
+    dateTime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginAnalysisShadowsSetDateTimeArgs: z.ZodObject<{
+    dateTime: z.ZodString;
+}, z.core.$strip>;
+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 declare const PluginAnalysisShadowsDateTimeResult: z.ZodString;
+export type PluginAnalysisShadowsDateTimeResult = z.infer<typeof PluginAnalysisShadowsDateTimeResult>;
+//# sourceMappingURL=shadows.d.ts.map

package/dist/api/analysis/shadows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadows.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/shadows.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,wBAAwB;;IAG5C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,OAAO,CAAC,EAAE,kCAAkC,GAC3C,eAAe,CAAC,OAAO,CAAC;IAE3B;;;;;;;;;;;;;;;;;OAiBG;aACa,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC;IAEnD;;;;;;;;;;;;;;;OAeG;aACa,SAAS,IAAI,eAAe,CAAC,OAAO,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;aACa,WAAW,CACzB,QAAQ,EAAE,MAAM,GACf,eAAe,CAAC,mCAAmC,CAAC;IAEvD;;;;;;;;;;;;;;;;;;;;OAoBG;aACa,WAAW,IAAI,eAAe,CAAC,mCAAmC,CAAC;CACpF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC;;iBAE7C,CAAA;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CACtD,OAAO,kCAAkC,CAC1C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;iBAE/C,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,aAAa,CAAA;AAC7D,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA"}

package/dist/api/analysis/solar.d.ts

@@ -0,0 +1,249 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Analysis solar — sample solar exposure at caller-chosen points.
+ *
+ * Unlike the heatmap studies (which raster the model's own surfaces), this
+ * samples solar exposure at **points you supply** — an instant (sun visible? /
+ * irradiance now) or aggregated over a date range (shaded fraction / cumulative
+ * irradiance). Positions are **world plan-space** coordinates, the same units
+ * and frame as plugin geometry reads; the backend echoes them verbatim and
+ * never re-projects.
+ *
+ * Raw numbers only: this renders no heatmap, mutates no geometry, and writes no
+ * save commands — visualization is the plugin's job. Large grids run as a job
+ * (`status: "running"` until complete); every result carries `modelRevision` +
+ * `inputHash` so the caller can mark it stale after a geometry change.
+ *
+ * Accessed via `snaptrude.analysis.solar`.
+ */
+export declare abstract class PluginAnalysisSolarApi {
+    constructor();
+    /**
+     * Sample solar exposure at a set of points.
+     *
+     * Provide **exactly one** timing mode: `dateTime` (a single instant →
+     * `mode: "instant"`, results in `W/m²`), or `startDate` + `endDate` (a range
+     * → `mode: "range"`, results aggregated in `kWh/m²`). `results` is paged —
+     * follow `nextCursor` until it is `null`. Each point's optional `normal`
+     * gives plane-of-array irradiance; omit it for a horizontal sample.
+     *
+     * @param args - {@linkcode PluginSolarSampleGridArgs}: the `points`, exactly
+     *   one timing mode (`dateTime` XOR `startDate`+`endDate`), and an optional
+     *   `includeHourlyArtifact` to attach a downloadable per-hour series.
+     * @returns A {@linkcode PluginSolarSampleGridResult} — the run `status`,
+     *   `mode`/`units`, provenance (`weather`, `modelRevision`, `inputHash`),
+     *   this page of `results`, an optional `hourlyArtifact`, and `nextCursor`.
+     * @throws When the project has no geo-located site (no location to sample
+     *   solar exposure for).
+     *
+     * @examplePrompt What's the irradiance at these facade points at noon on June 21?
+     * @examplePrompt How shaded are these balcony points across the summer?
+     * @examplePrompt Sample direct sun visibility at these roof points right now
+     *
+     * # Example
+     * ```ts
+     * const grid = await snaptrude.analysis.solar.sampleGrid({
+     *   points: [
+     *     { id: "a", position: [0, 3, 0] },
+     *     { id: "b", position: [5, 3, 0], normal: [0, 0, 1] },
+     *   ],
+     *   dateTime: "2026-06-21T12:00:00+05:30",
+     * })
+     * for (const r of grid.results) {
+     *   console.log(r.id, r.directSunVisible, r.totalIrradiance, grid.units)
+     * }
+     * ```
+     */
+    abstract sampleGrid(args: PluginSolarSampleGridArgs): PluginApiReturn<PluginSolarSampleGridResult>;
+}
+/**
+ * Status of a {@linkcode PluginAnalysisSolarApi.sampleGrid} run.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"running"` | The job is in flight — poll again |
+ * | `"complete"` | Results are final |
+ * | `"cancelled"` | The run was cancelled |
+ * | `"failed"` | The run failed |
+ */
+export declare const PluginSolarRunStatus: z.ZodEnum<{
+    complete: "complete";
+    failed: "failed";
+    running: "running";
+    cancelled: "cancelled";
+}>;
+export type PluginSolarRunStatus = z.infer<typeof PluginSolarRunStatus>;
+/**
+ * Timing mode of the run — chosen by which timing args were supplied.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"instant"` | Single `dateTime` — irradiance in `W/m²` |
+ * | `"range"` | `startDate`+`endDate` — irradiance aggregated in `kWh/m²` |
+ */
+export declare const PluginSolarSampleMode: z.ZodEnum<{
+    range: "range";
+    instant: "instant";
+}>;
+export type PluginSolarSampleMode = z.infer<typeof PluginSolarSampleMode>;
+/**
+ * Irradiance units of the results — `W/m²` (instant) or `kWh/m²` (range).
+ */
+export declare const PluginSolarUnits: z.ZodEnum<{
+    "W/m2": "W/m2";
+    "kWh/m2": "kWh/m2";
+}>;
+export type PluginSolarUnits = z.infer<typeof PluginSolarUnits>;
+/**
+ * Downloadable per-hour artifact (present only when `includeHourlyArtifact`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `url` | `string` | Signed download URL |
+ * | `format` | `"parquet" \| "csv-gz"` | File format |
+ * | `expiresAt` | `string` | ISO 8601 expiry of the signed URL |
+ */
+export declare const PluginSolarHourlyArtifact: z.ZodObject<{
+    url: z.ZodString;
+    format: z.ZodEnum<{
+        parquet: "parquet";
+        "csv-gz": "csv-gz";
+    }>;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type PluginSolarHourlyArtifact = z.infer<typeof PluginSolarHourlyArtifact>;
+/**
+ * A caller-supplied point to sample.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Caller-chosen id, echoed back verbatim on the result |
+ * | `position` | `[number, number, number]` | World plan-space `[x, y, z]` |
+ * | `normal` | `[number, number, number]`? | Surface normal for plane-of-array; omit = horizontal |
+ */
+export declare const PluginSolarSamplePoint: z.ZodObject<{
+    id: z.ZodString;
+    position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    normal: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+export type PluginSolarSamplePoint = z.infer<typeof PluginSolarSamplePoint>;
+/**
+ * Arguments for {@linkcode PluginAnalysisSolarApi.sampleGrid}.
+ *
+ * Provide **exactly one** timing mode: `dateTime` (instant) XOR
+ * `startDate`+`endDate` (range).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode PluginSolarSamplePoint}`[]` | Points to sample |
+ * | `dateTime` | `string`? | Instant mode: local ISO 8601 with offset |
+ * | `startDate` | `string`? | Range mode: inclusive start `"YYYY-MM-DD"` |
+ * | `endDate` | `string`? | Range mode: inclusive end `"YYYY-MM-DD"` |
+ * | `includeHourlyArtifact` | `boolean`? | Attach a downloadable per-hour series |
+ */
+export declare const PluginSolarSampleGridArgs: z.ZodObject<{
+    points: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        normal: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    dateTime: z.ZodOptional<z.ZodString>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+    includeHourlyArtifact: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginSolarSampleGridArgs = z.infer<typeof PluginSolarSampleGridArgs>;
+/**
+ * One sampled point's result. Irradiance fields are in the enclosing result's
+ * `units` and are omitted when the backend did not compute them.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The point's caller-chosen id |
+ * | `directSunVisible` | `boolean` | Instant mode: sun disc visible from the point |
+ * | `shadeFraction` | `number` | `0`..`1`; range mode: fraction of sun-up hours shaded |
+ * | `directIrradiance` | `number`? | Direct component, in the result's `units` |
+ * | `diffuseIrradiance` | `number`? | Diffuse component, in the result's `units` |
+ * | `totalIrradiance` | `number`? | Total (direct + diffuse), in the result's `units` |
+ */
+export declare const PluginSolarSampleResult: z.ZodObject<{
+    id: z.ZodString;
+    directSunVisible: z.ZodBoolean;
+    shadeFraction: z.ZodNumber;
+    directIrradiance: z.ZodOptional<z.ZodNumber>;
+    diffuseIrradiance: z.ZodOptional<z.ZodNumber>;
+    totalIrradiance: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginSolarSampleResult = z.infer<typeof PluginSolarSampleResult>;
+/**
+ * Result of {@linkcode PluginAnalysisSolarApi.sampleGrid} — one page.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginSolarRunStatus} | Run status |
+ * | `mode` | {@linkcode PluginSolarSampleMode} | `"instant"` or `"range"` |
+ * | `coordinateSystem` | `"world-plan-space"` | Echo of the input frame |
+ * | `modelRevision` | `string` | Geometry revision sampled against (staleness key) |
+ * | `inputHash` | `string` | Hash of points+dates+geometry (staleness key) |
+ * | `units` | {@linkcode PluginSolarUnits} | `"W/m2"` (instant) or `"kWh/m2"` (range) |
+ * | `sunUpHours` | `number` | Sun-up hours over the sampled window |
+ * | `weather` | {@linkcode PluginWeatherSourceMeta} \| `null` | Resolved weather file, or `null` |
+ * | `weatherQuality` | `string[]` | Deduped quality flags present in the consumed rows |
+ * | `results` | {@linkcode PluginSolarSampleResult}`[]` | This page of per-point results |
+ * | `hourlyArtifact` | {@linkcode PluginSolarHourlyArtifact} \| `null` | Per-hour download, or `null` |
+ * | `nextCursor` | `string \| null` | Next page cursor; `null` = last page |
+ */
+export declare const PluginSolarSampleGridResult: z.ZodObject<{
+    status: z.ZodEnum<{
+        complete: "complete";
+        failed: "failed";
+        running: "running";
+        cancelled: "cancelled";
+    }>;
+    mode: z.ZodEnum<{
+        range: "range";
+        instant: "instant";
+    }>;
+    coordinateSystem: z.ZodLiteral<"world-plan-space">;
+    modelRevision: z.ZodString;
+    inputHash: z.ZodString;
+    units: z.ZodEnum<{
+        "W/m2": "W/m2";
+        "kWh/m2": "kWh/m2";
+    }>;
+    sunUpHours: z.ZodNumber;
+    weather: z.ZodNullable<z.ZodObject<{
+        weatherFileId: z.ZodString;
+        station: z.ZodString;
+        sourceId: z.ZodString;
+        distanceKm: z.ZodNullable<z.ZodNumber>;
+        selectionMethod: z.ZodEnum<{
+            "nearest-station": "nearest-station";
+            "user-upload": "user-upload";
+            "project-override": "project-override";
+        }>;
+        checksum: z.ZodString;
+        windReferenceHeightM: z.ZodNumber;
+    }, z.core.$strip>>;
+    weatherQuality: z.ZodArray<z.ZodString>;
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        directSunVisible: z.ZodBoolean;
+        shadeFraction: z.ZodNumber;
+        directIrradiance: z.ZodOptional<z.ZodNumber>;
+        diffuseIrradiance: z.ZodOptional<z.ZodNumber>;
+        totalIrradiance: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    hourlyArtifact: z.ZodNullable<z.ZodObject<{
+        url: z.ZodString;
+        format: z.ZodEnum<{
+            parquet: "parquet";
+            "csv-gz": "csv-gz";
+        }>;
+        expiresAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginSolarSampleGridResult = z.infer<typeof PluginSolarSampleGridResult>;
+//# sourceMappingURL=solar.d.ts.map

package/dist/api/analysis/solar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solar.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/solar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;aACa,UAAU,CACxB,IAAI,EAAE,yBAAyB,GAC9B,eAAe,CAAC,2BAA2B,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;EAA+B,CAAA;AACjE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;EAA6B,CAAA;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB;;;;;;;iBAIpC,CAAA;AACF,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,yBAAyB,CACjC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;iBAIjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;iBA0BlC,CAAA;AACJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,yBAAyB,CACjC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB;;;;;;;iBAOlC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAatC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA"}