@snaptrude/plugin-core 0.0.0-dev-20260908074328 → 0.0.0-dev-20260921132444

package/src/api/program/spreadsheet.ts

@@ -820,6 +820,144 @@ export abstract class PluginProgramSpreadsheetApi {
    * ```
    */
   public abstract ping(): PluginApiReturn<PluginProgramSpreadsheetPingResult>
+
+  // --- Custom program sheets (grouped program views) -----------------------------
+
+  /**
+   * Create a **custom program sheet** — a live view of the program grouped by a
+   * configurable hierarchy (the Program tab's "Custom" sheet with *Organize →
+   * Group by*).
+   *
+   * Unlike {@linkcode PluginProgramSpreadsheetApi.createSheet} (a blank sheet you
+   * write cells into), a custom sheet is data-bound: its rows are the project's
+   * spaces, re-rendered from the model, grouped by `groupBy` in order (e.g.
+   * `["departmentName", "<metadataHeaderId>", "label"]` for a healthcare
+   * department → sub-department → room hierarchy) and showing the `properties`
+   * columns. Valid property ids come from
+   * {@linkcode PluginProgramSpreadsheetApi.listCustomSheetProperties} — built-in
+   * properties plus every program metadata header id. The configuration is
+   * saved with the sheet.
+   *
+   * @param name - The sheet name to create (must not already exist).
+   * @param options - Optional `groupBy` (property ids, outermost first; default
+   *   none), `properties` (column property ids, in order; default
+   *   `["label", "areas"]`), and `groupColors` (property id → CSS hex fill for
+   *   that level's group headers).
+   * @returns The sheet's {@linkcode PluginSpreadsheetCustomSheet} configuration.
+   * @throws If a sheet named `name` already exists, or a property id is unknown.
+   *
+   * @examplePrompt Create a custom sheet grouped by department then sub-department
+   * @examplePrompt Make a program view grouped by storey and label
+   * @examplePrompt Build a grouped program sheet for the healthcare hierarchy
+   * @examplePrompt Add a custom sheet with a department → room type group-by
+   *
+   * # Example
+   * ```ts
+   * const { headers } = await snaptrude.program.metadata.listHeaders()
+   * const subDept = headers.find((h) => h.name === "Sub-department")
+   * await snaptrude.program.spreadsheet.createCustomSheet("Clinical Program", {
+   *   groupBy: ["departmentName", subDept.headerId, "label"],
+   *   properties: ["label", "count", "areas", "netAreaAchieved"],
+   * })
+   * ```
+   */
+  public abstract createCustomSheet(
+    name: string,
+    options?: {
+      groupBy?: string[]
+      properties?: string[]
+      groupColors?: Record<string, string>
+    },
+  ): PluginApiReturn<PluginProgramSpreadsheetCustomSheetResult>
+
+  /**
+   * Update a custom program sheet's group-by hierarchy, columns, or group colors.
+   *
+   * A **sparse** update: omitted fields are left unchanged. The sheet is
+   * re-rendered once and the configuration saved.
+   *
+   * @param sheetName - The custom sheet to update.
+   * @param options - Any of `groupBy`, `properties`, `groupColors` (see
+   *   {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}).
+   * @returns The sheet's updated {@linkcode PluginSpreadsheetCustomSheet}.
+   * @throws If `sheetName` is not a custom program sheet, or a property id is
+   *   unknown.
+   *
+   * @examplePrompt Change the custom sheet to group by storey first
+   * @examplePrompt Add the Occupancy column to my grouped program sheet
+   * @examplePrompt Regroup the Clinical Program sheet by department only
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.spreadsheet.updateCustomSheet("Clinical Program", {
+   *   groupBy: ["storey", "departmentName"],
+   * })
+   * ```
+   */
+  public abstract updateCustomSheet(
+    sheetName: string,
+    options: {
+      groupBy?: string[]
+      properties?: string[]
+      groupColors?: Record<string, string>
+    },
+  ): PluginApiReturn<PluginProgramSpreadsheetCustomSheetResult>
+
+  /**
+   * Get a custom program sheet's configuration.
+   *
+   * @param sheetName - The sheet to read.
+   * @returns Its {@linkcode PluginSpreadsheetCustomSheet}, or `null` when no
+   *   custom program sheet has that name (plain sheets return `null` too).
+   *
+   * @examplePrompt How is the Clinical Program sheet grouped?
+   * @examplePrompt Get the group-by configuration of this custom sheet
+   *
+   * # Example
+   * ```ts
+   * const cfg = await snaptrude.program.spreadsheet.getCustomSheet("Clinical Program")
+   * if (cfg) console.log(cfg.groupBy, cfg.properties)
+   * ```
+   */
+  public abstract getCustomSheet(
+    sheetName: string,
+  ): PluginApiReturn<PluginProgramSpreadsheetGetCustomSheetResult>
+
+  /**
+   * List the custom program sheets in the workbook with their configurations.
+   *
+   * @returns A {@linkcode PluginProgramSpreadsheetListCustomSheetsResult} with a
+   *   `sheets` array (empty when there are none).
+   *
+   * @examplePrompt List the custom program sheets
+   * @examplePrompt Which sheets are grouped program views?
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.program.spreadsheet.listCustomSheets()
+   * ```
+   */
+  public abstract listCustomSheets(): PluginApiReturn<PluginProgramSpreadsheetListCustomSheetsResult>
+
+  /**
+   * List the property ids a custom program sheet can show as columns or group by.
+   *
+   * Built-in properties (`label`, `departmentName`, `storey`, `areas`, …) plus
+   * one entry per program metadata header (its `headerId`). `groupable` is
+   * `false` for computed properties that can only be columns.
+   *
+   * @returns A {@linkcode PluginProgramSpreadsheetListCustomSheetPropertiesResult}.
+   *
+   * @examplePrompt What can I group a custom program sheet by?
+   * @examplePrompt List the columns available for a custom sheet
+   *
+   * # Example
+   * ```ts
+   * const { properties } = await snaptrude.program.spreadsheet.listCustomSheetProperties()
+   * const groupable = properties.filter((p) => p.groupable).map((p) => p.id)
+   * ```
+   */
+  public abstract listCustomSheetProperties(): PluginApiReturn<PluginProgramSpreadsheetListCustomSheetPropertiesResult>
 }
 
 /**
@@ -2414,3 +2552,147 @@ export const PluginProgramSpreadsheetAddImageResult = z.object({
 export type PluginProgramSpreadsheetAddImageResult = z.infer<
   typeof PluginProgramSpreadsheetAddImageResult
 >
+
+/**
+ * A custom program sheet's configuration — the grouped, data-bound program view
+ * created by {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The sheet's name |
+ * | `groupBy` | `string[]` | Group-by hierarchy, outermost first (property ids); `[]` when ungrouped |
+ * | `properties` | `string[]` | Column property ids in column order (`""` marks an unassigned column) |
+ * | `groupColors` | `Record<string, string>` | Property id → CSS hex fill of that level's group headers |
+ * | `proposalId` | `string \| null` | The proposal the sheet belongs to, or `null` when the project has none |
+ */
+export const PluginSpreadsheetCustomSheet = z.object({
+  sheetName: z.string(),
+  groupBy: z.array(z.string()),
+  properties: z.array(z.string()),
+  groupColors: z.record(z.string(), z.string()),
+  proposalId: z.string().nullable(),
+})
+export type PluginSpreadsheetCustomSheet = z.infer<
+  typeof PluginSpreadsheetCustomSheet
+>
+
+/**
+ * The configurable part of a custom program sheet, for
+ * {@linkcode PluginProgramSpreadsheetApi.createCustomSheet} /
+ * {@linkcode PluginProgramSpreadsheetApi.updateCustomSheet}. All fields optional.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | `string[]?` | Group-by hierarchy, outermost first (property ids) |
+ * | `properties` | `string[]?` | Column property ids, in order |
+ * | `groupColors` | `Record<string, string>?` | Property id → CSS hex fill for that level's group headers |
+ */
+export const PluginSpreadsheetCustomSheetConfig = z.object({
+  groupBy: z.array(z.string().trim().min(1)).max(10).optional(),
+  properties: z.array(z.string()).max(50).optional(),
+  groupColors: z.record(z.string(), z.string()).optional(),
+})
+export type PluginSpreadsheetCustomSheetConfig = z.infer<
+  typeof PluginSpreadsheetCustomSheetConfig
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.createCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The sheet name to create |
+ * | `groupBy` / `properties` / `groupColors` | — | See {@linkcode PluginSpreadsheetCustomSheetConfig} |
+ */
+export const PluginProgramSpreadsheetCreateCustomSheetArgs =
+  PluginSpreadsheetCustomSheetConfig.extend({
+    name: z.string().trim().min(1),
+  })
+export type PluginProgramSpreadsheetCreateCustomSheetArgs = z.infer<
+  typeof PluginProgramSpreadsheetCreateCustomSheetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramSpreadsheetApi.updateCustomSheet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetName` | `string` | The custom sheet to update |
+ * | `groupBy` / `properties` / `groupColors` | — | Sparse; see {@linkcode PluginSpreadsheetCustomSheetConfig} |
+ */
+export const PluginProgramSpreadsheetUpdateCustomSheetArgs =
+  PluginSpreadsheetCustomSheetConfig.extend({
+    sheetName: z.string().trim().min(1),
+  })
+export type PluginProgramSpreadsheetUpdateCustomSheetArgs = z.infer<
+  typeof PluginProgramSpreadsheetUpdateCustomSheetArgs
+>
+
+/** Result of `createCustomSheet` / `updateCustomSheet` — the sheet's configuration. */
+export const PluginProgramSpreadsheetCustomSheetResult = PluginSpreadsheetCustomSheet
+export type PluginProgramSpreadsheetCustomSheetResult = z.infer<
+  typeof PluginProgramSpreadsheetCustomSheetResult
+>
+
+/** Arguments for {@linkcode PluginProgramSpreadsheetApi.getCustomSheet}. */
+export const PluginProgramSpreadsheetGetCustomSheetArgs = z.object({
+  sheetName: z.string().trim().min(1),
+})
+export type PluginProgramSpreadsheetGetCustomSheetArgs = z.infer<
+  typeof PluginProgramSpreadsheetGetCustomSheetArgs
+>
+
+/** Result of {@linkcode PluginProgramSpreadsheetApi.getCustomSheet} — the configuration, or `null`. */
+export const PluginProgramSpreadsheetGetCustomSheetResult =
+  PluginSpreadsheetCustomSheet.nullable()
+export type PluginProgramSpreadsheetGetCustomSheetResult = z.infer<
+  typeof PluginProgramSpreadsheetGetCustomSheetResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.listCustomSheets}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheets` | {@linkcode PluginSpreadsheetCustomSheet}`[]` | Every custom program sheet |
+ */
+export const PluginProgramSpreadsheetListCustomSheetsResult = z.object({
+  sheets: z.array(PluginSpreadsheetCustomSheet),
+})
+export type PluginProgramSpreadsheetListCustomSheetsResult = z.infer<
+  typeof PluginProgramSpreadsheetListCustomSheetsResult
+>
+
+/**
+ * A property a custom program sheet can show or group by.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Property id (built-in key, or a metadata `headerId`) |
+ * | `name` | `string` | Display name |
+ * | `groupable` | `boolean` | Whether the sheet can group by it |
+ * | `custom` | `boolean` | `true` for program metadata headers, `false` for built-ins |
+ */
+export const PluginSpreadsheetCustomSheetProperty = z.object({
+  id: z.string(),
+  name: z.string(),
+  groupable: z.boolean(),
+  custom: z.boolean(),
+})
+export type PluginSpreadsheetCustomSheetProperty = z.infer<
+  typeof PluginSpreadsheetCustomSheetProperty
+>
+
+/**
+ * Result of {@linkcode PluginProgramSpreadsheetApi.listCustomSheetProperties}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `properties` | {@linkcode PluginSpreadsheetCustomSheetProperty}`[]` | Built-ins first, then metadata headers |
+ */
+export const PluginProgramSpreadsheetListCustomSheetPropertiesResult = z.object({
+  properties: z.array(PluginSpreadsheetCustomSheetProperty),
+})
+export type PluginProgramSpreadsheetListCustomSheetPropertiesResult = z.infer<
+  typeof PluginProgramSpreadsheetListCustomSheetPropertiesResult
+>

