@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/presentation/slideshow.ts

@@ -1,134 +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
->
+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
+>

package/src/api/presentation/tables.ts

@@ -1,84 +1,84 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import type { PluginCanvasShape } from "./placedViews"
-
-/**
- * Presentation tables — place data tables on Present-mode sheets.
- *
- * The scriptable counterpart of the Present canvas's table paste (the flow
- * that turns a Program-mode / Google Sheets / Excel paste into a table
- * shape): {@linkcode PluginPresentationTablesApi.place} takes plain string
- * rows and creates one table shape on a sheet. Requires Present mode to be
- * open.
- *
- * Accessed via `snaptrude.presentation.tables`.
- */
-export abstract class PluginPresentationTablesApi {
-  constructor() {}
-
-  /**
-   * Place a table on a sheet.
-   *
-   * Creates one table shape from `table.rows` — the same shape the Present
-   * canvas creates when a spreadsheet table is pasted — and returns the
-   * created shape as a canvas-shape record. Cells are plain strings; rows may
-   * be ragged (each row needs at least one cell), capped at 10000 cells
-   * total. `options.position` is sheet-local (relative to the sheet's
-   * top-left, in canvas units — the same convention as `annotate.*`); when
-   * omitted the table lands where the paste flow would auto-place it (the
-   * center of the current viewport). One undo step. Requires Present mode to
-   * be open.
-   *
-   * @param sheetId - The sheet to place the table on.
-   * @param table - The table content: `rows`, an array of string-cell rows.
-   * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
-   *   top-left — defaults to the paste flow's auto-placement).
-   * @returns The created table shape as a {@linkcode PluginCanvasShape}.
-   * @throws If Present mode is not open, the sheet id is invalid, or the
-   *   table is empty / exceeds the 10000-cell cap.
-   *
-   * @examplePrompt Put the area schedule as a table on Sheet 1
-   * @examplePrompt Add a table of the room programs to the cover sheet
-   * @examplePrompt Paste this data as a table on the sheet
-   * @examplePrompt Place a two-column table of space names and areas
-   *
-   * # Example
-   * ```ts
-   * const shape = await snaptrude.presentation.tables.place("sheet_1", {
-   *   rows: [
-   *     ["Room", "Area"],
-   *     ["Kitchen", "12.4 m²"],
-   *     ["Living", "28.0 m²"],
-   *   ],
-   * }, { position: { x: 40, y: 40 } })
-   * ```
-   */
-  public abstract place(
-    sheetId: string,
-    table: { rows: string[][] },
-    options?: { position?: { x: number; y: number } },
-  ): PluginApiReturn<PluginCanvasShape>
-}
-
-/**
- * Arguments for {@linkcode PluginPresentationTablesApi.place}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to place the table on |
- * | `rows` | `string[][]` | Table cells as string rows (non-empty; ≤ 10000 cells total) |
- * | `position` | `{ x: number; y: number } \| undefined` | Sheet-local position (default: paste auto-placement) |
- */
-export const PluginPresentationTablesPlaceArgs = z.object({
-  sheetId: z.string().min(1),
-  rows: z
-    .array(z.array(z.string()).min(1))
-    .min(1)
-    .refine((rows) => rows.reduce((n, r) => n + r.length, 0) <= 10000, {
-      message: "table exceeds the 10000-cell cap",
-    }),
-  position: z.object({ x: z.number(), y: z.number() }).optional(),
-})
-export type PluginPresentationTablesPlaceArgs = z.infer<
-  typeof PluginPresentationTablesPlaceArgs
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import type { PluginCanvasShape } from "./placedViews"
+
+/**
+ * Presentation tables — place data tables on Present-mode sheets.
+ *
+ * The scriptable counterpart of the Present canvas's table paste (the flow
+ * that turns a Program-mode / Google Sheets / Excel paste into a table
+ * shape): {@linkcode PluginPresentationTablesApi.place} takes plain string
+ * rows and creates one table shape on a sheet. Requires Present mode to be
+ * open.
+ *
+ * Accessed via `snaptrude.presentation.tables`.
+ */
+export abstract class PluginPresentationTablesApi {
+  constructor() {}
+
+  /**
+   * Place a table on a sheet.
+   *
+   * Creates one table shape from `table.rows` — the same shape the Present
+   * canvas creates when a spreadsheet table is pasted — and returns the
+   * created shape as a canvas-shape record. Cells are plain strings; rows may
+   * be ragged (each row needs at least one cell), capped at 10000 cells
+   * total. `options.position` is sheet-local (relative to the sheet's
+   * top-left, in canvas units — the same convention as `annotate.*`); when
+   * omitted the table lands where the paste flow would auto-place it (the
+   * center of the current viewport). One undo step. Requires Present mode to
+   * be open.
+   *
+   * @param sheetId - The sheet to place the table on.
+   * @param table - The table content: `rows`, an array of string-cell rows.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
+   *   top-left — defaults to the paste flow's auto-placement).
+   * @returns The created table shape as a {@linkcode PluginCanvasShape}.
+   * @throws If Present mode is not open, the sheet id is invalid, or the
+   *   table is empty / exceeds the 10000-cell cap.
+   *
+   * @examplePrompt Put the area schedule as a table on Sheet 1
+   * @examplePrompt Add a table of the room programs to the cover sheet
+   * @examplePrompt Paste this data as a table on the sheet
+   * @examplePrompt Place a two-column table of space names and areas
+   *
+   * # Example
+   * ```ts
+   * const shape = await snaptrude.presentation.tables.place("sheet_1", {
+   *   rows: [
+   *     ["Room", "Area"],
+   *     ["Kitchen", "12.4 m²"],
+   *     ["Living", "28.0 m²"],
+   *   ],
+   * }, { position: { x: 40, y: 40 } })
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    table: { rows: string[][] },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginCanvasShape>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationTablesApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place the table on |
+ * | `rows` | `string[][]` | Table cells as string rows (non-empty; ≤ 10000 cells total) |
+ * | `position` | `{ x: number; y: number } \| undefined` | Sheet-local position (default: paste auto-placement) |
+ */
+export const PluginPresentationTablesPlaceArgs = z.object({
+  sheetId: z.string().min(1),
+  rows: z
+    .array(z.array(z.string()).min(1))
+    .min(1)
+    .refine((rows) => rows.reduce((n, r) => n + r.length, 0) <= 10000, {
+      message: "table exceeds the 10000-cell cap",
+    }),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationTablesPlaceArgs = z.infer<
+  typeof PluginPresentationTablesPlaceArgs
+>

package/src/api/presentation/viewPresets.ts

@@ -0,0 +1,241 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+/** Presets are document-local. Their ids are stable across reload; built-ins are immutable. */
+export const PluginViewPreset = z.object({
+  id: z.string(),
+  name: z.string(),
+  builtIn: z.boolean(),
+  revision: z.number().int().nonnegative(),
+})
+export type PluginViewPreset = z.infer<typeof PluginViewPreset>
+export const PluginViewPresetIdArgs = z
+  .object({ presetId: z.string().min(1) })
+  .strict()
+export type PluginViewPresetIdArgs = z.infer<typeof PluginViewPresetIdArgs>
+export const PluginViewPresetCreateArgs = z
+  .object({ name: z.string().trim().min(1), fromDrawingId: z.string().min(1) })
+  .strict()
+export type PluginViewPresetCreateArgs = z.infer<
+  typeof PluginViewPresetCreateArgs
+>
+export const PluginViewPresetRenameArgs = PluginViewPresetIdArgs.extend({
+  name: z.string().trim().min(1),
+})
+export type PluginViewPresetRenameArgs = z.infer<
+  typeof PluginViewPresetRenameArgs
+>
+export const PluginViewPresetUpdateArgs = PluginViewPresetIdArgs.extend({
+  fromDrawingId: z.string().min(1),
+})
+export type PluginViewPresetUpdateArgs = z.infer<
+  typeof PluginViewPresetUpdateArgs
+>
+export const PluginViewPresetDeleteArgs = PluginViewPresetIdArgs.extend({
+  replacementId: z.string().min(1),
+})
+export type PluginViewPresetDeleteArgs = z.infer<
+  typeof PluginViewPresetDeleteArgs
+>
+
+/**
+ * Reusable styles for kernel-plan drawings, stored in the Present document.
+ *
+ * A preset holds every style category of a native kernel plan. A drawing is
+ * bound to one with {@linkcode PluginPresentationDrawingsApi.applyPreset}; its
+ * own style changes are overrides on top, dropped by
+ * {@linkcode PluginPresentationDrawingsApi.resetOverrides}. Presets apply only
+ * to drawings whose `drawings.getCapabilities(drawingId).presets` is `true`.
+ * Local title text is excluded from preset values.
+ *
+ * Presets are document-local; their ids survive reload. Built-in presets are
+ * immutable. Catalog writes (`create`, `copy`, `rename`, `update`, `delete`)
+ * are native document metadata and are **not undoable**; binding a drawing or
+ * changing its overrides uses Present undo. Every method requires **Present
+ * mode to be open** and throws `PRECONDITION_FAILED` ("Present mode is not
+ * open") when it is closed; no method switches tabs.
+ *
+ * Accessed via `snaptrude.presentation.viewPresets`.
+ */
+export abstract class PluginPresentationViewPresetsApi {
+  /**
+   * List the preset catalog: built-ins first, then custom presets by name.
+   *
+   * @returns Every {@linkcode PluginViewPreset}.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open.
+   *
+   * @examplePrompt List the available drawing style presets
+   * @examplePrompt Which custom presets does this presentation have?
+   * @examplePrompt Is there a Planning Issue preset?
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.presentation.viewPresets.list()
+   * const custom = presets.filter((preset) => !preset.builtIn)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginViewPreset[]>
+
+  /**
+   * Read one preset by id.
+   *
+   * @param presetId - The preset to read.
+   * @returns The {@linkcode PluginViewPreset}, or `null` if no preset has that id.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open.
+   *
+   * @examplePrompt Which preset is this drawing using?
+   * @examplePrompt Is this preset a built-in one?
+   * @examplePrompt Read the preset bound to the ground floor plan
+   *
+   * # Example
+   * ```ts
+   * const drawing = await snaptrude.presentation.drawings.get(drawingId)
+   * const preset = drawing?.presetId
+   *   ? await snaptrude.presentation.viewPresets.get(drawing.presetId)
+   *   : null
+   * ```
+   */
+  public abstract get(
+    presetId: string,
+  ): PluginApiReturn<PluginViewPreset | null>
+
+  /**
+   * Save a kernel-plan drawing's effective styles as a new custom preset and
+   * bind that drawing to it. Not undoable (catalog write).
+   *
+   * @param name - A unique preset name (non-empty after trimming).
+   * @param options - `fromDrawingId`: the kernel-plan drawing to take styles from.
+   * @returns The new {@linkcode PluginViewPreset}.
+   * @throws `VALIDATION` for an empty or duplicate name (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open, the document is
+   *   read-only, or the drawing is not a kernel vector plan (each with a
+   *   hint); `HANDLE_INVALID` if `fromDrawingId` is not a drawing.
+   *
+   * @examplePrompt Save this drawing's styles as a new preset
+   * @examplePrompt Make a preset called Planning Issue from this plan
+   * @examplePrompt Turn my restyled drawing into a reusable style
+   *
+   * # Example
+   * ```ts
+   * const capabilities = await snaptrude.presentation.drawings.getCapabilities(drawing.id)
+   * if (capabilities.presets) {
+   *   const preset = await snaptrude.presentation.viewPresets.create("Planning Issue", {
+   *     fromDrawingId: drawing.id,
+   *   })
+   * }
+   * ```
+   */
+  public abstract create(
+    name: string,
+    options: { fromDrawingId: string },
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Duplicate a preset under a native-generated unique name. Drawing bindings
+   * do not change. Not undoable (catalog write). Built-ins can be copied.
+   *
+   * @param presetId - The preset to copy.
+   * @returns The new custom {@linkcode PluginViewPreset}.
+   * @throws `PRECONDITION_FAILED` if Present mode is not open or the document
+   *   is read-only (each with a hint); `HANDLE_INVALID` if `presetId` does not
+   *   exist.
+   *
+   * @examplePrompt Duplicate this preset
+   * @examplePrompt Make an editable copy of the built-in preset
+   * @examplePrompt Copy the Planning Issue preset so I can change it
+   *
+   * # Example
+   * ```ts
+   * const copy = await snaptrude.presentation.viewPresets.copy(preset.id)
+   * await snaptrude.presentation.viewPresets.rename(copy.id, "Planning Issue B")
+   * ```
+   */
+  public abstract copy(presetId: string): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Rename a custom preset. Names must stay unique; built-ins cannot be
+   * renamed. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to rename.
+   * @param name - The new unique name (non-empty after trimming).
+   * @returns The renamed {@linkcode PluginViewPreset}.
+   * @throws `VALIDATION` when the catalog refuses: an empty or duplicate name,
+   *   a built-in preset, or an unknown `presetId` (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open or the document is
+   *   read-only (each with a hint).
+   *
+   * @examplePrompt Rename this preset to Client Review
+   * @examplePrompt Call the copied preset Planning Issue B
+   * @examplePrompt Change the name of my custom drawing style
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.viewPresets.rename(preset.id, "Client Review")
+   * ```
+   */
+  public abstract rename(
+    presetId: string,
+    name: string,
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Replace a custom preset's values with the effective styles of a drawing
+   * already bound to it, then refresh every bound drawing. Built-ins cannot
+   * be updated. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to update.
+   * @param options - `fromDrawingId`: a kernel-plan drawing bound to this preset.
+   * @returns The updated {@linkcode PluginViewPreset} (its `revision` grows).
+   * @throws `VALIDATION` when the catalog refuses: a built-in preset (with a
+   *   hint); `PRECONDITION_FAILED` if Present mode is not open, the document
+   *   is read-only, or the drawing is not a kernel vector plan bound to this
+   *   preset (each with a hint); `HANDLE_INVALID` if `fromDrawingId` is not a
+   *   drawing.
+   *
+   * @examplePrompt Update this preset from the current drawing styles
+   * @examplePrompt Push my style changes to every drawing using this preset
+   * @examplePrompt Save these overrides into the Planning Issue preset
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.viewPresets.update(drawing.presetId!, {
+   *   fromDrawingId: drawing.id,
+   * })
+   * ```
+   */
+  public abstract update(
+    presetId: string,
+    options: { fromDrawingId: string },
+  ): PluginApiReturn<PluginViewPreset>
+
+  /**
+   * Delete a custom preset and rebind its drawings to another existing
+   * preset. Built-ins cannot be deleted. Not undoable (catalog write).
+   *
+   * @param presetId - The custom preset to delete.
+   * @param options - `replacementId`: the existing preset its drawings move to
+   *   (not the deleted one).
+   * @returns Nothing.
+   * @throws `VALIDATION` when the catalog refuses: a built-in or unknown
+   *   `presetId`, or an unknown `replacementId` (with a hint);
+   *   `PRECONDITION_FAILED` if Present mode is not open or the document is
+   *   read-only (each with a hint).
+   *
+   * @examplePrompt Delete this preset
+   * @examplePrompt Remove the old style preset and switch its drawings to the default
+   * @examplePrompt Get rid of the Planning Issue B preset
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.presentation.viewPresets.list()
+   * const replacement = presets.find((each) => each.builtIn)!
+   * await snaptrude.presentation.viewPresets.delete(customPreset.id, {
+   *   replacementId: replacement.id,
+   * })
+   * ```
+   */
+  public abstract delete(
+    presetId: string,
+    options: { replacementId: string },
+  ): PluginApiReturn<void>
+}