superdoc 2.29.0 → 2.30.0-next.19

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

@@ -3,11 +3,12 @@ import { DiagnosticsConfig } from './diagnostics.js';
 import { Doc as YDoc } from 'yjs';
 import { HocuspocusProviderWebsocket } from '@hocuspocus/provider';
 import { Ref, ComputedRef } from 'vue';
-import { ContentControlType, HyperlinkTarget } from '../../../../document-api/src/index.js';
+import { HyperlinkTarget, SelectionInfo } from '../../../../document-api/src/index.js';
 import { DocumentFontOption, FontAssetUrlResolver, FontFamilyOption, FontLoadSummary, FontResolutionRecord } from '../../../../shared/font-system/src/index.js';
 import { SuperDoc as SuperDocClass } from '../SuperDoc.js';
 import { SuperDocActiveEditorExtensions, SuperDocExtension } from '../extensions/index.js';
 import { BrowserDocumentApi } from '../../public/browser-document-api.js';
+import { ContentControlClickPayload, ContentControlRef } from '../../public/content-control-ref.js';
 import { CustomCommandContext, FontFamilyOption as ToolbarFontFamilyOption } from '../../public/ui/types.js';
 export type { DocumentFontOption, FontFamilyOption, FontLoadSummary, FontResolutionRecord, } from '../../../../shared/font-system/src/index.js';
 export type SuperDoc = SuperDocClass;
@@ -449,12 +450,41 @@ export interface V2AuthoringFacade {
  * `#assignUserColor()` after `#init`.
  */
 export interface User {
+    commentIdentity?: {
+        providerId: string;
+        userId: string;
+    } | null;
+    /** Stable application user id. Collaborative change records report it as the actor id. */
     id?: string | null;
     name?: string | null;
     email?: string | null;
     image?: string | null;
+    /**
+     * Opaque identity claim published with this session's change records, such as
+     * a JWT your server signs. SuperDoc never verifies it.
+     */
+    claim?: UserClaim;
     [key: string]: unknown;
 }
+/** Context passed to a {@link UserClaim} function. */
+export interface UserClaimContext {
+    /** Collaboration document id of the session. */
+    documentId: string;
+    /** Yjs client id of the session. */
+    clientId: number;
+}
+/**
+ * Identity claim for {@link User.claim}: a string, or a function that returns
+ * one for the session's collaboration document and Yjs client id.
+ */
+export type UserClaim = string | ((ctx: UserClaimContext) => string | Promise<string>);
+/** Per-session retention of attributed change records (`doc.changes`). */
+export interface ChangesConfig {
+    /** Maximum number of retained records. Defaults to 1000. */
+    retainRecords?: number;
+    /** Maximum retained size in bytes, including captured updates. Defaults to 8 MiB. */
+    retainBytes?: number;
+}
 /** V2-neutral active editor facade exposed by legacy shell methods. */
 export interface EditorCommands {
     search?: (text: string | RegExp, options?: Record<string, unknown>) => SearchMatch[];
@@ -848,9 +878,6 @@ export interface ProofingProvider {
     suggest?: (request: ProofingSuggestRequest) => Promise<ProofingSuggestResult>;
     dispose?: () => Promise<void> | void;
 }
-export interface SelectionInfo {
-    [key: string]: unknown;
-}
 /**
  * Font surface on a SuperDoc instance (`superdoc.fonts`). The substitution- and load-aware
  * answer to "what fonts does this document use and did SuperDoc render them faithfully" -
@@ -3178,19 +3205,7 @@ export interface EditorTransactionEvent {
     /** Header/footer variant (`default`, `first`, `even`, `odd`) when available. */
     sectionType?: string | null;
 }
-/** A content control reported by an Editor interaction callback. */
-export interface ContentControlRef {
-    /** Content-control id from the DOCX. */
-    id: string;
-    /** Content-control tag, when the DOCX defines one. */
-    tag?: string;
-    /** Display name from the DOCX, when defined. */
-    alias?: string;
-    /** Content-control type, such as `text`, `checkbox`, or `date`. */
-    controlType: ContentControlType;
-    /** Whether the control is inline or contains one or more blocks. */
-    scope: 'inline' | 'block';
-}
+export type { ContentControlRef } from '../../public/content-control-ref.js';
 /**
  * Previous content-control reference shape.
  * @deprecated replaceWith=`ContentControlRef` compat-indefinitely=v2 event payload compatibility
@@ -3216,13 +3231,7 @@ export interface ContentControlActiveChangePayload {
     /** Reported source of the selection change. */
     source: 'keyboard' | 'pointer';
 }
