superdoc 2.29.0-next.9 → 2.30.0-next.13

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

package/dist/superdoc/src/public/ui/document-change-records.d.ts

@@ -0,0 +1,7 @@
+import { ChangeRecord, StoryLocator } from '../../../../document-api/src/index.js';
+import { SuperDocDocumentChange } from './types.js';
+type RemoteDocumentChangeFacts = Omit<SuperDocDocumentChange, 'documentEpoch' | 'seq'>;
+export declare function remoteChangeRecordsOf(event: Record<string, unknown>): ChangeRecord[];
+export declare function storiesOfChangeRecords(records: readonly ChangeRecord[]): StoryLocator[];
+export declare function remoteDocumentChange(records: readonly ChangeRecord[]): RemoteDocumentChangeFacts;
+export {};

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

@@ -0,0 +1,14 @@
+export declare function readEntityTarget(row: unknown): unknown | null;
+export declare function isHostGeometryTarget(target: unknown): boolean;
+export declare function readTrackedChangeNavigationTarget(row: unknown, options?: {
+    preferStableBlock?: boolean;
+}): unknown | null;
+export declare function storyLocatorSignature(story: unknown): string;
+export declare function readEntityStory(row: unknown): unknown | null;
+export declare function entityRowMatchesRequest(row: unknown, id: string, story?: unknown): boolean;
+export declare function readEntityRequestStory(row: unknown): unknown | undefined;
+export declare function layoutStoryDatasetToStoryLocator(raw: unknown): unknown;
+export declare function storyKeyToStoryLocator(raw: unknown): unknown;
+export declare function readSelectionTarget(row: unknown): unknown | null;
+export declare function readContentControlRequestId(input: unknown): string | null;
+export declare function readEntityId(row: unknown): string | null;

package/dist/superdoc/src/public/ui/font-options.d.ts

@@ -0,0 +1,7 @@
+import { FontFamilyOption, FontSizeOption } from './types.js';
+export declare const DEFAULT_FONT_FAMILY_OPTIONS: readonly FontFamilyOption[];
+export declare function canonicalFontFamilyName(family: string): string;
+export declare function normalizeDocumentFontOptions(raw: unknown): FontFamilyOption[];
+export declare function normalizePickerFontOptions(raw: unknown): FontFamilyOption[];
+export declare function composeFontFamilyOptions(documentOptions: readonly FontFamilyOption[], pickerOptions?: readonly FontFamilyOption[]): FontFamilyOption[];
+export declare const DEFAULT_FONT_SIZE_OPTIONS: readonly FontSizeOption[];

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

@@ -2,22 +2,16 @@
  * Maps SDRunProps field names to InlineRunPatch field names.
  * SDRunProps (read-side) and InlineRunPatch (write-side) use different keys
  * for the same properties; direct assignment between them is forbidden.
- *
- * @param {Record<string, unknown>} props - SDRunProps object from doc.getNodeById
- * @returns {Record<string, unknown>} InlineRunPatch ready for doc.format.apply
  */
-export function sdRunPropsToInlineRunPatch(props: Record<string, unknown>): Record<string, unknown>;
+export declare function sdRunPropsToInlineRunPatch(props: Record<string, unknown>): Record<string, unknown>;
 /**
  * Serializes a selection to a stable string key used to detect whether
  * the target selection is the same as the source (skip apply in that case).
  *
  * Falls back to the plain text target when the host has not populated an
  * explicit `selectionTarget` yet.
- *
- * @param {{ selectionTarget?: unknown; target?: unknown } | null | undefined} selection
- * @returns {string}
  */
