@snaptrude/plugin-core 0.9.9 → 0.9.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.9",
+  "version": "0.9.10",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

@@ -29,10 +29,14 @@ export interface PluginCoreModeSetResult {
  * Not to be confused with the viewport's 2D/3D camera mode
  * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
  *
- * `set` covers `design`, `bim`, and `present` — in-page switches.
- * `program` opens in its own browser tab in the product, which a plugin worker
- * cannot do, so `set("program")` fails with `PRECONDITION_FAILED`; `get()`
- * still reports `"program"` for code running in the Program tab.
+ * `set` covers `design`, `bim`, and `present` — in-page switches — and
+ * `program`, which opens the Program tab (a paired browser window) through the
+ * same path as the top bar's Program button. Because the open happens outside a
+ * user gesture the browser may block the pop-up; the editor then shows its
+ * "Allow pop-up to continue" modal and the tab opens when the user confirms.
+ * `get()` reports `"program"` only for code running in the Program tab itself.
+ * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
+ * the tab is ready before calling `program.spreadsheet.*`.
  */
 export abstract class PluginCoreModeApi {
   constructor() {}
@@ -74,16 +78,24 @@ export abstract class PluginCoreModeApi {
    * Switch the editor to another application mode — the same action as
    * clicking that tab in the top menu bar.
    *
-   * Supported: `"design"`, `"bim"`, `"present"`. Switching to
-   * `"program"` is rejected with `PRECONDITION_FAILED` (the Program surface
-   * opens in its own browser tab in the product; a plugin cannot open one).
+   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
+   * the Program tab (a paired browser window) exactly as the top bar's Program
+   * button does, and resolves once that tab has connected to the editor (up to
+   * ~90s — the browser may block the pop-up, in which case the editor shows an
+   * "Allow pop-up to continue" modal and waits for the user to confirm).
+   * Idempotent when the Program tab is already open. Note `get()` in the model
+   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
+   * a separate window.
    *
    * @param mode - Target mode token from {@linkcode PluginAppMode}
    * @returns The committed `{ mode }` after the switch.
+   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
+   *   pop-up modal or the tab does not connect within the timeout.
    *
    * @examplePrompt Switch to present mode
    * @examplePrompt Open BIM mode
    * @examplePrompt Go back to design mode
+   * @examplePrompt Open program mode
    *
    * # Example
    * ```ts

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() {}
 }