superdoc 2.2.1 → 2.3.0

package/dist/superdoc/src/public/ui/commands.d.ts

@@ -0,0 +1,249 @@
+import { SuperDocUIReason } from './reasons.js';
+/**
+ * The 14 canonical v2-native command ids. These are the historically stable
+ * `superdoc/ui` built-ins; the broader catalog below adds v1 headless-toolbar
+ * coverage. Kept as a named export because it is part of the public `superdoc/ui`
+ * surface (`verify-public-facade-emit.cjs`, consumer typechecks).
+ */
+export declare const BUILT_IN_COMMAND_IDS: {
+    readonly bold: "bold";
+    readonly italic: "italic";
+    readonly underline: "underline";
+    readonly strikethrough: "strikethrough";
+    readonly fontFamily: "font-family";
+    readonly fontSize: "font-size";
+    readonly setFontFamily: "setFontFamily";
+    readonly setFontSize: "setFontSize";
+    readonly undo: "undo";
+    readonly redo: "redo";
+    readonly acceptChange: "acceptChange";
+    readonly rejectChange: "rejectChange";
+    readonly acceptAllChanges: "acceptAllChanges";
+    readonly rejectAllChanges: "rejectAllChanges";
+    readonly bulletList: "bullet-list";
+    readonly numberedList: "numbered-list";
+};
+/** Union of built-in command ids. */
+export type BuiltInCommandId = (typeof BUILT_IN_COMMAND_IDS)[keyof typeof BUILT_IN_COMMAND_IDS];
+/**
+ * How a catalog command is (or is not) backed by a public surface.
+ *
+ *   - `routed`      → backed by a public surface today.
+ *   - `deferred`    → recognized v1 workflow the public Document API can back,
+ *                     intentionally not wired (reports `command-deferred`).
+ *                     No descriptor uses this in the functional-parity state.
+ *   - `context-gap` → a real v2 operation whose required document context
+ *                     cannot be resolved from public custom-UI state (the
+ *                     table cell-context family). Fails closed with a precise,
+ *                     named reason (`table-context-unavailable`), NOT the
+ *                     generic `command-deferred`.
+ *   - `unsupported` → no public v2 equivalent (product decision) or unknown id.
+ */
+export type CommandDisposition = 'routed' | 'deferred' | 'context-gap' | 'unsupported';
+/** A tracked-change decision a command performs. */
+export interface TrackDecisionSpec {
+    kind: 'accept' | 'reject';
+    scope: 'id' | 'all';
+}
+/**
+ * How an inline-format command builds its public Document API input from the
+ * live selection.
+ *
+ * The v2 public Document API (`activeEditor.doc.format.*`) requires an explicit
+ * `target`/`ref` — it does NOT default to the current selection (see
+ * `@superdoc/document-api` `format.ts` `validateTargetLocator`). The controller
+ * therefore resolves the live selection to a `SelectionTarget` and passes
+ * `{ target, value }`. A command with no resolvable range selection fails
+ * closed with `range-selection-required` rather than calling the operation with
+ * a missing target (which would throw `INVALID_INPUT`).
+ */
+export interface InlineFormatSpec {
+    /** Inline run-property key (`bold`, `color`, `highlight`, `fontFamily`, `fontSize`, ...). */
+    key: string;
+    /**
+     * - `toggle`: boolean mark, value = `!active` so the command flips on/off.
+     * - `value-string`: string value (color, font family) taken from the payload.
+     * - `value-number`: numeric value (font size) taken from the payload.
+     * - `clear`: clear direct inline formatting on the selection via `format.apply`.
+     */
+    kind: 'toggle' | 'value-string' | 'value-number' | 'clear';
+}
+/**
+ * How a block-level paragraph command builds its `format.paragraph.*` /
+ * `styles.paragraph.*` input from the current paragraph block(s).
+ *
+ * The selection's `blockId` is the same identifier the public block ops accept
+ * as `nodeId` (both resolve to the OOXML `paraId` in the private v2 document-api
+ * adapter write path). The controller
+ * therefore synthesizes a `ParagraphTarget` (`{ kind:'block',
+ * nodeType:'paragraph', nodeId }`) for each block the selection covers and
+ * routes the operation per block. A command with no resolvable current block
+ * fails closed with `selection-required`.
+ */
+export interface BlockParagraphSpec {
+    /**
+     * - `alignment`: `format.paragraph.setAlignment({ target, alignment })`.
+     * - `spacing-line`: `format.paragraph.setSpacing({ target, line, lineRule:'auto' })`.
+     * - `style`: `styles.paragraph.setStyle({ target, styleId })`.
+     * - `direction`: `format.paragraph.setDirection({ target, direction })`.
+     */
+    kind: 'alignment' | 'spacing-line' | 'style' | 'direction';
+    /** Fixed value for direction commands (`ltr` / `rtl`). */
+    fixedValue?: string;
+}
+/**
+ * How a list command builds its `lists.*` input from the current block. Routes
+ * through `lists.apply` (seed a list), `lists.remove` (toggle off when the
+ * block is already that list kind), or the hybrid indent family. For
+ * `indent` / `outdent`, actual list items use `lists.indent` /
+ * `lists.outdent`, while plain paragraphs fall back to
+ * `format.paragraph.setIndentation` / `clearIndentation` so the legacy toolbar
+ * semantics stay truthful in custom UIs.
+ */
+export interface ListCommandSpec {
+    mode: 'toggle-seed' | 'indent' | 'outdent';
+    /** List kind seeded by `lists.apply` for `toggle-seed`. */
+    seed?: 'bullet' | 'ordered';
+}
+/**
+ * How a link command routes through `hyperlinks.*`. With a range selection over
+ * non-link text and an href → `hyperlinks.wrap`. With a collapsed target and
+ * text/href → `hyperlinks.insert`. With an active link and a new href →
+ * `hyperlinks.patch`. With an active link and `{ href: null }` →
+ * `hyperlinks.remove` (unwrap).
+ */
+export interface LinkCommandSpec {
+    kind: 'link';
+}
+/**
+ * How a create command routes through `create.*`. Insertion location is derived
+ * from the current block (`{ kind:'after', nodeId }`) or defaults to
+ * `documentEnd` when there is no selection.
+ */
+export interface CreateCommandSpec {
+    kind: 'table' | 'image' | 'toc';
+}
+/**
+ * How a table cell-context command routes through a `tables.*` operation once
+ * the current table context is resolved.
+ *
+ * The whole `table-*` family routes against the live table context projected by
+ * the shared V2 table-context facade (`host.getTableContext()`, surfaced as
+ * `ui.tables.getContext()`). The controller derives the `TableLocator` inputs
+ * (`nodeId`, `rowIndex` / `columnIndex`, cell locator, merge range) from that
+ * snapshot — never from private editor internals. A command with no resolvable
+ * table context fails closed with `table-context-unavailable`.
+ */
+export interface TableCommandSpec {
+    /** Which table operation this command performs against the current context. */
+    action: 'insert-row-before' | 'insert-row-after' | 'delete-row' | 'insert-column-before' | 'insert-column-after' | 'delete-column' | 'delete-table' | 'merge-cells' | 'split-cell' | 'remove-borders';
+    /** Document API operation member invoked on `activeEditor.doc.tables`. */
+    op: string;
+    /** Whether this action needs a resolved cell node (split) rather than table + index. */
+    requiresCell?: boolean;
+}
+/**
+ * Declarative descriptor for a built-in command id. Pure data plus pure
+ * payload-normalizer functions — it holds no controller closures, so the
+ * catalog stays a portable source of truth the controller interprets.
+ */
+export interface CommandDescriptor {
+    /** Stable command id (matches the v1 headless-toolbar id where applicable). */
+    id: string;
+    /** Command family, for documentation / grouping. */
+    family: string;
+    /** Disposition: routed today, deferred, or unsupported. */
+    disposition: CommandDisposition;
+    /** Whether running this command mutates the document (read-only guarded). */
+    mutates: boolean;
+    /**
+     * Canonical id this command is an alias of, when it routes the same public
+     * behavior under a different (e.g. v1 kebab) id.
+     */
+    aliasOf?: string;
+    /** Other ids that alias this command (documentation). */
+    aliases?: readonly string[];
+    /** Dotted path on the public Document API facade (`activeEditor.doc`). */
+    docRoute?: string;
+    /** Public SuperDoc-instance method this command calls. */
+    instanceRoute?: string;
+    /** Fixed argument passed to `instanceRoute` instead of the payload. */
+    fixedArg?: unknown;
+    /** Tracked-change decision this command performs. */
+    trackDecision?: TrackDecisionSpec;
+    /** Selection mark whose presence marks this command active. */
+    activeMark?: string;
+    /**
+     * Inline-format routing spec. When present, the command routes through an
+     * inline `format.*` operation against the live selection target rather than
+     * forwarding the raw payload, and requires a non-empty range selection.
+     */
+    inline?: InlineFormatSpec;
+    /**
+     * Block-level paragraph routing spec. When present, the command resolves the
+     * current paragraph block(s) from the selection and routes a
+     * `format.paragraph.*` / `styles.paragraph.*` operation per block.
+     */
+    blockParagraph?: BlockParagraphSpec;
+    /** List routing spec (`lists.apply` / `remove` / `indent` / `outdent`). */
+    list?: ListCommandSpec;
+    /** Hyperlink routing spec (`hyperlinks.wrap` / `patch` / `remove`). */
+    link?: LinkCommandSpec;
+    /** Create routing spec (`create.table` / `create.image` / `create.tableOfContents`). */
+    create?: CreateCommandSpec;
+    /** Table cell-context routing spec (`tables.*` against the live table context). */
+    table?: TableCommandSpec;
+    /** Controller state slice the command's `value` is read from. */
+    valueFrom?: 'zoom' | 'documentMode' | 'ruler' | 'formattingMarks' | 'measurementUnit';
+    /** Pure normalizer applied to the payload before routing. */
+    normalizePayload?: (payload: unknown) => unknown;
+    /** Stable reason for deferred / unsupported commands. */
+    reason?: SuperDocUIReason;
+}
+/** Strip a trailing `pt` unit from v1-style font sizes (`"12pt"` → `"12"`). */
+export declare function normalizeFontSizePayload(payload: unknown): unknown;
+/**
+ * Normalize v1-style zoom payloads to the percentage `SuperDoc.setZoom`
+ * expects (`100 === 100%`). Accepts `150`, `"150%"`, `"1.5"`, or `1.5`.
+ * Percentages pass through as numbers; legacy fraction-style values in the
+ * `0..5` range are converted to percentages (`1.5` → `150`).
+ */
+export declare function normalizeZoomPayload(payload: unknown): unknown;
+/**
+ * Normalize a measurement-unit payload to the `'in'` / `'cm'` form
+ * `SuperDoc.setMeasurementUnit` expects. Accepts the canonical `'in'` / `'cm'`,
+ * a `{ value }` wrapper, or common long forms (`"inches"`, `"centimeters"`).
+ * An unrecognized value passes through so the instance method can reject it.
+ */
+export declare function normalizeMeasurementUnitPayload(payload: unknown): unknown;
+/**
+ * Normalize a v1-style color payload to the `#RRGGBB` form the inline
+ * `format.color` / `format.highlight` operations expect. Accepts `"#RRGGBB"`,
+ * `"RRGGBB"`, or `{ value }`. `null` (clear) passes through unchanged; an
+ * unrecognized value is returned as-is so the operation can reject it.
+ */
+export declare function normalizeColorPayload(payload: unknown): unknown;
+/** Normalize a v1 alignment payload (`"left"`, `{ value }`, `"justified"`) to a `ParagraphAlignment`. */
+export declare function normalizeAlignmentPayload(payload: unknown): unknown;
+/**
+ * Normalize a v1 line-height payload to OOXML auto line spacing (240ths of a
+ * line: 240 = single, 360 = 1.5×, 480 = double). A multiplier in the `0..10`
+ * range is converted (`1.5` → `360`); a larger raw value passes through.
+ */
+export declare function normalizeLineHeightPayload(payload: unknown): unknown;
+/** Preserve semantic style intent; normalize legacy linked-style payloads to a concrete ID. */
+export declare function normalizeStyleIdPayload(payload: unknown): unknown;
+/** Resolve a document-mode payload (`"viewing"` or `{ mode }`) to the mode string. */
+export declare function normalizeDocumentModePayload(payload: unknown): unknown;
+/**
+ * The built-in command catalog. Order is documentation-only. Every v1
+ * headless-toolbar id appears here with an explicit disposition; the 14
+ * canonical v2 ids route today, the kebab track-change selection ids and the
+ * zoom / document-mode ids are newly routed in this unit, and the remaining v1
+ * workflows are deferred or marked product-unsupported with a stable reason.
+ */
+export declare const COMMAND_CATALOG: readonly CommandDescriptor[];
+/** All built-in command ids known to the controller (routed + deferred + unsupported). */
+export declare const ALL_BUILT_IN_COMMAND_IDS: readonly string[];
+/** Resolve a command descriptor by id, or `null` when the id is unknown. */
+export declare function getCommandDescriptor(id: string): CommandDescriptor | null;

