superdoc 2.2.1 → 2.3.0

package/dist/document-api/src/types/node.d.ts

@@ -0,0 +1,9 @@
+import { HeadingNodeInfo, ListItemNodeInfo, ParagraphNodeInfo } from './paragraph.types.js';
+import { LineBreakNodeInfo, RunNodeInfo, TabNodeInfo } from './inline.types.js';
+import { TableCellNodeInfo, TableNodeInfo, TableRowNodeInfo } from './tables.types.js';
+import { ImageNodeInfo } from './media.types.js';
+import { BookmarkNodeInfo, ContentControlInfo, HyperlinkNodeInfo } from './structured.types.js';
+import { CommentNodeInfo } from './comments.types.js';
+import { FootnoteRefNodeInfo } from './references.types.js';
+import { TableOfContentsNodeInfo } from '../toc/toc.types.js';
+export type NodeInfo = ParagraphNodeInfo | HeadingNodeInfo | ListItemNodeInfo | TableNodeInfo | TableRowNodeInfo | TableCellNodeInfo | TableOfContentsNodeInfo | ImageNodeInfo | ContentControlInfo | RunNodeInfo | BookmarkNodeInfo | CommentNodeInfo | HyperlinkNodeInfo | FootnoteRefNodeInfo | TabNodeInfo | LineBreakNodeInfo;

package/dist/document-api/src/types/paragraph.types.d.ts

@@ -0,0 +1,61 @@
+import { BaseNodeInfo } from './base.js';
+export interface ParagraphNodeInfo extends BaseNodeInfo {
+    nodeType: 'paragraph';
+    kind: 'block';
+    properties: ParagraphProperties;
+}
+export interface HeadingNodeInfo extends BaseNodeInfo {
+    nodeType: 'heading';
+    kind: 'block';
+    properties: HeadingProperties;
+}
+export interface ListItemNodeInfo extends BaseNodeInfo {
+    nodeType: 'listItem';
+    kind: 'block';
+    properties: ListItemProperties;
+}
+export type ParagraphIndentation = {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+    unit?: 'twip' | 'pt' | 'px';
+};
+export type ParagraphSpacing = {
+    before?: number;
+    after?: number;
+    line?: number;
+    unit?: 'twip' | 'pt' | 'px';
+};
+export type ParagraphNumbering = {
+    numId?: number;
+    level?: number;
+};
+export type ListNumbering = {
+    marker?: string;
+    path?: number[];
+    ordinal?: number;
+    listIndex?: number;
+};
+export interface ParagraphProperties {
+    styleId?: string;
+    alignment?: 'left' | 'right' | 'center' | 'justify' | 'start' | 'end' | 'distributed';
+    indentation?: ParagraphIndentation;
+    spacing?: ParagraphSpacing;
+    keepWithNext?: boolean;
+    outlineLevel?: number;
+    paragraphNumbering?: ParagraphNumbering;
+}
+export interface HeadingProperties extends ParagraphProperties {
+    /**
+     * Headings are paragraphs with a heading style.
+     */
+    headingLevel: 1 | 2 | 3 | 4 | 5 | 6;
+}
+export interface ListItemProperties extends ParagraphProperties {
+    /**
+     * List items are paragraphs with numbering.
+     * This keeps list semantics explicit without creating a separate structure.
+     */
+    numbering?: ListNumbering;
+}

package/dist/document-api/src/types/placement.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Placement and nesting policy types for structural insert/replace operations.
+ */
+/** Where to place structural content relative to the target. */
+export type Placement = 'before' | 'after' | 'insideStart' | 'insideEnd';
+/** Valid placement values for runtime validation. */
+export declare const PLACEMENT_VALUES: ReadonlySet<string>;
+/** Default placement for structural insert when not specified. */
+export declare const DEFAULT_PLACEMENT: Placement;
+/** Policy controlling whether nested tables are permitted. */
+export type TableNestingPolicy = 'forbid' | 'allow';
+/** Valid table nesting policy values for runtime validation. */
+export declare const TABLE_NESTING_POLICY_VALUES: ReadonlySet<string>;
+/** Policy object for controlling structural nesting behavior. */
+export interface NestingPolicy {
+    tables?: TableNestingPolicy;
+}
+/** Default nesting policy: nested tables are forbidden. */
+export declare const DEFAULT_NESTING_POLICY: Readonly<Required<NestingPolicy>>;
+/**
+ * Failure codes specific to structural placement violations.
+ * These extend the existing ReceiptFailureCode vocabulary.
+ */
+export type StructuralFailureCode = 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'EMPTY_FRAGMENT' | 'INVALID_FRAGMENT';

