@snaptrude/plugin-core 0.10.0 → 1.0.0

package/src/api/presentation/standards.ts

@@ -0,0 +1,445 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+import {
+  PluginGraphicsAnnotationCategory,
+  PluginGraphicsCategory,
+  PluginGraphicsLineStyleId,
+  PluginGraphicsModelCategory,
+  PluginGraphicsOverrideCategory,
+  PluginGraphicsPatternId,
+  PluginGraphicsPen,
+  PluginGraphicsScale,
+  PluginGraphicsViewId,
+  PluginGraphicsViewKind,
+} from "./graphics"
+
+/** All widths and annotation geometry here are paper millimetres, in either project unit system. */
+export const PluginStandardUnits = z.enum(["METRIC", "IMPERIAL"])
+export const PluginStandardWidth = z.union([
+  z.literal(0),
+  z.number().finite().min(0.02).max(12.7),
+])
+const PenKey = z.string().regex(/^(?:[1-9]|1[0-6])$/)
+const ScaleKey = z.string().refine((key) => {
+  const value = Number(key)
+  return (
+    String(value) === key &&
+    Number.isInteger(value) &&
+    value >= 1 &&
+    value <= 24000
+  )
+}, "Use a canonical integer scale denominator from 1 to 24000")
+const Color = z.string().regex(/^#[0-9a-f]{6}$/i)
+const TextSize = z.number().finite().min(0.5).max(25)
+const HeadRadius = z.number().finite().min(2).max(25)
+const DimensionLength = z.number().finite().min(0).max(10)
+const TickLength = z.number().finite().min(0.5).max(6)
+const Background = z.enum(["opaque", "transparent"])
+
+/** Stored sparse line-weight tables; a missing cell inherits the pinned stock. */
+const StoredLineWeights = z
+  .object({
+    model: z.record(ScaleKey, z.record(PenKey, PluginStandardWidth)).optional(),
+    annotation: z.record(PenKey, PluginStandardWidth).optional(),
+    perspective: z.record(PenKey, PluginStandardWidth).optional(),
+    columns: z
+      .object({
+        added: z.array(PluginGraphicsScale).optional(),
+        deleted: z.array(PluginGraphicsScale).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+const StoredObjectStyle = z
+  .object({
+    projection: PluginGraphicsPen.optional(),
+    cut: PluginGraphicsPen.optional(),
+    color: Color.optional(),
+  })
+  .strict()
+const StoredText = z
+  .object({
+    Dimension: z.object({ textMm: TextSize.optional() }).strict().optional(),
+    Grids: z
+      .object({
+        textMm: TextSize.optional(),
+        bubbleRadiusMm: HeadRadius.optional(),
+      })
+      .strict()
+      .optional(),
+    Space: z
+      .object({
+        nameTextMm: TextSize.optional(),
+        areaTextMm: TextSize.optional(),
+      })
+      .strict()
+      .optional(),
+    Sections: z
+      .object({
+        textMm: TextSize.optional(),
+        headRadiusMm: HeadRadius.optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+const StoredDimension = z
+  .object({
+    tickMm: TickLength.optional(),
+    witnessGapMm: DimensionLength.optional(),
+    witnessExtensionMm: DimensionLength.optional(),
+    lineExtensionMm: DimensionLength.optional(),
+    textOffsetMm: DimensionLength.optional(),
+    textBackground: Background.optional(),
+  })
+  .strict()
+const StoredLineStyle = z
+  .object({
+    weight: PluginGraphicsPen.optional(),
+    pattern: PluginGraphicsPatternId.optional(),
+  })
+  .strict()
+
+/**
+ * The project's stored sparse graphic standard. stockId is read-only through
+ * the API: update never accepts it. The native commit pins a stock when needed;
+ * native standard-file import preserves a validated file's stock choice.
+ * Omitted values inherit stock defaults; all numeric lengths are paper mm.
+ */
+export const PluginGraphicStandard = z
+  .object({
+    stockId: z.string().optional(),
+    lineWeights: StoredLineWeights.optional(),
+    objectStyles: z
+      .partialRecord(PluginGraphicsCategory, StoredObjectStyle)
+      .optional(),
+    annotationText: StoredText.optional(),
+    // Reads retain retired stored ids (e.g. property-line); update accepts current ids only.
+    lineStyles: z.record(z.string(), StoredLineStyle).optional(),
+    dimensionStyle: StoredDimension.optional(),
+  })
+  .strict()
+export type PluginGraphicStandard = z.infer<typeof PluginGraphicStandard>
+
+/**
+ * Column operations for one standard update, not the stored added/deleted lists.
+ * Added columns copy the currently resolved column. Only listed scales can be
+ * columns; at least one column must remain. reset restores a whole column,
+ * including an added column whose individual cells have no stock default.
+ */
+export const PluginStandardColumnPatch = z
+  .object({
+    add: z.array(PluginGraphicsScale).optional(),
+    delete: z.array(PluginGraphicsScale).optional(),
+    reset: z.array(PluginGraphicsScale).optional(),
+  })
+  .strict()
+  .superRefine((ops, ctx) => {
+    const used = new Set<number>()
+    for (const field of ["add", "delete", "reset"] as const) {
+      for (const scale of new Set(ops[field] ?? [])) {
+        if (used.has(scale)) {
+          ctx.addIssue({
+            code: "custom",
+            path: [field],
+            message: "A column cannot have conflicting operations in one patch",
+          })
+        }
+        used.add(scale)
+      }
+    }
+  })
+export type PluginStandardColumnPatch = z.infer<
+  typeof PluginStandardColumnPatch
+>
+
+const ObjectStylePatch = z
+  .object({
+    projection: PluginGraphicsPen.nullable().optional(),
+    cut: PluginGraphicsPen.nullable().optional(),
+    color: Color.nullable().optional(),
+  })
+  .strict()
+const ObjectStylesPatch = z
+  .partialRecord(PluginGraphicsCategory, ObjectStylePatch)
+  .superRefine((rows, ctx) => {
+    for (const category of PluginGraphicsAnnotationCategory.options) {
+      const row = rows[category]
+      if (row?.cut !== undefined || row?.color !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: [category],
+          message: "Annotation Object Styles have only a projection pen",
+        })
+      }
+    }
+  })
+
+/**
+ * Sparse edits, applied atomically as one native commit. Omitted leaves stay
+ * unchanged; null resets a leaf through its native setter. No stockId field.
+ * In an imperial project, newly edited nonzero widths must be at least 0.0254 mm
+ * (0.001in), even though API values are always paper mm. Native file import has
+ * its own cross-unit normalization and does not convert physical widths.
+ */
+export const PluginGraphicStandardPatch = z
+  .object({
+    lineWeights: z
+      .object({
+        model: z
+          .record(ScaleKey, z.record(PenKey, PluginStandardWidth.nullable()))
+          .optional(),
+        annotation: z.record(PenKey, PluginStandardWidth.nullable()).optional(),
+        perspective: z
+          .record(PenKey, PluginStandardWidth.nullable())
+          .optional(),
+        columns: PluginStandardColumnPatch.optional(),
+      })
+      .strict()
+      .optional(),
+    objectStyles: ObjectStylesPatch.optional(),
+    annotationText: z
+      .object({
+        Dimension: z
+          .object({ textMm: TextSize.nullable().optional() })
+          .strict()
+          .optional(),
+        Grids: z
+          .object({
+            textMm: TextSize.nullable().optional(),
+            bubbleRadiusMm: HeadRadius.nullable().optional(),
+          })
+          .strict()
+          .optional(),
+        Space: z
+          .object({
+            nameTextMm: TextSize.nullable().optional(),
+            areaTextMm: TextSize.nullable().optional(),
+          })
+          .strict()
+          .optional(),
+        Sections: z
+          .object({
+            textMm: TextSize.nullable().optional(),
+            headRadiusMm: HeadRadius.nullable().optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+    lineStyles: z
+      .partialRecord(
+        PluginGraphicsLineStyleId,
+        z
+          .object({
+            weight: PluginGraphicsPen.nullable().optional(),
+            pattern: PluginGraphicsPatternId.nullable().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    dimensionStyle: z
+      .object({
+        tickMm: TickLength.nullable().optional(),
+        witnessGapMm: DimensionLength.nullable().optional(),
+        witnessExtensionMm: DimensionLength.nullable().optional(),
+        lineExtensionMm: DimensionLength.nullable().optional(),
+        textOffsetMm: DimensionLength.nullable().optional(),
+        textBackground: Background.nullable().optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+export type PluginGraphicStandardPatch = z.infer<
+  typeof PluginGraphicStandardPatch
+>
+
+/** Reset tab ids. text resets annotation sizes and dimension geometry together, like the UI. */
+export const PluginGraphicStandardTab = z.enum([
+  "objectStyles",
+  "model",
+  "perspective",
+  "annotation",
+  "text",
+  "lineStyles",
+])
+export type PluginGraphicStandardTab = z.infer<typeof PluginGraphicStandardTab>
+
+/** A pen number with its physical paper width; 0 mm means hidden. */
+const PenWidth = z.object({ pen: PluginGraphicsPen, mm: PluginStandardWidth })
+const ResolvedModelStyle = z.object({
+  projection: PluginGraphicsPen,
+  cut: PluginGraphicsPen.nullable(),
+  projectionMm: PluginStandardWidth,
+  cutMm: PluginStandardWidth,
+  color: Color,
+})
+const ResolvedAnnotationStyle = z.object({
+  projection: PluginGraphicsPen,
+  lineMm: PluginStandardWidth,
+})
+const ResolvedLineStyle = z.object({
+  weight: PluginGraphicsPen,
+  pattern: PluginGraphicsPatternId,
+  mm: PluginStandardWidth,
+})
+
+/**
+ * Native resolved values for a target view/scale. Pens are numbered 1–16;
+ * widths, text, dash lengths and dimension geometry are paper mm. Model pens
+ * use the reported nearest column (finer column wins a tie). Perspective and
+ * annotation pens are scale-free. Category overrides are included where the
+ * native canvas applies them; hidden/halftone are arrays, never engine Sets.
+ * A disabled free3D renderer uses legacy widths, not these configured paper pens.
+ */
+export const PluginResolvedGraphicStandard = z.object({
+  viewId: z.string().nullable(),
+  kind: PluginGraphicsViewKind,
+  units: PluginStandardUnits,
+  stockId: z.string(),
+  scale: PluginGraphicsScale,
+  column: PluginGraphicsScale,
+  columns: z.array(PluginGraphicsScale).min(1),
+  table: z.enum(["model", "perspective"]),
+  featureEnabled: z.boolean(),
+  viewOverridesApplied: z.boolean(),
+  pens: z.object({
+    model: z.array(PenWidth).length(16),
+    perspective: z.array(PenWidth).length(16),
+    annotation: z.array(PenWidth).length(16),
+  }),
+  model: z.record(PluginGraphicsModelCategory, ResolvedModelStyle),
+  annotation: z.record(
+    PluginGraphicsAnnotationCategory,
+    ResolvedAnnotationStyle,
+  ),
+  lines: z.record(PluginGraphicsLineStyleId, ResolvedLineStyle),
+  patterns: z.record(
+    PluginGraphicsPatternId,
+    z.array(z.number().finite().nonnegative()).max(8),
+  ),
+  text: z.object({
+    nameMm: TextSize,
+    areaMm: TextSize,
+    dimensionMm: TextSize,
+    gridTextMm: TextSize,
+    gridBubbleRadiusMm: HeadRadius,
+    sectionTextMm: TextSize,
+    sectionHeadRadiusMm: HeadRadius,
+  }),
+  dimension: z.object({
+    tickMm: TickLength,
+    witnessGapMm: DimensionLength,
+    witnessExtensionMm: DimensionLength,
+    lineExtensionMm: DimensionLength,
+    textOffsetMm: DimensionLength,
+    opaque: z.boolean(),
+  }),
+  hidden: z.array(PluginGraphicsOverrideCategory),
+  halftone: z.array(PluginGraphicsOverrideCategory),
+})
+export type PluginResolvedGraphicStandard = z.infer<
+  typeof PluginResolvedGraphicStandard
+>
+
+/**
+ * Resolve for the current view by default. A supplied denominator previews a
+ * different paper scale without moving the camera or writing the saved view.
+ * The table defaults to model for paper views and perspective for free3D.
+ */
+export const PluginGraphicStandardResolveOptions = z
+  .object({
+    viewId: PluginGraphicsViewId.optional(),
+    scale: PluginGraphicsScale.optional(),
+    table: z.enum(["model", "perspective"]).optional(),
+  })
+  .strict()
+export type PluginGraphicStandardResolveOptions = z.infer<
+  typeof PluginGraphicStandardResolveOptions
+>
+export const PluginGraphicStandardResolveArgs = z
+  .object({ options: PluginGraphicStandardResolveOptions.optional() })
+  .strict()
+export const PluginGraphicStandardUpdateArgs = z
+  .object({ patch: PluginGraphicStandardPatch })
+  .strict()
+export const PluginGraphicStandardResetArgs = z
+  .object({ tab: PluginGraphicStandardTab.optional() })
+  .strict()
+export const PluginGraphicStandardImportArgs = z
+  .object({ text: z.string() })
+  .strict()
+
+/**
+ * Project graphic standards, shared across views and saved through the same
+ * undoable native commit as Object Styles. No team standard access or writes.
+ * Do not write stockId: update refuses it, while the native commit pins the
+ * appropriate stock. Validated file import follows the UI's version/stock rules.
+ * All writes are flag-gated; reads and export remain available with the flag off.
+ */
+export abstract class PluginPresentationStandardsApi {
+  /**
+   * Read the stored sparse standard; omitted fields inherit stock values.
+   * @returns A detached settings record. stockId is read-only through this API.
+   */
+  public abstract get(): PluginApiReturn<PluginGraphicStandard>
+
+  /**
+   * Read the actual native resolution, including applicable view overrides.
+   * No camera, view, preference or project data changes.
+   * @param options - Target view, denominator and optional model/perspective table.
+   * @returns Resolved paper-mm values, or null for an unknown/inaccessible explicit view.
+   * @examplePrompt How thick are the wall cut lines at 1:50?
+   * @example await snaptrude.presentation.standards.getResolved({ scale: 50, table: "model" })
+   */
+  public abstract getResolved(
+    options?: PluginGraphicStandardResolveOptions,
+  ): PluginApiReturn<PluginResolvedGraphicStandard | null>
+
+  /**
+   * Apply only supplied fields as one saved, undoable native commit. Validate
+   * the whole patch first; invalid fields never leave a partial edit behind.
+   * @param patch - Sparse edits; lengths are paper mm, pens are integers 1–16.
+   * @returns The resulting stored sparse standard.
+   * @throws VALIDATION for invalid/unknown fields, imperial minima, invalid
+   *   columns or stockId. PRECONDITION_FAILED while Paper Pens is disabled.
+   * @examplePrompt Make wall cut lines heavier throughout the project
+   * @example await snaptrude.presentation.standards.update({ objectStyles: { Walls: { cut: 6 } } })
+   */
+  public abstract update(
+    patch: PluginGraphicStandardPatch,
+  ): PluginApiReturn<PluginGraphicStandard>
+
+  /**
+   * Reset an editable tab, or all tabs, through the native reset functions.
+   * One saved undo step; stock retention/pruning follows the native commit.
+   * @param tab - Omit for all tabs. text includes dimension geometry.
+   * @returns The resulting stored standard.
+   */
+  public abstract reset(
+    tab?: PluginGraphicStandardTab,
+  ): PluginApiReturn<PluginGraphicStandard>
+
+  /**
+   * Serialize the native standard-file format. No browser download or save.
+   * The file includes its stock/version and stores widths in paper mm.
+   * @returns JSON text suitable for import in another project, including cross-unit import.
+   * @examplePrompt Export the line standard
+   */
+  public abstract export(): PluginApiReturn<string>
+
+  /**
+   * Import native standard-file JSON exactly as the dialog does, replacing the
+   * project standard in one saved undo step. Never edits team preferences.
+   * @param text - File text, at most 1,000,000 UTF-8 bytes.
+   * @returns The resulting stored standard.
+   * @throws VALIDATION with details.reason NOT_A_STANDARD, NEWER_STANDARD or
+   *   STANDARD_TOO_LARGE. PRECONDITION_FAILED with reason PAPER_PENS_DISABLED
+   *   when the feature is off. Existing project data is unchanged on failure.
+   * @examplePrompt Match the line weights in this standard file
+   */
+  public abstract import(text: string): PluginApiReturn<PluginGraphicStandard>
+}

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>
+}