@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

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

@@ -1,234 +1,234 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-// Type-only: src/handles.ts type-only-imports ArenaKind from this file, so the
-// cycle stays purely type-level and is erased at emit.
-import type { AnyArenaHandle } from "../../../handles"
-import { Handle } from "../../../handles"
-
-/**
- * The 13 registry-arena handle kinds — the releasable families. Entity-style
- * handles (component / material / underlay / terrain / importJob / comment) are
- * raw engine ids with no arena entry and therefore no lifecycle: passing one to
- * `release` is a silent no-op like any other unknown id.
- */
-export const ArenaKind = z.enum([
-  "vec3",
-  "quat",
-  "line",
-  "arc",
-  "spline",
-  "circle",
-  "profile",
-  "contour",
-  "brep",
-  "face",
-  "edge",
-  "halfedge",
-  "vertex",
-])
-export type ArenaKind = z.infer<typeof ArenaKind>
-
-/** Max handles accepted by a single `release` / `endScope(retain)` call. */
-export const RELEASE_BATCH_MAX = 10_000
-
-/**
- * An opaque token identifying a handle scope opened by
- * {@linkcode PluginCoreHandlesApi.beginScope}. It is NOT an arena handle —
- * it pins no memory, and `release(token)` is a silent no-op; only
- * {@linkcode PluginCoreHandlesApi.endScope} consumes it.
- */
-export type ScopeToken = string
-
-/**
- * Handle lifecycle — free host-side handle registry entries the plugin no
- * longer needs, individually ({@linkcode release}), by kind
- * ({@linkcode releaseAll}), or as a mint-recording region
- * ({@linkcode beginScope} / {@linkcode endScope}).
- *
- * Releasing is a handle-lifecycle operation only: it frees the registry entry
- * (host memory + quota room) and makes the handle unresolvable. It never
- * deletes engine-side geometry or scene entities.
- *
- * Accessed via `snaptrude.core.handles`.
- */
-export abstract class PluginCoreHandlesApi {
-  constructor() {}
-
-  /**
-   * Free arena handles in bulk. Unknown, foreign, or already-released ids are
-   * silent no-ops — there is no per-id result and no count, so responses can
-   * never be used as an existence oracle.
-   *
-   * @param handles The handles to release (max {@linkcode RELEASE_BATCH_MAX} per call)
-   * @returns Nothing
-   *
-   * # Example
-   * ```ts
-   * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
-   * // ... read what you need ...
-   * await snaptrude.core.handles.release(faces)
-   * ```
-   */
-  public abstract release(handles: ReadonlyArray<AnyArenaHandle>): PluginApiReturn<void>
-
-  /**
-   * Free every live arena handle of one kind, or ALL arena handles when the
-   * kind is omitted. Useful at batch boundaries — e.g. a poll loop that mints
-   * a fresh footprint contour per tick.
-   *
-   * @param kind Optional arena kind to restrict the sweep to
-   * @returns Nothing
-   *
-   * # Example
-   * ```ts
-   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
-   * // ... measure ...
-   * await snaptrude.core.handles.releaseAll("contour")
-   * ```
-   */
-  public abstract releaseAll(kind?: ArenaKind): PluginApiReturn<void>
-
-  /**
-   * Open a mint-recording scope: every arena handle MINTED after this call
-   * (fresh mints only — identity-deduped re-registrations of pre-existing
-   * objects are not captured) is freed when the matching
-   * {@linkcode endScope} runs. Scopes nest, up to 64 deep — always pair
-   * begin/end in try/finally.
-   *
-   * @returns The scope token to pass to {@linkcode endScope}
-   *
-   * # Example
-   * ```ts
-   * for (const space of spaces) {
-   *   const scope = await snaptrude.core.handles.beginScope()
-   *   try {
-   *     const footprint = await snaptrude.design.query.spaces.getFootprint(space)
-   *     const area = await snaptrude.core.geom.query.contour.getArea(footprint)
-   *   } finally {
-   *     await snaptrude.core.handles.endScope(scope) // footprint (and intermediates) freed
-   *   }
-   * }
-   * ```
-   */
-  public abstract beginScope(): PluginApiReturn<ScopeToken>
-
-  /**
-   * Close a scope by its token and free every handle it recorded, except those
-   * listed in `retain`. Retained handles are promoted to the enclosing scope
-   * (if any), so nesting composes like block scopes. Closing is
-   * token-addressed: an out-of-order close (interleaved async tasks) frees
-   * only that scope's mints and leaves other open scopes intact. Always pair
-   * begin/end in try/finally so a thrown body cannot leak the scope.
-   *
-   * @param scope The token returned by the matching {@linkcode beginScope}
-   * @param retain Handles minted inside the scope that must survive it
-   * @returns Nothing
-   *
-   * # Example
-   * ```ts
-   * const scope = await snaptrude.core.handles.beginScope()
-   * const outline = await snaptrude.design.query.spaces.getFootprint(space)
-   * const outer = await snaptrude.core.geom.query.contour.getOuterProfile(outline)
-   * await snaptrude.core.handles.endScope(scope, [outer]) // outline freed, outer survives
-   * ```
-   */
-  public abstract endScope(
-    scope: ScopeToken,
-    retain?: ReadonlyArray<AnyArenaHandle>
-  ): PluginApiReturn<void>
-
-  /**
-   * Live handle-registry statistics for the calling plugin, plus the host
-   * page's JS heap usage (when the browser exposes it). Diagnostic surface for
-   * verifying that releases actually shrink host memory.
-   *
-   * @returns Arena entry counts, open scope depth, and host heap bytes
-   *
-   * # Example
-   * ```ts
-   * const before = await snaptrude.core.handles.stats()
-   * await snaptrude.core.handles.releaseAll("vec3")
-   * const after = await snaptrude.core.handles.stats()
-   * console.log(`freed ${before.values - after.values} value entries`)
-   * ```
-   */
-  public abstract stats(): PluginApiReturn<PluginHandlesStatsResult>
-}
-
-/**
- * Wire-normalize one handle argument: a raw id string passes through; a live
- * `Handle` instance (direct host callers — console harness, host-internal) or a
- * structured-clone-stripped `{id}` / tagged `{__h}` shape collapses to its id.
- * Deliberately shape-lax beyond that (non-empty string) — a malformed id is
- * just an id that resolves nowhere (anti-oracle).
- */
-const handleIdWire = z.preprocess((v) => {
-  if (typeof v === "string") return v
-  if (v instanceof Handle) return v.id
-  if (v && typeof v === "object") {
-    const o = v as Record<string, unknown>
-    if (typeof o.__h === "string") return o.__h
-    if (typeof o.id === "string") return o.id
-  }
-  return v
-}, z.string().min(1))
-
-/**
- * Arguments for {@linkcode PluginCoreHandlesApi.release}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `handles` | `string[]` | Handles to release (≤ {@linkcode RELEASE_BATCH_MAX}) |
- */
-export const PluginHandlesReleaseArgs = z.object({
-  handles: z.array(handleIdWire).max(RELEASE_BATCH_MAX),
-})
-export type PluginHandlesReleaseArgs = z.infer<typeof PluginHandlesReleaseArgs>
-
-/**
- * Arguments for {@linkcode PluginCoreHandlesApi.releaseAll}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `kind` | {@linkcode ArenaKind} (optional) | Restrict the sweep to one kind |
- */
-export const PluginHandlesReleaseAllArgs = z.object({
-  kind: ArenaKind.optional(),
-})
-export type PluginHandlesReleaseAllArgs = z.infer<typeof PluginHandlesReleaseAllArgs>
-
-/**
- * Arguments for {@linkcode PluginCoreHandlesApi.endScope}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `scope` | {@linkcode ScopeToken} | Token from the matching `beginScope` |
- * | `retain` | `string[]` (optional) | Scope-minted handles that must survive |
- */
-export const PluginHandlesEndScopeArgs = z.object({
-  scope: z.string().regex(/^scope_[A-Za-z0-9_-]+$/, 'expected a "scope" token'),
-  retain: z.array(handleIdWire).max(RELEASE_BATCH_MAX).optional(),
-})
-export type PluginHandlesEndScopeArgs = z.infer<typeof PluginHandlesEndScopeArgs>
-
-/**
- * Result of {@linkcode PluginCoreHandlesApi.stats}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `resources` | `number` | Live resource-arena entries (profile/contour) |
- * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/spline/circle) |
- * | `topology` | `number` | Live topology-arena entries (brep/face/edge/halfedge/vertex) |
- * | `scopes` | `number` | Currently open handle scopes |
- * | `hostHeapUsedBytes` | `number \| null` | Host page `usedJSHeapSize` (null where unsupported) |
- * | `hostHeapTotalBytes` | `number \| null` | Host page `totalJSHeapSize` (null where unsupported) |
- */
-export const PluginHandlesStatsResult = z.object({
-  resources: z.number().int().nonnegative(),
-  values: z.number().int().nonnegative(),
-  topology: z.number().int().nonnegative(),
-  scopes: z.number().int().nonnegative(),
-  hostHeapUsedBytes: z.number().nullable(),
-  hostHeapTotalBytes: z.number().nullable(),
-})
-export type PluginHandlesStatsResult = z.infer<typeof PluginHandlesStatsResult>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+// Type-only: src/handles.ts type-only-imports ArenaKind from this file, so the
+// cycle stays purely type-level and is erased at emit.
+import type { AnyArenaHandle } from "../../../handles"
+import { Handle } from "../../../handles"
+
+/**
+ * The 13 registry-arena handle kinds — the releasable families. Entity-style
+ * handles (component / material / underlay / terrain / importJob / comment) are
+ * raw engine ids with no arena entry and therefore no lifecycle: passing one to
+ * `release` is a silent no-op like any other unknown id.
+ */
+export const ArenaKind = z.enum([
+  "vec3",
+  "quat",
+  "line",
+  "arc",
+  "spline",
+  "circle",
+  "profile",
+  "contour",
+  "brep",
+  "face",
+  "edge",
+  "halfedge",
+  "vertex",
+])
+export type ArenaKind = z.infer<typeof ArenaKind>
+
+/** Max handles accepted by a single `release` / `endScope(retain)` call. */
+export const RELEASE_BATCH_MAX = 10_000
+
+/**
+ * An opaque token identifying a handle scope opened by
+ * {@linkcode PluginCoreHandlesApi.beginScope}. It is NOT an arena handle —
+ * it pins no memory, and `release(token)` is a silent no-op; only
+ * {@linkcode PluginCoreHandlesApi.endScope} consumes it.
+ */
+export type ScopeToken = string
+
+/**
+ * Handle lifecycle — free host-side handle registry entries the plugin no
+ * longer needs, individually ({@linkcode release}), by kind
+ * ({@linkcode releaseAll}), or as a mint-recording region
+ * ({@linkcode beginScope} / {@linkcode endScope}).
+ *
+ * Releasing is a handle-lifecycle operation only: it frees the registry entry
+ * (host memory + quota room) and makes the handle unresolvable. It never
+ * deletes engine-side geometry or scene entities.
+ *
+ * Accessed via `snaptrude.core.handles`.
+ */
+export abstract class PluginCoreHandlesApi {
+  constructor() {}
+
+  /**
+   * Free arena handles in bulk. Unknown, foreign, or already-released ids are
+   * silent no-ops — there is no per-id result and no count, so responses can
+   * never be used as an existence oracle.
+   *
+   * @param handles The handles to release (max {@linkcode RELEASE_BATCH_MAX} per call)
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * // ... read what you need ...
+   * await snaptrude.core.handles.release(faces)
+   * ```
+   */
+  public abstract release(handles: ReadonlyArray<AnyArenaHandle>): PluginApiReturn<void>
+
+  /**
+   * Free every live arena handle of one kind, or ALL arena handles when the
+   * kind is omitted. Useful at batch boundaries — e.g. a poll loop that mints
+   * a fresh footprint contour per tick.
+   *
+   * @param kind Optional arena kind to restrict the sweep to
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   * // ... measure ...
+   * await snaptrude.core.handles.releaseAll("contour")
+   * ```
+   */
+  public abstract releaseAll(kind?: ArenaKind): PluginApiReturn<void>
+
+  /**
+   * Open a mint-recording scope: every arena handle MINTED after this call
+   * (fresh mints only — identity-deduped re-registrations of pre-existing
+   * objects are not captured) is freed when the matching
+   * {@linkcode endScope} runs. Scopes nest, up to 64 deep — always pair
+   * begin/end in try/finally.
+   *
+   * @returns The scope token to pass to {@linkcode endScope}
+   *
+   * # Example
+   * ```ts
+   * for (const space of spaces) {
+   *   const scope = await snaptrude.core.handles.beginScope()
+   *   try {
+   *     const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   *     const area = await snaptrude.core.geom.query.contour.getArea(footprint)
+   *   } finally {
+   *     await snaptrude.core.handles.endScope(scope) // footprint (and intermediates) freed
+   *   }
+   * }
+   * ```
+   */
+  public abstract beginScope(): PluginApiReturn<ScopeToken>
+
+  /**
+   * Close a scope by its token and free every handle it recorded, except those
+   * listed in `retain`. Retained handles are promoted to the enclosing scope
+   * (if any), so nesting composes like block scopes. Closing is
+   * token-addressed: an out-of-order close (interleaved async tasks) frees
+   * only that scope's mints and leaves other open scopes intact. Always pair
+   * begin/end in try/finally so a thrown body cannot leak the scope.
+   *
+   * @param scope The token returned by the matching {@linkcode beginScope}
+   * @param retain Handles minted inside the scope that must survive it
+   * @returns Nothing
+   *
+   * # Example
+   * ```ts
+   * const scope = await snaptrude.core.handles.beginScope()
+   * const outline = await snaptrude.design.query.spaces.getFootprint(space)
+   * const outer = await snaptrude.core.geom.query.contour.getOuterProfile(outline)
+   * await snaptrude.core.handles.endScope(scope, [outer]) // outline freed, outer survives
+   * ```
+   */
+  public abstract endScope(
+    scope: ScopeToken,
+    retain?: ReadonlyArray<AnyArenaHandle>
+  ): PluginApiReturn<void>
+
+  /**
+   * Live handle-registry statistics for the calling plugin, plus the host
+   * page's JS heap usage (when the browser exposes it). Diagnostic surface for
+   * verifying that releases actually shrink host memory.
+   *
+   * @returns Arena entry counts, open scope depth, and host heap bytes
+   *
+   * # Example
+   * ```ts
+   * const before = await snaptrude.core.handles.stats()
+   * await snaptrude.core.handles.releaseAll("vec3")
+   * const after = await snaptrude.core.handles.stats()
+   * console.log(`freed ${before.values - after.values} value entries`)
+   * ```
+   */
+  public abstract stats(): PluginApiReturn<PluginHandlesStatsResult>
+}
+
+/**
+ * Wire-normalize one handle argument: a raw id string passes through; a live
+ * `Handle` instance (direct host callers — console harness, host-internal) or a
+ * structured-clone-stripped `{id}` / tagged `{__h}` shape collapses to its id.
+ * Deliberately shape-lax beyond that (non-empty string) — a malformed id is
+ * just an id that resolves nowhere (anti-oracle).
+ */
+const handleIdWire = z.preprocess((v) => {
+  if (typeof v === "string") return v
+  if (v instanceof Handle) return v.id
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>
+    if (typeof o.__h === "string") return o.__h
+    if (typeof o.id === "string") return o.id
+  }
+  return v
+}, z.string().min(1))
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.release}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `handles` | `string[]` | Handles to release (≤ {@linkcode RELEASE_BATCH_MAX}) |
+ */
+export const PluginHandlesReleaseArgs = z.object({
+  handles: z.array(handleIdWire).max(RELEASE_BATCH_MAX),
+})
+export type PluginHandlesReleaseArgs = z.infer<typeof PluginHandlesReleaseArgs>
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.releaseAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode ArenaKind} (optional) | Restrict the sweep to one kind |
+ */
+export const PluginHandlesReleaseAllArgs = z.object({
+  kind: ArenaKind.optional(),
+})
+export type PluginHandlesReleaseAllArgs = z.infer<typeof PluginHandlesReleaseAllArgs>
+
+/**
+ * Arguments for {@linkcode PluginCoreHandlesApi.endScope}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | {@linkcode ScopeToken} | Token from the matching `beginScope` |
+ * | `retain` | `string[]` (optional) | Scope-minted handles that must survive |
+ */
+export const PluginHandlesEndScopeArgs = z.object({
+  scope: z.string().regex(/^scope_[A-Za-z0-9_-]+$/, 'expected a "scope" token'),
+  retain: z.array(handleIdWire).max(RELEASE_BATCH_MAX).optional(),
+})
+export type PluginHandlesEndScopeArgs = z.infer<typeof PluginHandlesEndScopeArgs>
+
+/**
+ * Result of {@linkcode PluginCoreHandlesApi.stats}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `resources` | `number` | Live resource-arena entries (profile/contour) |
+ * | `values` | `number` | Live value-arena entries (vec3/quat/line/arc/spline/circle) |
+ * | `topology` | `number` | Live topology-arena entries (brep/face/edge/halfedge/vertex) |
+ * | `scopes` | `number` | Currently open handle scopes |
+ * | `hostHeapUsedBytes` | `number \| null` | Host page `usedJSHeapSize` (null where unsupported) |
+ * | `hostHeapTotalBytes` | `number \| null` | Host page `totalJSHeapSize` (null where unsupported) |
+ */
+export const PluginHandlesStatsResult = z.object({
+  resources: z.number().int().nonnegative(),
+  values: z.number().int().nonnegative(),
+  topology: z.number().int().nonnegative(),
+  scopes: z.number().int().nonnegative(),
+  hostHeapUsedBytes: z.number().nullable(),
+  hostHeapTotalBytes: z.number().nullable(),
+})
+export type PluginHandlesStatsResult = z.infer<typeof PluginHandlesStatsResult>

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