-/** Details reported when someone clicks inside a content control. */
-export interface ContentControlClickPayload {
-    /** Innermost clicked content control. */
-    target: ContentControlRef;
-    /** Content-control clicks always originate from a pointer. */
-    source: 'pointer';
-}
+export type { ContentControlClickPayload } from '../../public/content-control-ref.js';
 export interface SuperDocLayoutEngineOptions {
     /**
      * Layout engine flow mode.
@@ -3881,6 +3890,37 @@ export interface TrackChangesInteractionConfig {
      */
     allowDecisions?: boolean;
 }
+/** Native keyboard writing assistance requested from the device keyboard. */
+export interface WritingAssistanceConfig {
+    /** Let the keyboard apply autocorrect and predictive replacements (default: false). */
+    autocorrect?: boolean;
+    /** Keyboard auto-capitalization mode (default: 'off'). */
+    autocapitalize?: 'off' | 'sentences' | 'words' | 'characters';
+    /** Let the keyboard underline and suggest spelling fixes (default: false). */
+    spellcheck?: boolean;
+}
+/**
+ * Opt-in touch behavior for this Editor. Every field defaults to off, and
+ * omitted or `false` values keep the existing touch behavior unchanged.
+ * Mouse, pen and keyboard input are never affected.
+ */
+export interface TouchInteractionConfig {
+    /**
+     * Opt in to SuperDoc-owned touch gestures (default: false).
+     *
+     * When enabled, a stationary touch hold on document content opens the
+     * existing SuperDoc context menu when the finger lifts, with the same caret
+     * and selection rules as a right-click. The lift does not activate content
+     * underneath. Where the browser shows its own text-selection menu for the
+     * hold (iOS Safari), it is dismissed once the SuperDoc menu opens and the
+     * held word stays selected in SuperDoc; where the browser reports the hold
+     * as a context-menu event (Android Chrome), the existing right-click path
+     * opens the menu once. A hold during IME composition does nothing. Taps and
+     * swipes keep their existing behavior. Hosts that disable the context menu,
+     * and viewing mode, keep native behavior. Read when the editor mounts.
+     */
+    gestures?: boolean;
+}
 /**
  * Controls which interactions this Editor allows, independent of what
  * SuperDoc renders.
@@ -3893,6 +3933,10 @@ export interface InteractionConfig {
     comments?: CommentInteractionConfig;
     /** Tracked-change interaction policy. */
     trackedChanges?: TrackChangesInteractionConfig;