package/dist/document-api/src/types/query-match.types.d.ts

@@ -0,0 +1,212 @@
+import { BlockNodeAddress, BlockNodeType, NodeAddress } from './base.js';
+import { SelectionTarget, TextCoordinateSpace } from './address.js';
+import { TextSelector, NodeSelector } from './query.js';
+import { DiscoveryItem, DiscoveryResult } from './discovery.js';
+import { InlineToggleDirective } from './style-policy.types.js';
+import { StoryLocator } from './story.types.js';
+export type CardinalityRequirement = 'any' | 'first' | 'exactlyOne' | 'all';
+/** Maximum total length for a match snippet (D11). */
+export declare const SNIPPET_MAX_LENGTH = 500;
+/** Maximum characters of surrounding context on each side of the match (D11). */
+export declare const SNIPPET_CONTEXT_CHARS = 100;
+/**
+ * Character offsets within a snippet identifying the matched text.
+ *
+ * Invariants (D17):
+ * - `start >= 0 && end <= snippet.length`
+ * - `start < end` (zero-width matches are dropped before snippet assembly per D20)
+ */
+export interface HighlightRange {
+    start: number;
+    end: number;
+}
+/** Direct toggle states: what the run explicitly declares at run level. */
+export interface MatchDirectStyles {
+    bold: InlineToggleDirective;
+    italic: InlineToggleDirective;
+    underline: InlineToggleDirective;
+    strike: InlineToggleDirective;
+}
+/** Effective visual states: what the user sees after style cascade resolution. */
+export interface MatchEffectiveStyles {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strike: boolean;
+}
+/**
+ * Two-layer inline style state for a single run.
+ *
+ * - `direct`: tri-state directives reflecting the run's explicit formatting.
+ * - `effective`: boolean visual state after style cascade resolution.
+ * - Non-toggle properties remain at top level.
+ */
+export interface MatchStyle {
+    direct: MatchDirectStyles;
+    effective: MatchEffectiveStyles;
+    /** 6-digit lowercase hex with `#` prefix (e.g., `#ff0000`). */
+    color?: string;
+    /** 6-digit lowercase hex with `#` prefix. */
+    highlight?: string;
+    /** Raw font family string from the document (e.g., `"Calibri"`). */
+    fontFamily?: string;
+    /** Font size in points, rounded to 1 decimal place. */
+    fontSizePt?: number;
+}
+/**
+ * A contiguous span of text within a block sharing identical mark-signature.
+ *
+ * Invariant (D4: run-tiling): within a block, runs exactly tile the block's
+ * matched range with no gaps and no overlaps.
+ */
+export interface MatchRun {
+    /** Block-relative character offsets. */
+    range: {
+        start: number;
+        end: number;
+    };
+    /** Coordinate space for `range`. Omitted means `visible`. */
+    coordinateSpace?: TextCoordinateSpace;
+    /** The text content of this run. */
+    text: string;
+    /**
+     * OOXML character style definition ID (`w:rStyle` `w:val`): the key into
+     * `styles.xml`. Omitted when no character style is applied (D10a).
+     */
+    styleId?: string;
+    /** Resolved inline style state for this run. */
+    styles: MatchStyle;
+    /** Run-scoped ephemeral ref (V3, scope: 'run'). */
+    ref: string;
+}
+/**
+ * A single block's participation in a logical match.
+ * Contains the block-scoped text and its decomposition into style runs.
+ */
+export interface MatchBlock {
+    /** The PM node's stable block ID. */
+    blockId: string;
+    /** The PM node type name (e.g., 'paragraph', 'heading', 'listItem'). */
+    nodeType: BlockNodeType | string;
+    /** Block-relative character offsets of the match within this block. */
+    range: {
+        start: number;
+        end: number;
+    };
+    /** Coordinate space for `range`. Omitted means `visible`. */
+    coordinateSpace?: TextCoordinateSpace;
+    /** The matched text within this block. */
+    text: string;
+    /**
+     * Paragraph-level style metadata (D10).
+     * `styleId` is the OOXML paragraph style definition ID (`w:pStyle` `w:val`).
+     * Omitted when no paragraph style metadata is available.
+     */
+    paragraphStyle?: {
+        styleId?: string;
+        isListItem?: boolean;
+        listLevel?: number;
+    };
+    /** Block-scoped ephemeral ref (V3, scope: 'block'). */
+    ref: string;
+    /**
+     * Style runs within the matched range, in offset order (D16).
+     * Runs exactly tile `range` (D4 invariant).
+     */
+    runs: MatchRun[];
+}
+/**
+ * Domain fields for a text-selector match.
+ *
+ * Always has blocks, snippet, highlightRange (D18).
+ * `blocks` is a non-empty tuple: a text match always covers at least one block.
+ */
+export interface TextMatchDomain {
+    /** Discriminator: always `'text'` for text-selector matches. */
+    matchKind: 'text';
+    /** Address of the containing block in document order (D14). Text matches always yield the block. */
+    address: BlockNodeAddress;
+    /**
+     * Canonical mutation-ready selection target for this text match.
+     *
+     * Can be passed directly to `doc.delete({ target })`, `doc.replace({ target, text })`,
+     * or `doc.format.apply({ target, inline })` for cross-block mutations.
+     */
+    target: SelectionTarget;
+    /** Coordinate space for `target` and `blocks`. Omitted means `visible`. */
+    coordinateSpace?: TextCoordinateSpace;
+    /** Matched text plus surrounding context (D11). */
+    snippet: string;
+    /** Character offsets within `snippet` identifying the matched text (D17). */
+    highlightRange: HighlightRange;
+    /** Block decomposition of the match, in document order (D16). */
+    blocks: [MatchBlock, ...MatchBlock[]];
+    /**
+     * Regex-mode only: capture groups from the match, index `i` holding group
+     * `i + 1` (`null` for non-participating groups). Absent for plain
+     * (`contains`) text matches.
+     */
+    groups?: readonly (string | null)[];
+}
+/**
+ * Domain fields for a node-selector match.
+ *
+ * No blocks, no snippet (D13, D18).
+ * Block-level nodes use a stable nodeId ref. Inline nodes use an ephemeral
+ * V3 ref (anchor offsets are position-dependent).
+ */
+export interface NodeMatchDomain {
+    /** Discriminator: always `'node'` for node-selector matches. */
+    matchKind: 'node';
+    /** Address of the first matched block in document order (D14). */
+    address: NodeAddress;
+    /** Always empty for node matches. Discriminator: `blocks.length === 0`. */
+    blocks: [];
+}
+/** Discriminated union of match domain types. Use `matchKind` as the canonical discriminator (`'text'` or `'node'`). */
+export type QueryMatchDomain = TextMatchDomain | NodeMatchDomain;
+/** A single match item in the discovery envelope. */
+export type QueryMatchItem = DiscoveryItem<QueryMatchDomain>;
+/** Text match item (blocks.length > 0). */
+export type TextMatchItem = DiscoveryItem<TextMatchDomain>;
+/** Node match item (blocks.length === 0). */
+export type NodeMatchItem = DiscoveryItem<NodeMatchDomain>;
+/**
+ * Metadata for `query.match`: always present on the output envelope.
+ *
+ * - `effectiveResolved: true`: converter context was available; `styles.effective`
+ *   on every run reflects full cascade resolution.
+ * - `effectiveResolved: false`: converter context was unavailable (headless/non-DOCX);
+ *   `styles.effective` is derived from `direct` only.
+ */
+export interface QueryMatchMeta {
+    effectiveResolved: boolean;
+}
+export interface QueryMatchInput {
+    /** Selector for query.match. Text selectors may opt into deleted tracked text via `includeDeletedText`. */
+    select: TextSelector | NodeSelector;
+    within?: BlockNodeAddress;
+    /** Restrict matching to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    require?: CardinalityRequirement;
+    /** Match evaluation mode. `'candidates'` (default) returns best-effort matches; `'strict'` enforces exact semantics (future). */
+    mode?: 'strict' | 'candidates';
+    includeNodes?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Standardized discovery output for `query.match`.
+ *
+ * Narrows the shared `DiscoveryResult` envelope so that `meta: QueryMatchMeta`
+ * is **required** (not optional). SDK/client code consuming `query.match` gets
+ * `output.meta.effectiveResolved` as a non-optional boolean.
+ *
+ * Items are `DiscoveryItem<TextMatchDomain | NodeMatchDomain>`:
+ * - `id`: deterministic identity, revision-scoped (format: `m:<index>`, D7)
+ * - `handle`: mutation-ready `ResolvedHandle` with `ref`, `refStability`, `targetKind`
+ * - Plus domain fields (`address`, `blocks`, `snippet`, `highlightRange`)
+ */
+export type QueryMatchOutput = Omit<DiscoveryResult<DiscoveryItem<QueryMatchDomain>, QueryMatchMeta>, 'meta'> & {
+    meta: QueryMatchMeta;
+};

package/dist/document-api/src/types/query.d.ts

@@ -0,0 +1,133 @@
+import { BlockNodeAddress, NodeAddress, NodeKind, NodeType } from './base.js';
+import { NodeInfo } from './node.js';
+import { Range, TextAddress, SelectionTarget } from './address.js';
+import { DiscoveryOutput } from './discovery.js';
+import { StoryLocator } from './story.types.js';
+export interface TextSelector {
+    type: 'text';
+    /** Text to match. In regex mode, patterns are validated for syntax, length, and safety before execution. */
+    pattern: string;
+    /**
+     * Controls text matching strategy.
+     * - `contains`: literal substring matching (default). Use this for literal text.
+     * - `regex`: regular expression matching. Patterns are validated for syntax, maximum length, and safety.
+     */
+    mode?: 'contains' | 'regex';
+    /**
+     * Controls case sensitivity for text matching.
+     * Defaults to false (case-insensitive).
+     */
+    caseSensitive?: boolean;
+    /**
+     * When true, matches must start and end on a word boundary.
+     * Defaults to false.
+     */
+    wholeWord?: boolean;
+    /**
+     * When true, includes text from pending tracked deletions in search results.
+     * Defaults to false (Word-compatible behavior: deleted text is not searchable).
+     *
+     * Note: this flag controls match discovery only. The `node` payload in each
+     * result item is still projected using the visible text model, so deleted runs
+     * will not appear in `item.node` even when they caused the match.
+     */
+    includeDeletedText?: boolean;
+}
+export interface NodeSelector {
+    type: 'node';
+    nodeType?: NodeType;
+    kind?: NodeKind;
+}
+/**
+ * Selector shorthand for find queries.
+ *
+ * `{ nodeType: 'paragraph' }` is sugar for `{ type: 'node', nodeType: 'paragraph' }`.
+ *
+ * For dual-context node types (`sdt`, `image`), omitting `kind`
+ * may return both block and inline matches.
+ */
+export type Selector = {
+    nodeType: NodeType;
+} | NodeSelector | TextSelector;
+export interface Query {
+    /** Selector that determines which nodes to match. */
+    select: NodeSelector | TextSelector;
+    within?: BlockNodeAddress;
+    /** Restrict the query to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    limit?: number;
+    offset?: number;
+    /**
+     * Cardinality requirement for the result set.
+     * Used for future enforcement: currently passed through without behavioral change.
+     */
+    require?: 'any' | 'first' | 'exactlyOne' | 'all';
+    /**
+     * Whether to hydrate `result.nodes` for matched addresses.
+     * This is independent from text-match context, which is intrinsic for text selectors.
+     */
+    includeNodes?: boolean;
+    /**
+     * Controls whether unknown nodes are returned in diagnostics.
+     * Unknown nodes are never included in matches.
+     */
+    includeUnknown?: boolean;
+}
+export interface MatchContext {
+    address: NodeAddress;
+    snippet: string;
+    highlightRange: Range;
+    /**
+     * Canonical mutation-ready selection target for this text match.
+     *
+     * Built from the first and last text ranges. Can be passed directly to
+     * `doc.delete({ target })`, `doc.replace({ target, text })`, etc.
+     */
+    target?: SelectionTarget;
+    /**
+     * Text ranges matching the query, expressed as block-relative offsets.
+     * For cross-paragraph matches, this will include one range per block.
+     *
+     * Block-relative ranges for display/discovery. Use `context.target` (SelectionTarget) for mutations.
+     */
+    textRanges?: TextAddress[];
+}
+export interface UnknownNodeDiagnostic {
+    message: string;
+    address?: NodeAddress;
+    hint?: string;
+}
+export interface QueryResult {
+    /**
+     * Matched node addresses.
+     *
+     * For text selectors, these addresses identify containing block nodes.
+     * Exact matched spans are exposed via `context[*].textRanges`.
+     */
+    matches: NodeAddress[];
+    total: number;
+    /** Optional hydrated node payloads aligned with `matches` when `includeNodes` is true. */
+    nodes?: NodeInfo[];
+    context?: MatchContext[];
+    diagnostics?: UnknownNodeDiagnostic[];
+}
+/**
+ * Domain fields for a find discovery item (C3c).
+ *
+ * Merges the parallel-array fields (`matches[i]`, `nodes[i]`, `context[i]`)
+ * into a single per-item object.
+ */
+export interface FindItemDomain {
+    address: NodeAddress;
+    node?: NodeInfo;
+    context?: MatchContext;
+}
+/**
+ * Standardized discovery output for `find`.
+ *
+ * Extends `DiscoveryOutput<FindItemDomain>` with an optional
+ * top-level `diagnostics` array for unknown-node reporting.
+ */
+export type FindOutput = DiscoveryOutput<FindItemDomain> & {
+    diagnostics?: UnknownNodeDiagnostic[];
+};

package/dist/document-api/src/types/receipt.d.ts

@@ -0,0 +1,191 @@
+import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, TrackedChangeAddress } from './address.js';
+import { BlockNodeAddress } from './base.js';
+import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
+import { StoryLocator } from './story.types.js';
+export type ReceiptInsert = TrackedChangeAddress;
+export type ReceiptEntity = EntityAddress;
+export type AffectedRef = TextAddress | BookmarkAddress | EntityAddress | BlockNavigationAddress;
+export type AffectedRefRemapping = {
+    from: AffectedRef;
+    to: AffectedRef;
+};
+export type ReceiptFailureCode = 'NO_OP' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'CAPABILITY_UNAVAILABLE' | 'PERMISSION_DENIED' | 'STALE_REVISION' | 'REVISION_MISMATCH' | 'MATCH_NOT_FOUND' | 'AMBIGUOUS_MATCH' | 'STYLE_CONFLICT' | 'PRECONDITION_FAILED' | 'COMMENT_CASCADE_PARTIAL' | 'INVALID_INPUT' | 'CROSS_BLOCK_MATCH' | 'SPAN_FRAGMENTED' | 'TARGET_MOVED' | 'PLAN_CONFLICT_OVERLAP' | 'INVALID_STEP_COMBINATION' | 'REVISION_CHANGED_SINCE_COMPILE' | 'INVALID_INSERTION_CONTEXT' | 'DOCUMENT_IDENTITY_CONFLICT' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR' | 'PAGE_NUMBERS_NOT_MATERIALIZED' | 'INCOMPATIBLE_DEFINITIONS' | 'NO_COMPATIBLE_PREVIOUS' | 'ALREADY_CONTINUOUS' | 'NO_PREVIOUS_LIST' | 'NO_ADJACENT_SEQUENCE' | 'ALREADY_SAME_SEQUENCE' | 'LEVEL_OUT_OF_RANGE' | 'LEVEL_NOT_FOUND' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'EMPTY_FRAGMENT' | 'INVALID_FRAGMENT' | 'INVALID_PAYLOAD' | 'CAPABILITY_UNSUPPORTED' | 'ADDRESS_STALE' | 'DUPLICATE_ID' | 'INVALID_CONTEXT' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'LOCK_VIOLATION' | 'TYPE_MISMATCH' | 'UNSUPPORTED_SOURCE' | 'INVALID_PACKAGE' | 'UNSUPPORTED_TEMPLATE_CONTENT';
+export type ReceiptFailure = {
+    code: ReceiptFailureCode;
+    message: string;
+    details?: unknown;
+};
+export type ReviewWarningFeature = 'comments' | 'trackedChanges';
+export type ReviewWarning = {
+    /** Stable warning code (e.g. `comments-export-non-exact`). */
+    code: string;
+    /** Human-readable message for diagnostics and consumer logs. */
+    message: string;
+    /** Which review feature produced this warning. */
+    feature: ReviewWarningFeature;
+    /** Severity locked to `warning` so this lane never carries failures or info noise. */
+    severity: 'warning';
+    /** Public id of the affected review object, when known. */
+    affectedObjectId?: string;
+    /** Package part URI the warning concerns, when known. */
+    affectedPartUri?: string;
+    /**
+     * Whether export / save can proceed despite the warning. `true` means
+     * the receipt still represents a successful operation; `false` means the
+     * caller should treat this as a soft block (the kernel surfaced the
+     * warning before raising `Receipt.failure`).
+     */
+    canProceed: boolean;
+};
+/**
+ * A per-story descriptor of how visible text was shifted by an
+ * operation. Callers maintain their own held-ref state by applying these
+ * deltas:
+ *
+ * - Any caller-held text address whose `range.start` is `>= atChar` in the
+ *   same `story` gets `range.start += delta` (and similarly `range.end`).
+ * - Any caller-held text address whose range straddles `atChar` is
+ *   *invalidated* — the kernel already lists those in `invalidatedRefs`.
+ *
+ * Negative `delta` describes a deletion. Positive `delta` describes an
+ * insertion (e.g. when a `<w:del>` is rejected and its content is restored
+ * to the visible flow).
+ *
+ * One entry per story. Cross-story shifts are reported as separate entries.
+ */
+export interface TextRangeShift {
+    /** The story whose text was shifted. */
+    story: StoryLocator;
+    /** Character offset in the story's flattened text where the shift begins. */
+    atChar: number;
+    /** Net change in characters. Negative for deletions, positive for insertions. */
+    delta: number;
+}
+/** A visible text span created by a mutation (e.g. `doc.insert`). */
+export interface TextMutationEffect {
+    kind: 'insertedText';
+    /**
+     * Block-absolute address of the created span. `range.start` is the base
+     * offset within the target block (nonzero when text was appended into a
+     * non-empty paragraph), so callers can shift phrase-relative offsets.
+     */
+    target: TextAddress;
+    /** Selection target covering the created span, for selection-consuming APIs. */
+    selectionTarget: SelectionTarget;
+    /** The visible text that was created. */
+    text: string;
+}
+/** A block created by a structural mutation (e.g. paragraph/heading insert). */
+export interface BlockMutationEffect {
+    kind: 'insertedBlock';
+    /** Address of the created block. */
+    target: BlockNodeAddress;
+    /**
+     * The created block's visible text span, when the inserted text is known and
+     * simple enough to address. Omitted for rich content where an exact text
+     * span is not currently available.
+     */
+    insertedText?: TextMutationEffect;
+}
+/**
+ * Post-mutation created-content lane. Additive and operation-agnostic: insert
+ * populates `insertedText` (and `insertedBlocks` for structural inserts);
+ * future mutations can populate the same lane without changing
+ * `resolution.target`.
+ */
+export interface ReceiptEffects {
+    /** Visible text spans created by the mutation, in document order. */
+    insertedText?: TextMutationEffect[];
+    /** Blocks created by the mutation, in document order. */
+    insertedBlocks?: BlockMutationEffect[];
+}
+export type ReceiptSuccess = {
+    success: true;
+    /**
+     * Convenience id for operations that create exactly one primary durable entity.
+     * Generic consumers should prefer `inserted`; this field exists for simple
+     * create-and-follow-up flows such as `comments.create` → `comments.patch`.
+     */
+    id?: string;
+    /** Entities created by the operation and safe for callers to hold. */
+    inserted?: ReceiptEntity[];
+    /** Entities whose content or metadata changed but whose identity survived. */
+    updated?: ReceiptEntity[];
+    /** Entities removed by the operation. */
+    removed?: ReceiptEntity[];
+    /** Caller-held refs that no longer resolve after the operation. */
+    invalidatedRefs?: AffectedRef[];
+    /** Caller-held refs whose identity survived at a different address. */
+    remappedRefs?: AffectedRefRemapping[];
+    /** Stories whose content revision changed because of the operation. */
+    affectedStories?: StoryLocator[];
+    /**
+     * Text-range shifts produced by the operation. Optional.
+     * Undefined for ops that don't change visible text (most comment ops).
+     * Populated by tracked-change accept/reject operations that delete or
+     * restore visible content. See {@link TextRangeShift}.
+     */
+    textRangeShifts?: TextRangeShift[];
+    /**
+     * Transaction id of the successful commit. Optional and
+     * additive — engines that lack a per-tx identity omit it. v2 populates
+     * this for every successful mutation so callers can wire the receipt to
+     * their own history bookkeeping (undo / redo correlation, audit logs).
+     */
+    txId?: string;
+    /**
+     * Review foundation: allowed non-exact mappings or
+     * non-load-bearing degradations the spec permits. See {@link ReviewWarning}.
+     * Forbidden semantic loss MUST surface as `Receipt.failure`, not here.
+     * The first real emitter is comment export.
+     */
+    warnings?: ReviewWarning[];
+    /**
+     * Post-mutation created-content spans (inserted visible text / blocks).
+     * Distinct from `resolution.target`, which is the resolved mutation target /
+     * insertion point. See {@link ReceiptEffects}.
+     */
+    effects?: ReceiptEffects;
+};
+export type ReceiptFailureResult = {
+    success: false;
+    failure: ReceiptFailure;
+};
+export type Receipt = ReceiptSuccess | ReceiptFailureResult;
+export type TextMutationRange = {
+    from: number;
+    to: number;
+};
+export type TextMutationResolution = {
+    /**
+     * Requested input target from the caller, when provided.
+     * For insert-without-target calls this is omitted.
+     */
+    requestedTarget?: TextAddress;
+    /**
+     * Effective target used by the adapter after canonical resolution.
+     * For cross-block selections this reflects the first block only -
+     * use {@link selectionTarget} for the full resolved range.
+     */
+    target: TextAddress;
+    /**
+     * Engine-resolved absolute document range for the effective target.
+     */
+    range: TextMutationRange;
+    /**
+     * Snapshot of text currently covered by the resolved range.
+     * Empty for collapsed insert targets.
+     */
+    text: string;
+    /**
+     * Full selection target for cross-block mutations.
+     * Present when the resolved range spans more than one block.
+     * Single-block mutations omit this field.
+     */
+    selectionTarget?: SelectionTarget;
+};
+export type TextMutationReceipt = (ReceiptSuccess & {
+    resolution: TextMutationResolution;
+}) | (ReceiptFailureResult & {
+    resolution: TextMutationResolution;
+});

package/dist/document-api/src/types/references.types.d.ts

@@ -0,0 +1,9 @@
+import { BaseNodeInfo } from './base.js';
+export interface FootnoteRefNodeInfo extends BaseNodeInfo {
+    nodeType: 'footnoteRef';
+    kind: 'inline';
+    properties: FootnoteRefProperties;
+}
+export interface FootnoteRefProperties {
+    noteId?: string;
+}