superdoc 2.4.0-next.2 → 2.4.0-next.21

package/dist/superdoc/src/core/types/index.d.ts

@@ -25,8 +25,16 @@ export type { BrowserDocumentApi } from '../../public/browser-document-api.js';
 export interface ToolbarDropdownOption {
     /** Row text, and the default command argument when the row is chosen. */
     label?: string;
-    /** Stable row identity, used for selection state. */
-    key?: string;
+    /**
+     * Stable row identity, used for selection state and handed to the command.
+     *
+     * Numbers included, because the built-in zoom dropdown uses them
+     * (`key: 0.5`, `key: 1`) and the runtime passes the value through
+     * unchanged. This is what a `command` callback reads as `context.option`,
+     * so a string-only declaration here made a numeric key unusable at the far
+     * end even once the config side accepted it.
+     */
+    key?: string | number;
     /** Attributes spread onto the rendered row. */
     props?: Record<string, unknown>;
     [key: string]: unknown;
@@ -56,37 +64,350 @@ export interface ToolbarCustomButtonContext extends CustomCommandContext {
     argument?: unknown;
 }
 /**
- * A custom entry appended to the built-in toolbar's default item set.
+ * What a custom toolbar entry does when activated.
  *
- * Intentionally loose. `name` and `command` are the two members the runtime
- * contract already fixes, and the rest stays open because the public
- * toolbar-item shape has not been decided yet (#1098).
- *
- * Tightening it further needs that contract first. `useToolbarItem` accepting
- * a `type` only proves construction does not throw, not that the entry renders
- * as a top-level toolbar item -- `options` has no render branch at all,
- * `dropdown` needs rows and a trigger, and `overflow` draws only when the
- * separately-built overflow list is non-empty, which `customButtons` cannot
- * populate. Encoding those rules here would publish a contract on the strength
- * of constructor behavior, and they need rendered-behavior tests rather than
- * direct `useToolbarItem` construction to establish.
- */
-export interface ToolbarCustomButton {
-    /** Unique item name. Also derives the registered command id. */
+ * A function is registered as a custom command and invoked with
+ * {@link ToolbarCustomButtonContext}; a string is read as a canonical V2
+ * command id and routed through the shared controller. An unknown id is
+ * accepted at compile time and then reported through the toolbar's
+ * `exception` event as "Command not handled" -- so the string form stays
+ * unnarrowed, but a typo is diagnosed at runtime rather than ignored.
+ */
+export type ToolbarCustomButtonCommand = string | ((context: ToolbarCustomButtonContext) => unknown);
+/** Members every custom toolbar entry carries, whatever its type. */
+interface ToolbarCustomEntryBase {
+    /**
+     * Unique item name, which also derives the registered command id and the
+     * rendered `data-item` attribute.
+     *
+     * Uniqueness is enforced at construction rather than here: a name that
+     * repeats, or that matches a built-in item, used to render a second control
+     * under the same `data-item` with neither responding.
+     */
     name: string;
+    /** Which toolbar group the entry joins. Defaults to `center`. */
+    group?: 'left' | 'center' | 'right' | (string & {});
+    /** Hover text. */
+    tooltip?: string;
+    /** Render the entry as unavailable. Honored: a disabled entry does not run. */
+    disabled?: boolean;
+    /** Extra DOM hooks. Both are read straight onto the rendered control. */
+    attributes?: {
+        /**
+         * Appended to the item's class list. Any value Vue's `class` binding
+         * takes: a string, an array, a condition map, or a nesting of those.
+         *
+         * AIDEV-NOTE: unconstrained for the same reason as `dropdownStyles`, and
+         * verified rather than assumed. This lands inside an array binding --
+         * `ToolbarButton` renders `:class="['sd-toolbar-item',
+         * attributes.className]"` -- so Vue resolves it, and `string` rejected
+         * `['compact', { active: isActive }]`, the ordinary way to write a
+         * conditional class. There is also nothing to import or mirror:
+         * `@vue/shared` types the input as `normalizeClass(value: unknown)`, so
+         * Vue does not name this shape either, and any union written here would
+         * be narrower than what Vue accepts. A browser test asserts the array and
+         * the condition map both resolve, including that a false branch is
+         * dropped rather than stringified.
+         */
+        className?: unknown;
+        /** Sets `aria-label`, which is otherwise absent on a custom entry. */
+        ariaLabel?: string;
+    };
+    /** Render the control at reduced width. */
+    isNarrow?: boolean;
+    /** Render the control at increased width. */
+    isWide?: boolean;
+    /**
+     * `active` and `activeIcon` are rejected by name because both are dead.
+     * `useToolbarItem` hard-codes the initial active state to `false` and
+     * discards the option, and nothing in the toolbar reads `activeIcon`. Set
+     * the state from the command instead, which does work.
+     */
+    active?: never;
+    activeIcon?: never;
+    /**
+     * Open on purpose. `useToolbarItem` accepts 37 fields and forwards them, and
+     * closing this list around the ones I could enumerate rejected seven working
+     * configurations in review -- `label`, `hasCaret`, `dropdownValueKey`, row
+     * `icon`, `attributes`, `splitButton`, `argument` -- each of which renders or
+     * is forwarded by code the enumeration missed.
+     *
+     * So the guarantees here are structural rather than exhaustive: which `type`
+     * values render at all, that a button and a dropdown each have something
+     * visible, that a dropdown has rows, and that the two dead fields above are
+     * refused. A misspelled rare field still compiles, which is the same
+     * trade-off `CommentsConfig` makes for the same reason -- the runtime passes
+     * the whole bag through, so a closed type would be wrong more often than a
+     * typo is.
+     */
+    [key: string]: unknown;
+}
+/**
+ * A custom button.
+ *
+ * `icon` is required, which is stricter than the runtime check and deliberately
+ * so. Construction accepts `icon` **or** `defaultLabel`, but only the icon
+ * reaches the DOM: a button carrying `defaultLabel` alone builds, mounts, and
+ * draws nothing, leaving an empty control in the toolbar. Requiring `icon`
+ * keeps this type to shapes that produce something a user can see.
+ *
+ * `label` is not accepted at all. It is the *live* label a built-in item
+ * rewrites as state changes, it does not satisfy the affordance check, and a
+ * button carrying only `label` is rejected at construction.
+ *
+ * AIDEV-NOTE: `defaultLabel` renders nothing for a custom button. The check in
+ * `use-toolbar-item.js` treats it as an affordance and `ToolbarButton.vue`
+ * never draws it. Widening this type to accept `defaultLabel` alone requires
+ * fixing that render first, or it re-admits invisible buttons (#1098).
+ */
+export interface ToolbarCustomButtonItem extends ToolbarCustomEntryBase {
+    type: 'button';
+    /** Inline SVG or markup. The only thing a custom button actually renders. */
+    icon: string;
     /**
-     * What the entry does when activated. A function is registered as a custom
-     * command and invoked with {@link ToolbarCustomButtonContext}; a string is
-     * read as a canonical V2 command id and routed through the shared controller
-     * (`built-in-toolbar.js:948`).
+     * Static label kept for the affordance check and for parity with the legacy
+     * spelling. It does not render today; pair it with `icon`, never alone.
+     */
+    defaultLabel?: string;
+    /**
+     * Visible text drawn beside the icon. Unlike `defaultLabel` this really is
+     * rendered, but it does not satisfy the affordance check on its own, so it
+     * accompanies `icon` rather than replacing it.
+     */
+    label?: string;
+    /**
+     * What the button does. Optional because omitting it renders a control that
+     * does nothing rather than failing, which is legal today; an entry meant to
+     * be actionable should always carry one.
+     */
+    command?: ToolbarCustomButtonCommand;
+}
+/**
+ * One selectable row in a custom dropdown.
+ *
+ * Both members are required: `key` is what reaches the command through
+ * {@link ToolbarCustomButtonContext.option}, and `label` is the only text the
+ * row renders, so a row missing either draws blank or selects as `undefined`.
+ */
+interface ToolbarCustomDropdownOptionBase {
+    /**
+     * Drawn beside the row's label, or a function returning it.
      *
-     * Optional because a separator has nothing to do. An actionable entry that
-     * omits it silently no-ops on click -- a real defect, but one this type
-     * cannot flag without the variant split that #1098 owns.
+     * Not string-only: `OptionIcon` returns whatever this resolves to straight
+     * from a render function, so a Vue VNode works as well as markup.
+     *
+     * `object` rather than `Record<string, unknown>`, which was the first
+     * attempt and admitted only inferred object literals -- a value already
+     * typed as Vue's `VNode` has no string index signature and so failed to
+     * assign. `object` accepts both without importing Vue's types into the
+     * public surface.
+     */
+    icon?: string | object | ((option: ToolbarCustomDropdownOption) => unknown);
+    /** Render the row as unavailable. */
+    disabled?: boolean;
+    /** Added to the row's class list. */
+    class?: unknown;
+    /**
+     * Spread onto the rendered row as attributes, and its `class` is merged
+     * with the one above. Declared here as well as on `ToolbarDropdownOption`,
+     * which it mirrors.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Open, like the `ToolbarDropdownOption` it mirrors, because
+     * `dropdownValueKey` names a member to read dynamically: a row can carry
+     * `{ label, key, value }` and send `value` to the command. Closing this
+     * would make that shape uncompilable while it still works.
      */
-    command?: string | ((context: ToolbarCustomButtonContext) => unknown);
     [key: string]: unknown;
 }
+/**
+ * One row in a custom dropdown.
+ *
+ * A selectable row needs both `label` and `key`: `label` is the only text it
+ * renders, and `key` is what reaches the command through
+ * {@link ToolbarCustomButtonContext.option}.
+ *
+ * A `type: 'render'` row is the exception and is why this is a union rather
+ * than one interface. `ToolbarDropdown` routes those to its `RenderOption`
+ * branch and never reads `label` for them, so requiring it would reject rows
+ * the runtime supports -- which the first version of this type did.
+ */
+export type ToolbarCustomDropdownOption = (ToolbarCustomDropdownOptionBase & {
+    /**
+     * Application metadata. A row carrying `{ type: 'action', label, key }`
+     * stays selectable and reaches the command verbatim, so this member is
+     * open.
+     *
+     * AIDEV-NOTE: that openness means `{ type: 'render', label, key }` with
+     * no renderer still matches this branch, so the render branch's
+     * required `render` does not catch it (#1098). `Exclude<string,
+     * 'render'>` does not help -- subtracting a literal from the wide
+     * `string` type leaves `string` -- and neither does a branded
+     * intersection, because a plain string literal remains assignable to
+     * both. Closing this needs a literal union of the metadata values the
+     * product supports, which is a contract decision rather than a
+     * transcription. The runtime treats such a row as render-only and draws
+     * a blank, inert row.
+     */
+    type?: string;
+    /** Text rendered for the row. */
+    label: string;
+    /**
+     * Value handed to the command when this row is chosen, and the row's
+     * Vue key. Numbers are allowed because the built-in zoom dropdown uses
+     * them (`key: 0.5`, `key: 1`), and `ButtonGroup` passes the value
+     * through to `selectedValue` unchanged.
+     */
+    key: string | number;
+}) | (ToolbarCustomDropdownOptionBase & {
+    /** Rendered through `RenderOption` rather than as a selectable row. */
+    type: 'render';
+    /**
+     * Required, because `RenderOption` returns `null` unless this is
+     * callable. A render row is also excluded from selection, so one
+     * without a renderer is a permanently blank row that cannot be clicked.
+     */
+    render: () => unknown;
+    label?: string;
+    key?: string | number;
+});
+/**
+ * A custom dropdown.
+ *
+ * `options` is required and must be non-empty: a dropdown with no rows, or an
+ * empty array, renders no trigger at all, so the entry silently disappears
+ * rather than drawing something inert.
+ *
+ * The trigger rule is looser than a button's -- `label` works here as well as
+ * `icon` -- because the dropdown draws its own trigger rather than going
+ * through the button affordance check.
+ */
+interface ToolbarCustomDropdownBase extends ToolbarCustomEntryBase {
+    type: 'dropdown';
+    /**
+     * Static fallback trigger text. Present for parity with the legacy spelling
+     * and does not render, which is why it does not satisfy the trigger
+     * requirement below.
+     */
+    defaultLabel?: string;
+    /**
+     * The rows the dropdown offers. Empty is accepted, and is not a mistake on
+     * its own: `#updateHighlightColors` assigns `nestedOptions` after the item
+     * is built, so a dropdown can construct empty and fill in later. An empty
+     * one renders no menu rather than breaking -- `ButtonGroup` guards the
+     * branch on `nestedOptions.value.length`.
+     *
+     * AIDEV-NOTE: this was a nonempty tuple until #1188 review. The tuple did
+     * reject `options: []`, and it also rejected every array TypeScript cannot
+     * see the length of -- `rows.map(...)`, a `Row[]` variable, a function
+     * return. Those are how dropdown rows are normally built; `lineHeight` in
+     * `default-items.js` builds its own rows with `.map()`. The obvious escape,
+     * `readonly T[] & { 0: T }`, rejects all four (measured, not assumed): an
+     * array type carries no index-0 property for the intersection to satisfy.
+     * So please do not reintroduce a tuple here -- and note there is no runtime
+     * check to fall back on either, deliberately, because an empty dropdown is
+     * a legitimate intermediate state.
+     *
+     * `readonly` so an `as const` array is accepted: the runtime only iterates
+     * this and copies the elements into `nestedOptions`, never mutating the
+     * consumer's array.
+     */
+    options: readonly ToolbarCustomDropdownOption[];
+    /** Draw the dropdown caret beside the trigger. Rendered by `ToolbarButton`. */
+    hasCaret?: boolean;
+    /**
+     * Which member of the selected row becomes the command's `argument`.
+     *
+     * Defaults to `label`, not `key`: `ButtonGroup.handleSelect` reads
+     * `option[dropdownValueKey]` and falls back to `option.label` when this is
+     * unset. So a dropdown whose display text differs from its value has to set
+     * `'key'` explicitly, or the command receives the text a user sees rather
+     * than the value it stands for. Any member name works, not just `key`: a row
+     * carrying `{ label, key, value }` can send `value`. `context.option` always
+     * carries the whole row either way.
+     */
+    dropdownValueKey?: string;
+    /**
+     * Inline styles for the dropdown's own element -- its trigger and wrapper --
+     * forwarded unchanged to Vue's `:style` binding.
+     *
+     * Not the open panel: `ButtonGroup` styles that separately through
+     * `menu-props`, which `customButtons` cannot reach. Widths set here size the
+     * control in the toolbar, not the menu it opens.
+     *
+     * AIDEV-NOTE: deliberately unconstrained. Restating Vue's `StyleValue` here
+     * was attempted three times and was wrong each time -- string-valued
+     * objects rejected `{ padding: 0 }`, object-only rejected
+     * `'min-width: 200px'`, and a hand-written union rejected a value already
+     * typed as `CSSProperties`, whose index signature a structural restatement
+     * does not match. The shape set is Vue's to define and moves with Vue, so
+     * mirroring it by hand keeps rejecting working configuration. Importing
+     * `StyleValue` would pull a Vue type into the public surface, which this
+     * package avoids elsewhere.
+     */
+    dropdownStyles?: unknown;
+    /**
+     * `key` of the row to show as selected before the user picks one. Matches
+     * the row `key` type, numbers included.
+     */
+    selectedValue?: string | number;
+    /** Invoked with the chosen row on {@link ToolbarCustomButtonContext.option}. */
+    command?: ToolbarCustomButtonCommand;
+}
+/**
+ * A dropdown needs a trigger a user can see, and it has three ways to draw
+ * one. `ToolbarButton` renders `icon` and `label` in its non-split branch and,
+ * beside them, `.sd-dropdown-caret` on `v-if="hasCaret"` alone -- so a compact
+ * caret-only dropdown is a real control, not an oversight. It renders with a
+ * measurable width and opens its rows; only `defaultLabel` draws nothing.
+ *
+ * Splitting the variant is what makes at-least-one enforceable rather than
+ * advisory. Pair a caret-only trigger with `attributes.ariaLabel`, since
+ * there is no text for a screen reader to announce.
+ */
+export type ToolbarCustomDropdownItem = (ToolbarCustomDropdownBase & {
+    icon: string;
+    label?: string;
+    hasCaret?: boolean;
+}) | (ToolbarCustomDropdownBase & {
+    label: string;
+    icon?: string;
+    hasCaret?: boolean;
+}) | (ToolbarCustomDropdownBase & {
+    hasCaret: true;
+    icon?: string;
+    label?: string;
+});
+/** A visual divider. Renders on its own and has nothing to run. */
+export interface ToolbarCustomSeparatorItem extends ToolbarCustomEntryBase {
+    type: 'separator';
+}
+/**
+ * A custom entry appended to the built-in toolbar's default item set.
+ *
+ * What this guarantees is structural, not exhaustive. Each variant fixes the
+ * shape of the entry -- which `type` values render at all, that a button and a
+ * dropdown each carry something visible, that a dropdown has rows -- while the
+ * field list itself stays open, because `useToolbarItem` accepts 37 fields and
+ * forwards them. Closing that list rejected eight working configurations
+ * during review, and a rejected working config is a worse failure than the
+ * autocomplete it buys.
+ *
+ * Two of the five `useToolbarItem` types are absent because they render
+ * nothing: `options` constructs without throwing and `ButtonGroup` has no
+ * branch for it, and `overflow` draws only from the separately-built overflow
+ * list, which `customButtons` cannot populate.
+ *
+ * Two fields are refused by name on {@link ToolbarCustomEntryBase} for the
+ * same reason: `active` is discarded (`useToolbarItem` hard-codes the initial
+ * state to `false`) and `activeIcon` has no toolbar reader at all.
+ *
+ * Derived from a rendered-behavior survey rather than from the constructor
+ * (#1098): construction succeeding proves only that nothing threw, which for
+ * this surface was never the same question as whether a control appeared.
+ */
+export type ToolbarCustomButton = ToolbarCustomButtonItem | ToolbarCustomDropdownItem | ToolbarCustomSeparatorItem;
 export type V2AuthoringSelectionCollapse = 'start' | 'end' | null;
 export type V2AuthoringResult = {
     ok: true;
@@ -843,6 +1164,111 @@ export type LinkPopoverResolution = {
  * default popover.
  */
 export type LinkPopoverResolver = (ctx: LinkPopoverContext) => LinkPopoverResolution | null | undefined;
+/**
+ * Canonical presentation settings for the built-in comments UI.
+ *
+ * Presentation only, and deliberately not the whole of `modules.comments`.
+ * That block also carries `readOnly` and `allowResolve`, which resolve through
+ * `interaction.comments`, and `permissionResolver`, which is read off
+ * `modules.comments` or the top-level `Config`. All three are stripped from
+ * this bag: policy outlives the built-in UI, so an application drawing its own
+ * comment surface still has to honor it. See the fields themselves, which are
+ * rejected by name with the spelling that applies to each.
+ *
+ * Open on purpose, for the same reason `modules.comments` is: the runtime
+ * merges this bag over that block and spreads the result through the comments
+ * store, which accepts pass-through keys. Closing it would reject working
+ * configurations, which is a worse failure than the missing autocomplete it
+ * would buy. The named fields are the ones the shell reads.
+ */
+export type CommentsConfig = {
+    /** How comments present themselves as the surface narrows. */
+    displayMode?: 'auto' | 'sidebar' | 'inline';
+    /** CSS selector for an explicit width measurement target in `auto` mode. */
+    compactMeasurementSelector?: string;
+    /** Fixed compact-mode breakpoint override, in pixels. */
+    compactBreakpointPx?: number;
+    /** Comment highlight colors (internal/external and active overrides). */
+    highlightColors?: {
+        /** Base highlight color for internal comments. */
+        internal?: string;
+        /** Base highlight color for external comments. */
+        external?: string;
+        /** Active highlight color override for internal comments. */
+        activeInternal?: string;
+        /** Active highlight color override for external comments. */
+        activeExternal?: string;
+    };
+    /** Comment highlight opacity, active and inactive. */
+    highlightOpacity?: {
+        /** Opacity for the active comment highlight. */
+        active?: number;
+        /** Opacity for inactive comment highlights. */
+        inactive?: number;
+    };
+    /** Highlight color used while hovering a comment. */
+    highlightHoverColor?: string;
+    /** Tracked-change highlight colors. */
+    trackChangeHighlightColors?: TrackChangeHighlightColors;
+    /** Active tracked-change highlight colors (defaults to the above). */
+    trackChangeActiveHighlightColors?: TrackChangeHighlightColors;
+    /**
+     * Policy, not presentation. `normalizeUiConfig` strips all three from this
+     * bag before anything reads it, so accepting them here would advertise a
+     * setting that is silently discarded.
+     *
+     * `readOnly` and `allowResolve` belong on `interaction.comments`, where they
+     * resolve and keep applying to an application drawing its own comment
+     * surface.
+     *
+     * `permissionResolver` is collaboration wiring rather than policy, and has
+     * no `ui` spelling at all. `pickResolver` takes the first of
+     * `modules.comments.permissionResolver` and the top-level
+     * `Config.permissionResolver`, in that order, so either works and the
+     * comments-scoped one wins.
+     */
+    readOnly?: never;
+    allowResolve?: never;
+    permissionResolver?: never;
+} & Record<string, unknown>;
+/** Border and background colors for one tracked-change highlight state. */
+export interface TrackChangeHighlightColors {
+    /** Border color for inserted text. */
+    insertBorder?: string;
+    /** Background color for inserted text. */
+    insertBackground?: string;
+    /** Border color for deleted text. */
+    deleteBorder?: string;
+    /** Background color for deleted text. */
+    deleteBackground?: string;
+    /** Border color for a format change. */
+    formatBorder?: string;
+}
+/**
+ * Canonical configuration for the chrome drawn around content controls.
+ *
+ * `chrome` is the whole option bag this surface has. `'default'` and `'none'`
+ * are the only values the painter and the v2 host accept; anything else is
+ * coerced back to `'default'`.
+ */
+export interface ContentControlsConfig {
+    /** Whether SuperDoc draws its own chrome around each content control. */
+    chrome?: 'default' | 'none';
+}
+/**
+ * Canonical configuration for the built-in link popover.
+ *
+ * `popoverResolver` supersedes `modules.links.popoverResolver`, which stays
+ * supported for all of v2. Setting both keeps the canonical one; the legacy
+ * spelling only applies when the canonical one is absent.
+ */
+export interface LinkPopoverConfig {
+    /**
+     * Called when a user clicks a link, to decide which popover to show.
+     * Returning `null` or `undefined` falls back to the built-in popover.
+     */
+    popoverResolver?: LinkPopoverResolver;
+}
 /** Context object passed to context menu callbacks (showWhen, render, action, menuProvider). */
 export interface ContextMenuContext {
     /** The editor instance. */
@@ -1650,6 +2076,17 @@ export interface FindReplaceConfig {
         width?: number | string;
         maxWidth?: number | string;
         maxHeight?: number | string;
+        /**
+         * Focus the find input when the surface opens. Defaults to `true`; set
+         * `false` to leave focus wherever the user had it.
+         *
+         * Honored but undeclared until #1094: `useFindReplace` spreads this whole
+         * bag into the surface request, and `SurfaceManager` applies it last, over
+         * the `modules.surfaces.floating` defaults.
+         */
+        autoFocus?: boolean;
+        /** Close the surface on a pointer press outside it. Defaults to `false`. */
+        closeOnOutsidePointerDown?: boolean;
     };
 }
 /**
@@ -2439,18 +2876,36 @@ export interface SuperDocExceptionEditorPayload {
     code?: string;
     documentId?: string | null;
 }
+/**
+ * Exception payload raised by the built-in toolbar.
+ *
+ * Emitted for a command that failed and for a custom entry the toolbar could
+ * not build, in which case `itemName` is the entry that was skipped and the
+ * message names the field that would fix it. Reaches the host as well as the
+ * toolbar, because entries are built inside the toolbar constructor and
+ * nothing can have subscribed to the toolbar yet.
+ */
+export interface SuperDocExceptionToolbarPayload {
+    error: Error;
+    /** The value originally thrown, before it was normalized to an `Error`. */
+    originalError: unknown;
+    /** The toolbar item involved, or `null` when the entry had no usable name. */
+    itemName: string | null;
+    editor?: Editor | null;
+}
 /**
  * Union of all `exception` event payloads SuperDoc emits at runtime.
- * Consumers can narrow with `'stage' in payload` (store init) or
- * `'code' in payload` (editor lifecycle).
+ * Consumers can narrow with `'stage' in payload` (store init),
+ * `'code' in payload` (editor lifecycle), or `'itemName' in payload`
+ * (built-in toolbar).
  *
- * The union exists today because three independent emit sites
- * (`initializeDocuments`, the restore path, and the editor lifecycle)
- * pre-date a shared error contract. Normalizing them to a single
- * payload shape is a separate follow-up; consumers can narrow with
+ * The union exists today because four independent emit sites
+ * (`initializeDocuments`, the restore path, the editor lifecycle, and the
+ * built-in toolbar) pre-date a shared error contract. Normalizing them to a
+ * single payload shape is a separate follow-up; consumers can narrow with
  * the `in` checks above in the meantime.
  */
-export type SuperDocExceptionPayload = SuperDocExceptionStorePayload | SuperDocExceptionRestorePayload | SuperDocExceptionEditorPayload;
+export type SuperDocExceptionPayload = SuperDocExceptionStorePayload | SuperDocExceptionRestorePayload | SuperDocExceptionEditorPayload | SuperDocExceptionToolbarPayload;
 /**
  * Zoom mode. `manual` holds whatever value was last set; `fit-width`
  * continuously recomputes the zoom that fits the page width into the
@@ -2638,12 +3093,16 @@ export interface UIConfig {
          */
         fonts?: ToolbarFontOption[];
         /**
-         * Custom toolbar buttons appended to the default item set.
+         * Custom toolbar entries appended to the default item set. See
+         * `ToolbarCustomButton` for which shapes render.
          *
-         * `name` and the `command` callback are typed; the rest of the
-         * `ToolbarItem` shape stays open because it is not yet public (#1098).
+         * `readonly` so an `as const` array is accepted. Without it the array
+         * built in a separate variable had no way through: widening turns each
+         * `type` into `string`, `as const` is the documented answer to that,
+         * and a mutable field then rejected the result. The toolbar only reads
+         * this.
          */
-        customButtons?: ToolbarCustomButton[];
+        customButtons?: readonly ToolbarCustomButton[];
         /**
          * Show the formatting marks (pilcrow) button in the toolbar. Off by
          * default. Distinct from `layoutEngineOptions.showFormattingMarks`, which
@@ -2654,7 +3113,7 @@ export interface UIConfig {
         showTableOfContentsButton?: boolean;
     };
     /** Built-in comments UI. Enabled by default. */
-    comments?: boolean | Record<string, unknown>;
+    comments?: boolean | CommentsConfig;
     /** Built-in right-click and slash context menu. Enabled by default. */
     contextMenu?: boolean | ContextMenuConfig;
     /**
@@ -2662,16 +3121,20 @@ export interface UIConfig {
      * SuperDoc intercept Cmd+F / Ctrl+F; `editor.ui.search` stays available to
      * custom UI either way.
      */
-    search?: boolean | Record<string, unknown>;
-    /** Built-in popover shown when a link is selected. Disabled by default. */
-    linkPopover?: boolean | Record<string, unknown>;
+    search?: boolean | FindReplaceConfig;
+    /**
+     * Built-in popover shown when a link is clicked. It renders by default;
+     * pass `false` (or `ui: false`) to suppress it. Supplying a
+     * {@link LinkPopoverConfig.popoverResolver} replaces it with your own UI.
+     */
+    linkPopover?: boolean | LinkPopoverConfig;
     /** Built-in ruler. Disabled by default. */
     ruler?: boolean | {
         /** Element or selector to render the ruler into. */
         container?: string | HTMLElement;
     };
     /** Built-in chrome drawn around content controls. Enabled by default. */
-    contentControls?: boolean | Record<string, unknown>;
+    contentControls?: boolean | ContentControlsConfig;
 }
 /**
  * What the user is permitted to do, as distinct from what SuperDoc draws.

package/dist/superdoc/src/helpers/comment-small-screen.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Whether a context-menu event landed inside the tracked-change carrier that
+ * is already visually active. The review visual owner maintains this marker,
+ * so the right-click path can stay synchronous and avoid a catalog lookup or
+ * document-wide DOM query.
+ *
+ * @param {EventTarget | null} target
+ * @returns {boolean}
+ */
+export function isActiveTrackedChangeContextMenuTarget(target: EventTarget | null): boolean;
 /**
  * Normalize adaptive comments UI policy fields.
  *

package/dist/superdoc/src/helpers/v2-review-mutation-impact.d.ts

@@ -9,6 +9,7 @@
  * one authoritative catalog after render instead of issuing one read per id.
  */
 export function getV2TrackedChangeMutationImpact(event: any): {
+    allResolved?: any;
     upsertIds: Set<any>;
     removedIds: Set<any>;
     remappedPairs: {

package/dist/superdoc/src/helpers/v2-review-mutation-reconciler.d.ts

@@ -12,7 +12,7 @@ export function createV2ReviewMutationReconciler({ getContext, reconcile, hydrat
     onReconciled: any;
 }): {
     enqueue: (impact: any) => void;
-    enqueueAfterPaint(impact: any, waitForPaint: any): void;
+    enqueueAfterPaint(impact: any, waitForPaint: any): Promise<any>;
     onRender: (supersedesInFlight?: boolean) => void;
     reset(): void;
     getPendingIds(): Set<any>;