@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/program/layout.ts

@@ -19,10 +19,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`.
  */
@@ -35,9 +46,16 @@ export 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.
@@ -53,11 +71,14 @@ export 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
@@ -98,6 +119,8 @@ export 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
@@ -118,6 +141,92 @@ export abstract class PluginProgramLayoutApi {
     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
+   * }
+   * ```
+   */
+  public 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(", ")}`)
+   * ```
+   */
+  public abstract stack(): PluginApiReturn<PluginProgramLayoutStackResult>
+
   /**
    * Get the state of the layout run.
    *
@@ -130,6 +239,10 @@ export 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
@@ -150,11 +263,13 @@ export 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
@@ -180,11 +295,13 @@ export 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 const PluginProgramLayoutRunArgs = z.object({
   spaceIds: z.array(z.string()).optional(),
   departmentIds: z.array(z.string()).optional(),
   envelopeId: z.string().optional(),
+  autoCommit: z.boolean().optional(),
 })
 export type PluginProgramLayoutRunArgs = z.infer<
   typeof PluginProgramLayoutRunArgs
@@ -217,11 +334,13 @@ export type PluginProgramLayoutRunResult = z.infer<
  * | `"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 const PluginProgramLayoutJobStatus = z.enum([
   "running",
   "active",
   "inactive",
+  "pendingReview",
 ])
 export type PluginProgramLayoutJobStatus = z.infer<
   typeof PluginProgramLayoutJobStatus
@@ -232,10 +351,12 @@ export type PluginProgramLayoutJobStatus = z.infer<
  *
  * | 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 const PluginProgramLayoutJobState = z.object({
   status: PluginProgramLayoutJobStatus,
+  totalSolutions: z.number().int().optional(),
 })
 export type PluginProgramLayoutJobState = z.infer<
   typeof PluginProgramLayoutJobState
@@ -250,3 +371,52 @@ export const PluginProgramLayoutStateResult =
 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 const PluginProgramLayoutApplySolutionArgs = z.object({
+  index: z.number().int().min(0),
+})
+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 const PluginProgramLayoutApplyResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+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 const PluginProgramLayoutStackResult = z.object({
+  success: z.boolean(),
+  skippedStoreys: z.array(z.number()),
+  error: z.string().optional(),
+})
+export type PluginProgramLayoutStackResult = z.infer<
+  typeof PluginProgramLayoutStackResult
+>

package/src/api/program/site.ts

@@ -6,8 +6,9 @@ import { PluginAreaUnit } from "./metrics"
  * 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.
@@ -64,7 +65,8 @@ export abstract class PluginProgramSiteApi {
   public 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
@@ -88,7 +90,7 @@ export 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.
@@ -184,16 +186,67 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public 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}`)
+   * ```
+   */
+  public 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)
+   * ```
+   */
+  public 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 const PluginSiteFootprintPoint = z.object({
   x: z.number(),
@@ -417,3 +470,48 @@ export const PluginProgramSiteNorthAngleResult = z.number().nullable()
 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 const PluginProgramSiteTimezoneResult = z.string().nullable()
+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 const PluginProgramSiteWeather = z.object({
+  weatherFileId: z.string(),
+  station: z.string(),
+  checksum: z.string(),
+  selectionMethod: z.enum([
+    "nearest-station",
+    "user-upload",
+    "project-override",
+  ]),
+})
+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 const PluginProgramSiteWeatherResult =
+  PluginProgramSiteWeather.nullable()
+export type PluginProgramSiteWeatherResult = z.infer<
+  typeof PluginProgramSiteWeatherResult
+>