-export function selectionKey(selection: {
+export declare function selectionKey(selection: {
     selectionTarget?: unknown;
     target?: unknown;
 } | null | undefined): string;

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

@@ -0,0 +1,7 @@
+import { ParagraphBatchOperation, SDParagraphProps, SDTabStop } from '../../../../document-api/src/index.js';
+export type ParagraphPaintOperation = ParagraphBatchOperation;
+type ParagraphPaintProperties = Omit<SDParagraphProps, 'tabs'> & {
+    tabs?: Partial<SDTabStop>[];
+};
+export declare function captureParagraphPaintOperations(props: ParagraphPaintProperties, supports?: (operationId: ParagraphPaintOperation['operationId']) => boolean): ParagraphPaintOperation[];
+export {};

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

@@ -0,0 +1,29 @@
+import { SDRunProps } from '../../../../document-api/src/index.js';
+import { ParagraphPaintOperation } from './format-painter-paragraph.js';
+export type FormatPainterMode = 'idle' | 'armed' | 'persistent';
+export interface FormatPainterParagraphSnapshot {
+    styleId: string | null;
+    inheritedFontKeys?: Array<'fontFamily' | 'fontSize'>;
+    operations: ParagraphPaintOperation[];
+    markRunProps: SDRunProps | null;
+    numbering: {
+        numId: number;
+        level?: number;
+    } | null;
+    listStyle: unknown | null;
+}
+export interface FormatPainterSnapshot {
+    story: unknown | null;
+    inline: Record<string, unknown>;
+    mixedInlineKeys: string[];
+    paragraph: FormatPainterParagraphSnapshot | null;
+}
+export declare const FORMAT_PAINTER_BOOLEAN_KEYS: Set<string>;
+export interface FormatPainterState {
+    mode: FormatPainterMode;
+    snapshot: FormatPainterSnapshot | null;
+    sourceSelectionKey: string | null;
+    lastClickAt: number;
+    pointerSelecting: boolean;
+    keyboardSelecting: boolean;
+}

package/dist/superdoc/src/public/ui/heavy-read-policy.d.ts

@@ -0,0 +1,11 @@
+import { SliceStatus } from './types.js';
+export interface HeavyDocReadPolicyEntry {
+    key: string;
+    match: 'exact' | 'prefix';
+    note: string;
+}
+export declare const HEAVY_DOC_READ_POLICY: readonly HeavyDocReadPolicyEntry[];
+export declare const COMMENTS_CATALOG_PART_URIS: ReadonlySet<string>;
+export declare function isHeavyDocReadKey(key: string): boolean;
+export declare const STATUS_RANK: Record<SliceStatus, number>;
+export declare function combineStatus(...statuses: readonly SliceStatus[]): SliceStatus;

package/dist/superdoc/src/public/ui/host-events.d.ts

@@ -0,0 +1,3 @@
+import { ContentControlClickPayload } from './types.js';
+export declare const HOST_EVENTS: readonly ["document-replaced", "editorCreate", "active-editor-change", "document-mode-change", "formatting-marks-change", "zoomChange", "measurement-unit-change", "viewport-change", "fonts-changed"];
+export declare function isContentControlClickPayload(value: unknown): value is ContentControlClickPayload;

package/dist/superdoc/src/public/ui/inline-values.d.ts

@@ -0,0 +1,80 @@
+import { SelectionSlice, SelectionTarget, SuperDocUIState } from './types.js';
+import { LooseRecord } from './loose-record.js';
+import { CommandDescriptor } from './commands.js';
+import { selectionStoryLocator } from './selection-targets.js';
+export { selectionStoryLocator };
+export type EffectiveInlineUniformityState = {
+    state: 'uniform';
+    value: string;
+} | {
+    state: 'mixed' | 'unresolvable' | 'absent';
+};
+export declare function readEffectiveInlineUniformityStates(raw: unknown): Record<string, EffectiveInlineUniformityState> | null;
+export type SelectionTextSegment = {
+    blockId: string;
+    start: number;
+    end: number;
+};
+export declare const PROJECTED_INLINE_SELECTION_VALUE_KEYS: readonly ["fontFamily", "fontSize", "color", "highlight"];
+export type ProjectedInlineSelectionValueKey = (typeof PROJECTED_INLINE_SELECTION_VALUE_KEYS)[number];
+export type ProjectedInlineSelectionValues = Partial<Record<ProjectedInlineSelectionValueKey, string>>;
+export declare const EFFECTIVE_MARK_KEYS: readonly ["bold", "italic", "underline", "strikethrough"];
+export type EffectiveMarkKey = (typeof EFFECTIVE_MARK_KEYS)[number];
+export type EffectiveMarkValues = Partial<Record<EffectiveMarkKey, boolean>>;
+export type OptimisticInlineSelectionValue = {
+    selectionSignature: string;
+    value: string;
+};
+export type OptimisticInlineToggle = {
+    selectionSignature: string;
+    active: boolean;
+    generation: number;
+    settled: boolean;
+    editorSource: unknown;
+    documentSource: unknown;
+    documentMode: SuperDocUIState['documentMode'];
+};
+export type OptimisticParagraphAlignment = {
+    selectionSignature: string;
+    value: 'left' | 'center' | 'right' | 'justify';
+    generation: number;
+    settled: boolean;
+    canReconcile: boolean;
+};
+export type PendingInlineToggleMutation = {
+    key: string;
+    mutate: () => unknown;
+    result: Promise<unknown>;
+    resolve: (value: unknown | PromiseLike<unknown>) => void;
+};
+export declare function isProjectedInlineSelectionValueKey(value: string): value is ProjectedInlineSelectionValueKey;
+export declare function selectionTextSegments(selection: SelectionSlice): SelectionTextSegment[];
+export declare function selectionInlineValueStorySignature(selection: SelectionSlice): string;
+export declare function selectionInlineValueSignature(selection: SelectionSlice): string | null;
+export declare function selectionEffectiveUniformitySignature(selection: SelectionSlice): string | null;
+export declare function normalizeOptimisticInlineSelectionValue(key: ProjectedInlineSelectionValueKey, value: unknown): string | null;
+export declare function rangesOverlap(left: {
+    start: number;
+    end: number;
+}, right: {
+    start: number;
+    end: number;
+}): boolean;
+export declare function queryMatchItemSegments(item: LooseRecord | null | undefined): SelectionTextSegment[];
+export declare function sameSelectionTextSegments(left: readonly SelectionTextSegment[], right: readonly SelectionTextSegment[]): boolean;
+export declare function pickSelectionTextQueryItem(result: LooseRecord | null, selection: SelectionSlice): LooseRecord | null;
+export declare function readProjectedInlineStyleValue(styles: LooseRecord | null | undefined, key: ProjectedInlineSelectionValueKey): string | undefined;
+export declare function normalizeLayoutFontFamily(value: unknown): string | undefined;
+export declare function normalizeLayoutFontSizePt(value: unknown): string | undefined;
+export declare function normalizeProjectedInlineStyleValueKey(key: ProjectedInlineSelectionValueKey, value: string): string;
+export declare function projectInlineValuesFromQueryItem(item: LooseRecord | null, selection: SelectionSlice): ProjectedInlineSelectionValues;
+export declare function collectProjectionTextBlocks(blocks: unknown): LooseRecord[];
+export declare function projectionBlockMatchesId(block: LooseRecord, id: string): boolean;
+export declare function projectionRunSelectionLength(run: LooseRecord): number;
+export declare function inlineFormatMethod(descriptor: CommandDescriptor): string | null;
+export declare const CLEAR_INLINE_PATCH: Readonly<Record<string, null>>;
+export declare const TRACKED_CLEAR_INLINE_PATCH: Readonly<Record<string, null>>;
+export declare function buildInlineFormatInput(spec: {
+    key: string;
+    kind: 'toggle' | 'value-string' | 'value-number' | 'clear';
+}, target: SelectionTarget, payload: unknown, active: boolean): LooseRecord | null;

package/dist/superdoc/src/public/ui/loose-record.d.ts

@@ -0,0 +1,4 @@
+export type AnyFn = (...args: unknown[]) => unknown;
+export type LooseRecord = Record<string, unknown>;
+export declare function readRecord(value: unknown): LooseRecord | undefined;
+export declare function readRecordList(value: unknown): Array<LooseRecord | undefined>;

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

@@ -94,6 +94,7 @@ export declare const SUPERDOC_UI_REASONS: {
      * are never gated by this reason.
      */
     readonly contentControlLocked: "content-control-locked";
+    readonly deletedTextFormattingUnsupported: "deleted-text-formatting-unsupported";
     /**
      * The current user is not allowed to run this command under the product
      * permissionResolver / role matrix (SD-3845). Distinct from document

package/dist/superdoc/src/public/ui/selection-targets.d.ts

@@ -0,0 +1,53 @@
+import { SelectionCapture, SelectionPoint, SelectionSlice, SelectionTarget, TextTarget } from './types.js';
+import { LooseRecord } from './loose-record.js';
+import { TextAddress, TextSegment } from '../../../../document-api/src/index.js';
+export declare const EMPTY_SELECTION: SelectionSlice;
+export declare function textTargetSegments(target: TextTarget | null | undefined): readonly TextSegment[];
+export declare function selectionPointWithBlockId(point: SelectionPoint | null | undefined): Extract<SelectionPoint, {
+    kind: 'text';
+}> | undefined;
+export declare function selectionBlockRange(selection: SelectionSlice): {
+    startBlockId: string;
+    endBlockId: string;
+} | null;
+export declare function selectionBlockIds(selection: SelectionSlice): string[];
+export declare const MAX_REACTIVE_SELECTION_BLOCK_READS = 64;
+export declare function canProbeEverySelectedBlock(blockIds: readonly string[]): boolean;
+export declare function selectionStoryLocator(selection: SelectionSlice): unknown | undefined;
+export declare function selectionStory(selection: SelectionSlice): LooseRecord;
+export declare function paragraphTarget(blockId: string, story?: unknown): LooseRecord;
+export declare function listsBlockTarget(blockId: string): LooseRecord;
+export declare function listItemTarget(blockId: string, story?: unknown): LooseRecord;
+export declare function selectionTextAddresses(selection: SelectionSlice): TextAddress[];
+export declare function textAddressesFromTarget(target: unknown): LooseRecord[];
+export declare function collapsedTextAddressFromTarget(target: unknown): LooseRecord | null;
+export declare function collapsedTextAddressFromSelection(selection: SelectionSlice): LooseRecord | null;
+export declare function isHeaderFooterCaret(selection: SelectionSlice): boolean;
+export declare function createLocationAt(selection: SelectionSlice, mode: 'nodeId' | 'target'): LooseRecord;
+export declare function hyperlinkAddressToSelectionTarget(address: LooseRecord | null | undefined): LooseRecord | null;
+export declare function hyperlinkTargetFromHref(href: string): LooseRecord;
+export declare function isAddressableSegment(segment: unknown): segment is {
+    blockId: string;
+    range: {
+        start: number;
+        end: number;
+    };
+};
+export declare function selectionTargetFromTextTarget(target: SelectionSlice['target'] | SelectionCapture['target'] | null): SelectionTarget | null;
+export type CellSelectionCapture = SelectionCapture & {
+    _tableCellSelectionTarget?: unknown;
+    _paintedSelectionTarget?: unknown;
+};
+export type TextSelectionTarget = SelectionTarget & {
+    start: Extract<SelectionTarget['start'], {
+        kind: 'text';
+    }>;
+    end: Extract<SelectionTarget['end'], {
+        kind: 'text';
+    }>;
+};
+export declare function capturedTableCellTarget(value: unknown): TextSelectionTarget | null;
+export declare function selectionTargetForRestore(capture: SelectionCapture): SelectionTarget | null;
+export declare function resolveInlineSelectionTarget(selection: SelectionSlice): SelectionTarget | null;
+export declare function selectionHasOnlyDeletedText(selection: SelectionSlice): boolean;
+export declare function selectionTouchesDeletedText(selection: SelectionSlice): boolean;

package/dist/superdoc/src/public/ui/shared-tracked-changes-catalog.d.ts

@@ -0,0 +1,16 @@
+export type SharedUiTrackedChangesCatalogState = {
+    refCount: number;
+    generation: number;
+    abortController: AbortController;
+    inFlight: {
+        generation: number;
+        commitSeq: number;
+        promise: Promise<unknown>;
+    } | null;
+    activeMutationTokens: Set<string>;
+    commitSeq: number;
+    countedCommitEvents: WeakSet<object>;
+};
+export declare const sharedUiTrackedChangesCatalogByHost: WeakMap<object, SharedUiTrackedChangesCatalogState>;
+export declare function acquireSharedUiTrackedChangesCatalog(host: object): SharedUiTrackedChangesCatalogState;
+export declare function releaseSharedUiTrackedChangesCatalog(host: object, state: SharedUiTrackedChangesCatalogState): void;

package/dist/superdoc/src/public/ui/tracked-change-ids.d.ts

@@ -0,0 +1,51 @@
+import { CommentInfo, SelectionSlice, TrackChangeInfo, TrackChangesItem } from './types.js';
+import { LooseRecord } from './loose-record.js';
+import { SuperDocUIReason } from './reasons.js';
+export declare function identityText(value: unknown): string;
+export type TrackChangeAuthorship = Pick<TrackChangeInfo, 'author' | 'authorEmail'> & {
+    authorId?: unknown;
+};
+export declare function trackedChangeOwnedByCurrentUser(change: TrackChangeAuthorship, currentUser: LooseRecord | null): boolean;
+export declare function readCollapsedHostTrackChangeId(snapshot: unknown): string | null;
+export declare function isNonCollapsedHostSelection(snapshot: unknown): boolean;
+export type SelectionTrackDecisionPlan = {
+    kind: 'ids';
+    ids: readonly string[];
+} | {
+    kind: 'id';
+    id: string;
+    story?: unknown;
+} | {
+    kind: 'range';
+    target: LooseRecord;
+    changeId: string | null;
+    story?: unknown;
+    permissionIds?: readonly string[];
+} | {
+    kind: 'blocked';
+    reason: SuperDocUIReason;
+} | {
+    kind: 'unavailable';
+};
+export interface TrackedChangeIdContext {
+    toPublicId(rawId: string): string | null;
+    aliasesFor(publicId: string): readonly string[];
+}
+export declare const trackedChangeIdContextCache: WeakMap<readonly unknown[], TrackedChangeIdContext>;
+export declare function readTrackChangeProvenanceIds(item: unknown): string[];
+export declare function buildTrackedChangeIdContext(items: readonly unknown[]): TrackedChangeIdContext;
+export declare const storyScopedTrackedChangeIdContextCache: WeakMap<readonly unknown[], Map<string, TrackedChangeIdContext>>;
+export declare const declaredBodyItemsCache: WeakMap<readonly unknown[], readonly unknown[]>;
+export declare function buildStoryScopedTrackedChangeIdContext(items: readonly unknown[], story: unknown): TrackedChangeIdContext;
+export declare function isTextboxStory(story: unknown): boolean;
+export declare function resolveStorylessCanonicalTrackedChangeId(items: readonly unknown[], selectionIds: readonly string[]): string | null;
+export declare function declaredBodyItems(items: readonly unknown[]): readonly unknown[];
+export declare function resolveSelectionActiveChangeId(options: {
+    selectionIds: readonly string[];
+    publicIds?: readonly string[];
+    selection: SelectionSlice;
+    bodyItems: readonly unknown[];
+    allStoryItems: readonly unknown[] | null;
+}): string | null;
+export declare function resolveActiveCommentId(items: readonly CommentInfo[], commentId: string): string | null;
+export declare function trackChangesItemPayload(item: TrackChangesItem): TrackChangeInfo;

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

@@ -1,5 +1,6 @@
-import { CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, EntityAddress, TextAddress, BookmarkAddress, TextTarget, ScrollIntoViewInput, ScrollIntoViewOutput, SelectionInfo, SelectionTarget, Receipt, ReceiptFailureCode, ContentControlInfo, ContentControlTarget, StyleCatalogItem, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StoryLocator as DocumentStoryLocator } from '../../../../document-api/src/index.js';
+import { CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, EntityAddress, TextAddress, BookmarkAddress, TextTarget, ScrollIntoViewInput, ScrollIntoViewOutput, SelectionInfo, SelectionTarget, Receipt, ReceiptFailureCode, ContentControlInfo, ContentControlTarget, StyleCatalogItem, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StoryLocator as DocumentStoryLocator, ChangeRecord } from '../../../../document-api/src/index.js';
 import { BrowserDocumentApi, PartialBrowserDocumentApi } from '../browser-document-api.js';
+import { ContentControlClickPayload } from '../content-control-ref.js';
 import { ExportParams } from '../export-types.js';
 import { SuperDocVisualHandle, SuperDocVisualOptions } from '../../core/extensions/types.js';
 import { DocumentReplacementResult } from '../document-replacement.js';
@@ -31,10 +32,11 @@ import { BuiltInCommandId } from './commands.js';
  * (`scripts/ensure-types.cjs` `rewriteDocApiPaths`), so no bare private
  * specifier leaks into the emitted `.d.ts`.
  */
-export type { Receipt, DocumentApiRejectionReason, DocumentApiRejectionDetails, TextRangeRejectionReason, ContentControlCreationRejectionReason, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, BookmarkAddress, ScrollIntoViewInput, ScrollIntoViewOutput, DocumentApi, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, ContentControlTarget, RichContentInsertInput, OperationCapabilityResolveResult, SDHtmlMarkdownSupportCheckResult, PictureWatermarkInput, RetainedPictureWatermarkInput, TextWatermark, WatermarkInfo, WatermarkTarget, WatermarksApplyInput, WatermarksApplyResult, WatermarksApplySuccess, WatermarksApplyTarget, TemporaryMutationOperation, TemporaryOperationResultTarget, TemporaryOperationEffects, TemporaryMutationInput, TemporaryMutationReplaceInput, TemporaryMutationHandleInput, TemporaryMutationReceipt, StoryLocator as DocumentStoryLocator, OperationId, OperationCall, OperationInput, OperationOptions, OperationOutput, } from '../../../../document-api/src/index.js';
+export type { Receipt, DocumentApiRejectionReason, DocumentApiRejectionDetails, TextRangeRejectionReason, ContentControlCreationRejectionReason, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, BookmarkAddress, ScrollIntoViewInput, ScrollIntoViewOutput, DocumentApi, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, ContentControlTarget, RichContentInsertInput, OperationCapabilityResolveResult, SDHtmlMarkdownSupportCheckResult, PictureWatermarkInput, RetainedPictureWatermarkInput, TextWatermark, WatermarkInfo, WatermarkTarget, WatermarksApplyInput, WatermarksApplyResult, WatermarksApplySuccess, WatermarksApplyTarget, TemporaryMutationOperation, TemporaryOperationResultTarget, TemporaryOperationEffects, TemporaryMutationInput, TemporaryMutationReplaceInput, TemporaryMutationHandleInput, TemporaryMutationReceipt, StoryLocator as DocumentStoryLocator, ChangeRecord, ChangeActor, ChangeCause, ChangeProvenance, BlockChange, OperationId, OperationCall, OperationInput, OperationOptions, OperationOutput, } from '../../../../document-api/src/index.js';
 export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, } from '../../../../document-api/src/index.js';
 export type { ListPresetId } from '../../../../document-api/src/index.js';
 export type { BrowserDocumentApi, PartialBrowserDocumentApi } from '../browser-document-api.js';
+export type { ContentControlClickPayload, ContentControlRef } from '../content-control-ref.js';
 export type { DocumentReplacementResult } from '../document-replacement.js';
 export type { SuperDocUIReason } from './reasons.js';
 export type { BuiltInCommandId } from './commands.js';
@@ -164,6 +166,7 @@ export interface FontSizeOption {
 }
 /** Observable enable/active state for a toolbar-style command. */
 export interface CommandState {
+    pending?: boolean;
     /** Availability for a control in the current selection / mode snapshot. */
     enabled: boolean;
     /** Compatibility inverse of `enabled` for demo code that models commands as disabled. */
@@ -689,6 +692,12 @@ export interface SuperDocDocumentChange {
     } | {
         kind: 'unknown';
     };
+    /**
+     * Attributed change records behind a remote change, oldest first. Present
+     * only when the engine recorded the remote transactions; `scope` is then
+     * derived from the stories the records touched.
+     */
+    records?: ChangeRecord[];
 }
 /** Document-level state slice. */
 export interface DocumentSlice {
@@ -824,6 +833,17 @@ export interface ViewportGetRectsResult {
     /** One result per input. An invalidated batch contains no usable rectangles. */
     results: readonly ViewportRectResult[];
 }
+export interface ViewportPositionAtInput {
+    x: number;
+    y: number;
+    signal?: AbortSignal;
+}
+export type ViewportPositionAtResult = {
+    status: 'resolved';
+    target: SelectionTarget;
+} | {
+    status: 'no-target' | 'stale' | 'cancelled' | 'disposed' | 'unavailable';
+};
 /** Result of `ui.viewport.getRect`. */
 export interface ViewportRectResult {
     /** Whether the target resolved to any painted geometry. */
@@ -865,6 +885,7 @@ export interface SelectionHandle extends SnapshotSubscribable<SelectionSlice> {
      * Fails closed with a stable reason when the host cannot honor the target.
      */
     apply(target: SelectionTarget): WorkflowActionResult;
+    applyAndWait(target: SelectionTarget): Promise<WorkflowActionResult>;
     /**
      * Place the browser caret before or after a live inline content control.
      * Placement does not edit the document or create an undo entry.
@@ -1132,6 +1153,7 @@ export interface ContentControlsHandle extends SnapshotSubscribable<ContentContr
      * should use {@link observe}.
      */
     observeActivePath(listener: (snapshot: ContentControlsSlice) => void): () => void;
+    onClick(listener: (payload: ContentControlClickPayload) => void): () => void;
     /** Event-shaped alias of {@link observe}. */
     subscribe(listener: (event: {
         snapshot: ContentControlsSlice;
@@ -1284,6 +1306,7 @@ export interface ViewportHandle {
     getRect(input: ViewportGetRectInput): ViewportRectResult;
     /** At most 5000 targets, yielding every 32. Never forces unpainted pages to render. */
     getRects(input: ViewportGetRectsInput): Promise<ViewportGetRectsResult>;
+    positionAt(input: ViewportPositionAtInput): Promise<ViewportPositionAtResult>;
     /**
      * Subscribe to geometry invalidation after selection, zoom, scroll, resize,
      * layout, or repaint changes. The callback is coalesced to one per frame.

package/dist/superdoc/src/public/ui/ui-bench-timing.d.ts

@@ -0,0 +1,9 @@
+export declare function uiBenchNowMs(): number;
+export declare function readUiBenchRuntime(): {
+    sink: ((event: Record<string, unknown>) => void) | null;
+    workerContext: {
+        commandId: string | null;
+        commandKind: string | null;
+    } | null;
+};
+export declare function emitUiBenchTiming(event: Record<string, unknown>): void;