+    /** Opt-in touch behavior. Omitted fields keep the existing behavior. */
+    touch?: TouchInteractionConfig;
+    /** Native keyboard writing assistance. Everything is off when omitted. */
+    writingAssistance?: WritingAssistanceConfig;
 }
 /**
  * Shared plumbing for dialogs and floating overlays, including surfaces the
@@ -3937,16 +3981,25 @@ export interface SurfacesConfig {
     };
 }
 /**
- * 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.
+ * Worker URLs accepted by v2. The editor runs on the page and starts no
+ * document worker, so only `collaboration` is used, and only by collaboration
+ * targets with `providerType: 'extension'`.
  */
 interface V2WorkerUrlsConfig {
-    /** Main document worker used by non-collaborative v2 documents. */
+    /**
+     * @deprecated The editor runs on the page and starts no document worker.
+     * Accepted and ignored for configuration compatibility.
+     */
     document?: string | URL;
-    /** Collaboration-capable document worker used by v2 collaboration rooms. */
+    /**
+     * Your provider-extension collaboration worker, built with
+     * `bootstrapSuperDocCollaborationWorker` from the same SuperDoc version.
+     * Must be a same-origin module worker URL. Required for
+     * `providerType: 'extension'`; ignored by the built-in providers, which
+     * sync on the page.
+     */
     collaboration?: string | URL;
-    /** @deprecated Review processing runs in the document worker. Accepted for configuration compatibility. */
+    /** @deprecated Accepted and ignored for configuration compatibility. */
     reviewIndex?: string | URL;
 }
 export interface Config {
@@ -4172,12 +4225,25 @@ export interface Config {
     onReady?: (params: SuperDocReadyPayload) => void;
     /** Callback when comments are updated. */
     onCommentsUpdate?: (params: SuperDocCommentsUpdatePayload) => void;
+    /**
+     * Called when someone accepts a tracked change from its bubble in the comments sidebar.
+     * Receives the tracked-change comment and the active editor. In SuperDoc 2 it runs after the accept is applied.
+     */
+    onTrackedChangeBubbleAccept?: (comment: Comment, editor: Editor | null) => void;
+    /**
+     * Called when someone rejects a tracked change from its bubble in the comments sidebar.
+     * Receives the tracked-change comment and the active editor. In SuperDoc 2 it runs after the reject is applied.
+     */
+    onTrackedChangeBubbleReject?: (comment: Comment, editor: Editor | null) => void;
     /**
      * Callback when the selection enters, leaves, or moves between content controls.
      * @deprecated replaceWith=`superdoc.ui.contentControls.observe` compat-indefinitely=v2 event compatibility
      */
     onContentControlActiveChange?: (params: ContentControlActiveChangePayload) => void;
-    /** Callback when someone clicks inside a content control. */
+    /**
+     * Callback when someone clicks inside a content control.
+     * @deprecated replaceWith=`superdoc.ui.contentControls.onClick` removeIn=v3.0
+     */
     onContentControlClick?: (params: ContentControlClickPayload) => void;
     /** Callback when awareness is updated. */
     onAwarenessUpdate?: (params: SuperDocAwarenessUpdatePayload) => void;
@@ -4232,6 +4298,8 @@ export interface Config {
      * Callback when the zoom level changes. Fires for every zoom source:
      * `setZoom()`, the toolbar zoom control, and fit-width
      * adjustments.
+     *
+     * @deprecated replaceWith=`superdoc.ui.zoom.observe` removeIn=v3.0
      */
     onZoomChange?: (params: SuperDocZoomPayload) => void;
     /**
@@ -4404,22 +4472,22 @@ export interface Config {
      */
     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.
+     * Worker URLs. Only `collaboration` is used: the provider-extension
+     * collaboration worker for `providerType: 'extension'`. `document` and
+     * `reviewIndex` are accepted and ignored because the editor runs on the page.
      */
     workerUrls?: V2WorkerUrlsConfig;
     /**
-     * Budget for the document worker to start up, in milliseconds
-     * (default: 30000). Measured from worker spawn, so it covers script
-     * download, parsing, evaluation, and the worker's first response to
-     * SuperDoc. Raise it when a large worker chunk is served
-     * over a slow connection or a cold dev-server cache; lower it to fail faster.
-     * Worker load errors are reported immediately and do not wait for this
-     * budget. Must be a finite positive number no greater than 2147483647, the
-     * platform timer ceiling above which a delay would fire immediately.
+     * Budget for the provider-extension collaboration worker
+     * (`workerUrls.collaboration`, `providerType: 'extension'`) to start up and
+     * send its first response, in milliseconds. Defaults to the collaboration
+     * `syncTimeoutMs`, or 30000. Worker load errors are reported immediately and
+     * do not wait for this budget. Ignored by the built-in providers and by
+     * documents opened without collaboration, which start no worker.
      */
     workerStartupTimeoutMs?: number;
+    /** Retention of attributed change records read through `activeEditor.doc.changes`. */
+    changes?: ChangesConfig;
     /**
      * Whether `layoutEngineOptions` are passed when a DOCX editor opens.
      *

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

@@ -72,6 +72,12 @@ interface V2ReviewWindowDiagnostics {
     records: readonly Record<string, unknown>[];
 }
 interface V2ReviewWindowController {
+    noteAnalysisProgress?(progress: {
+        state: string;
+        done: number;
+        total: number;
+        stage: string | null;
+    } | null): void;
     setContext(context: V2ReviewWindowContext | null): void;
     onCommittedPagePaint?(commit: V2CommittedPageWindow): void;
     refreshCommittedWindow(reason?: string): void;

package/dist/superdoc/src/helpers/deprecation.d.ts

@@ -1,4 +1,13 @@
-import { Editor } from '../core/types/index.js';
+/**
+ * Deprecation utilities for steering consumers toward the Document API.
+ *
+ * ProseMirror will be removed in a future major version. These helpers emit
+ * one-time console warnings when deprecated properties are accessed on an
+ * editor instance handed to consumer callbacks (onEditorCreate, etc.).
+ *
+ * Internal code continues to use the raw Editor — only the consumer-facing
+ * boundary wraps the editor with a Proxy.
+ */
 /**
  * Log a console.warn once per key. Subsequent calls with the same key are no-ops.
  */
@@ -12,9 +21,9 @@ export declare function warnOnce(key: string, message: string): void;
  *
  * @returns Proxied editor (or the original if null/already wrapped)
  */
-export declare function createDeprecatedEditorProxy<T extends Editor | null | undefined>(editor: T): T;
+export declare function createDeprecatedEditorProxy<T extends object | null | undefined>(editor: T): T;
 /**
  * Unwrap a potentially proxied editor back to the raw Editor instance.
  * Safe to call on an already-raw editor — returns it unchanged.
  */
-export declare function unwrapEditor(editor: Editor | null | undefined): Editor | null | undefined;
+export declare function unwrapEditor<T extends object>(editor: T | null | undefined): T | null | undefined;

package/dist/superdoc/src/helpers/object-guards.d.ts

@@ -1,2 +1,3 @@
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
 export declare function isThenable(value: unknown): value is PromiseLike<unknown>;

package/dist/superdoc/src/helpers/v2-review-geometry-delivery.d.ts

@@ -0,0 +1,22 @@
+export interface ReviewGeometryDeliveryPayload extends Readonly<Record<string, unknown>> {
+    documentEpoch?: unknown;
+    paintEpoch?: unknown;
+    commitSequence?: unknown;
+    generation?: unknown;
+    pageIndices?: unknown;
+    zoomScale?: unknown;
+    reviewGeometry?: unknown;
+}
+type Render = {
+    mountContainer: HTMLElement | null;
+    documentId?: string | null;
+    epoch?: number | null;
+};
+export declare function createReviewGeometryDelivery<T extends Render>(deliver: (value: T, payload: ReviewGeometryDeliveryPayload) => void): {
+    notify: (documentId: string, payload: ReviewGeometryDeliveryPayload, current: T | null, ready?: boolean) => boolean;
+    observe: (current: T) => void;
+    flush(current: T): boolean;
+    replay(current: T): boolean;
+    reset(): void;
+};
+export {};

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

@@ -16,6 +16,7 @@ interface ToolbarButtonItem {
     attributes: Ref<{
         className?: unknown;
         ariaLabel?: string;
+        ariaBusy?: boolean;
     }>;
     nestedOptions?: Ref<{
         label?: string;

package/dist/superdoc/src/public/content-control-ref.d.ts

@@ -0,0 +1,12 @@
+import { ContentControlType } from '../../../document-api/src/index.js';
+export interface ContentControlRef {
+    id: string;
+    tag?: string;
+    alias?: string;
+    controlType: ContentControlType;
+    scope: 'inline' | 'block';
+}
+export interface ContentControlClickPayload {
+    target: ContentControlRef;
+    source: 'pointer';
+}

package/dist/superdoc/src/public/index.d.cts

@@ -1,6 +1,7 @@
 // Generated by scripts/ensure-types.cjs. Do not edit by hand.
 import type { AwarenessState as __Cjs_AwarenessState } from './index.js' with { "resolution-mode": "import" };
 import type { AwarenessUser as __Cjs_AwarenessUser } from './index.js' with { "resolution-mode": "import" };
+import type { BlockChange as __Cjs_BlockChange } from './index.js' with { "resolution-mode": "import" };
 import type { BlockNavigationAddress as __Cjs_BlockNavigationAddress } from './index.js' with { "resolution-mode": "import" };
 import type { BlocksListResult as __Cjs_BlocksListResult } from './index.js' with { "resolution-mode": "import" };
 import type { BookmarkAddress as __Cjs_BookmarkAddress } from './index.js' with { "resolution-mode": "import" };
@@ -8,6 +9,11 @@ import type { BookmarkInfo as __Cjs_BookmarkInfo } from './index.js' with { "res
 import type { BorrowedSuperDocUI as __Cjs_BorrowedSuperDocUI } from './index.js' with { "resolution-mode": "import" };
 import type { BuiltInCommandId as __Cjs_BuiltInCommandId } from './index.js' with { "resolution-mode": "import" };
 import type { CanPerformPermissionParams as __Cjs_CanPerformPermissionParams } from './index.js' with { "resolution-mode": "import" };
+import type { ChangeActor as __Cjs_ChangeActor } from './index.js' with { "resolution-mode": "import" };
+import type { ChangeCause as __Cjs_ChangeCause } from './index.js' with { "resolution-mode": "import" };
+import type { ChangeProvenance as __Cjs_ChangeProvenance } from './index.js' with { "resolution-mode": "import" };
+import type { ChangeRecord as __Cjs_ChangeRecord } from './index.js' with { "resolution-mode": "import" };
+import type { ChangesConfig as __Cjs_ChangesConfig } from './index.js' with { "resolution-mode": "import" };
 import type { CollaborationConfig as __Cjs_CollaborationConfig } from './index.js' with { "resolution-mode": "import" };
 import type { CommentAddress as __Cjs_CommentAddress } from './index.js' with { "resolution-mode": "import" };
 import type { CommentInteractionConfig as __Cjs_CommentInteractionConfig } from './index.js' with { "resolution-mode": "import" };
@@ -283,6 +289,7 @@ import type { ToolbarItemId as __Cjs_ToolbarItemId } from './index.js' with { "r
 import type { ToolbarOptionalItemId as __Cjs_ToolbarOptionalItemId } from './index.js' with { "resolution-mode": "import" };
 import type { ToolbarRegion as __Cjs_ToolbarRegion } from './index.js' with { "resolution-mode": "import" };
 import type { ToolbarStringId as __Cjs_ToolbarStringId } from './index.js' with { "resolution-mode": "import" };
+import type { TouchInteractionConfig as __Cjs_TouchInteractionConfig } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangeAuthor as __Cjs_TrackChangeAuthor } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangeHighlightColors as __Cjs_TrackChangeHighlightColors } from './index.js' with { "resolution-mode": "import" };
 import type { TrackChangesAuthorColorsConfig as __Cjs_TrackChangesAuthorColorsConfig } from './index.js' with { "resolution-mode": "import" };
@@ -298,14 +305,18 @@ import type { UIConfig as __Cjs_UIConfig } from './index.js' with { "resolution-
 import type { UpgradeToCollaborationOptions as __Cjs_UpgradeToCollaborationOptions } from './index.js' with { "resolution-mode": "import" };
 import type { UpgradeToCollaborationResult as __Cjs_UpgradeToCollaborationResult } from './index.js' with { "resolution-mode": "import" };
 import type { User as __Cjs_User } from './index.js' with { "resolution-mode": "import" };
+import type { UserClaim as __Cjs_UserClaim } from './index.js' with { "resolution-mode": "import" };
+import type { UserClaimContext as __Cjs_UserClaimContext } from './index.js' with { "resolution-mode": "import" };
 import type { V2CollaborationConfig as __Cjs_V2CollaborationConfig } from './index.js' with { "resolution-mode": "import" };
 import type { ViewingOptions as __Cjs_ViewingOptions } from './index.js' with { "resolution-mode": "import" };
 import type { ViewingTrackedChangesMode as __Cjs_ViewingTrackedChangesMode } from './index.js' with { "resolution-mode": "import" };
 import type { ViewingVisibilityConfig as __Cjs_ViewingVisibilityConfig } from './index.js' with { "resolution-mode": "import" };
 import type { ViewOptions as __Cjs_ViewOptions } from './index.js' with { "resolution-mode": "import" };
+import type { WritingAssistanceConfig as __Cjs_WritingAssistanceConfig } from './index.js' with { "resolution-mode": "import" };
 export type { __Cjs_AwarenessState as AwarenessState };
 export type { __Cjs_AwarenessUser as AwarenessUser };
 export declare const BlankDOCX: typeof import('./index.js', { with: { "resolution-mode": "import" } }).BlankDOCX;
+export type { __Cjs_BlockChange as BlockChange };
 export type { __Cjs_BlockNavigationAddress as BlockNavigationAddress };
 export type { __Cjs_BlocksListResult as BlocksListResult };
 export type { __Cjs_BookmarkAddress as BookmarkAddress };
@@ -314,6 +325,11 @@ export type { __Cjs_BorrowedSuperDocUI as BorrowedSuperDocUI };
 export declare const buildTheme: typeof import('./index.js', { with: { "resolution-mode": "import" } }).buildTheme;
 export type { __Cjs_BuiltInCommandId as BuiltInCommandId };
 export type { __Cjs_CanPerformPermissionParams as CanPerformPermissionParams };
+export type { __Cjs_ChangeActor as ChangeActor };
+export type { __Cjs_ChangeCause as ChangeCause };
+export type { __Cjs_ChangeProvenance as ChangeProvenance };
+export type { __Cjs_ChangeRecord as ChangeRecord };
+export type { __Cjs_ChangesConfig as ChangesConfig };
 export type { __Cjs_CollaborationConfig as CollaborationConfig };
 export type { __Cjs_CommentAddress as CommentAddress };
 export type { __Cjs_CommentInteractionConfig as CommentInteractionConfig };
@@ -600,6 +616,7 @@ export type { __Cjs_ToolbarItemId as ToolbarItemId };
 export type { __Cjs_ToolbarOptionalItemId as ToolbarOptionalItemId };
 export type { __Cjs_ToolbarRegion as ToolbarRegion };
 export type { __Cjs_ToolbarStringId as ToolbarStringId };
+export type { __Cjs_TouchInteractionConfig as TouchInteractionConfig };
 export type { __Cjs_TrackChangeAuthor as TrackChangeAuthor };
 export type { __Cjs_TrackChangeHighlightColors as TrackChangeHighlightColors };
 export type { __Cjs_TrackChangesAuthorColorsConfig as TrackChangesAuthorColorsConfig };
@@ -615,8 +632,11 @@ export type { __Cjs_UIConfig as UIConfig };
 export type { __Cjs_UpgradeToCollaborationOptions as UpgradeToCollaborationOptions };
 export type { __Cjs_UpgradeToCollaborationResult as UpgradeToCollaborationResult };
 export type { __Cjs_User as User };
+export type { __Cjs_UserClaim as UserClaim };
+export type { __Cjs_UserClaimContext as UserClaimContext };
 export type { __Cjs_V2CollaborationConfig as V2CollaborationConfig };
 export type { __Cjs_ViewingOptions as ViewingOptions };
 export type { __Cjs_ViewingTrackedChangesMode as ViewingTrackedChangesMode };
 export type { __Cjs_ViewingVisibilityConfig as ViewingVisibilityConfig };
 export type { __Cjs_ViewOptions as ViewOptions };
+export type { __Cjs_WritingAssistanceConfig as WritingAssistanceConfig };

package/dist/superdoc/src/public/index.d.ts

@@ -115,7 +115,7 @@ export type { SuperDocLayoutEngineOptions as LayoutEngineOptions } from '../core
 export type { FlowBlock, FlowMode, Layout, Fragment as LayoutFragment, Page as LayoutPage } from '../../../layout-engine/contracts/src/index.js';
 export type { LayoutMetrics } from '../../../layout-engine/layout-bridge/src/index.js';
 export type { LayoutMode } from '../../../layout-engine/painters/dom/src/index.js';
-export type { CommentInteractionConfig, CommentsConfig, CommentsLayout, CommentsResponsiveConfig, TrackChangesInteractionConfig, } from '../core/types/index.js';
+export type { CommentInteractionConfig, CommentsConfig, CommentsLayout, CommentsResponsiveConfig, TouchInteractionConfig, TrackChangesInteractionConfig, WritingAssistanceConfig, } from '../core/types/index.js';
 export type { TrackChangeHighlightColors } from '../core/types/index.js';
 export type { ContentControlsConfig } from '../core/types/index.js';
 export type { RulerConfig } from '../core/types/index.js';
@@ -200,6 +200,9 @@ export type { UpgradeToCollaborationResult } from '../core/types/index.js';
 export type { SuperDocCollaborationUpgradeError } from '../core/types/index.js';
 export type { V2CollaborationConfig } from '../core/types/index.js';
 export type { User } from '../core/types/index.js';
+export type { UserClaim, UserClaimContext } from '../core/types/index.js';
+export type { ChangesConfig } from '../core/types/index.js';
+export type { BlockChange, ChangeActor, ChangeCause, ChangeProvenance, ChangeRecord } from '../../../document-api/src/index.js';
 export type { ViewOptions } from '../core/types/index.js';
 export type { ViewingOptions } from '../core/types/index.js';
 export type { ViewingTrackedChangesMode } from '../core/types/index.js';

package/dist/superdoc/src/public/ui/async-read-cache.d.ts

@@ -0,0 +1,32 @@
+export type AsyncReadEntry = {
+    token: string | null;
+    value: unknown;
+    hasSettled: boolean;
+    inflightToken: string | null;
+    failedToken?: string | null;
+    failureCount?: number;
+    retryAtMs?: number;
+    settled?: Promise<void>;
+};
+export type AsyncReadSettlement = {
+    key: string;
+    settledAtMs: number;
+    commandId: string | null;
+    commandKind: string | null;
+};
+export interface AsyncReadCacheOptions {
+    isDisposed: () => boolean;
+    recomputeAfterSettle: () => void;
+    recomputeWhenRetryDue: () => void;
+}
+export declare function failureRetryDelayMs(failureCount: number): number;
+export declare function createAsyncReadCache(options: AsyncReadCacheOptions): {
+    entries: Map<string, AsyncReadEntry>;
+    issue: (key: string, token: string, run: () => unknown, normalize: (raw: unknown) => unknown) => AsyncReadEntry | null;
+    seed: (key: string, token: string | null, value: unknown, inflightToken?: string | null) => void;
+    clearKeys: (predicate: (key: string) => boolean) => void;
+    scheduleRefresh: () => void;
+    scheduleFailureRetry: (retryAtMs: number) => void;
+    cancelFailureRetry: () => void;
+    drainSettlements: () => AsyncReadSettlement[];
+};

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

@@ -0,0 +1,39 @@
+import { LooseRecord } from './loose-record.js';
+import { TableCommandSpec } from './commands.js';
+export declare const PARAGRAPH_INDENT_STEP_TWIPS = 720;
+export type ParagraphIndentationTwips = {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+};
+export declare function pointsToTwips(value: number): number;
+export declare function readParagraphIndentationFromResult(result: unknown): ParagraphIndentationTwips | null;
+export interface ResolvedTableContext {
+    canMerge: boolean;
+    tableNodeId: string;
+    rowIndex: number;
+    columnIndex: number;
+    cellNodeId: string | null;
+    mergeRange: {
+        start: {
+            rowIndex: number;
+            columnIndex: number;
+        };
+        end: {
+            rowIndex: number;
+            columnIndex: number;
+        };
+    } | null;
+}
+export declare function readMergeRange(range: LooseRecord | undefined): {
+    start: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    end: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+} | null;
+export declare function buildTableCommandInput(action: TableCommandSpec['action'], context: ResolvedTableContext): LooseRecord | null;

package/dist/superdoc/src/public/ui/command-results.d.ts

@@ -0,0 +1,39 @@
+import { SuperDocUIReason } from './reasons.js';
+import { CommandExecutionResult, CommandState, ListPresetId, PartialLinkEditReceipt, Receipt, SelectionSlice, SuperDocUIFailureReceipt, SuperDocUIReceiptFailureCode, ViewportRect, ViewportRectResult, WorkflowActionResult } from './types.js';
+import { AnyFn, LooseRecord } from './loose-record.js';
+import { CommandDescriptor, TrackDecisionSpec, UiDocRoute } from './commands.js';
+export declare const SUPERDOC_UI_REASON_VALUES: Set<string>;
+export declare function coerceSuperDocUIReason(reason: unknown, fallback: SuperDocUIReason): SuperDocUIReason;
+export declare function normalizeHostSelectionApplyResult(result: unknown): WorkflowActionResult;
+export declare const LIST_TOGGLE_KINDS: Record<string, 'bullet' | 'ordered'>;
+export declare function listToggleKind(id: string): 'bullet' | 'ordered' | null;
+export declare const TOOLBAR_LIST_STYLE_PRESETS: Record<string, ListPresetId>;
+export declare function presetFromToolbarStyleKey(styleKey: string): {
+    preset?: ListPresetId;
+    behavior?: 'toggleStyle';
+};
+export declare function safeCall<T>(fn: (() => T) | undefined, fallback: T): T;
+export declare function hostMethod(target: unknown, name: string): ((...args: unknown[]) => unknown) | null;
+export declare function hasAbortedFlag(value: unknown): value is {
+    readonly aborted: boolean;
+};
+export declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
+export declare function resolveDocOperation(doc: LooseRecord | null, path: UiDocRoute): AnyFn | null;
+export declare function failedReceipt(message: string, code?: Exclude<SuperDocUIReceiptFailureCode, 'PARTIAL_LINK_EDIT'>): SuperDocUIFailureReceipt;
+export declare function partialLinkEditFailure(hyperlinkResult: CommandExecutionResult, textResult: CommandExecutionResult): PartialLinkEditReceipt;
+export declare const MIRRORED_EDIT_COMMAND_IDS: {
+    readonly undo: "history.undo";
+    readonly redo: "history.redo";
+};
+export declare function normalizeCommandState(state: Partial<CommandState>, source: CommandState['source']): CommandState;
+export declare function commandResultFromOperationResult(result: unknown): CommandExecutionResult;
+export declare function isSuccessfulReceipt(result: CommandExecutionResult): result is Extract<Receipt, {
+    success: true;
+}>;
+export declare function commandResultSucceeded(result: CommandExecutionResult): boolean;
+export declare function combineCommandResults(results: readonly CommandExecutionResult[]): CommandExecutionResult;
+export declare function trackDecisionCommand(id: string): TrackDecisionSpec | null;
+export declare function rectResult(rects: readonly ViewportRect[]): ViewportRectResult;
+export declare function rectFailure(reason: string): ViewportRectResult;
+export declare function relativizeRects(result: ViewportRectResult, relativeTo?: HTMLElement): ViewportRectResult;
+export declare function commandIsActive(descriptor: CommandDescriptor, selection: SelectionSlice): boolean;

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

@@ -1,4 +1,8 @@
+import { OperationId } from '../../../../document-api/src/index.js';
 import { SuperDocUIReason } from './reasons.js';
+export type InternalUiDocRoute = 'format.readEffectiveInlineUniformity' | 'lists.indentRange' | 'lists.outdentRange' | 'lists.outdentInStory' | 'lists.removeInStory';
+export type DocumentApiAliasRoute = 'format.strikethrough';
+export type UiDocRoute = OperationId | DocumentApiAliasRoute | InternalUiDocRoute;
 /**
  * The original v2-native command ids. These are the historically stable
  * `superdoc/ui` built-ins; the broader catalog below adds v1 headless-toolbar
@@ -192,7 +196,7 @@ export interface CommandDescriptor {
     /** Other ids that alias this command (documentation). */
     aliases?: readonly string[];
     /** Dotted path on the public Document API facade (`activeEditor.doc`). */
-    docRoute?: string;
+    docRoute?: UiDocRoute;
     /** Public SuperDoc-instance method this command calls. */
     instanceRoute?: string;
     /** Fixed argument passed to `instanceRoute` instead of the payload. */

package/dist/superdoc/src/public/ui/content-controls-handle.d.ts

@@ -0,0 +1,31 @@
+import { LooseRecord } from './loose-record.js';
+import { ContentControlsHandle, ContentControlsSlice, ScrollIntoViewInput, SelectionTarget, SnapshotSubscribable, Subscribable, SuperDocUIState, ViewportRectResult, WorkflowActionResult, WorkflowScrollResult } from './types.js';
+type ScrollPlacement = {
+    block?: ScrollIntoViewInput['block'];
+    behavior?: ScrollIntoViewInput['behavior'];
+};
+export interface ContentControlsHandleDeps {
+    superdoc: unknown;
+    select: (selector: (state: Pick<SuperDocUIState, 'contentControls'>) => ContentControlsSlice) => Subscribable<ContentControlsSlice>;
+    snapshotHandle: (sub: Subscribable<ContentControlsSlice>) => SnapshotSubscribable<ContentControlsSlice>;
+    leasedDirectorySnapshot: (passive: Subscribable<ContentControlsSlice>, directory: Subscribable<ContentControlsSlice>) => SnapshotSubscribable<ContentControlsSlice>;
+    directoryLeaseHeld: () => boolean;
+    demandCatalog: () => void;
+    isDisposed: () => boolean;
+    currentEditor: () => LooseRecord | null;
+    currentHost: () => LooseRecord | null;
+    documentContentControls: () => unknown;
+    rectOf: (target: SelectionTarget) => ViewportRectResult;
+    scrollIntoView: (target: SelectionTarget, placement: ScrollPlacement) => Promise<WorkflowScrollResult>;
+    applySelection: (target: SelectionTarget) => WorkflowActionResult;
+    activateChrome: (id: string) => void;
+    onDocumentReset: (hook: () => void) => void;
+    onDestroy: (detach: () => void) => void;
+}
+export interface ContentControlsController {
+    handle: ContentControlsHandle;
+    clearHighlight: () => void;
+    clearClickListeners: () => void;
+}
+export declare function createContentControlsHandle(deps: ContentControlsHandleDeps): ContentControlsController;
+export {};

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

@@ -8,7 +8,7 @@ type FirstPartyCommandMutation = {
     };
     supports: (memberPath: string) => boolean;
     run: (memberPath: string, args: readonly unknown[]) => unknown;
-    runListApply: (input: unknown) => Promise<boolean>;
+    runListApply: (input: unknown) => Promise<unknown>;
 };
 export declare function registerFirstPartyCommandMutation(superdoc: object, host: object, mutation: FirstPartyCommandMutation): void;
 /**
@@ -18,21 +18,5 @@ export declare function registerFirstPartyCommandMutation(superdoc: object, host
 export declare function readFirstPartyPageNumbers(ui: object): Promise<unknown>;
 export declare function executeFirstPartyCommandAsync(ui: Pick<SuperDocUI, 'commands'>, id: string, payload?: unknown): Promise<CommandExecutionResult>;
 export declare function executeFirstPartyShortcutAsync(ui: object, id: string, payload?: unknown): Promise<CommandExecutionResult>;
-/**
- * Heavy-read policy for the async read coordinator (source-loading deferral).
- * One shared table: the coordinator's gate and the table-driven policy tests
- * both consume THIS list, so the deferred set cannot silently drift from the
- * tested set. Keys are coordinator cache keys (exact) or key families
- * (prefix). See the gate in `readAsync` for the runtime semantics.
- */
-interface HeavyDocReadPolicyEntry {
-    key: string;
-    match: 'exact' | 'prefix';
-    /** Audit rationale — why this key is catalog-scale (or reserved). */
-    note: string;
-}
-export declare const HEAVY_DOC_READ_POLICY: readonly HeavyDocReadPolicyEntry[];
-/** Whether a coordinator cache key falls under the heavy-read policy. */
-export declare function isHeavyDocReadKey(key: string): boolean;
 export declare function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI;
 export {};