@snaptrude/plugin-core 0.8.0 → 0.9.1

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

@@ -0,0 +1,603 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Analysis daylight — standards-grade annual daylight metrics (IES LM-83).
+ *
+ * Runs an annual daylight simulation over per-space sensor grids and returns
+ * **numeric** per-sensor and aggregate metrics — no textures, no heatmap, no
+ * model mutation. Two metrics are supported: **ASE** (Annual Sunlight
+ * Exposure) and **sDA** (Spatial Daylight Autonomy, sDA300/50%).
+ *
+ * **Run semantics.** `metrics: ["ASE"]` runs **synchronously** — `compute`
+ * returns the full result directly, no `runId`. Any request including
+ * `"sDA"` (alone or with ASE) runs **asynchronously**: `compute` submits the
+ * job and immediately returns `{ status: "running", runId, sensors: [],
+ * aggregates: [] }`; call {@linkcode PluginAnalysisDaylightApi.poll} with the
+ * `runId` until `status` is `"complete"` (or `"failed"`).
+ *
+ * **Blind operation.** sDA is computed WITH dynamic blind operation per the
+ * IES LM-83 2% rule: windows are grouped by storey + facade orientation, and
+ * for every occupied hour blind groups close (default 5% diffuse
+ * transmittance) until no more than 2% of the analysis points receive direct
+ * sun. This API **operates the blinds for you** — sDA without blind operation
+ * is not LM-83-compliant, so there is no switch to turn it off. The run's
+ * `provenance.blinds` reports the groups, their closed hours, and any hours
+ * where no combination satisfies the rule.
+ *
+ * **Surface optics.** The optional `optics` arg overrides surface optics.
+ * Resolution order per surface: per-material (`optics.materials`, keyed by
+ * material **name** as shown in Snaptrude) → per-category
+ * (`optics.categories`) → LM-83/convention defaults:
+ *
+ * | Category | Default | Property |
+ * |---|---|---|
+ * | `wall` | `0.5` | reflectance |
+ * | `ceiling` | `0.7` | reflectance |
+ * | `floor` | `0.2` | reflectance |
+ * | `furniture` | `0.5` | reflectance |
+ * | `glazing` | `0.65` | transmittance (Tvis) |
+ * | `context` | `0.2` | reflectance |
+ * | blinds (closed) | `0.05` | diffuse transmittance |
+ *
+ * Glazing takes visible **transmittance** (Tvis) exactly as manufacturers
+ * quote it; the backend converts it to Radiance glass transmissivity
+ * internally.
+ *
+ * Every result carries a full `provenance` echo (weather file, thresholds,
+ * grid, location, resolved optics, blind operation, warnings, excluded
+ * spaces) plus `modelRevision` + `inputHash` for staleness. Positions are
+ * **world plan-space** coordinates.
+ *
+ * `compute` is write-gated and Pro-gated host-side, exactly like
+ * {@linkcode PluginAnalysisIlluminanceApi.compute}.
+ *
+ * Accessed via `snaptrude.analysis.daylight`.
+ */
+export declare abstract class PluginAnalysisDaylightApi {
+    constructor();
+    /**
+     * Compute annual daylight metrics for the model's spaces.
+     *
+     * Sensors are laid out per-space from the `grid` spec; request the metrics
+     * you want in `metrics` (`["ASE"]`, `["sDA"]`, or both). ASE-only runs are
+     * **synchronous** and return the full result directly. Any run including
+     * `"sDA"` is **asynchronous**: this returns `{ status: "running", runId,
+     * sensors: [], aggregates: [] }` immediately — pass the `runId` to
+     * {@linkcode PluginAnalysisDaylightApi.poll} until the run completes.
+     * sDA is computed with LM-83 dynamic blind operation (see the class doc);
+     * pass `optics` to override surface reflectances / glazing transmittance.
+     *
+     * @param args - {@linkcode PluginDaylightComputeArgs}: the `standard`
+     *   (`"IES-LM-83-23"`), the `metrics` to compute, an optional occupancy
+     *   `schedule`, optional surface `optics` overrides, and the sensor `grid`
+     *   spec.
+     * @returns A {@linkcode PluginDaylightResults} — per-sensor `sensors`,
+     *   scope-rolled `aggregates`, the full `provenance` echo, `nextCursor`
+     *   (`null` when all sensors fit in one page), and `runId` on
+     *   asynchronous (sDA) runs.
+     * @throws When the workspace is not on a **Pro** plan.
+     * @throws When plugin writes are disabled.
+     * @throws When the project has no geo-located site (no location to compute
+     *   daylight for) or no spaces to analyse.
+     *
+     * @examplePrompt Run an LM-83 ASE daylight analysis on all my spaces
+     * @examplePrompt Which rooms fail annual sunlight exposure?
+     * @examplePrompt Compute ASE with a 0.6m sensor grid at desk height
+     * @examplePrompt Run an LM-83 sDA analysis with blinds operated
+     * @examplePrompt Which spaces meet sDA300/50%?
+     * @examplePrompt Compute sDA with 70% reflective ceilings and Tvis 0.6 glazing
+     *
+     * # Example
+     * ```ts
+     * let res = await snaptrude.analysis.daylight.compute({
+     *   standard: "IES-LM-83-23",
+     *   metrics: ["sDA", "ASE"],
+     *   grid: { spacingM: 0.6, workplaneHeightM: 0.76, boundaryOffsetM: 0.5 },
+     *   optics: { materials: { "Glass - Clear": { transmittance: 0.6 } } },
+     * })
+     * const runId = res.runId
+     * while (res.status === "running" && runId) {
+     *   await new Promise((r) => setTimeout(r, 5000))
+     *   res = await snaptrude.analysis.daylight.poll({ runId })
+     * }
+     * const failing = res.aggregates.filter(
+     *   (a) => a.scope === "space" && (a.sdaPercent ?? 0) < 55,
+     * )
+     * ```
+     */
+    abstract compute(args: PluginDaylightComputeArgs): PluginApiReturn<PluginDaylightResults>;
+    /**
+     * Poll an asynchronous daylight run started by
+     * {@linkcode PluginAnalysisDaylightApi.compute}.
+     *
+     * Returns the same {@linkcode PluginDaylightResults} shape as `compute`:
+     * `status: "running"` while the job is in flight (empty `sensors` /
+     * `aggregates`), `"complete"` with the full data once done. Poll every few
+     * seconds — an annual sDA simulation takes minutes, not milliseconds.
+     * Completed results page sensors exactly like a synchronous run: follow
+     * `nextCursor` via the `cursor` arg.
+     *
+     * @param args - {@linkcode PluginDaylightPollArgs}: the `runId` returned by
+     *   `compute`, plus an optional sensor-page `cursor`.
+     * @returns A {@linkcode PluginDaylightResults} for the run.
+     * @throws When the `runId` is unknown, or when the run failed (surfaced as
+     *   a typed `OPERATION_FAILED`).
+     *
+     * @examplePrompt Check whether my sDA run has finished
+     * @examplePrompt Get the results of the daylight run
+     */
+    abstract poll(args: PluginDaylightPollArgs): PluginApiReturn<PluginDaylightResults>;
+}
+/**
+ * A daylight metric to compute. `"ASE"` (Annual Sunlight Exposure) runs
+ * synchronously; any request including `"sDA"` (Spatial Daylight Autonomy,
+ * sDA300/50% with LM-83 dynamic blind operation) runs asynchronously —
+ * `compute` returns a `runId` to pass to
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ */
+export declare const PluginDaylightMetric: z.ZodEnum<{
+    ASE: "ASE";
+    sDA: "sDA";
+}>;
+export type PluginDaylightMetric = z.infer<typeof PluginDaylightMetric>;
+/**
+ * Status of a daylight run. ASE-only runs are synchronous, so their result is
+ * `"complete"`; runs including sDA return `"running"` from `compute` and
+ * progress to `"complete"` (or `"failed"`) via
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ */
+export declare const PluginDaylightRunStatus: z.ZodEnum<{
+    complete: "complete";
+    failed: "failed";
+    running: "running";
+    cancelled: "cancelled";
+}>;
+export type PluginDaylightRunStatus = z.infer<typeof PluginDaylightRunStatus>;
+/**
+ * Sensor-grid spec: spacing, workplane height, and boundary inset (all metres).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacingM` | `number` | Sensor spacing |
+ * | `workplaneHeightM` | `number` | Sensor height above the floor |
+ * | `boundaryOffsetM` | `number` | Inset from the space boundary |
+ */
+export declare const PluginDaylightGrid: z.ZodObject<{
+    spacingM: z.ZodNumber;
+    workplaneHeightM: z.ZodNumber;
+    boundaryOffsetM: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDaylightGrid = z.infer<typeof PluginDaylightGrid>;
+/**
+ * Optional occupancy schedule (local hours). Defaults to the LM-83 default
+ * (8am–6pm) when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `startHour` | `number` | Occupied-period start hour, local (`0`..`24`) |
+ * | `endHour` | `number` | Occupied-period end hour, local (`0`..`24`) |
+ */
+export declare const PluginDaylightSchedule: z.ZodObject<{
+    startHour: z.ZodNumber;
+    endHour: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDaylightSchedule = z.infer<typeof PluginDaylightSchedule>;
+/**
+ * Opaque surface optics: visible reflectance (`0`..`1`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `reflectance` | `number` | Visible reflectance (`0`..`1`) |
+ */
+export declare const PluginDaylightOpaqueOptics: z.ZodObject<{
+    reflectance: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDaylightOpaqueOptics = z.infer<typeof PluginDaylightOpaqueOptics>;
+/**
+ * Glazing optics: visible **transmittance** (Tvis, `0`..`1`) exactly as
+ * manufacturers quote it. The backend converts it to Radiance glass
+ * transmissivity internally — never pre-convert.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `transmittance` | `number` | Visible transmittance Tvis (`0`..`1`) |
+ */
+export declare const PluginDaylightGlazingOptics: z.ZodObject<{
+    transmittance: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDaylightGlazingOptics = z.infer<typeof PluginDaylightGlazingOptics>;
+/**
+ * Optics for one material: {@linkcode PluginDaylightOpaqueOptics}
+ * (`reflectance`) for opaque surfaces, or
+ * {@linkcode PluginDaylightGlazingOptics} (`transmittance`) for glazing.
+ */
+export declare const PluginDaylightMaterialOptics: z.ZodUnion<readonly [z.ZodObject<{
+    reflectance: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    transmittance: z.ZodNumber;
+}, z.core.$strip>]>;
+export type PluginDaylightMaterialOptics = z.infer<typeof PluginDaylightMaterialOptics>;
+/**
+ * Per-category optics overrides. Categories cover every surface in the
+ * model; omitted categories use the LM-83/convention defaults (wall `0.5`,
+ * ceiling `0.7`, floor `0.2`, furniture `0.5`, glazing Tvis `0.65`,
+ * context `0.2`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `wall` | {@linkcode PluginDaylightOpaqueOptics}? | Walls, columns, beams, doors, frames (default `0.5`) |
+ * | `ceiling` | {@linkcode PluginDaylightOpaqueOptics}? | Down-facing slab faces (default `0.7`) |
+ * | `floor` | {@linkcode PluginDaylightOpaqueOptics}? | Up-facing slab faces (default `0.2`) |
+ * | `furniture` | {@linkcode PluginDaylightOpaqueOptics}? | Furniture (default `0.5`) |
+ * | `glazing` | {@linkcode PluginDaylightGlazingOptics}? | Window/door glass (default Tvis `0.65`) |
+ * | `context` | {@linkcode PluginDaylightOpaqueOptics}? | Terrain / context masses (default `0.2`) |
+ */
+export declare const PluginDaylightCategoryDefaults: z.ZodObject<{
+    wall: z.ZodOptional<z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>>;
+    ceiling: z.ZodOptional<z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>>;
+    floor: z.ZodOptional<z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>>;
+    furniture: z.ZodOptional<z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>>;
+    glazing: z.ZodOptional<z.ZodObject<{
+        transmittance: z.ZodNumber;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginDaylightCategoryDefaults = z.infer<typeof PluginDaylightCategoryDefaults>;
+/**
+ * Closed-blind optics: diffuse transmittance of the closed state. Defaults to
+ * the LM-83 `0.05` (5% diffuse) when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `transmittance` | `number` | Closed-blind diffuse transmittance (`0`..`1`) |
+ */
+export declare const PluginDaylightBlindsOptics: z.ZodObject<{
+    transmittance: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDaylightBlindsOptics = z.infer<typeof PluginDaylightBlindsOptics>;
+/**
+ * Surface-optics overrides for a daylight run. Resolution order per surface:
+ * `materials` (by material name) → `categories` → LM-83/convention defaults.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `materials` | `Record<string,` {@linkcode PluginDaylightMaterialOptics}`>`? | Keyed by material **name** as shown in Snaptrude (the same names `design.query.geometry.getTriangulatedMeshes` returns in `materialIds`); applies wherever the material appears and wins over category defaults |
+ * | `categories` | {@linkcode PluginDaylightCategoryDefaults}? | Per-category defaults override |
+ * | `blinds` | {@linkcode PluginDaylightBlindsOptics}? | Closed-blind state (default `0.05` diffuse) |
+ */
+export declare const PluginDaylightOptics: z.ZodObject<{
+    materials: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        reflectance: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        transmittance: z.ZodNumber;
+    }, z.core.$strip>]>>>;
+    categories: z.ZodOptional<z.ZodObject<{
+        wall: z.ZodOptional<z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>>;
+        ceiling: z.ZodOptional<z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>>;
+        floor: z.ZodOptional<z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>>;
+        furniture: z.ZodOptional<z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>>;
+        glazing: z.ZodOptional<z.ZodObject<{
+            transmittance: z.ZodNumber;
+        }, z.core.$strip>>;
+        context: z.ZodOptional<z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    blinds: z.ZodOptional<z.ZodObject<{
+        transmittance: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginDaylightOptics = z.infer<typeof PluginDaylightOptics>;
+/**
+ * Arguments for {@linkcode PluginAnalysisDaylightApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `standard` | `"IES-LM-83-23"` | Daylight standard; only supported value |
+ * | `metrics` | {@linkcode PluginDaylightMetric}`[]` | Metrics to compute (`["ASE"]` synchronous; including `"sDA"` asynchronous) |
+ * | `schedule` | {@linkcode PluginDaylightSchedule}? | Occupancy hours (default 8am–6pm) |
+ * | `grid` | {@linkcode PluginDaylightGrid} | Sensor-grid spec |
+ * | `optics` | {@linkcode PluginDaylightOptics}? | Surface-optics overrides (per-material → per-category → LM-83 defaults) |
+ */
+export declare const PluginDaylightComputeArgs: z.ZodObject<{
+    standard: z.ZodLiteral<"IES-LM-83-23">;
+    metrics: z.ZodArray<z.ZodEnum<{
+        ASE: "ASE";
+        sDA: "sDA";
+    }>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        startHour: z.ZodNumber;
+        endHour: z.ZodNumber;
+    }, z.core.$strip>>;
+    grid: z.ZodObject<{
+        spacingM: z.ZodNumber;
+        workplaneHeightM: z.ZodNumber;
+        boundaryOffsetM: z.ZodNumber;
+    }, z.core.$strip>;
+    optics: z.ZodOptional<z.ZodObject<{
+        materials: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            reflectance: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            transmittance: z.ZodNumber;
+        }, z.core.$strip>]>>>;
+        categories: z.ZodOptional<z.ZodObject<{
+            wall: z.ZodOptional<z.ZodObject<{
+                reflectance: z.ZodNumber;
+            }, z.core.$strip>>;
+            ceiling: z.ZodOptional<z.ZodObject<{
+                reflectance: z.ZodNumber;
+            }, z.core.$strip>>;
+            floor: z.ZodOptional<z.ZodObject<{
+                reflectance: z.ZodNumber;
+            }, z.core.$strip>>;
+            furniture: z.ZodOptional<z.ZodObject<{
+                reflectance: z.ZodNumber;
+            }, z.core.$strip>>;
+            glazing: z.ZodOptional<z.ZodObject<{
+                transmittance: z.ZodNumber;
+            }, z.core.$strip>>;
+            context: z.ZodOptional<z.ZodObject<{
+                reflectance: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        blinds: z.ZodOptional<z.ZodObject<{
+            transmittance: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginDaylightComputeArgs = z.infer<typeof PluginDaylightComputeArgs>;
+/**
+ * Arguments for {@linkcode PluginAnalysisDaylightApi.poll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `runId` | `string` | The run id returned by `compute` |
+ * | `cursor` | `string`? | Sensor-page cursor from a previous page's `nextCursor` |
+ */
+export declare const PluginDaylightPollArgs: z.ZodObject<{
+    runId: z.ZodString;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginDaylightPollArgs = z.infer<typeof PluginDaylightPollArgs>;
+/**
+ * One sensor's record. Positions are world plan-space `[x, y, z]`. Metric
+ * fields are present when the corresponding metric was requested: the ASE
+ * pair for `"ASE"`, `da300Percent`/`sdaPass` for `"sDA"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sensorId` | `string` | Sensor id |
+ * | `position` | `[number, number, number]` | World plan-space `[x, y, z]` |
+ * | `spaceId` | `string` | `ComponentHandle` id of the containing space |
+ * | `storeyId` | `string` | Storey the sensor is on |
+ * | `areaWeightM2` | `number` | Floor area this sensor represents (m²) |
+ * | `occupiedHours` | `number` | Occupied hours per the schedule |
+ * | `directSunHoursAtOrAbove1000Lux` | `number`? | ASE numerator (shades ignored per LM-83); present when ASE requested |
+ * | `aseFail` | `boolean`? | Direct-sun hours > 250 (fails ASE); present when ASE requested |
+ * | `da300Percent` | `number`? | % of occupied hours at or above 300 lux, blinds operated; present when sDA requested |
+ * | `sdaPass` | `boolean`? | `da300Percent >= 50`; present when sDA requested |
+ */
+export declare const PluginDaylightSensorRecord: z.ZodObject<{
+    sensorId: z.ZodString;
+    position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    spaceId: z.ZodString;
+    storeyId: z.ZodString;
+    areaWeightM2: z.ZodNumber;
+    occupiedHours: z.ZodNumber;
+    directSunHoursAtOrAbove1000Lux: z.ZodOptional<z.ZodNumber>;
+    aseFail: z.ZodOptional<z.ZodBoolean>;
+    da300Percent: z.ZodOptional<z.ZodNumber>;
+    sdaPass: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginDaylightSensorRecord = z.infer<typeof PluginDaylightSensorRecord>;
+/**
+ * Scope of a rolled-up aggregate.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"project"` | Whole project (aggregate `id` is `null`) |
+ * | `"storey"` | One storey (`id` = storey id) |
+ * | `"space"` | One space (`id` = space `ComponentHandle` id) |
+ */
+export declare const PluginDaylightAggregateScope: z.ZodEnum<{
+    storey: "storey";
+    space: "space";
+    project: "project";
+}>;
+export type PluginDaylightAggregateScope = z.infer<typeof PluginDaylightAggregateScope>;
+/**
+ * An area-weighted rollup for a scope. Metric fields are present when the
+ * corresponding metric was requested.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | {@linkcode PluginDaylightAggregateScope} | `"project"` \| `"storey"` \| `"space"` |
+ * | `id` | `string \| null` | Scope id; `null` for project scope |
+ * | `analysisAreaM2` | `number` | Analysed floor area (m²) |
+ * | `asePercent` | `number`? | Area-weighted % of the analysis area failing ASE; present when ASE requested |
+ * | `sdaPercent` | `number`? | Area-weighted % of the analysis area passing sDA300/50%; present when sDA requested |
+ */
+export declare const PluginDaylightAggregate: z.ZodObject<{
+    scope: z.ZodEnum<{
+        storey: "storey";
+        space: "space";
+        project: "project";
+    }>;
+    id: z.ZodNullable<z.ZodString>;
+    analysisAreaM2: z.ZodNumber;
+    asePercent: z.ZodOptional<z.ZodNumber>;
+    sdaPercent: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginDaylightAggregate = z.infer<typeof PluginDaylightAggregate>;
+/**
+ * Full provenance echo of a daylight run — a **loose** record: the known keys
+ * below are typed (all optional), and any additional backend-supplied keys pass
+ * through unmodified. `weather` is the resolved {@linkcode PluginWeatherSourceMeta}
+ * (or `null`); `surfaceReflectances` maps material/family-default key →
+ * reflectance so callers can tell per-material values from defaults.
+ */
+export declare const PluginDaylightProvenance: z.ZodObject<{
+    engine: z.ZodOptional<z.ZodString>;
+    engineVersion: z.ZodOptional<z.ZodString>;
+    standardProfile: z.ZodOptional<z.ZodString>;
+    thresholds: z.ZodOptional<z.ZodObject<{
+        aseLux: z.ZodNumber;
+        aseHours: z.ZodNumber;
+    }, z.core.$loose>>;
+    weather: z.ZodOptional<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>>>;
+    occupancySchedule: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        hoursPerYear: z.ZodNumber;
+    }, z.core.$loose>>;
+    grid: z.ZodOptional<z.ZodObject<{
+        spacingM: z.ZodNumber;
+        workplaneHeightM: z.ZodNumber;
+        boundaryOffsetM: z.ZodNumber;
+    }, z.core.$strip>>;
+    location: z.ZodOptional<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        timezone: z.ZodString;
+        trueNorthDeg: z.ZodNumber;
+    }, z.core.$loose>>;
+    surfaceReflectances: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    modelRevision: z.ZodOptional<z.ZodString>;
+    inputHash: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludedSpaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        spaceId: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    failedGeometry: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        componentId: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$loose>;
+export type PluginDaylightProvenance = z.infer<typeof PluginDaylightProvenance>;
+/**
+ * Result of {@linkcode PluginAnalysisDaylightApi.compute} and
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginDaylightRunStatus} | `"complete"` on synchronous (ASE-only) runs; `"running"` then `"complete"`/`"failed"` on sDA runs |
+ * | `runId` | `string`? | Run id for {@linkcode PluginAnalysisDaylightApi.poll}; present on asynchronous (sDA) runs |
+ * | `sensors` | {@linkcode PluginDaylightSensorRecord}`[]` | Per-sensor records (paged; empty while `"running"`) |
+ * | `aggregates` | {@linkcode PluginDaylightAggregate}`[]` | Scope rollups (all scopes, not paged; empty while `"running"`) |
+ * | `provenance` | {@linkcode PluginDaylightProvenance} | Full run provenance echo |
+ * | `nextCursor` | `string \| null` | Next sensor page cursor; `null` = last page |
+ */
+export declare const PluginDaylightResults: z.ZodObject<{
+    status: z.ZodEnum<{
+        complete: "complete";
+        failed: "failed";
+        running: "running";
+        cancelled: "cancelled";
+    }>;
+    runId: z.ZodOptional<z.ZodString>;
+    sensors: z.ZodArray<z.ZodObject<{
+        sensorId: z.ZodString;
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        spaceId: z.ZodString;
+        storeyId: z.ZodString;
+        areaWeightM2: z.ZodNumber;
+        occupiedHours: z.ZodNumber;
+        directSunHoursAtOrAbove1000Lux: z.ZodOptional<z.ZodNumber>;
+        aseFail: z.ZodOptional<z.ZodBoolean>;
+        da300Percent: z.ZodOptional<z.ZodNumber>;
+        sdaPass: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    aggregates: z.ZodArray<z.ZodObject<{
+        scope: z.ZodEnum<{
+            storey: "storey";
+            space: "space";
+            project: "project";
+        }>;
+        id: z.ZodNullable<z.ZodString>;
+        analysisAreaM2: z.ZodNumber;
+        asePercent: z.ZodOptional<z.ZodNumber>;
+        sdaPercent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    provenance: z.ZodObject<{
+        engine: z.ZodOptional<z.ZodString>;
+        engineVersion: z.ZodOptional<z.ZodString>;
+        standardProfile: z.ZodOptional<z.ZodString>;
+        thresholds: z.ZodOptional<z.ZodObject<{
+            aseLux: z.ZodNumber;
+            aseHours: z.ZodNumber;
+        }, z.core.$loose>>;
+        weather: z.ZodOptional<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>>>;
+        occupancySchedule: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            hoursPerYear: z.ZodNumber;
+        }, z.core.$loose>>;
+        grid: z.ZodOptional<z.ZodObject<{
+            spacingM: z.ZodNumber;
+            workplaneHeightM: z.ZodNumber;
+            boundaryOffsetM: z.ZodNumber;
+        }, z.core.$strip>>;
+        location: z.ZodOptional<z.ZodObject<{
+            latitude: z.ZodNumber;
+            longitude: z.ZodNumber;
+            timezone: z.ZodString;
+            trueNorthDeg: z.ZodNumber;
+        }, z.core.$loose>>;
+        surfaceReflectances: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        modelRevision: z.ZodOptional<z.ZodString>;
+        inputHash: z.ZodOptional<z.ZodString>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludedSpaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            spaceId: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>>;
+        failedGeometry: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            componentId: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$loose>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type PluginDaylightResults = z.infer<typeof PluginDaylightResults>;
+//# sourceMappingURL=daylight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daylight.d.ts","sourceRoot":"","sources":["../../../src/api/analysis/daylight.ts"],"names":[],"mappings":"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"}