package/src/api/workspace/index.ts

@@ -10,13 +10,16 @@ import { PluginApiReturn } from "../../types"
  * Teams are **read-only** here (no create/invite/delete in v1, a deliberate
  * safety decision); there are no folders in v1. A `projectId` is the project's
  * floorkey. Plan limits are enforced by the backend — a limit rejection surfaces
- * as a normal host error. It also carries the workspace-level mode switch for
+ * as a normal host error. It also carries the workspace-level mode switches for
  * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
- * {@linkcode PluginWorkspaceApi.closePresentMode}).
+ * {@linkcode PluginWorkspaceApi.closePresentMode}) and Program mode
+ * ({@linkcode PluginWorkspaceApi.openProgramMode} /
+ * {@linkcode PluginWorkspaceApi.closeProgramMode}).
  *
  * - {@linkcode PluginWorkspaceApi.projects} — Create, copy, list, read & rename projects
  * - {@linkcode PluginWorkspaceApi.teams} — Read teams and their members
  * - {@linkcode PluginWorkspaceApi.openPresentMode} / {@linkcode PluginWorkspaceApi.closePresentMode} — Open/close the Present-mode documentation editor
+ * - {@linkcode PluginWorkspaceApi.openProgramMode} / {@linkcode PluginWorkspaceApi.closeProgramMode} — Open/close the Program tab (the spreadsheet the `program.spreadsheet.*` calls run in)
  */
 export abstract class PluginWorkspaceApi {
   /** Projects — create, copy, list, read & rename. See {@linkcode PluginWorkspaceProjectsApi}. */
@@ -68,6 +71,52 @@ export abstract class PluginWorkspaceApi {
    */
   public abstract closePresentMode(): PluginApiReturn<void>
 
+  /**
+   * Open Program mode — the Program tab the `program.spreadsheet.*` calls run in.
+   *
+   * Runs the top bar's own Program-button sequence (remember the preference,
+   * open or re-link the paired Program window) and resolves only once that tab
+   * has connected to the editor over its channel, so a `program.spreadsheet.*`
+   * call issued right after this resolves finds the tab open. The open happens
+   * outside a user gesture, so the browser may block the pop-up; the editor
+   * then shows its "Allow pop-up to continue" modal and this call keeps waiting
+   * (up to ~90s) for the user to confirm. Idempotent — resolves immediately
+   * when the Program tab is already connected, and is a no-op when the plugin is
+   * itself running in the Program tab. Write-gated.
+   *
+   * @throws `PRECONDITION_FAILED` if the user dismisses the pop-up modal or the
+   *   Program tab does not connect within the timeout.
+   *
+   * @examplePrompt Open program mode
+   * @examplePrompt Open the Program tab so I can build a custom sheet
+   * @examplePrompt Switch to the program spreadsheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.openProgramMode()
+   * const { sheets } = await snaptrude.program.spreadsheet.listSheets()
+   * ```
+   */
+  public abstract openProgramMode(): PluginApiReturn<void>
+
+  /**
+   * Close the Program tab.
+   *
+   * Idempotent — a no-op when no Program tab is connected. Write-gated, like
+   * {@linkcode PluginWorkspaceApi.openProgramMode}.
+   *
+   * @throws `PRECONDITION_FAILED` if the tab is still connected after ~15s.
+   *
+   * @examplePrompt Close program mode
+   * @examplePrompt Close the Program tab
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.closeProgramMode()
+   * ```
+   */
+  public abstract closeProgramMode(): PluginApiReturn<void>
+
   constructor() {}
 }
 

package/src/errors/codes.ts

@@ -5,13 +5,8 @@
  * APPEND-ONLY: codes are a published contract; never rename or remove one.
  * Handle-resolution failures deliberately collapse to ONE code
  * (`HANDLE_INVALID`) so error responses cannot be used as an existence /
- * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6) — with one deliberate
- * exception: `HANDLE_STALE` marks a handle the caller legitimately held that a
- * parametric resolution (merge / split / rebuild) has since retired — a
- * lifetime fact about the caller's own write-scoped handle, not an oracle
- * (forged / never-issued ids still collapse to `HANDLE_INVALID`).
- * `HANDLE_KIND_MISMATCH` stays distinct because the kind is information the
- * caller already holds.
+ * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6). `HANDLE_KIND_MISMATCH`
+ * stays distinct because the kind is information the caller already holds.
  */
 export const PLUGIN_ERROR_CODES = [
   "VALIDATION",
@@ -37,10 +32,6 @@ export const PLUGIN_ERROR_CODES = [
   "NO_ACTIVE_STRUCTURE",
   "NO_ELIGIBLE_ELEMENTS",
   "PROPOSAL_SWITCH_BLOCKED",
-  "HANDLE_STALE",
-  "KIND_HIDDEN_IN_MODE",
-  "MERGED_INTO_EXISTING",
-  "BLOCKED_IN_BIM",
   "INTERNAL",
   "UNKNOWN",
 ] as const
@@ -132,25 +123,6 @@ export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
     category: "execution",
     hintTemplate: "Wait for the in-canvas agent run to finish, then retry.",
   },