package/dist/superdoc/src/public/ui/create-super-doc-ui.d.ts

@@ -0,0 +1,18 @@
+import { SuperDocUI, SuperDocUIOptions } from './types.js';
+/**
+ * Heavy-read policy for the async read coordinator (source-loading deferral).
+ * One shared table: the coordinator's gate and the table-driven policy tests
+ * both consume THIS list, so the deferred set cannot silently drift from the
+ * tested set. Keys are coordinator cache keys (exact) or key families
+ * (prefix). See the gate in `readAsync` for the runtime semantics.
+ */
+export interface HeavyDocReadPolicyEntry {
+    key: string;
+    match: 'exact' | 'prefix';
+    /** Audit rationale — why this key is catalog-scale (or reserved). */
+    note: string;
+}
+export declare const HEAVY_DOC_READ_POLICY: readonly HeavyDocReadPolicyEntry[];
+/** Whether a coordinator cache key falls under the heavy-read policy. */
+export declare function isHeavyDocReadKey(key: string): boolean;
+export declare function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI;

package/dist/superdoc/src/public/ui/entity-at.d.ts

@@ -0,0 +1,29 @@
+import { ViewportEntityHit } from './types.js';
+/**
+ * A collected hit, optionally carrying the raw painter `data-story-key` string
+ * read off the run/marker element. `storyKey` is an internal carrier the
+ * controller PREFERS over the layout-story when mapping a tracked change to a
+ * public {@link StoryLocator}; it is never surfaced on a returned public hit
+ * (the controller resolves a locator from it, then builds the public hit
+ * fresh). Kept off the public {@link ViewportEntityHit} so consumers still only
+ * switch on the typed public shape.
+ */
+export interface CollectedEntityHit extends ViewportEntityHit {
+    storyKey?: string;
+}
+/**
+ * Read painted entities off `el` and every ancestor up to the document root, or
+ * up to and INCLUDING `stopAt` when given. Innermost-first ordering: a tracked
+ * change inside a comment highlight returns `[{ trackedChange }, { comment }]`,
+ * matching what a switch on `hits[0]` expects when picking the most specific
+ * entity.
+ *
+ * `stopAt` bounds the walk to the visible host: its own attributes are read, but
+ * the walk never climbs into an app wrapper ABOVE it, so wrapper data-* cannot
+ * leak into the hits. Omitting it keeps the original walk-to-document-root.
+ *
+ * Returns `[]` for null / non-Element starts. Uses duck-typed `getAttribute`
+ * access so it works under any DOM implementation (happy-dom, jsdom, real
+ * browser) without an `instanceof` check that could fail across realms.
+ */
+export declare function collectEntityHitsFromChain(start: Element | null, stopAt?: Element | null): CollectedEntityHit[];

