@snaptrude/plugin-core 0.7.1 → 0.9.0

package/dist/api/program/layout.d.ts

@@ -18,10 +18,21 @@ import { PluginApiReturn } from "../../types";
  *    longer `"running"` — a run can take up to 20 minutes.
  * 3. {@linkcode PluginProgramLayoutApi.cancel} aborts an in-flight run.
  *
- * `arrange` produces several candidate layouts and **auto-commits the first
- * solution** as one undoable edit (there is no interactive solution-review
- * over the plugin boundary); `pack` re-shapes and applies its single result
- * directly. Both are **Pro-plan-gated**, matching the product UI.
+ * `arrange` produces several candidate layouts. By default it **auto-commits
+ * the first solution** as one undoable edit; pass `autoCommit: false` to hold
+ * the candidates for review instead — `getState` then reports
+ * `status: "pendingReview"` with `totalSolutions`, and
+ * {@linkcode PluginProgramLayoutApi.applySolution} commits the one you pick
+ * (the headless counterpart of the product's "Solution N of M → Apply" bar).
+ * `pack` re-shapes and applies its single result directly. Both are
+ * **Pro-plan-gated**, matching the product UI.
+ *
+ * {@linkcode PluginProgramLayoutApi.stack} is the **cross-storey** action —
+ * the product's *Pack in envelope* / auto-stack. It splits the building
+ * envelope by storey and packs each storey's departments into its slice as one
+ * undoable edit. Unlike `arrange` / `pack`, it is **not** the async-job model:
+ * it resolves inline when the whole multi-storey pack is done (no `getState`
+ * polling) and returns the storeys it had to skip. It is Pro-gated too.
  *
  * Accessed via `snaptrude.program.layout`.
  */
@@ -33,9 +44,16 @@ export declare abstract class PluginProgramLayoutApi {
      * Starts the backend job and **returns immediately** — poll
      * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
      * `"running"` (a run can take up to 20 minutes). The solver produces
-     * several candidate layouts; this **auto-commits the first solution** as one
-     * undoable edit (no interactive review over the plugin boundary). Starting a
-     * run while one is in flight replaces it.
+     * several candidate layouts; by default this **auto-commits the first
+     * solution** as one undoable edit. Pass `autoCommit: false` to review them
+     * instead: the run finishes with `status: "pendingReview"` and
+     * `totalSolutions` in `getState`, and
+     * {@linkcode PluginProgramLayoutApi.applySolution} commits the candidate you
+     * pick ({@linkcode PluginProgramLayoutApi.cancel} discards them). An
+     * arrange **without an envelope** applies directly (there is nothing to
+     * review) regardless of `autoCommit`. Starting a run while one is in flight
+     * replaces it; while solutions are pending review, new runs are refused —
+     * apply or cancel first.
      *
      * With no `options`, operates on the eligible Room/Department masses on the
      * active storey and auto-detects the single buildable envelope there.
@@ -51,11 +69,14 @@ export declare abstract class PluginProgramLayoutApi {
      * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
      * @throws When more than one envelope is on the active storey and none was
      *   given (ambiguous).
+     * @throws When arrange solutions are pending review (apply or cancel them
+     *   first).
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Arrange the rooms in the envelope
      * @examplePrompt Lay out the departments inside the building envelope
      * @examplePrompt Auto-arrange the program spaces
+     * @examplePrompt Arrange the rooms but let me pick the solution
      *
      * # Example
      * ```ts
@@ -93,6 +114,8 @@ export declare abstract class PluginProgramLayoutApi {
      * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
      * @throws When more than one envelope is on the active storey and none was
      *   given (ambiguous).
+     * @throws When arrange solutions are pending review (apply or cancel them
+     *   first).
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Pack the rooms into the envelope
@@ -110,6 +133,88 @@ export declare abstract class PluginProgramLayoutApi {
      * ```
      */
     abstract pack(options?: PluginProgramLayoutRunArgs): PluginApiReturn<PluginProgramLayoutRunResult>;
+    /**
+     * Apply one of the pending arrange solutions.
+     *
+     * The headless counterpart of the product's **"Solution N of M → Apply"**
+     * review bar: after an {@linkcode PluginProgramLayoutApi.arrange} run
+     * started with `autoCommit: false` finishes with `status: "pendingReview"`,
+     * this commits the candidate at `index` (0-based,
+     * `0 ≤ index < totalSolutions` from
+     * {@linkcode PluginProgramLayoutApi.getState}) as **one undoable edit** and
+     * discards the other candidates. `getState` then reports
+     * `status: "active"`.
+     *
+     * @param index - 0-based index of the pending solution to apply.
+     * @returns A {@linkcode PluginProgramLayoutApplyResult} —
+     *   `{ success: true }` when the solution was applied.
+     * @throws When no arrange solutions are pending review (no
+     *   `arrange({ autoCommit: false })` run has finished, or its solutions were
+     *   already applied / cancelled).
+     * @throws When `index` is out of range for the pending solutions.
+     * @throws When plugin writes are disabled.
+     *
+     * @examplePrompt Apply the second arrange solution
+     * @examplePrompt Pick layout solution 3 and commit it
+     * @examplePrompt Apply the arrange solution I chose
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.layout.arrange({ autoCommit: false })
+     * let job = await snaptrude.program.layout.getState()
+     * while (job?.status === "running") {
+     *   await new Promise((r) => setTimeout(r, 5000))
+     *   job = await snaptrude.program.layout.getState()
+     * }
+     * if (job?.status === "pendingReview") {
+     *   console.log(`${job.totalSolutions} candidate layouts`)
+     *   await snaptrude.program.layout.applySolution(1) // commit the second one
+     * }
+     * ```
+     */
+    abstract applySolution(index: number): PluginApiReturn<PluginProgramLayoutApplyResult>;
+    /**
+     * Stack the program across **every storey** of the building — the product's
+     * *Pack in envelope* / auto-stack.
+     *
+     * Splits the building envelope massing into per-storey envelope slices, then
+     * packs each storey's departments into its slice, applying the whole
+     * multi-storey result as **one undoable edit**.
+     *
+     * Unlike {@linkcode PluginProgramLayoutApi.arrange} /
+     * {@linkcode PluginProgramLayoutApi.pack}, this **is not** the async-job
+     * model: `await` it and it resolves when the stack is done — there is no
+     * `getState` polling. It operates on the whole active model (no id / envelope
+     * arguments): it auto-discovers the departments and envelope on each storey.
+     *
+     * Storeys that have departments but **no envelope** are reported in
+     * `skippedStoreys` (nothing was packed there). A storey's departments must
+     * already be on that storey — `stack` does not move departments between
+     * floors, it lays out each floor's program into that floor's envelope.
+     *
+     * @returns A {@linkcode PluginProgramLayoutStackResult} — `success: true`
+     *   with the (possibly empty) `skippedStoreys` when the stack was applied, or
+     *   `success: false` with an `error` when the run failed (e.g. the adjacency
+     *   service was unreachable).
+     * @throws When the project is not on a Pro plan.
+     * @throws When plugin writes are disabled.
+     * @throws When an `arrange` / `pack` run, or another `stack`, is already in
+     *   flight, or arrange solutions are pending review (finish, apply, or
+     *   `cancel` first).
+     *
+     * @examplePrompt Stack the program across all floors
+     * @examplePrompt Auto-stack the departments into the envelope on every storey
+     * @examplePrompt Pack the whole building's program into its envelope
+     *
+     * # Example
+     * ```ts
+     * const { success, skippedStoreys, error } = await snaptrude.program.layout.stack()
+     * if (!success) throw new Error(error)
+     * if (skippedStoreys.length)
+     *   console.warn(`No envelope on storeys: ${skippedStoreys.join(", ")}`)
+     * ```
+     */
+    abstract stack(): PluginApiReturn<PluginProgramLayoutStackResult>;
     /**
      * Get the state of the layout run.
      *
@@ -122,6 +227,10 @@ export declare abstract class PluginProgramLayoutApi {
      * | `"running"` | A run is in flight — keep polling |
      * | `"active"` | The run finished and its layout is applied to the model |
      * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+     * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidates await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
+     *
+     * While `status` is `"pendingReview"` the state also carries
+     * `totalSolutions` — the number of candidate layouts to pick from.
      *
      * @returns A {@linkcode PluginProgramLayoutStateResult} with the run
      *   `status`, or `null` when no run result is available (never ran or was
@@ -141,11 +250,13 @@ export declare abstract class PluginProgramLayoutApi {
     /**
      * Cancel the in-flight layout run.
      *
-     * Aborts the backend job and discards any pending solution. A no-op
-     * (returns `false`) when nothing is running.
+     * Aborts the backend job and discards any pending solution. Also discards
+     * a finished run's **pending-review** solutions (after
+     * `arrange({ autoCommit: false })`) without applying one. A no-op (returns
+     * `false`) when nothing is running and nothing is pending.
      *
-     * @returns `true` when a run was cancelled, `false` when nothing was
-     *   running.
+     * @returns `true` when a run was cancelled or pending solutions were
+     *   discarded, `false` when there was nothing to cancel.
      * @throws When plugin writes are disabled.
      *
      * @examplePrompt Cancel the arrange
@@ -170,11 +281,13 @@ export declare abstract class PluginProgramLayoutApi {
  * | `spaceIds` | `string[] \| undefined` | Component ids of the Room masses to lay out |
  * | `departmentIds` | `string[] \| undefined` | Component ids of the Department masses to lay out |
  * | `envelopeId` | `string \| undefined` | The envelope to fit into — a mass component id or a buildable-envelope handle (`be_…`); omit to auto-detect the single envelope on the active storey |
+ * | `autoCommit` | `boolean \| undefined` | `arrange` only — `true` / omitted (default) auto-commits the first candidate solution; `false` holds the candidates for review via {@linkcode PluginProgramLayoutApi.applySolution}. Ignored by `pack` (it applies its single result directly) |
  */
 export declare const PluginProgramLayoutRunArgs: z.ZodObject<{
     spaceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     departmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     envelopeId: z.ZodOptional<z.ZodString>;
+    autoCommit: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type PluginProgramLayoutRunArgs = z.infer<typeof PluginProgramLayoutRunArgs>;
 /**
@@ -201,11 +314,13 @@ export type PluginProgramLayoutRunResult = z.infer<typeof PluginProgramLayoutRun
  * | `"running"` | A run is in flight — keep polling |
  * | `"active"` | The run finished and its layout is applied to the model |
  * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
+ * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidate solutions await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
  */
 export declare const PluginProgramLayoutJobStatus: z.ZodEnum<{
     running: "running";
     active: "active";
     inactive: "inactive";
+    pendingReview: "pendingReview";
 }>;
 export type PluginProgramLayoutJobStatus = z.infer<typeof PluginProgramLayoutJobStatus>;
 /**
@@ -213,14 +328,17 @@ export type PluginProgramLayoutJobStatus = z.infer<typeof PluginProgramLayoutJob
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` |
+ * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` \| `"pendingReview"` |
+ * | `totalSolutions` | `number \| undefined` | Number of candidate solutions awaiting review — present only while `status` is `"pendingReview"` |
  */
 export declare const PluginProgramLayoutJobState: z.ZodObject<{
     status: z.ZodEnum<{
         running: "running";
         active: "active";
         inactive: "inactive";
+        pendingReview: "pendingReview";
     }>;
+    totalSolutions: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginProgramLayoutJobState = z.infer<typeof PluginProgramLayoutJobState>;
 /**
@@ -232,7 +350,49 @@ export declare const PluginProgramLayoutStateResult: z.ZodNullable<z.ZodObject<{
         running: "running";
         active: "active";
         inactive: "inactive";
+        pendingReview: "pendingReview";
     }>;
+    totalSolutions: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>>;
 export type PluginProgramLayoutStateResult = z.infer<typeof PluginProgramLayoutStateResult>;
+/**
+ * Arguments for {@linkcode PluginProgramLayoutApi.applySolution}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `index` | `number` | 0-based index of the pending solution to apply (`0 ≤ index < totalSolutions`) |
+ */
+export declare const PluginProgramLayoutApplySolutionArgs: z.ZodObject<{
+    index: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramLayoutApplySolutionArgs = z.infer<typeof PluginProgramLayoutApplySolutionArgs>;
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.applySolution}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the chosen solution was applied |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export declare const PluginProgramLayoutApplyResult: z.ZodObject<{
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramLayoutApplyResult = z.infer<typeof PluginProgramLayoutApplyResult>;
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.stack} — reports whether the
+ * cross-storey stack was applied and which storeys were skipped.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the stack was applied |
+ * | `skippedStoreys` | `number[]` | Storey values that had departments but no envelope, so nothing was packed there |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export declare const PluginProgramLayoutStackResult: z.ZodObject<{
+    success: z.ZodBoolean;
+    skippedStoreys: z.ZodArray<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramLayoutStackResult = z.infer<typeof PluginProgramLayoutStackResult>;
 //# sourceMappingURL=layout.d.ts.map

package/dist/api/program/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;aACa,OAAO,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;aACa,IAAI,CAClB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;aACa,QAAQ,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAE3E;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;iBAIrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;;EAIvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAEtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;kBACH,CAAA;AACxC,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;aACa,OAAO,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;aACa,IAAI,CAClB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;aACa,aAAa,CAC3B,KAAK,EAAE,MAAM,GACZ,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;aACa,KAAK,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;aACa,QAAQ,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAE3E;;;;;;;;;;;;;;;;;;;;OAoBG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;CACnD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;;EAKvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;iBAGtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;kBACH,CAAA;AACxC,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;iBAE/C,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B;;;iBAGzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;;;;iBAIzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}

package/dist/api/program/site.d.ts

@@ -4,8 +4,9 @@ import { PluginApiReturn } from "../../types";
  * Program site — read the planning context of the project's site/plot.
  *
  * The **site** is the set of plot/parcel footprints the program is planned
- * against: their total area, per-parcel footprints (in scene XZ coordinates),
- * and — when the project is geo-located on terrain — their geographic
+ * against: their total area, per-parcel footprints (world XZ plan coordinates
+ * in Snaptrude units — the same plan space as a space's `planPoints`), and —
+ * when the project is geo-located on terrain — their geographic
  * (latitude/longitude) rings. This is the program-planning view of the site;
  * zoning numbers (setbacks, FAR/FSI, height limits) live in the site-analysis
  * sheet and are not read here.
@@ -59,7 +60,8 @@ export declare abstract class PluginProgramSiteApi {
      */
     abstract getArea(): PluginApiReturn<PluginProgramSiteAreaResult>;
     /**
-     * List the site parcels with their footprints (in scene coordinates).
+     * List the site parcels with their footprints (world XZ plan coordinates,
+     * Snaptrude units).
      *
      * @returns A {@linkcode PluginProgramSiteListPolygonsResult} with each parcel's
      *   id, area, label, and 2D footprint (XZ ground-plane points). Empty when the
@@ -82,7 +84,7 @@ export declare abstract class PluginProgramSiteApi {
      *
      * Only available when the project is geo-located on terrain; returns `[]` (no
      * rings) otherwise. Use {@linkcode PluginProgramSiteApi.listPolygons} for the
-     * scene-coordinate footprints that are always available.
+     * world-coordinate footprints that are always available.
      *
      * @returns A {@linkcode PluginProgramSiteListGeoPolygonsResult} with one ring
      *   of `{ lat, lng, alt }` points per parcel.
@@ -175,15 +177,64 @@ export declare abstract class PluginProgramSiteApi {
      * ```
      */
     abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>;
+    /**
+     * Get the IANA timezone of the project's geographic location.
+     *
+     * The timezone identifier (e.g. `"America/New_York"`, `"Asia/Kolkata"`)
+     * looked up from the same geo-location
+     * {@linkcode PluginProgramSiteApi.getLocation} returns. Returns `null` when
+     * the project is not geo-located on terrain.
+     *
+     * @returns A {@linkcode PluginProgramSiteTimezoneResult} — the IANA timezone
+     *   id string, or `null` when the project has no geo-located site.
+     *
+     * @examplePrompt What timezone is this project in?
+     * @examplePrompt Get the site's IANA timezone
+     * @examplePrompt What's the local time zone at the project location?
+     * @examplePrompt Which timezone should I use for the sun study schedule?
+     *
+     * # Example
+     * ```ts
+     * const timezone = await snaptrude.program.site.getTimezone()
+     * if (timezone) console.log(`Project timezone: ${timezone}`)
+     * ```
+     */
+    abstract getTimezone(): PluginApiReturn<PluginProgramSiteTimezoneResult>;
+    /**
+     * Get the weather file resolved for the project site.
+     *
+     * A lightweight read of the EPW weather file the `analysis.*` sun and
+     * daylight studies compute against — its catalog id, station name, content
+     * checksum, and how it was selected. This is the same file (same
+     * `weatherFileId`) that {@linkcode PluginAnalysisWeatherApi.getSeries} reads
+     * rows from and that a daylight run echoes in its provenance. Returns `null`
+     * when the project has no geo-located site (no weather file to resolve).
+     *
+     * @returns A {@linkcode PluginProgramSiteWeatherResult} —
+     *   `{ weatherFileId, station, checksum, selectionMethod }`, or `null` when
+     *   the project has no geo-located site.
+     *
+     * @examplePrompt Which weather file is my project using?
+     * @examplePrompt What EPW station was resolved for this site?
+     * @examplePrompt Get the weather file id for the daylight analysis
+     *
+     * # Example
+     * ```ts
+     * const weather = await snaptrude.program.site.getWeather()
+     * if (weather) console.log(weather.station, weather.selectionMethod)
+     * ```
+     */
+    abstract getWeather(): PluginApiReturn<PluginProgramSiteWeatherResult>;
 }
 /**
- * A 2D ground-plane point of a site parcel footprint, in scene coordinates
- * (metres on the project's XZ plane).
+ * A 2D ground-plane point of a site parcel footprint, in world XZ plan
+ * coordinates (Snaptrude units) — the same plan space as a space's
+ * `planPoints`, so site parcels overlay space footprints directly.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `x` | `number` | X coordinate (scene metres) |
- * | `z` | `number` | Z coordinate (scene metres) |
+ * | `x` | `number` | X coordinate (world, Snaptrude units) |
+ * | `z` | `number` | Z coordinate (world, Snaptrude units) |
  */
 export declare const PluginSiteFootprintPoint: z.ZodObject<{
     x: z.ZodNumber;
@@ -448,4 +499,50 @@ export type PluginProgramSiteLocationResult = z.infer<typeof PluginProgramSiteLo
  */
 export declare const PluginProgramSiteNorthAngleResult: z.ZodNullable<z.ZodNumber>;
 export type PluginProgramSiteNorthAngleResult = z.infer<typeof PluginProgramSiteNorthAngleResult>;
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getTimezone} — the IANA timezone
+ * id of the project's geo-location (e.g. `"Europe/London"`), or `null` when
+ * the project is not geo-located.
+ */
+export declare const PluginProgramSiteTimezoneResult: z.ZodNullable<z.ZodString>;
+export type PluginProgramSiteTimezoneResult = z.infer<typeof PluginProgramSiteTimezoneResult>;
+/**
+ * A summary of the weather file resolved for the project site. Matches the
+ * relevant fields of `analysis.weather`'s `PluginWeatherSourceMeta`;
+ * `selectionMethod` is one of `"nearest-station"`, `"user-upload"`, or
+ * `"project-override"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `core.io.import.epw`) |
+ * | `station` | `string` | Station/file name |
+ * | `checksum` | `string` | sha256 of the EPW file |
+ * | `selectionMethod` | `"nearest-station" \| "user-upload" \| "project-override"` | How the file was matched |
+ */
+export declare const PluginProgramSiteWeather: z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramSiteWeather = z.infer<typeof PluginProgramSiteWeather>;
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getWeather} — the resolved weather
+ * file summary, or `null` when the project has no geo-located site.
+ */
+export declare const PluginProgramSiteWeatherResult: z.ZodNullable<z.ZodObject<{
+    weatherFileId: z.ZodString;
+    station: z.ZodString;
+    checksum: z.ZodString;
+    selectionMethod: z.ZodEnum<{
+        "nearest-station": "nearest-station";
+        "user-upload": "user-upload";
+        "project-override": "project-override";
+    }>;
+}, z.core.$strip>>;
+export type PluginProgramSiteWeatherResult = z.infer<typeof PluginProgramSiteWeatherResult>;
 //# sourceMappingURL=site.d.ts.map

package/dist/api/program/site.d.ts.map

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