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

package/src/api/program/layout.ts

@@ -9,8 +9,31 @@ import { PluginApiReturn } from "../../types"
  * three of the space-planning workflow that starts with
  * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
  *
- * _(Authored ahead — both methods are optional until the host lands them in
- * the next increment, and are kept out of the discovery manifest until then.)_
+ * Both {@linkcode PluginProgramLayoutApi.arrange} and
+ * {@linkcode PluginProgramLayoutApi.pack} run as an **asynchronous backend
+ * job** on the space-solver service:
+ *
+ * 1. `arrange` / `pack` start the job and **return immediately** — they do
+ *    not wait for the layout.
+ * 2. Poll {@linkcode PluginProgramLayoutApi.getState} until `status` is no
+ *    longer `"running"` — a run can take up to 20 minutes.
+ * 3. {@linkcode PluginProgramLayoutApi.cancel} aborts an in-flight run.
+ *
+ * `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`.
  */
@@ -19,23 +42,86 @@ export abstract class PluginProgramLayoutApi {
 
   /**
    * Arrange the spaces inside the envelope using the computed adjacency data.
-   * _(Authored ahead — optional until the host lands.)_
+   *
+   * 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; 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.
+   *
+   * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — the
+   *   space / department masses to arrange and the envelope to fit them in.
+   *   Omitted fields fall back to the active-storey defaults.
+   * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
+   *   when the job was started. Solver failures surface through
+   *   {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`), not
+   *   as a rejected call.
+   * @throws When the project is not on a Pro plan.
+   * @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
    * const { success, error } = await snaptrude.program.layout.arrange()
-   * if (!success) console.log("Arrange failed:", error)
+   * if (!success) throw new Error(error)
+   * // poll until the layout is applied
+   * let job = await snaptrude.program.layout.getState()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.program.layout.getState()
+   * }
    * ```
    */
-  public arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+  public abstract arrange(
+    options?: PluginProgramLayoutRunArgs,
+  ): PluginApiReturn<PluginProgramLayoutRunResult>
 
   /**
    * Pack the spaces into the envelope (a tighter fit than arrange).
-   * _(Authored ahead — optional until the host lands.)_
+   *
+   * Like {@linkcode PluginProgramLayoutApi.arrange}, this starts the backend
+   * job and **returns immediately** — poll
+   * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
+   * `"running"` (up to 20 minutes). Pack re-shapes mass geometry to fit and
+   * **applies its single result directly** (no solution review). Starting a
+   * run while one is in flight replaces it.
+   *
+   * With no `options`, operates on the eligible Room/Department masses on the
+   * active storey and auto-detects the single buildable envelope there.
+   *
+   * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — same
+   *   shape as `arrange`; omitted fields fall back to the active-storey
+   *   defaults.
+   * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
+   *   when the job was started. Solver failures surface through
+   *   {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`).
+   * @throws When the project is not on a Pro plan.
+   * @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
    * @examplePrompt Fit the program spaces tightly into the building
@@ -43,20 +129,193 @@ export abstract class PluginProgramLayoutApi {
    *
    * # Example
    * ```ts
-   * const { success, error } = await snaptrude.program.layout.pack()
-   * if (!success) console.log("Pack failed:", error)
+   * const { success } = await snaptrude.program.layout.pack({ envelopeId: "be_..." })
+   * let job = await snaptrude.program.layout.getState()
+   * while (job?.status === "running") {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   job = await snaptrude.program.layout.getState()
+   * }
+   * ```
+   */
+  public 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
+   * }
+   * ```
+   */
+  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 pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+  public abstract stack(): PluginApiReturn<PluginProgramLayoutStackResult>
+
+  /**
+   * Get the state of the layout run.
+   *
+   * The polling read for the async job started by
+   * {@linkcode PluginProgramLayoutApi.arrange} /
+   * {@linkcode PluginProgramLayoutApi.pack}. `status` values:
+   *
+   * | Status | Meaning |
+   * |---|---|
+   * | `"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
+   *   cancelled).
+   *
+   * @examplePrompt Is the arrange done?
+   * @examplePrompt Check the status of the layout run
+   * @examplePrompt Did the pack finish?
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.program.layout.getState()
+   * if (job?.status === "active") console.log("layout applied")
+   * ```
+   */
+  public abstract getState(): PluginApiReturn<PluginProgramLayoutStateResult>
+
+  /**
+   * Cancel the in-flight layout run.
+   *
+   * 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 or pending solutions were
+   *   discarded, `false` when there was nothing to cancel.
+   * @throws When plugin writes are disabled.
+   *
+   * @examplePrompt Cancel the arrange
+   * @examplePrompt Stop the running layout job
+   * @examplePrompt Abort the pack in envelope
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.layout.cancel()
+   * ```
+   */
+  public abstract cancel(): PluginApiReturn<boolean>
 }
 
+/**
+ * Arguments for {@linkcode PluginProgramLayoutApi.arrange} /
+ * {@linkcode PluginProgramLayoutApi.pack}. All fields are optional — omitted
+ * fields fall back to the eligible masses and the single envelope on the
+ * active storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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
+>
+
 /**
  * Result of {@linkcode PluginProgramLayoutApi.arrange} /
- * {@linkcode PluginProgramLayoutApi.pack}.
+ * {@linkcode PluginProgramLayoutApi.pack} — reports whether the run was
+ * **started**, not whether the layout finished (poll
+ * {@linkcode PluginProgramLayoutApi.getState} for completion).
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `success` | `boolean` | Whether the layout run completed |
+ * | `success` | `boolean` | Whether the layout run was started |
  * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
  */
 export const PluginProgramLayoutRunResult = z.object({
@@ -66,3 +325,98 @@ export const PluginProgramLayoutRunResult = z.object({
 export type PluginProgramLayoutRunResult = z.infer<
   typeof PluginProgramLayoutRunResult
 >
+
+/**
+ * The status of a layout run.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"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
+>
+
+/**
+ * The state of a layout run.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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
+>
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.getState} — the run state, or
+ * `null` when no run result is available (never ran or was cancelled).
+ */
+export const PluginProgramLayoutStateResult =
+  PluginProgramLayoutJobState.nullable()
+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
+>