-  HANDLE_STALE: {
-    category: "handle",
-    hintTemplate:
-      "The entity was retired by a parametric resolution (merge/split/rebuild); re-query for its successor.",
-  },
-  KIND_HIDDEN_IN_MODE: {
-    category: "execution",
-    hintTemplate:
-      "This entity kind has no representation in the current mode/LOD; switch mode or target a visible kind.",
-  },
-  MERGED_INTO_EXISTING: {
-    category: "execution",
-    hintTemplate:
-      "The created geometry merged into an existing entity; use the surviving handles from details.",
-  },
-  BLOCKED_IN_BIM: {
-    category: "execution",
-    hintTemplate: "This operation is unavailable in BIM mode; switch to Design and retry.",
-  },
   INTERNAL: {
     category: "internal",
     hintTemplate: "Host-side fault. Report with errorId.",

package/src/handles.ts

@@ -115,6 +115,19 @@ export type UnderlayHandle = EntityId<"underlay">
  */
 export type TerrainHandle = EntityId<"terrain">
 
+/**
+ * A **dimension line** — one measurement annotation left behind by the Measuring
+ * Tape tool (NOT a width/height/depth property; see `design.dimensions`).
+ * Entity-style: the token IS the raw engine dimension id (`dim_…`), resolved live
+ * host-side from the dimension-line registry (`getDimensionLineMap()`) — not via
+ * `ComponentUtility.FindComponentById`, which does not index dimension lines (a
+ * dimension line is not a Component). No arena, no quota, stable across
+ * undo/redo and across reloads (the record persists with the project). Returned
+ * by `design.dimensions.create` and consumed by every other
+ * `design.dimensions.*` method.
+ */
+export type DimensionHandle = EntityId<"dimension">
+
 /**
  * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
  * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
@@ -233,6 +246,17 @@ export const ImportJobHandle = z
   .min(1)
   .transform((s) => s as ImportJobHandle)
 
+/**
+ * {@linkcode DimensionHandle} is an entity-style handle — the raw `dim_…` engine
+ * id, validated only as a non-empty string (no `"<kind>_"` prefix enforcement),
+ * resolved live host-side against the dimension-line registry (existence
+ * enforced there, as `HANDLE_INVALID`).
+ */
+export const DimensionHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as DimensionHandle)
+
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")

package/test/errors.test.mjs

@@ -178,10 +178,6 @@ test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)",
     "NO_ACTIVE_STRUCTURE",
     "NO_ELIGIBLE_ELEMENTS",
     "PROPOSAL_SWITCH_BLOCKED",
-    "HANDLE_STALE",
-    "KIND_HIDDEN_IN_MODE",
-    "MERGED_INTO_EXISTING",
-    "BLOCKED_IN_BIM",
     "INTERNAL",
     "UNKNOWN",
   ])