package/dist/superdoc/src/public/ui/equality.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shallow equality used by the controller to suppress redundant slice
+ * notifications. v2-native, dependency-free.
+ */
+/**
+ * Returns `true` when `a` and `b` are the same reference, or are objects with
+ * the same own-enumerable keys and `Object.is`-equal values one level deep.
+ * Arrays compare by index. Primitives compare with `Object.is`.
+ */
+export declare function shallowEqual(a: unknown, b: unknown): boolean;

package/dist/superdoc/src/public/ui/format-painter-helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Maps SDRunProps field names to InlineRunPatch field names.
+ * SDRunProps (read-side) and InlineRunPatch (write-side) use different keys
+ * for the same properties; direct assignment between them is forbidden.
+ *
+ * @param {Record<string, unknown>} props - SDRunProps object from doc.getNodeById
+ * @returns {Record<string, unknown>} InlineRunPatch ready for doc.format.apply
+ */
+export function sdRunPropsToInlineRunPatch(props: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Returns true when a selection segment spans the full visible text of its block.
+ * A collapsed caret is NOT a full paragraph.
+ *
+ * @param {{ range: { start: number; end: number } }} segment
+ * @param {number | null | undefined} blockVisibleLength
+ */
+export function isFullParagraph(segment: {
+    range: {
+        start: number;
+        end: number;
+    };
+}, blockVisibleLength: number | null | undefined): boolean;
+/**
+ * Serializes a selection to a stable string key used to detect whether
+ * the target selection is the same as the source (skip apply in that case).
+ *
+ * Falls back to the plain text target when the host has not populated an
+ * explicit `selectionTarget` yet.
+ *
+ * @param {{ selectionTarget?: unknown; target?: unknown } | null | undefined} selection
+ * @returns {string}
+ */
+export function selectionKey(selection: {
+    selectionTarget?: unknown;
+    target?: unknown;
+} | null | undefined): string;

package/dist/superdoc/src/public/ui/react.d.ts

@@ -0,0 +1,81 @@
+import { ReactNode } from 'react';
+import { BorrowedSuperDocUI, CommandState, CommentsSlice, ContentControlsSlice, DocumentSlice, FontFamilyOption, FontSizeOption, SelectionSlice, Subscribable, SuperDocLike, ToolbarSnapshotSlice, TrackChangesSlice, ZoomSlice } from './types.js';
+/** The raw SuperDoc instance (or host stub) handed to the provider. */
+export type SuperDocHost = SuperDocLike;
+/** Props accepted by {@link SuperDocUIProvider}. */
+export interface SuperDocUIProviderProps {
+    /** Child tree that consumes the controller via hooks. */
+    children?: ReactNode;
+}
+/**
+ * Root provider. Call {@link useSetSuperDoc} from your editor-mount
+ * component's ready callback to bind a running SuperDoc instance; the hooks
+ * below then read that instance's own controller (`superdoc.ui`).
+ *
+ * The provider is a consumer, not an owner. SuperDoc creates the controller
+ * and destroys it in `superdoc.destroy()`, so unmounting or rebinding the
+ * provider leaves it running for the built-in toolbar and any other consumer
+ * of the same instance. Every React hook therefore observes the same command
+ * state the rest of the application sees.
+ */
+export declare function SuperDocUIProvider(props: SuperDocUIProviderProps): import('react').ReactElement;
+/**
+ * Read the controller, or `null` until a SuperDoc instance is bound.
+ *
+ * Borrowed: the bound instance owns teardown, so the returned type omits
+ * `destroy()`. A provider-built fallback controller is disposed by the provider.
+ */
+export declare function useSuperDocUI(): BorrowedSuperDocUI | null;
+/** Read the raw bound SuperDoc host, or `null` until one is bound. */
+export declare function useSuperDocHost(): SuperDocHost | null;
+/** Get the stable callback used to bind a running SuperDoc instance. */
+export declare function useSetSuperDoc(): (superdoc: SuperDocHost) => void;
+/**
+ * Minimal value source the slice hooks consume: a synchronous snapshot read
+ * plus a value-direct `observe` (immediate first emit, then on change). Every
+ * domain handle satisfies this directly; command/font hooks adapt to it.
+ */
+interface SliceSource<T> {
+    getSnapshot(): T;
+    observe(listener: (value: T) => void): () => void;
+}
+/**
+ * Normalize a `pick` result into a {@link SliceSource}. Domain handles and the
+ * command/font hooks already expose the snapshot-shaped contract
+ * (`getSnapshot` + `observe`) and pass through unchanged. A raw `ui.select(...)`
+ * {@link Subscribable} (`get` + `subscribe`) is adapted: it `subscribe`s FIRST,
+ * then emits the current value, so a synchronous recompute triggered by the
+ * first listener is not missed (the substrate's `subscribe` does not emit on
+ * attach). Exported for unit tests; not re-exported by the `superdoc/ui/react`
+ * facade, so it stays off the public surface.
+ */
+export declare function toSliceSource<T>(source: SliceSource<T> | Subscribable<T>): SliceSource<T>;
+/**
+ * Subscribe to a derived slice of controller state. `pick` selects a value
+ * source from the controller: a domain handle / snapshot source
+ * ({@link SliceSource}) or a raw `ui.select(...)` {@link Subscribable}, both
+ * normalized via {@link toSliceSource}. `initial` is returned until the
+ * controller is bound.
+ */
+export declare function useSuperDocSlice<T>(pick: (ui: BorrowedSuperDocUI) => SliceSource<T> | Subscribable<T>, initial: T): T;
+/** Subscribe to the selection slice. */
+export declare function useSuperDocSelection(): SelectionSlice;
+/** Subscribe to the comments slice. */
+export declare function useSuperDocComments(): CommentsSlice;
+/** Subscribe to the content-controls slice. */
+export declare function useSuperDocContentControls(): ContentControlsSlice;
+/** Subscribe to the track-changes slice. */
+export declare function useSuperDocTrackChanges(): TrackChangesSlice;
+/** Subscribe to the toolbar snapshot slice. */
+export declare function useSuperDocToolbar(): ToolbarSnapshotSlice;
+/** Subscribe to a single command's enable/active state. */
+export declare function useSuperDocCommand(id: string): CommandState;
+/** Subscribe to the document slice. */
+export declare function useSuperDocDocument(): DocumentSlice;
+/** Subscribe to available font-family options. */
+export declare function useSuperDocFontOptions(): readonly FontFamilyOption[];
+/** Subscribe to available font-size options. */
+export declare function useSuperDocFontSizeOptions(): readonly FontSizeOption[];
+/** Subscribe to the zoom slice. */
+export declare function useSuperDocZoom(): ZoomSlice;
+export {};

package/dist/superdoc/src/public/ui/reasons.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Stable public reason taxonomy for the v2-native `superdoc/ui` controller.
+ *
+ * These strings are the canonical, stable vocabulary the controller uses to
+ * explain WHY a command or workflow handle is disabled, unsupported, deferred,
+ * or otherwise fails closed. They are part of the public custom-UI contract:
+ * consumer toolbars/panels can branch on them and migration docs reference
+ * them. Once shipped, a value must not be repurposed — add a new member rather
+ * than changing the meaning of an existing one.
+ *
+ * The reasons distinguish the failure-mode families a custom UI must tell
+ * apart (see `plans/v2-custom-ui-toolbar-parity-plan-set.md`, Workstream 2):
+ *
+ *   - command unsupported by v2            → `command-unsupported`
+ *   - reserved recognized/deferred command → `command-deferred`
+ *   - editor / Document API not ready yet   → `not-ready`, `document-api-unavailable`
+ *   - blocked by viewing / read-only state  → `document-readonly`
+ *   - blocked by missing selection/context  → `selection-required`,
+ *     `range-selection-required`, `context-unavailable`, `target-unresolved`,
+ *     `target-not-visible`, `geometry-unavailable`
+ *   - operation / host capability missing   → `operation-unavailable`,
+ *     `host-capability-unavailable`, `bulk-decisions-disabled`
+ *
+ * Geometry results (`viewport.getRect`, `metadata.getRect`) carry a separate,
+ * geometry-local `reason` vocabulary (`not-mounted`, `unresolved`,
+ * `invalid-target`, `not-ready`, `unavailable`); see `ViewportRectResult`.
+ * That vocabulary predates this taxonomy and is intentionally narrower.
+ */
+export declare const SUPERDOC_UI_REASONS: {
+    /** The active editor is not mounted / ready yet. */
+    readonly notReady: "not-ready";
+    /** The editor is ready but its Document API facade is not available or has not been published yet. */
+    readonly documentApiUnavailable: "document-api-unavailable";
+    /** The document is in viewing / read-only mode, so mutating commands are blocked. */
+    readonly documentReadonly: "document-readonly";
+    /** A selection is required and none is active. */
+    readonly selectionRequired: "selection-required";
+    /** A non-empty (range) selection is required and the current selection is collapsed/empty. */
+    readonly rangeSelectionRequired: "range-selection-required";
+    /** Required pointer / entity / document context could not be resolved. */
+    readonly contextUnavailable: "context-unavailable";
+    /** Painted geometry for the target could not be resolved. */
+    readonly geometryUnavailable: "geometry-unavailable";
+    /** A navigation / geometry target could not be resolved to a live document address. */
+    readonly targetUnresolved: "target-unresolved";
+    /** A navigation target was resolved but could not be brought into the visible viewport. */
+    readonly targetNotVisible: "target-not-visible";
+    /** The command is not supported by v2 at all. */
+    readonly commandUnsupported: "command-unsupported";
+    /** Reserved migration reason for a recognized command that is intentionally deferred. */
+    readonly commandDeferred: "command-deferred";
+    /**
+     * The command is a real v2 operation, but its required document context
+     * (the current table / row / column / cell) cannot be resolved from any
+     * public custom-UI state: `selection.current` exposes only text block ids,
+     * and no public operation resolves the table ancestry of a block. This is a
+     * precise, named context-facade gap — distinct from `command-deferred` — for
+     * the table cell-context command family.
+     */
+    readonly tableContextUnavailable: "table-context-unavailable";
+    /** The backing Document API / SuperDoc operation is not present on this host. */
+    readonly operationUnavailable: "operation-unavailable";
+    /** Bulk accept/reject decisions are disabled unless the host opts in. */
+    readonly bulkDecisionsDisabled: "bulk-decisions-disabled";
+    /** A host-owned capability (geometry, hit-test, navigation) is unavailable. */
+    readonly hostCapabilityUnavailable: "host-capability-unavailable";
+    /** Undo / redo cannot run because the host history stack has no matching entry. */
+    readonly historyEmpty: "history-empty";
+    /**
+     * The shared search/find surface is unavailable because the host does not
+     * expose a search facade (e.g. a pre-ready editor, a worker-backed v2 host,
+     * or a build without the search substrate). Search reads return empty and
+     * search actions fail closed rather than fabricating matches.
+     */
+    readonly searchUnavailable: "search-unavailable";
+    /** The search pattern is an invalid or unsafe regular expression. */
+    readonly searchInvalidPattern: "search-invalid-pattern";
+    /**
+     * Find-and-replace is intentionally out of the first v2 search parity tranche.
+     * The shared search surface implements query / navigation only; replace and
+     * replace-all fail closed with this reason until replace ships. This is an
+     * explicit product posture, not a missing-capability accident.
+     */
+    readonly replaceUnsupported: "replace-unsupported";
+    /**
+     * The selection overlaps a content control (SDT) whose lock mode
+     * (`contentLocked` / `sdtContentLocked`) forbids styling its content — Word
+     * parity (SD-3274): the toolbar must not leave styling controls clickable
+     * when the style change cannot apply. Alignment / paragraph-level commands
+     * are never gated by this reason.
+     */
+    readonly contentControlLocked: "content-control-locked";
+};
+/**
+ * Union of stable public reason strings. Surfaced on {@link CommandState} and
+ * other fail-closed handle results so consumers can branch on a stable cause
+ * rather than parsing free-form text.
+ */
+export type SuperDocUIReason = (typeof SUPERDOC_UI_REASONS)[keyof typeof SUPERDOC_UI_REASONS];