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

package/src/api/presentation/sheets.ts

@@ -8,8 +8,11 @@ import { PluginApiReturn } from "../../types"
  * These methods require **Present mode to be open** (the documentation editor) —
  * reads return `[]`/`null` and writes throw when it is not.
  *
- * `list`/`get` are reads; `create` adds a sheet and `place` drops a saved view
- * onto a sheet (returning the id of the created canvas shape).
+ * `list`/`get` are reads; the rest mutate and require Present mode to be open:
+ * `create` adds a sheet, `place` drops a saved view onto a sheet as a live
+ * linked view shape, `rename` relabels a sheet, `delete` removes one, `reorder`
+ * moves one in the sheet order, `setActive` navigates to one, and
+ * `updatePlacedView` re-renders placed views to the current model.
  *
  * Accessed via `snaptrude.presentation.sheets`.
  */
@@ -56,56 +59,321 @@ export abstract class PluginPresentationSheetsApi {
   /**
    * Create a new layout sheet.
    *
+   * Optionally sets the paper size and orientation — the same presets as the
+   * sheet header's size dropdown (ANSI A–E, Arch A–E1, ISO A4–A0). When `size`
+   * is omitted the sheet inherits the editor session's last-used size
+   * (initially ANSI B) in landscape, so pass `size` explicitly whenever the
+   * output format matters.
+   *
    * Requires Present mode to be open.
    *
    * @param name - Display name for the new sheet (optional).
+   * @param options - Optional `size` ({@linkcode PluginSheetSize} paper preset)
+   *   and `orientation` ({@linkcode PluginSheetOrientation}; `"landscape"` when
+   *   omitted).
    * @returns The newly created {@linkcode PluginPresentationSheet}.
    * @throws If Present mode is not open.
    *
    * @examplePrompt Create a new sheet called Cover
-   * @examplePrompt Add a layout sheet
-   * @examplePrompt Make a new presentation sheet named Floor Plans
+   * @examplePrompt Add an A3 landscape layout sheet
+   * @examplePrompt Make a new ANSI D presentation sheet named Floor Plans
+   * @examplePrompt Create a portrait A4 sheet
    *
    * # Example
    * ```ts
-   * const sheet = await snaptrude.presentation.sheets.create("Cover")
+   * const sheet = await snaptrude.presentation.sheets.create("Cover", {
+   *   size: "ISO_A3",
+   *   orientation: "landscape",
+   * })
    * ```
    */
   public abstract create(
     name?: string,
+    options?: { size?: PluginSheetSize; orientation?: PluginSheetOrientation },
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Set a sheet's paper size and/or orientation.
+   *
+   * Applies one of the standard paper presets — exactly what the sheet header's
+   * size dropdown and orientation toggle do. Content that no longer fits inside
+   * the resized sheet is moved out onto the canvas (matching the native
+   * behavior). Undoable. Does not change the user's remembered default size for
+   * new sheets.
+   *
+   * Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to resize.
+   * @param size - The paper preset ({@linkcode PluginSheetSize}).
+   * @param orientation - Optional {@linkcode PluginSheetOrientation}; keeps the
+   *   sheet's current orientation when omitted.
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Resize sheet_1 to A1
+   * @examplePrompt Make the cover sheet ANSI B portrait
+   * @examplePrompt Change this sheet to Arch D landscape
+   * @examplePrompt Set the sheet size to A3
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.setSize("sheet_1", "ISO_A1", "portrait")
+   * ```
+   */
+  public abstract setSize(
+    sheetId: string,
+    size: PluginSheetSize,
+    orientation?: PluginSheetOrientation,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Set a sheet's print margin.
+   *
+   * Applies one of the canonical margin presets — exactly what the sheet
+   * header's margin dropdown does. `margin` is unit-agnostic: `0 | 0.25 |
+   * 0.5 | 0.75 | 1`, displayed as None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial
+   * projects and None / 5mm / 10mm / 15mm / 20mm on metric ones. One undo
+   * step. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet.
+   * @param margin - The margin preset ({@linkcode PluginSheetMargin}).
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Set the sheet margin to half an inch
+   * @examplePrompt Remove the margins on sheet_1
+   * @examplePrompt Give the cover sheet a 10mm margin
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.setMargin("sheet_1", 0.5)
+   * ```
+   */
+  public abstract setMargin(
+    sheetId: string,
+    margin: PluginSheetMargin,
   ): PluginApiReturn<PluginPresentationSheet>
 
   /**
    * Place a saved view onto a sheet.
    *
-   * Drops the given view onto the sheet at an optional position and returns the
-   * id of the created canvas shape. Requires Present mode to be open.
+   * Drops the given view onto the sheet through the **native view drop** — the
+   * placed shape is a live linked view (the same shape the Present views panel's
+   * drag-drop creates), re-rendered from the current model, so
+   * {@linkcode PluginPresentationSheetsApi.updatePlacedView} refreshes it later.
+   * 2D and site-plan views are placed at an architectural scale: the closest
+   * standard scale by default (the native auto-fit), or the explicit `scale`
+   * when given — one of the standard values the placed view's Scale dropdown
+   * offers for the project's unit system (metric `10, 20, 50, 100, 150, 200,
+   * 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96` for 1/8″ = 1′,
+   * `120` for 1″ = 10′). 3D views have no scale — passing `scale` for one
+   * throws. Requires Present mode to be open.
    *
    * @param sheetId - The id of the sheet to place onto.
    * @param viewId - The id of the saved view to place.
    * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
-   *   where to place it (a default is used when omitted).
+   *   where to place it (sheet centre when omitted) — and `scale` — a standard
+   *   scale value for the project's unit system (2D/site-plan views only;
+   *   auto-fit when omitted).
    * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
    *   `shapeId`.
-   * @throws If Present mode is not open, or the sheet/view id is invalid.
+   * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
+   *   is not a standard value for the project's unit system, or `scale` is
+   *   passed for a 3D view.
    *
    * @examplePrompt Place the floor plan on Sheet 1
    * @examplePrompt Add this 3D view to the cover sheet
    * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
-   * @examplePrompt Put the Ground Floor view on sheet_1
+   * @examplePrompt Put the Ground Floor view on sheet_1 at 1:100 scale
+   * @examplePrompt Place the plan on the cover sheet at quarter-inch scale
    *
    * # Example
    * ```ts
-   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123")
+   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123", {
+   *   scale: 100, // 1:100 (metric project)
+   * })
    * ```
    */
   public abstract place(
     sheetId: string,
     viewId: string,
-    options?: { position?: PluginSheetPosition },
+    options?: { position?: PluginSheetPosition; scale?: number },
   ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
+
+  /**
+   * Rename a layout sheet.
+   *
+   * Sets the sheet's display name — the same label the sheets panel shows and
+   * that `list`/`get` read back. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Rename sheet_1 to Cover
+   * @examplePrompt Call the first sheet Ground Floor
+   * @examplePrompt Change this sheet's name to Site Plan
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.rename("sheet_1", "Cover")
+   * ```
+   */
+  public abstract rename(
+    sheetId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Delete a layout sheet.
+   *
+   * Removes the sheet (and its placed content) from the presentation and
+   * renumbers the remaining sheets. Requires Present mode to be open. Auto-diagram
+   * sheets cannot be deleted through the API — remove those from the Present UI.
+   *
+   * @param sheetId - The id of the sheet to delete.
+   * @returns The id of the deleted sheet
+   *   (a {@linkcode PluginPresentationSheetsDeleteResult}).
+   * @throws If Present mode is not open, the sheet id is invalid, or the sheet is
+   *   an auto-diagram sheet.
+   *
+   * @examplePrompt Delete sheet_2
+   * @examplePrompt Remove the Cover sheet
+   * @examplePrompt Get rid of the last layout sheet
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.sheets.delete("sheet_2")
+   * ```
+   */
+  public abstract delete(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheetsDeleteResult>
+
+  /**
+   * Move a sheet to a new position in the sheet order.
+   *
+   * Reorders the sheet to the given zero-based `index` (as the sheets panel does
+   * when a sheet is dragged) and renumbers the rest. `index` is clamped to the
+   * valid range. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to move.
+   * @param index - Zero-based target position in the sheet order.
+   * @returns The sheets in their new order
+   *   (a {@linkcode PluginPresentationSheetsListResult}).
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Move sheet_3 to the front
+   * @examplePrompt Make the Cover sheet the first sheet
+   * @examplePrompt Reorder this sheet to position 2
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.reorder("sheet_3", 0)
+   * ```
+   */
+  public abstract reorder(
+    sheetId: string,
+    index: number,
+  ): PluginApiReturn<PluginPresentationSheetsListResult>
+
+  /**
+   * Make a sheet the active sheet.
+   *
+   * Selects the sheet in the sheets panel and navigates the Present canvas to it
+   * (the same as clicking it in the panel). Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to activate.
+   * @returns The now-active {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Go to sheet_1
+   * @examplePrompt Open the Cover sheet
+   * @examplePrompt Switch to the Site Plan sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sheets.setActive("sheet_1")
+   * ```
+   */
+  public abstract setActive(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Refresh placed views to the current model state.
+   *
+   * Re-renders the presentation's placed **views** — the live linked view shapes —
+   * from the current model (the "Update views" action). Views placed with
+   * {@linkcode PluginPresentationSheetsApi.place} are live view shapes too, so
+   * they refresh along with panel-dropped ones. Pass `sheetId` to refresh only
+   * the views on that sheet, or omit it to refresh every placed view. Requires
+   * Present mode to be open.
+   *
+   * @param options - Optional `sheetId` — restrict the refresh to one sheet's
+   *   placed views (all placed views when omitted).
+   * @returns The ids of the placed view shapes submitted for refresh
+   *   (a {@linkcode PluginPresentationSheetsUpdatePlacedViewResult}).
+   * @throws If Present mode is not open, or `sheetId` is given but invalid.
+   *
+   * @examplePrompt Update all the placed views to the latest model
+   * @examplePrompt Refresh the views on sheet_1
+   * @examplePrompt Re-render the placed views after my edits
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView()
+   * ```
+   */
+  public abstract updatePlacedView(options?: {
+    sheetId?: string
+  }): PluginApiReturn<PluginPresentationSheetsUpdatePlacedViewResult>
 }
 
+/**
+ * Standard paper-size presets for layout sheets — identical to the sheet
+ * header's size dropdown in Present mode.
+ */
+export const PluginSheetSize = z.enum([
+  "ANSI_A",
+  "ANSI_B",
+  "ANSI_C",
+  "ANSI_D",
+  "ANSI_E",
+  "ARCH_A",
+  "ARCH_B",
+  "ARCH_C",
+  "ARCH_D",
+  "ARCH_E",
+  "ARCH_E1",
+  "ISO_A4",
+  "ISO_A3",
+  "ISO_A2",
+  "ISO_A1",
+  "ISO_A0",
+])
+export type PluginSheetSize = z.infer<typeof PluginSheetSize>
+
+/** Sheet orientation. */
+export const PluginSheetOrientation = z.enum(["landscape", "portrait"])
+export type PluginSheetOrientation = z.infer<typeof PluginSheetOrientation>
+
+/**
+ * Canonical sheet margin presets — unit-agnostic values matching the sheet
+ * header's margin dropdown: `0` (None), `0.25`, `0.5`, `0.75`, `1`.
+ * Displayed as None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial projects and
+ * None / 5mm / 10mm / 15mm / 20mm on metric ones.
+ */
+export const PluginSheetMargin = z.union([
+  z.literal(0),
+  z.literal(0.25),
+  z.literal(0.5),
+  z.literal(0.75),
+  z.literal(1),
+])
+export type PluginSheetMargin = z.infer<typeof PluginSheetMargin>
+
 /**
  * A layout sheet in the presentation.
  *
@@ -113,10 +381,16 @@ export abstract class PluginPresentationSheetsApi {
  * |---|---|---|
  * | `id` | `string` | Unique sheet id |
  * | `name` | `string` | Display name |
+ * | `size` | {@linkcode PluginSheetSize}` \| null` | Paper preset (`null` for a legacy sheet without one) |
+ * | `orientation` | {@linkcode PluginSheetOrientation}` \| null` | Orientation (`null` for a legacy sheet) |
+ * | `margin` | {@linkcode PluginSheetMargin}` \| null` | Margin preset (`null` when absent/unrecognized) |
  */
 export const PluginPresentationSheet = z.object({
   id: z.string(),
   name: z.string(),
+  size: PluginSheetSize.nullable(),
+  orientation: PluginSheetOrientation.nullable(),
+  margin: PluginSheetMargin.nullable(),
 })
 export type PluginPresentationSheet = z.infer<typeof PluginPresentationSheet>
 
@@ -160,11 +434,32 @@ export type PluginPresentationSheetsGetResult = z.infer<
 /** Arguments for {@linkcode PluginPresentationSheetsApi.create}. */
 export const PluginPresentationSheetsCreateArgs = z.object({
   name: z.string().optional(),
+  size: PluginSheetSize.optional(),
+  orientation: PluginSheetOrientation.optional(),
 })
 export type PluginPresentationSheetsCreateArgs = z.infer<
   typeof PluginPresentationSheetsCreateArgs
 >
 
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setSize}. */
+export const PluginPresentationSheetsSetSizeArgs = z.object({
+  sheetId: z.string(),
+  size: PluginSheetSize,
+  orientation: PluginSheetOrientation.optional(),
+})
+export type PluginPresentationSheetsSetSizeArgs = z.infer<
+  typeof PluginPresentationSheetsSetSizeArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setMargin}. */
+export const PluginPresentationSheetsSetMarginArgs = z.object({
+  sheetId: z.string(),
+  margin: PluginSheetMargin,
+})
+export type PluginPresentationSheetsSetMarginArgs = z.infer<
+  typeof PluginPresentationSheetsSetMarginArgs
+>
+
 /**
  * Arguments for {@linkcode PluginPresentationSheetsApi.place}.
  *
@@ -172,12 +467,14 @@ export type PluginPresentationSheetsCreateArgs = z.infer<
  * |---|---|---|
  * | `sheetId` | `string` | The sheet to place onto |
  * | `viewId` | `string` | The saved view to place |
- * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (a default is used when omitted) |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (sheet centre when omitted) |
+ * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted) |
  */
 export const PluginPresentationSheetsPlaceArgs = z.object({
   sheetId: z.string(),
   viewId: z.string(),
   position: PluginSheetPosition.optional(),
+  scale: z.number().positive().optional(),
 })
 export type PluginPresentationSheetsPlaceArgs = z.infer<
   typeof PluginPresentationSheetsPlaceArgs
@@ -196,3 +493,93 @@ export const PluginPresentationSheetsPlaceResult = z.object({
 export type PluginPresentationSheetsPlaceResult = z.infer<
   typeof PluginPresentationSheetsPlaceResult
 >
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationSheetsRenameArgs = z.object({
+  sheetId: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationSheetsRenameArgs = z.infer<
+  typeof PluginPresentationSheetsRenameArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.delete}. */
+export const PluginPresentationSheetsDeleteArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsDeleteArgs = z.infer<
+  typeof PluginPresentationSheetsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted sheet |
+ */
+export const PluginPresentationSheetsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationSheetsDeleteResult = z.infer<
+  typeof PluginPresentationSheetsDeleteResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.reorder}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to move |
+ * | `index` | `number` | Zero-based target position (clamped to range) |
+ */
+export const PluginPresentationSheetsReorderArgs = z.object({
+  sheetId: z.string(),
+  index: z.number().int().min(0),
+})
+export type PluginPresentationSheetsReorderArgs = z.infer<
+  typeof PluginPresentationSheetsReorderArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setActive}. */
+export const PluginPresentationSheetsSetActiveArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsSetActiveArgs = z.infer<
+  typeof PluginPresentationSheetsSetActiveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string`? | Restrict the refresh to one sheet's placed views |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationSheetsUpdatePlacedViewArgs = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the placed view shapes submitted for refresh |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationSheetsUpdatePlacedViewResult = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewResult
+>

package/src/api/presentation/slideshow.ts

@@ -0,0 +1,134 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation slideshow — run the Present-mode slideshow programmatically.
+ *
+ * The scriptable counterpart of the Present toolbar's slideshow: the
+ * slideshow plays **all** layout sheets in sheet order (hidden sheets are
+ * excluded) — `start` options only pick the slide it opens on. Slide
+ * navigation stays with the user (arrow keys / on-screen controls); there is
+ * intentionally no `next`/`prev`/`goTo`.
+ *
+ * **Fullscreen caveat:** browsers only grant fullscreen on a user gesture. A
+ * plugin-triggered `start` usually fails that check, in which case the
+ * slideshow catches the rejection and runs non-fullscreen (same slides, same
+ * controls, windowed).
+ *
+ * `start`/`stop` are write-gated; `getState` is a never-throw read. Requires
+ * Present mode to be open (except `getState`, which reports not-running).
+ *
+ * Accessed via `snaptrude.presentation.slideshow`.
+ */
+export abstract class PluginPresentationSlideshowApi {
+  constructor() {}
+
+  /**
+   * Start the slideshow.
+   *
+   * Launches the Present-mode slideshow over all layout sheets in sheet
+   * order. `options.startIndex` opens on that slide (clamped into range);
+   * otherwise `options.sheetIds` naming exactly one sheet opens on that
+   * sheet; otherwise it opens on the first slide. May run non-fullscreen —
+   * see the fullscreen caveat on
+   * {@linkcode PluginPresentationSlideshowApi}. Requires Present mode to be
+   * open with at least one sheet.
+   *
+   * @param options - Optional `sheetIds` (open on this sheet when exactly one
+   *   id is given) and `startIndex` (0-based slide to open on; wins over
+   *   `sheetIds`; clamped into range).
+   * @returns The {@linkcode PluginPresentationSlideshowState} after the
+   *   launch (`running: true` and the opening `index`).
+   * @throws If Present mode is not open or there are no sheets to present.
+   *
+   * @examplePrompt Start the slideshow
+   * @examplePrompt Present the sheets from the beginning
+   * @examplePrompt Start the slideshow on sheet 3
+   * @examplePrompt Play the presentation starting at the cover sheet
+   *
+   * # Example
+   * ```ts
+   * const state = await snaptrude.presentation.slideshow.start({ startIndex: 2 })
+   * console.log(state.running, state.index) // true, 2
+   * ```
+   */
+  public abstract start(options?: {
+    sheetIds?: string[]
+    startIndex?: number
+  }): PluginApiReturn<PluginPresentationSlideshowState>
+
+  /**
+   * Stop the slideshow.
+   *
+   * Closes the running slideshow (exiting fullscreen if it entered it) and
+   * returns to the Present canvas. A no-op when no slideshow is running.
+   *
+   * @returns The {@linkcode PluginPresentationSlideshowState} after the stop
+   *   (`running: false`).
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Stop the slideshow
+   * @examplePrompt Exit the presentation
+   * @examplePrompt Close the slideshow and go back to the sheets
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.slideshow.stop()
+   * ```
+   */
+  public abstract stop(): PluginApiReturn<PluginPresentationSlideshowState>
+
+  /**
+   * Read the slideshow state.
+   *
+   * A never-throw read: reports whether a slideshow is running and, when it
+   * is, the current 0-based slide index (`index` is `null` when not
+   * running — including when Present mode is closed).
+   *
+   * @returns The current {@linkcode PluginPresentationSlideshowState}.
+   *
+   * @examplePrompt Is the slideshow running?
+   * @examplePrompt Which slide is the presentation on?
+   * @examplePrompt Check the slideshow state
+   *
+   * # Example
+   * ```ts
+   * const { running, index } = await snaptrude.presentation.slideshow.getState()
+   * ```
+   */
+  public abstract getState(): PluginApiReturn<PluginPresentationSlideshowState>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationSlideshowApi.start}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetIds` | `string[] \| undefined` | Open on this sheet when exactly one id is given |
+ * | `startIndex` | `number \| undefined` | 0-based slide to open on (wins over `sheetIds`; clamped) |
+ */
+export const PluginPresentationSlideshowStartArgs = z.object({
+  sheetIds: z.array(z.string().min(1)).optional(),
+  startIndex: z.number().int().min(0).optional(),
+})
+export type PluginPresentationSlideshowStartArgs = z.infer<
+  typeof PluginPresentationSlideshowStartArgs
+>
+
+/**
+ * The slideshow state — result of {@linkcode PluginPresentationSlideshowApi.start},
+ * {@linkcode PluginPresentationSlideshowApi.stop}, and
+ * {@linkcode PluginPresentationSlideshowApi.getState}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `running` | `boolean` | Whether a slideshow is currently running |
+ * | `index` | `number \| null` | Current 0-based slide index (`null` when not running) |
+ */
+export const PluginPresentationSlideshowState = z.object({
+  running: z.boolean(),
+  index: z.number().int().nullable(),
+})
+export type PluginPresentationSlideshowState = z.infer<
+  typeof PluginPresentationSlideshowState
+>