@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/analysis/shadows.ts

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