@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

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/core/proposals/index.ts

@@ -6,7 +6,8 @@ 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),
+ * project. Each proposal owns a set of buckets (a bucket is a layer in the
+ * Layers panel; read them with `core.layers.get` / {@linkcode PluginCoreLayersApi}),
  * 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).
@@ -324,8 +325,8 @@ export abstract class PluginCoreProposalsApi {
  * | `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 |
+ * | `defaultBucketId` | `string` | Id of the proposal's default layer (cannot be unshared); read it with `core.layers.get` ({@linkcode PluginCoreLayersApi}) |
+ * | `bucketIds` | `string[]` | Ids of every layer in the Layers panel the proposal owns; read them with `core.layers.get` ({@linkcode PluginCoreLayersApi}) |
  * | `createdAt` | `string` | ISO creation timestamp |
  * | `createdBy` | `string` | User id of the creator |
  */

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

@@ -11,6 +11,7 @@ import {
   PluginStoryDeleteResult,
   PluginStoryDuplicateResult,
 } from "../../entity/story"
+import { PluginCoreStoreysLayersApi } from "./layers"
 
 /**
  * Storey (floor) management.
@@ -24,11 +25,22 @@ import {
  * API calls** that return Promises and support undo/redo via Snaptrude's command
  * system (except {@linkcode PluginCoreStoreysApi.setActive}, a view change).
  *
+ * - {@linkcode PluginCoreStoreysApi.layers} — each storey's sketch surfaces
+ *   (Wall, Rough) and imported underlays (CAD, PDF, image, terrain): list, get,
+ *   active layer get/set, show/hide. Not the Layers panel; that is `core.layers`.
+ *
  * Accessed via `snaptrude.core.storeys`.
  */
 export abstract class PluginCoreStoreysApi {
   constructor() {}
 
+  /**
+   * Storey layers — each storey's sketch surfaces and imported underlays (ids
+   * like `ly_5`), formerly `core.layers`. Not the layers in the Layers panel;
+   * use `core.layers` for those. See {@linkcode PluginCoreStoreysLayersApi}.
+   */
+  public abstract layers: PluginCoreStoreysLayersApi
+
   /**
    * Get properties of a storey by its storey number.
    *
@@ -178,12 +190,15 @@ export abstract class PluginCoreStoreysApi {
   /**
    * Make a storey the active storey — the same as clicking it in the storey/layer
    * panel. Subsequent draws and creates target this storey, and in 2D the
-   * viewport switches to it. This is a view/navigation change: it is **not**
+   * viewport switches to that storey's plan (and its cut range), unless the
+   * active view is already a plan on it.
+   * This is a view/navigation change: it is **not**
    * undoable and commits nothing to the model.
    *
    * @param storyValue - Integer storey number to activate
    * @returns A {@linkcode PluginStorySetActiveResult} echoing the now-active `storyValue`
-   * @throws `PRECONDITION_FAILED` if no storey has the given value
+   * @throws `PRECONDITION_FAILED` if no storey has the given value, or in 2D if
+   *   the storey has no plan
    *
    * @examplePrompt Switch to the second floor
    * @examplePrompt Make the ground storey active
@@ -292,3 +307,5 @@ export const PluginCoreStoreysListResult = z.object({
 export type PluginCoreStoreysListResult = z.infer<
   typeof PluginCoreStoreysListResult
 >
+
+export * from "./layers"

package/src/api/core/storeys/layers.ts

@@ -0,0 +1,339 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Storey layers — read and toggle a storey's sketch surfaces and imported
+ * underlays.
+ *
+ * These are each storey's built-in sketch surfaces (Wall, Rough) and its
+ * imported underlays (CAD, PDF, images, terrain, neighbourhood buildings), with
+ * ids like `ly_5`. They are **NOT** the layers in the product's Layers panel in
+ * the left sidebar; use {@linkcode PluginCoreLayersApi} (`core.layers`) for
+ * those. They are also not wall/floor construction-assembly material layers.
+ *
+ * Reads return plain records and never throw for a missing layer (`get` and
+ * `getActive` return `null`, `list` returns `[]`).
+ *
+ * Storey layers are created only by storey creation and `core.io.import.*`;
+ * delete underlays with `core.io.underlay.delete` / `core.io.terrain.delete`.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.storeys.layers` (formerly `core.layers`).
+ *
+ * Formerly `core.layers`. Calls in that shape on `core.layers` (`list(storeyId)`,
+ * `getActive(storeyId)`, `get` / `setActive` / `update(layerId, hidden)` with a
+ * `ly_*` id) are still routed here, so plugins built before 0.9.15 keep working.
+ */
+export abstract class PluginCoreStoreysLayersApi {
+  constructor() {}
+
+  /**
+   * List the storey layers of a storey.
+   *
+   * Optionally filter to a single {@linkcode PluginCoreStoreyLayerType}.
+   *
+   * @param storeyId - The storey whose layers to read.
+   * @param layerType - Optional {@linkcode PluginCoreStoreyLayerType} filter.
+   * @returns A {@linkcode PluginCoreStoreysLayersListResult} with a `layers` array
+   *   (empty when the storey is missing or has no matching layers).
+   *
+   * @examplePrompt List the sketch surfaces and underlays on this storey
+   * @examplePrompt Show all the PDF underlays on storey st_2
+   * @examplePrompt What CAD layers are on the ground floor?
+   *
+   * # Example
+   * ```ts
+   * const { layers } = await snaptrude.core.storeys.layers.list("st_2")
+   * for (const l of layers) console.log(l.name, l.layerType, l.hidden)
+   * ```
+   */
+  public abstract list(
+    storeyId: string,
+    layerType?: PluginCoreStoreyLayerType,
+  ): PluginApiReturn<PluginCoreStoreysLayersListResult>
+
+  /**
+   * Get a single storey layer by id.
+   *
+   * @param layerId - The id of the layer to read.
+   * @returns The matching {@linkcode PluginCoreStoreyLayer}, or `null` if no layer has
+   *   that id.
+   *
+   * @examplePrompt Get the storey drawing layer with id ly_5
+   * @examplePrompt Is storey layer ly_5 hidden?
+   * @examplePrompt Look up a storey underlay layer by id
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.storeys.layers.get("ly_5")
+   * if (layer) console.log(layer.name, layer.hidden, layer.locked)
+   * ```
+   */
+  public abstract get(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersGetResult>
+
+  /**
+   * Get the active storey layer of a storey.
+   *
+   * The active layer is the one new sketch geometry is drawn onto. Paired with
+   * {@linkcode PluginCoreStoreysLayersApi.setActive}.
+   *
+   * @param storeyId - The storey whose active layer to read.
+   * @returns The active {@linkcode PluginCoreStoreyLayer}, or `null` if the storey is
+   *   missing or has no active layer.
+   *
+   * @examplePrompt Which sketch surface (Wall/Rough) is active on this storey?
+   * @examplePrompt Get the active storey drawing layer on st_2
+   * @examplePrompt Which storey layer is new sketch geometry drawn onto?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.storeys.layers.getActive("st_2")
+   * if (active) console.log(active.name)
+   * ```
+   */
+  public abstract getActive(
+    storeyId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersGetActiveResult>
+
+  /**
+   * Make a storey layer the active layer of its storey.
+   *
+   * Paired with {@linkcode PluginCoreStoreysLayersApi.getActive}.
+   *
+   * @param layerId - The id of the layer to activate.
+   * @returns The id of the now-active layer.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Switch this storey's sketch surface to the Rough layer
+   * @examplePrompt Make storey layer ly_5 the active sketch surface
+   * @examplePrompt Switch the active storey layer to the CAD underlay
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.storeys.layers.setActive("ly_5")
+   * ```
+   */
+  public abstract setActive(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreStoreysLayersSetActiveResult>
+
+  /**
+   * Update a storey layer's visibility.
+   *
+   * A **sparse** update: omit `hidden` to leave it unchanged. This edit is **not
+   * undoable**. Locking and renaming are not exposed — layer `locked` is a
+   * read-only status here (setting it at runtime does not lock the live meshes or
+   * show a padlock in the app until a reload), and a rename cascades to every member
+   * mesh's `layerName`, a corruption hazard.
+   *
+   * @param layerId - The id of the layer to update.
+   * @param hidden - New hidden state (unchanged if omitted).
+   * @returns The updated {@linkcode PluginCoreStoreyLayer}.
+   * @throws If no layer has the given id.
+   *
+   * @examplePrompt Hide the PDF underlay layer
+   * @examplePrompt Show the CAD underlay again
+   * @examplePrompt Hide storey layer ly_5
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.storeys.layers.update("ly_5", true)
+   * ```
+   */
+  public abstract update(
+    layerId: string,
+    hidden?: boolean,
+  ): PluginApiReturn<PluginCoreStoreysLayersUpdateResult>
+}
+
+/**
+ * The kind of a storey layer.
+ *
+ * Author-drawable kinds (`floor`, `wall`, `ceiling`, `rough`, `default`) plus
+ * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
+ */
+export const PluginCoreStoreyLayerType = z.enum([
+  "floor",
+  "wall",
+  "ceiling",
+  "rough",
+  "default",
+  "image",
+  "cad",
+  "pdf",
+  "terrain",
+  "buildings",
+])
+export type PluginCoreStoreyLayerType = z.infer<typeof PluginCoreStoreyLayerType>
+
+/**
+ * A storey layer on a storey.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public layer id (e.g. `"ly_5"`) |
+ * | `name` | `string` | Display name |
+ * | `layerType` | {@linkcode PluginCoreStoreyLayerType} | The layer's kind |
+ * | `storeyId` | `string` | The stable id of the storey this layer belongs to |
+ * | `buildingId` | `string` | The stable id of the building this layer belongs to |
+ * | `hidden` | `boolean` | Whether the layer is hidden |
+ * | `locked` | `boolean` | Whether the layer is locked against edits |
+ * | `contentSummary` | `object` | A summary of what the layer holds (see below) |
+ *
+ * `contentSummary`:
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `hasFloorplan` | `boolean` | Whether the layer holds drawn floorplan geometry |
+ * | `pdfCount` | `number` | Number of PDF underlays on the layer |
+ * | `hasTerrain` | `boolean` | Whether the layer holds terrain |
+ */
+export const PluginCoreStoreyLayer = z.object({
+  id: z.string(),
+  name: z.string(),
+  layerType: PluginCoreStoreyLayerType,
+  storeyId: z.string(),
+  buildingId: z.string(),
+  hidden: z.boolean(),
+  locked: z.boolean(),
+  contentSummary: z.object({
+    hasFloorplan: z.boolean(),
+    pdfCount: z.number().int(),
+    hasTerrain: z.boolean(),
+  }),
+})
+export type PluginCoreStoreyLayer = z.infer<typeof PluginCoreStoreyLayer>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose layers to read |
+ * | `layerType` | {@linkcode PluginCoreStoreyLayerType}` \| undefined` | Optional layer-type filter |
+ */
+export const PluginCoreStoreysLayersListArgs = z.object({
+  storeyId: z.string(),
+  layerType: PluginCoreStoreyLayerType.optional(),
+})
+export type PluginCoreStoreysLayersListArgs = z.infer<
+  typeof PluginCoreStoreysLayersListArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layers` | {@linkcode PluginCoreStoreyLayer}`[]` | The storey's storey layers (empty when missing or none match) |
+ */
+export const PluginCoreStoreysLayersListResult = z.object({
+  layers: z.array(PluginCoreStoreyLayer),
+})
+export type PluginCoreStoreysLayersListResult = z.infer<
+  typeof PluginCoreStoreysLayersListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to read |
+ */
+export const PluginCoreStoreysLayersGetArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersGetArgs = z.infer<
+  typeof PluginCoreStoreysLayersGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.get} — the layer, or `null`
+ * when no layer has the given id.
+ */
+export const PluginCoreStoreysLayersGetResult = PluginCoreStoreyLayer.nullable()
+export type PluginCoreStoreysLayersGetResult = z.infer<
+  typeof PluginCoreStoreysLayersGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.getActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyId` | `string` | The storey whose active layer to read |
+ */
+export const PluginCoreStoreysLayersGetActiveArgs = z.object({
+  storeyId: z.string(),
+})
+export type PluginCoreStoreysLayersGetActiveArgs = z.infer<
+  typeof PluginCoreStoreysLayersGetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.getActive} — the active layer,
+ * or `null` when the storey is missing or has no active layer.
+ */
+export const PluginCoreStoreysLayersGetActiveResult = PluginCoreStoreyLayer.nullable()
+export type PluginCoreStoreysLayersGetActiveResult = z.infer<
+  typeof PluginCoreStoreysLayersGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to activate |
+ */
+export const PluginCoreStoreysLayersSetActiveArgs = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersSetActiveArgs = z.infer<
+  typeof PluginCoreStoreysLayersSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreStoreysLayersApi.setActive} — the now-active
+ * layer's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the now-active layer |
+ */
+export const PluginCoreStoreysLayersSetActiveResult = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreStoreysLayersSetActiveResult = z.infer<
+  typeof PluginCoreStoreysLayersSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreStoreysLayersApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to update |
+ * | `hidden` | `boolean \| undefined` | New hidden state (unchanged if omitted) |
+ */
+export const PluginCoreStoreysLayersUpdateArgs = z.object({
+  layerId: z.string(),
+  hidden: z.boolean().optional(),
+})
+export type PluginCoreStoreysLayersUpdateArgs = z.infer<
+  typeof PluginCoreStoreysLayersUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreStoreysLayersApi.update} — the updated layer. */
+export const PluginCoreStoreysLayersUpdateResult = PluginCoreStoreyLayer
+export type PluginCoreStoreysLayersUpdateResult = z.infer<
+  typeof PluginCoreStoreysLayersUpdateResult
+>

package/src/api/core/tags.ts

@@ -163,6 +163,40 @@ export abstract class PluginCoreTagsApi {
     componentId: ComponentHandle,
   ): PluginApiReturn<PluginCoreTagsGetTagsForComponentResult>
 
+  /**
+   * List the tags carried by many components in one call.
+   *
+   * The plural of {@linkcode PluginCoreTagsApi.listForComponent}: pass
+   * `componentIds` to read specific components (unknown ids are skipped), or
+   * omit it to read **every** taggable component (Mass/Floor space) in the
+   * project. Each entry carries the component id and its tags — one per tagged
+   * category, with the tag's `color` — so a plugin can color every space by a
+   * chosen category's tag in a single round-trip.
+   *
+   * @param componentIds - Optional `Component.id`s to read; omit for all spaces.
+   * @returns A {@linkcode PluginCoreTagsListForComponentsResult} with a
+   *   `components` array, one entry per component (in input order when
+   *   `componentIds` is given).
+   *
+   * @performance One round-trip for any number of components — use this instead of a `listForComponent` loop.
+   *
+   * @examplePrompt Get the tags of every space with their colors
+   * @examplePrompt List the tags on all rooms so I can color them by Occupancy
+   * @examplePrompt Which tag does each selected space carry?
+   *
+   * # Example
+   * ```ts
+   * const { components } = await snaptrude.core.tags.listForComponents()
+   * for (const c of components) {
+   *   const occupancy = c.tags.find((t) => t.categoryName === "Occupancy")
+   *   if (occupancy) paint(c.componentId, occupancy.color)
+   * }
+   * ```
+   */
+  public abstract listForComponents(
+    componentIds?: ComponentHandle[],
+  ): PluginApiReturn<PluginCoreTagsListForComponentsResult>
+
   /**
    * List the components carrying a given tag or category.
    *
@@ -588,6 +622,48 @@ export type PluginCoreTagsGetTagsForComponentResult = z.infer<
   typeof PluginCoreTagsGetTagsForComponentResult
 >
 
+/**
+ * Arguments for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]?` | Components to read; omit for every taggable component |
+ */
+export const PluginCoreTagsListForComponentsArgs = z.object({
+  componentIds: z.array(ComponentHandle).optional(),
+})
+export type PluginCoreTagsListForComponentsArgs = z.infer<
+  typeof PluginCoreTagsListForComponentsArgs
+>
+
+/**
+ * One component's tags, for {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The component's id |
+ * | `tags` | {@linkcode PluginCoreComponentTag}`[]` | Its tags, one per tagged category (empty when none) |
+ */
+export const PluginCoreComponentTags = z.object({
+  componentId: ComponentHandle,
+  tags: z.array(PluginCoreComponentTag),
+})
+export type PluginCoreComponentTags = z.infer<typeof PluginCoreComponentTags>
+
+/**
+ * Result of {@linkcode PluginCoreTagsApi.listForComponents}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode PluginCoreComponentTags}`[]` | One entry per component |
+ */
+export const PluginCoreTagsListForComponentsResult = z.object({
+  components: z.array(PluginCoreComponentTags),
+})
+export type PluginCoreTagsListForComponentsResult = z.infer<
+  typeof PluginCoreTagsListForComponentsResult
+>
+
 /**
  * Arguments for {@linkcode PluginCoreTagsApi.listComponents}. Provide exactly one
  * of `tagId`, `categoryId`. `untagged` is valid only with `categoryId`.

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

@@ -5,6 +5,11 @@ import { PluginApiReturn } from "../../../types"
  *
  * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
  * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
  */
 export abstract class PluginZoomApi {
   constructor() {}
@@ -12,6 +17,10 @@ export abstract class PluginZoomApi {
   /**
    * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` once the camera has been framed to the scene.
    *
    * @examplePrompt Zoom out so I can see the whole model
@@ -32,6 +41,10 @@ export abstract class PluginZoomApi {
   /**
    * Zoom (fit) the camera to the current selection.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` if there was a selection to frame; `false` if nothing is
    *   selected (no-op).
    *