@@ -1,84 +1,84 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-
-/**
- * Undo / redo of committed history entries.
- *
- * History steps operate on Snaptrude's command stack: {@linkcode PluginHistoryApi.undo}
- * steps back over committed entries, {@linkcode PluginHistoryApi.redo} re-applies
- * undone ones. Both take an optional step count (default 1) and report how many
- * steps were actually applied — fewer than requested when the stack runs out.
- *
- * Accessed via `snaptrude.core.history`.
- */
-export abstract class PluginHistoryApi {
-  constructor() {}
-
-  /**
-   * Step back over committed history entries.
-   *
-   * @param steps - (Optional) The number of entries to undo (default 1).
-   * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
-   *   entries actually undone (≤ `steps`; fewer if the undo stack ran out).
-   *
-   * @examplePrompt Undo my last change
-   * @examplePrompt Undo the last 3 actions
-   * @examplePrompt Revert what I just did to the model
-   * @examplePrompt Step back one change
-   * @examplePrompt Take back that last edit
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.history.undo()   // one step
-   * await snaptrude.core.history.undo(3)  // up to three steps
-   * ```
-   */
-  public abstract undo(steps?: number): PluginApiReturn<PluginHistoryStepResult>
-
-  /**
-   * Step forward over previously undone entries. Symmetric with
-   * {@linkcode PluginHistoryApi.undo}.
-   *
-   * @param steps - (Optional) The number of entries to redo (default 1).
-   * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
-   *   entries actually redone (≤ `steps`; fewer if the redo stack ran out).
-   *
-   * @examplePrompt Redo the change I just undid
-   * @examplePrompt Redo the last two undone actions
-   * @examplePrompt Bring back the edit I reverted
-   * @examplePrompt Step forward again in the history
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.history.redo()
-   * await snaptrude.core.history.redo(2)
-   * ```
-   */
-  public abstract redo(steps?: number): PluginApiReturn<PluginHistoryStepResult>
-}
-
-/**
- * Arguments for {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `steps` | `number?` | Number of history entries to step (positive integer). Defaults to 1. |
- */
-export const PluginHistoryStepArgs = z.object({
-  steps: z.number().int().positive().optional(),
-})
-
-export type PluginHistoryStepArgs = z.infer<typeof PluginHistoryStepArgs>
-
-/**
- * Result of {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `stepsApplied` | `number` | History entries actually stepped — `≤ steps`, fewer when the stack ran out. |
- */
-export const PluginHistoryStepResult = z.object({
-  stepsApplied: z.number().int().nonnegative(),
-})
-
-export type PluginHistoryStepResult = z.infer<typeof PluginHistoryStepResult>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Undo / redo of committed history entries.
+ *
+ * History steps operate on Snaptrude's command stack: {@linkcode PluginHistoryApi.undo}
+ * steps back over committed entries, {@linkcode PluginHistoryApi.redo} re-applies
+ * undone ones. Both take an optional step count (default 1) and report how many
+ * steps were actually applied — fewer than requested when the stack runs out.
+ *
+ * Accessed via `snaptrude.core.history`.
+ */
+export abstract class PluginHistoryApi {
+  constructor() {}
+
+  /**
+   * Step back over committed history entries.
+   *
+   * @param steps - (Optional) The number of entries to undo (default 1).
+   * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
+   *   entries actually undone (≤ `steps`; fewer if the undo stack ran out).
+   *
+   * @examplePrompt Undo my last change
+   * @examplePrompt Undo the last 3 actions
+   * @examplePrompt Revert what I just did to the model
+   * @examplePrompt Step back one change
+   * @examplePrompt Take back that last edit
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.history.undo()   // one step
+   * await snaptrude.core.history.undo(3)  // up to three steps
+   * ```
+   */
+  public abstract undo(steps?: number): PluginApiReturn<PluginHistoryStepResult>
+
+  /**
+   * Step forward over previously undone entries. Symmetric with
+   * {@linkcode PluginHistoryApi.undo}.
+   *
+   * @param steps - (Optional) The number of entries to redo (default 1).
+   * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
+   *   entries actually redone (≤ `steps`; fewer if the redo stack ran out).
+   *
+   * @examplePrompt Redo the change I just undid
+   * @examplePrompt Redo the last two undone actions
+   * @examplePrompt Bring back the edit I reverted
+   * @examplePrompt Step forward again in the history
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.history.redo()
+   * await snaptrude.core.history.redo(2)
+   * ```
+   */
+  public abstract redo(steps?: number): PluginApiReturn<PluginHistoryStepResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `steps` | `number?` | Number of history entries to step (positive integer). Defaults to 1. |
+ */
+export const PluginHistoryStepArgs = z.object({
+  steps: z.number().int().positive().optional(),
+})
+
+export type PluginHistoryStepArgs = z.infer<typeof PluginHistoryStepArgs>
+
+/**
+ * Result of {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `stepsApplied` | `number` | History entries actually stepped — `≤ steps`, fewer when the stack ran out. |
+ */
+export const PluginHistoryStepResult = z.object({
+  stepsApplied: z.number().int().nonnegative(),
+})
+
+export type PluginHistoryStepResult = z.infer<typeof PluginHistoryStepResult>