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

package/src/api/core/proposals/index.ts

@@ -0,0 +1,569 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+
+/**
+ * Proposals — read and edit the project's design options ("proposals").
+ *
+ * A **proposal** is a design option: one of several variants of the same
+ * project. Each proposal owns a set of buckets (a bucket == a drawing layer),
+ * and switching the active proposal shows/hides the buckets it owns. Proposals
+ * are **infrastructure**, not design — they own the buckets/layers geometry
+ * lives in — so they sit under `core`, not `design` (constitution §2A).
+ *
+ * Reads return plain records and never throw for a missing proposal (`get` and
+ * `getActive` return `null`, `list` / `listForComponent` return an empty list,
+ * `isActive` returns `false`). Ids are stable public strings.
+ *
+ * On legacy / no-proposal projects the scoping predicates degrade gracefully:
+ * `getActive` returns `null` and the reads return empty.
+ *
+ * Proposal writes are **not undoable** — create / rename / setActive / delete
+ * persist directly and bypass the undo stack; a `core.history.undo` will not
+ * reverse them. Each proposal keeps its own isolated undo stack for the
+ * geometry edits made inside it.
+ *
+ * Accessed via `snaptrude.core.proposals`.
+ */
+export abstract class PluginCoreProposalsApi {
+  constructor() {}
+
+  /**
+   * List the design options (proposals) in the active project.
+   *
+   * @returns A {@linkcode PluginCoreProposalsListResult} with a `proposals`
+   *   array (empty on a legacy / no-proposal project).
+   *
+   * @examplePrompt List all the design options in this project
+   * @examplePrompt How many proposals does this project have?
+   * @examplePrompt Show every design variant with its name
+   *
+   * # Example
+   * ```ts
+   * const { proposals } = await snaptrude.core.proposals.list()
+   * for (const p of proposals) console.log(p.id, p.name, p.isActive)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreProposalsListResult>
+
+  /**
+   * Get a single proposal by id.
+   *
+   * @param proposalId - The id of the proposal to read.
+   * @returns The matching {@linkcode PluginCoreProposalRef}, or `null` if no
+   *   proposal has that id.
+   *
+   * @examplePrompt Get the proposal with id prop_1
+   * @examplePrompt Look up a single design option by its id
+   * @examplePrompt Which buckets belong to proposal prop_2?
+   *
+   * # Example
+   * ```ts
+   * const proposal = await snaptrude.core.proposals.get("prop_1")
+   * if (proposal) console.log(proposal.name, proposal.bucketIds)
+   * ```
+   */
+  public abstract get(
+    proposalId: string,
+  ): PluginApiReturn<PluginCoreProposalsGetResult>
+
+  /**
+   * Get the active proposal.
+   *
+   * The active proposal is the design option currently shown and edited.
+   * Honors a present-mode capture override: while a present-mode capture is in
+   * flight this returns the captured proposal, not the redux-active one. Paired
+   * with {@linkcode PluginCoreProposalsApi.setActive}.
+   *
+   * @returns The active {@linkcode PluginCoreProposalRef}, or `null` on a legacy
+   *   / no-proposal project where nothing is active.
+   *
+   * @examplePrompt Which design option is active?
+   * @examplePrompt Get the current proposal
+   * @examplePrompt What proposal am I working in?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.proposals.getActive()
+   * if (active) console.log(active.id, active.name)
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginCoreProposalsGetActiveResult>
+
+  /**
+   * List the proposals a component belongs to.
+   *
+   * Returns **every** proposal whose buckets include the component — a bucket
+   * can be shared across proposals, so a component may appear in more than one.
+   *
+   * @param component - The component to look up.
+   * @returns A {@linkcode PluginCoreProposalsListForComponentResult} with a
+   *   `proposals` array (empty when the component is out of scope or the project
+   *   has no proposals).
+   *
+   * @examplePrompt Which design options is this component part of?
+   * @examplePrompt List the proposals that contain this wall
+   * @examplePrompt Is this element shared across multiple design variants?
+   *
+   * # Example
+   * ```ts
+   * const { proposals } = await snaptrude.core.proposals.listForComponent(wall)
+   * console.log(`shared across ${proposals.length} proposals`)
+   * ```
+   */
+  public abstract listForComponent(
+    component: ComponentHandle,
+  ): PluginApiReturn<PluginCoreProposalsListForComponentResult>
+
+  /**
+   * Test whether a proposal is the active one.
+   *
+   * @param proposalId - The id of the proposal to test.
+   * @returns `true` if it is the active proposal, otherwise `false` (including
+   *   when no proposal has that id).
+   *
+   * @examplePrompt Is proposal prop_2 the active one?
+   * @examplePrompt Check whether this design option is currently shown
+   * @examplePrompt Am I working in proposal prop_1?
+   *
+   * # Example
+   * ```ts
+   * if (await snaptrude.core.proposals.isActive("prop_1")) {
+   *   console.log("prop_1 is active")
+   * }
+   * ```
+   */
+  public abstract isActive(proposalId: string): PluginApiReturn<boolean>
+
+  /**
+   * Create a new design option (proposal) — blank, or configured from a base
+   * proposal (the New Proposal modal's two paths).
+   *
+   * **Pro-gated** (creating proposals requires a Pro plan, matching the UI) and
+   * **not undoable**. The name is capped at 24 characters.
+   *
+   * **Blank** (no `options`) — creates a bare proposal with a single empty
+   * default bucket; it does **not** carry forward the current proposal's
+   * layers, views, or targets, and the active proposal does **not** change.
+   *
+   * **Configured** (`options.baseProposalId`) — the modal's Configure path:
+   * carries the base proposal's buckets (layers) forward per `options.layers`,
+   * where each entry names a bucket of the base proposal and an action —
+   * `"share"` (the new proposal references the same live bucket) or
+   * `"duplicate"` (an independent copy of the bucket and its contents).
+   * Buckets not listed are left behind. Omitting `layers` carries **every**
+   * base bucket forward as a `"duplicate"` (the modal's default). The base
+   * proposal's views and area targets are copied either way, and the new
+   * proposal becomes the **active** one (implicit switch — blocked with
+   * `PROPOSAL_SWITCH_BLOCKED` while an in-canvas agent run is in flight, like
+   * {@linkcode PluginCoreProposalsApi.setActive}).
+   *
+   * @param name - Display name of the new proposal (capped at 24 chars).
+   * @param options - Optional configure path: `baseProposalId` (the proposal to
+   *   carry forward from) and `layers` (per-bucket `"share"` / `"duplicate"`
+   *   actions; omitted buckets are excluded, omitted `layers` duplicates all).
+   * @returns The new proposal's id (read the full record back with
+   *   {@linkcode PluginCoreProposalsApi.get}).
+   * @throws If the caller is not on a Pro plan, the name is empty/duplicate,
+   *   `layers` is passed without `baseProposalId`, the base proposal or a
+   *   listed bucket does not exist / does not belong to the base proposal, or
+   *   (configured only) `PROPOSAL_SWITCH_BLOCKED` while a canvas-agent run is
+   *   in flight.
+   *
+   * @examplePrompt Create a design option called Scheme B
+   * @examplePrompt Add a new proposal named Option 2
+   * @examplePrompt Duplicate the current proposal as Scheme C
+   * @examplePrompt Create a design option based on Proposal 1 that shares its site layer
+   *
+   * # Example
+   * ```ts
+   * // blank design option
+   * const { id } = await snaptrude.core.proposals.create("Scheme B")
+   *
+   * // configured from the active proposal: duplicate every layer
+   * const base = await snaptrude.core.proposals.getActive()
+   * if (base) {
+   *   const { id: dup } = await snaptrude.core.proposals.create("Scheme C", {
+   *     baseProposalId: base.id,
+   *   })
+   *   // …or share one layer and leave the rest behind
+   *   const { id: shared } = await snaptrude.core.proposals.create("Scheme D", {
+   *     baseProposalId: base.id,
+   *     layers: [{ bucketId: base.defaultBucketId, action: "share" }],
+   *   })
+   * }
+   * ```
+   */
+  public abstract create(
+    name: string,
+    options?: {
+      baseProposalId: string
+      layers?: { bucketId: string; action: "share" | "duplicate" }[]
+    },
+  ): PluginApiReturn<PluginCoreProposalsCreateResult>
+
+  /**
+   * Rename a proposal.
+   *
+   * **Not undoable.** The name is capped at 24 characters.
+   *
+   * @param proposalId - The id of the proposal to rename.
+   * @param name - The new display name (capped at 24 chars).
+   * @returns The updated {@linkcode PluginCoreProposalRef}.
+   * @throws If no proposal has the given id, or the name is empty / duplicates
+   *   another proposal.
+   *
+   * @examplePrompt Rename proposal prop_1 to Final Scheme
+   * @examplePrompt Change the name of this design option
+   * @examplePrompt Call proposal prop_2 "Option A"
+   *
+   * # Example
+   * ```ts
+   * const proposal = await snaptrude.core.proposals.rename("prop_1", "Final Scheme")
+   * ```
+   */
+  public abstract rename(
+    proposalId: string,
+    name: string,
+  ): PluginApiReturn<PluginCoreProposalsRenameResult>
+
+  /**
+   * Switch the active proposal.
+   *
+   * A **heavy scene switch** and **not undoable**. Switching clears the current
+   * selection, resets AI / streaming state, cancels proposal-scoped operations,
+   * retoggles bucket visibility to the new proposal's owned set, restores its
+   * per-proposal site/FSI settings, and realigns the views panel. After the
+   * switch, **writes** are guarded to the new active proposal (edits targeting
+   * components outside it are rejected), but **list reads are NOT
+   * proposal-filtered** — `design.query.list*` and similar reads stay
+   * project-wide; filter their results via
+   * {@linkcode PluginCoreProposalsApi.listForComponent} if you need
+   * proposal-scoped sets.
+   *
+   * **Blocked while an in-canvas agent run is in flight** — throws
+   * `PROPOSAL_SWITCH_BLOCKED` if a canvas-agent run is active (matching the UI's
+   * hard block), because a switch would cancel the in-flight run.
+   *
+   * @param proposalId - The id of the proposal to activate.
+   * @returns The id of the now-active proposal.
+   * @throws `PROPOSAL_SWITCH_BLOCKED` while a canvas-agent run is in flight; or
+   *   if no proposal has the given id.
+   *
+   * @examplePrompt Switch to proposal prop_2
+   * @examplePrompt Make Scheme B the active design option
+   * @examplePrompt Show me the other proposal
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.proposals.setActive("prop_2")
+   * ```
+   */
+  public abstract setActive(
+    proposalId: string,
+  ): PluginApiReturn<PluginCoreProposalsSetActiveResult>
+
+  /**
+   * Delete a proposal.
+   *
+   * **DANGEROUS AND IRREVERSIBLE — not undoable.** You must choose **exactly
+   * one** explicit disposition (mirroring the product's delete dialog):
+   *
+   * - `{ deleteObjects: true }` — delete the proposal AND **permanently
+   *   destroy the geometry** in its exclusive buckets. Buckets shared with
+   *   other proposals are never destroyed.
+   * - `{ targetProposalId }` — transfer **all** of this proposal's buckets to
+   *   another proposal first (keeping the geometry alive), then delete the
+   *   emptied proposal — "merge and remove". The target must be a
+   *   **different** proposal.
+   *
+   * A bare `delete(proposalId)` is **rejected**: there is no safe default —
+   * without a disposition the engine would drop the proposal's bucket records
+   * while leaving their components orphaned. Passing both dispositions at once
+   * is also rejected as ambiguous.
+   *
+   * It is **server-validated**: the backend refuses the delete (throws) if a
+   * collaborator is active in that proposal, and the check times out after
+   * ~10s. The project's **last remaining proposal cannot be deleted**. If the
+   * proposal is active, the host switches away first.
+   *
+   * @param proposalId - The id of the proposal to delete.
+   * @param options - Exactly one disposition: `{ deleteObjects: true }`
+   *   (destroy exclusive-bucket geometry) or `{ targetProposalId }` (transfer
+   *   buckets to that proposal, then delete).
+   * @returns Confirmation that the proposal was deleted.
+   * @throws If no disposition (or both) is given, `targetProposalId` equals
+   *   `proposalId`, no proposal has the given id, it is the only proposal, a
+   *   collaborator lock refuses the delete, or the server validation times out.
+   *
+   * @examplePrompt Delete proposal prop_2 and everything in it
+   * @examplePrompt Remove this design option and destroy its geometry
+   * @examplePrompt Merge prop_2's layers into prop_1 and delete prop_2
+   *
+   * # Example
+   * ```ts
+   * // destroy the proposal and its exclusive geometry
+   * await snaptrude.core.proposals.delete("prop_2", { deleteObjects: true })
+   * // …or keep the geometry by transferring its buckets to prop_1 first
+   * await snaptrude.core.proposals.delete("prop_2", { targetProposalId: "prop_1" })
+   * ```
+   */
+  public abstract delete(
+    proposalId: string,
+    options:
+      | { deleteObjects: true; targetProposalId?: never }
+      | { deleteObjects?: false; targetProposalId: string },
+  ): PluginApiReturn<PluginCoreProposalsDeleteResult>
+}
+
+/**
+ * A design option (proposal) in the active project.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public proposal id (e.g. `"prop_1"`) |
+ * | `name` | `string` | Display name (≤ 24 chars) |
+ * | `isActive` | `boolean` | Whether this is the active proposal |
+ * | `defaultBucketId` | `string` | Id of the proposal's default bucket (cannot be unshared) |
+ * | `bucketIds` | `string[]` | Ids of every bucket (layer) the proposal owns |
+ * | `createdAt` | `string` | ISO creation timestamp |
+ * | `createdBy` | `string` | User id of the creator |
+ */
+export const PluginCoreProposalRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  isActive: z.boolean(),
+  defaultBucketId: z.string(),
+  bucketIds: z.array(z.string()),
+  createdAt: z.string(),
+  createdBy: z.string(),
+})
+export type PluginCoreProposalRef = z.infer<typeof PluginCoreProposalRef>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `proposals` | {@linkcode PluginCoreProposalRef}`[]` | Every proposal in the active project |
+ */
+export const PluginCoreProposalsListResult = z.object({
+  proposals: z.array(PluginCoreProposalRef),
+})
+export type PluginCoreProposalsListResult = z.infer<
+  typeof PluginCoreProposalsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.get} /
+ * {@linkcode PluginCoreProposalsApi.isActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `proposalId` | `string` | The id of the proposal |
+ */
+export const PluginCoreProposalsGetArgs = z.object({
+  proposalId: z.string(),
+})
+export type PluginCoreProposalsGetArgs = z.infer<
+  typeof PluginCoreProposalsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.get} — the proposal, or `null`
+ * when no proposal has the given id.
+ */
+export const PluginCoreProposalsGetResult = PluginCoreProposalRef.nullable()
+export type PluginCoreProposalsGetResult = z.infer<
+  typeof PluginCoreProposalsGetResult
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.getActive} — the active proposal,
+ * or `null` when nothing is active (legacy / no-proposal project).
+ */
+export const PluginCoreProposalsGetActiveResult =
+  PluginCoreProposalRef.nullable()
+export type PluginCoreProposalsGetActiveResult = z.infer<
+  typeof PluginCoreProposalsGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.listForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The component to look up |
+ */
+export const PluginCoreProposalsListForComponentArgs = z.object({
+  component: ComponentHandle,
+})
+export type PluginCoreProposalsListForComponentArgs = z.infer<
+  typeof PluginCoreProposalsListForComponentArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.listForComponent} — the proposals
+ * the component belongs to (empty when out of scope or none). Same shape as
+ * {@linkcode PluginCoreProposalsListResult}.
+ */
+export const PluginCoreProposalsListForComponentResult =
+  PluginCoreProposalsListResult
+export type PluginCoreProposalsListForComponentResult = z.infer<
+  typeof PluginCoreProposalsListForComponentResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.isActive}. Alias of
+ * {@linkcode PluginCoreProposalsGetArgs}.
+ */
+export const PluginCoreProposalsIsActiveArgs = PluginCoreProposalsGetArgs
+export type PluginCoreProposalsIsActiveArgs = z.infer<
+  typeof PluginCoreProposalsIsActiveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.create}. A bare `name` makes
+ * a blank proposal; `baseProposalId` switches to the configured (carry-forward)
+ * path. `layers` requires `baseProposalId` — each entry names a bucket of the
+ * base proposal; omitted buckets are excluded, and omitting `layers` entirely
+ * duplicates every base bucket.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new proposal (capped at 24 chars) |
+ * | `baseProposalId` | `string \| undefined` | Proposal to carry forward from (configured path) |
+ * | `layers` | `{ bucketId: string; action: "share" \| "duplicate" }[] \| undefined` | Per-bucket carry-forward actions (requires `baseProposalId`) |
+ */
+export const PluginCoreProposalsCreateArgs = z
+  .object({
+    name: z.string(),
+    baseProposalId: z.string().optional(),
+    layers: z
+      .array(
+        z.object({
+          bucketId: z.string(),
+          action: z.enum(["share", "duplicate"]),
+        }),
+      )
+      .optional(),
+  })
+  .refine((v) => v.layers === undefined || v.baseProposalId !== undefined, {
+    message:
+      "layers requires baseProposalId — the layers describe how to carry the base proposal's buckets forward",
+  })
+export type PluginCoreProposalsCreateArgs = z.infer<
+  typeof PluginCoreProposalsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.create} — the id of the new
+ * proposal.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the newly created proposal |
+ */
+export const PluginCoreProposalsCreateResult = z.object({
+  id: z.string(),
+})
+export type PluginCoreProposalsCreateResult = z.infer<
+  typeof PluginCoreProposalsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `proposalId` | `string` | The id of the proposal to rename |
+ * | `name` | `string` | The new display name (capped at 24 chars) |
+ */
+export const PluginCoreProposalsRenameArgs = z.object({
+  proposalId: z.string(),
+  name: z.string(),
+})
+export type PluginCoreProposalsRenameArgs = z.infer<
+  typeof PluginCoreProposalsRenameArgs
+>
+
+/** Result of {@linkcode PluginCoreProposalsApi.rename} — the updated record. */
+export const PluginCoreProposalsRenameResult = PluginCoreProposalRef
+export type PluginCoreProposalsRenameResult = z.infer<
+  typeof PluginCoreProposalsRenameResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `proposalId` | `string` | The id of the proposal to activate |
+ */
+export const PluginCoreProposalsSetActiveArgs = z.object({
+  proposalId: z.string(),
+})
+export type PluginCoreProposalsSetActiveArgs = z.infer<
+  typeof PluginCoreProposalsSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.setActive} — the now-active
+ * proposal's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the now-active proposal |
+ */
+export const PluginCoreProposalsSetActiveResult = z.object({
+  id: z.string(),
+})
+export type PluginCoreProposalsSetActiveResult = z.infer<
+  typeof PluginCoreProposalsSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreProposalsApi.delete}. Exactly one
+ * disposition is required: `deleteObjects: true` XOR `targetProposalId` (a
+ * **different** proposal). A bare delete with neither is rejected.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `proposalId` | `string` | The id of the proposal to delete |
+ * | `deleteObjects` | `true \| undefined` | Destroy the geometry in exclusive buckets (mutually exclusive with `targetProposalId`) |
+ * | `targetProposalId` | `string \| undefined` | Transfer this proposal's buckets here before deleting (must differ from `proposalId`) |
+ */
+export const PluginCoreProposalsDeleteArgs = z
+  .object({
+    proposalId: z.string(),
+    deleteObjects: z.boolean().optional(),
+    targetProposalId: z.string().optional(),
+  })
+  .refine((v) => (v.deleteObjects === true) !== (v.targetProposalId != null), {
+    message:
+      "Provide exactly one disposition: deleteObjects: true (destroy exclusive-bucket geometry) or targetProposalId (transfer buckets, then delete)",
+  })
+  .refine(
+    (v) => v.targetProposalId == null || v.targetProposalId !== v.proposalId,
+    {
+      message: "targetProposalId must be a different proposal than proposalId",
+    },
+  )
+export type PluginCoreProposalsDeleteArgs = z.infer<
+  typeof PluginCoreProposalsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreProposalsApi.delete} — confirmation that the
+ * proposal was deleted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | Always `true` on success |
+ */
+export const PluginCoreProposalsDeleteResult = z.object({
+  deleted: z.literal(true),
+})
+export type PluginCoreProposalsDeleteResult = z.infer<
+  typeof PluginCoreProposalsDeleteResult
+>