superdoc 2.4.0-next.12 → 2.4.0-next.13

package/dist/style.layered.css

@@ -1769,11 +1769,11 @@ img[data-v-c95b2073] {
   pointer-events: auto;
 }
 
-.superdoc[data-v-62293b70] {
+.superdoc[data-v-25570fd2] {
   display: flex;
   position: relative;
 }
-.sd-visually-hidden[data-v-62293b70] {
+.sd-visually-hidden[data-v-25570fd2] {
   position: absolute;
   width: 1px;
   height: 1px;
@@ -1784,30 +1784,30 @@ img[data-v-c95b2073] {
   white-space: nowrap;
   border: 0;
 }
-.right-sidebar[data-v-62293b70] {
+.right-sidebar[data-v-25570fd2] {
   min-width: 320px;
   height: 100%;
 }
-.floating-comments[data-v-62293b70] {
+.floating-comments[data-v-25570fd2] {
   min-width: 300px;
   width: 300px;
   height: 100%;
   overflow: visible;
 }
-.superdoc__layers[data-v-62293b70] {
+.superdoc__layers[data-v-25570fd2] {
   height: 100%;
   position: relative;
   box-sizing: border-box;
 }
-.superdoc__document[data-v-62293b70] {
+.superdoc__document[data-v-25570fd2] {
   width: 100%;
   position: relative;
 }
-.superdoc__sub-document[data-v-62293b70] {
+.superdoc__sub-document[data-v-25570fd2] {
   width: 100%;
   position: relative;
 }
-.superdoc__selection-layer[data-v-62293b70] {
+.superdoc__selection-layer[data-v-25570fd2] {
   position: absolute;
   min-width: 100%;
   min-height: 100%;
@@ -1818,13 +1818,13 @@ img[data-v-c95b2073] {
 /* SD-3497: PDF whiteboard overlay sits above the rendered PDF canvas but below
    the PDF comment anchors (z-index 6 in PdfCommentsLayer) so anchors stay
    clickable, and below the selection layer (z-index 10). */
-.superdoc__whiteboard-layer[data-v-62293b70] {
+.superdoc__whiteboard-layer[data-v-25570fd2] {
   z-index: 4;
 }
-.superdoc__temp-selection[data-v-62293b70] {
+.superdoc__temp-selection[data-v-25570fd2] {
   position: absolute;
 }
-.superdoc__right-sidebar[data-v-62293b70] {
+.superdoc__right-sidebar[data-v-25570fd2] {
   width: 320px;
   min-width: 320px;
   padding: 0 10px;
@@ -1832,7 +1832,7 @@ img[data-v-c95b2073] {
   position: relative;
   z-index: 2;
 }
-.superdoc__compact-comment-popover[data-v-62293b70] {
+.superdoc__compact-comment-popover[data-v-25570fd2] {
   position: absolute;
   top: 12px;
   right: 12px;
@@ -1841,14 +1841,14 @@ img[data-v-c95b2073] {
 }
 
 /* Tools styles */
-.tools[data-v-62293b70] {
+.tools[data-v-25570fd2] {
   position: absolute;
   z-index: 3;
   display: flex;
   flex-direction: column;
   gap: var(--sd-ui-tools-gap, 6px);
 }
-.tools-item[data-v-62293b70] {
+.tools-item[data-v-25570fd2] {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -1859,10 +1859,10 @@ img[data-v-c95b2073] {
   cursor: pointer;
   position: relative;
 }
-.tools-item i[data-v-62293b70] {
+.tools-item i[data-v-25570fd2] {
   cursor: pointer;
 }
-.superdoc__tools-icon[data-v-62293b70] {
+.superdoc__tools-icon[data-v-25570fd2] {
   width: var(--sd-ui-tools-icon-size, 20px);
   height: var(--sd-ui-tools-icon-size, 20px);
   flex-shrink: 0;
@@ -1877,22 +1877,22 @@ img[data-v-c95b2073] {
 
 /* 834px is iPad screen size in portrait orientation */
 @media (max-width: 834px) {
-.superdoc .superdoc__layers[data-v-62293b70] {
+.superdoc .superdoc__layers[data-v-25570fd2] {
     margin: 0;
     border: 0 !important;
     box-shadow: none;
 }
-.superdoc__sub-document[data-v-62293b70] {
+.superdoc__sub-document[data-v-25570fd2] {
     max-width: 100%;
 }
-.superdoc__right-sidebar[data-v-62293b70] {
+.superdoc__right-sidebar[data-v-25570fd2] {
     padding: 10px;
     position: relative;
 }
 }
 
 /* AI Writer styles */
-.ai-writer-container[data-v-62293b70] {
+.ai-writer-container[data-v-25570fd2] {
   position: fixed;
   z-index: 1000;
   background: white;
@@ -1908,10 +1908,10 @@ img[data-v-c95b2073] {
   transform: translateY(-50%);
   z-index: 50;
 } */
-.ai-tool > svg[data-v-62293b70] {
+.ai-tool > svg[data-v-25570fd2] {
   fill: transparent;
 }
-.ai-tool[data-v-62293b70]::before {
+.ai-tool[data-v-25570fd2]::before {
   content: '';
   position: absolute;
   width: 20px;
@@ -1932,7 +1932,7 @@ img[data-v-c95b2073] {
   filter: brightness(1.2);
   transition: filter 0.2s ease;
 }
-.ai-tool[data-v-62293b70]:hover::before {
+.ai-tool[data-v-25570fd2]:hover::before {
   filter: brightness(1.3);
 }
 

package/dist/superdoc/src/core/SuperDoc.d.ts

@@ -30,6 +30,9 @@ interface SuperDocFormattingMarksPayload {
 interface SuperDocDocumentModeChangePayload {
     documentMode: DocumentMode;
 }
+interface SuperDocCommentsListChangePayload {
+    isRendered: boolean;
+}
 interface SuperDocPaginationPayload {
     totalPages: number;
     superdoc: SuperDoc;
@@ -51,6 +54,7 @@ interface SuperDocEventMap {
     editorDestroy: [];
     'pdf:document-ready': [];
     'sidebar-toggle': [boolean];
+    'comments-list-change': [SuperDocCommentsListChangePayload];
     /** Requests the shell open its find/replace surface (e.g. the toolbar search button). */
     'search:open': [];
     zoomChange: [SuperDocZoomPayload];

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.
- *
- * 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).
+ * What a custom toolbar entry does when activated.
  *
- * 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;
+    /**
+     * 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 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`).
+     * 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.
+     *
+     * Not string-only: `OptionIcon` returns whatever this resolves to straight
+     * from a render function, so a Vue VNode works as well as markup.
      *
-     * 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.
+     * `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;
@@ -2555,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
@@ -2754,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

package/dist/superdoc/src/helpers/v2-typing-review-hydration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Coalesce automatic review-catalog reconciliation behind a genuine typing
+ * quiet period. Every typing signal restarts the trailing timer; there is no
+ * maximum-wait escape hatch because that would deliberately run the expensive
+ * catalog reads in the middle of a sustained input burst.
+ */
+export function createV2TypingReviewHydrationScheduler({ hydrate, idleMs, setTimer, clearTimer, }: {
+    hydrate: any;
+    idleMs?: number | undefined;
+    setTimer?: ((callback: any, delay: any) => NodeJS.Timeout) | undefined;
+    clearTimer?: ((timer: any) => void) | undefined;
+}): {
+    schedule: () => void;
+    clear: () => void;
+    isPending: () => boolean;
+};

package/dist/superdoc/src/internal/toolbar/built-in/ToolbarButton.vue.d.ts

@@ -1,20 +1,20 @@
 declare const _default: import('vue').DefineComponent<{}, {
     $emit: (event: "buttonClick" | "textSubmit" | "mainClick", ...args: any[]) => void;
     active: boolean;
-    iconColor: string;
     isNarrow: boolean;
     isWide: boolean;
-    toolbarItem: Record<string, any>;
     defaultLabel: string;
+    iconColor: string;
+    toolbarItem: Record<string, any>;
     isOverflowItem: boolean;
     allowEnterPropagation: boolean;
     $props: {
         readonly active?: boolean | undefined;
-        readonly iconColor?: string | undefined;
         readonly isNarrow?: boolean | undefined;
         readonly isWide?: boolean | undefined;
-        readonly toolbarItem?: Record<string, any> | undefined;
         readonly defaultLabel?: string | undefined;
+        readonly iconColor?: string | undefined;
+        readonly toolbarItem?: Record<string, any> | undefined;
         readonly isOverflowItem?: boolean | undefined;
         readonly allowEnterPropagation?: boolean | undefined;
     };