superdoc 2.4.0-next.8 → 2.4.0

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;
     /**
-     * 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`).
+     * 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;
@@ -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
@@ -2852,6 +3195,19 @@ export interface SurfacesConfig {
         autoFocus?: boolean;
     };
 }
+/**
+ * Browser worker asset URLs for deployments where application code and built
+ * SuperDoc assets are served from different origins. Each URL must resolve to
+ * a same-origin module worker served by the embedding application.
+ */
+interface V2WorkerUrlsConfig {
+    /** Main document worker used by non-collaborative v2 documents. */
+    document?: string | URL;
+    /** Collaboration-capable document worker used by v2 collaboration rooms. */
+    collaboration?: string | URL;
+    /** Isolated review-index worker used for comments and tracked changes. */
+    reviewIndex?: string | URL;
+}
 export interface Config {
     /** The ID of the SuperDoc. */
     superdocId?: string;
@@ -3218,6 +3574,12 @@ export interface Config {
      * toolbar shows the baseline and documents render with system fonts.
      */
     fonts?: FontsConfig;
+    /**
+     * Optional same-origin URLs for v2's browser worker assets. Configure these
+     * when the application and SuperDoc bundle are served from different origins.
+     * Omitted entries keep SuperDoc's bundled worker URLs.
+     */
+    workerUrls?: V2WorkerUrlsConfig;
     /**
      * Opt-in toggle for the layout engine. Auto-disabled when web layout is
      * requested without `layoutEngineOptions.flowMode === 'semantic'`; the

package/dist/superdoc/src/core/v2-integration/v2-integration.d.ts

@@ -55,7 +55,7 @@ export function hasRealV2Integration(integration: SuperDocV2Integration | null |
  * @property {unknown} EditorComponent Vue component that boots the V2 DOCX editor.
  * @property {unknown} [RulerComponent] Optional Vue component for the V2 ruler.
  * @property {(...args: unknown[]) => unknown} [createGeometryPublisher] Factory for the V2 geometry publisher.
- * @property {(...args: unknown[]) => unknown} [createReviewHydrationController] Factory for the V2 review-row hydration controller.
+ * @property {(...args: unknown[]) => unknown} [createReviewWindowController] Factory for the committed V2 review-window controller.
  * @property {(value: unknown) => boolean} [isSyntheticTrackedChangeCommentLaneItem] Predicate for synthetic tracked-change comment-lane items.
  * @property {(value: unknown) => boolean} [isV2SyntheticTrackedChangeRow] Predicate for synthesized V2 tracked-change rows.
  */
@@ -83,9 +83,9 @@ export type SuperDocV2Integration = {
      */
     createGeometryPublisher?: ((...args: unknown[]) => unknown) | undefined;
     /**
-     * Factory for the V2 review-row hydration controller.
+     * Factory for the committed V2 review-window controller.
      */
-    createReviewHydrationController?: ((...args: unknown[]) => unknown) | undefined;
+    createReviewWindowController?: ((...args: unknown[]) => unknown) | undefined;
     /**
      * Predicate for synthetic tracked-change comment-lane items.
      */

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

@@ -2,11 +2,9 @@
  * Classify the tracked-change identities carried by a v2 mutation event.
  *
  * Receipt entities are the durable invalidation contract between the document
- * kernel and derived review UI. Consumers can refresh `upsertIds` narrowly via
- * `trackChanges.get(...)`, drop `removedIds` immediately, and leave a bounded
- * full-list reconciliation as background verification. History results are
- * different: undo/redo can restore many identities at once, so consumers use
- * one authoritative catalog after render instead of issuing one read per id.
+ * kernel and derived review UI. Consumers apply removals/remaps locally; the
+ * next committed window supplies surviving or restored rows. History follows
+ * the same bounded path and never enumerates invisible review identities.
  */
 export function getV2TrackedChangeMutationImpact(event: any): {
     allResolved?: any;

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

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

@@ -187,6 +187,17 @@ export class BuiltInToolbar extends EventEmitter<string | symbol, any> {
     _detachFormatPainterModeChange: any;
     /** Registered custom-button command unregister handles. */
     _customCommandRegs: Map<any, any>;
+    /**
+     * Custom entries already reported as unbuildable.
+     *
+     * `#makeToolbarItems` runs on every throttled resize and on font or
+     * active-editor changes, not only at construction, so a single static
+     * configuration error would otherwise fire `exception` once per rebuild --
+     * unbounded, into consumer telemetry, for a mistake that cannot change
+     * without a reconfigure. Keyed by name plus message so a different fault
+     * on the same entry still reports once.
+     */
+    _reportedInvalidCustomItems: Set<any>;
     /** Signature of the last-built font options, to skip redundant rebuilds. */
     _lastFontOptionsSignature: string;
     app: import('vue').App<Element> | undefined;

package/dist/superdoc/src/internal/toolbar/compatibility-catalog.d.ts

@@ -36,7 +36,7 @@ export interface BuiltInToolbarItemEntry {
  * docs present them; it is documentation-only.
  *
  * Every documented `Available buttons` entry from
- * `apps/docs/editor/built-in-ui/toolbar.mdx` appears here exactly once, plus the
+ * the built-in UI documentation appears here exactly once, plus the
  * `customButtons` shell concept.
  */
 export declare const BUILT_IN_TOOLBAR_CATALOG: readonly BuiltInToolbarItemEntry[];