superdoc 2.2.0 → 2.3.0

package/dist/document-api/src/toc/toc.d.ts

@@ -0,0 +1,25 @@
+import { MutationOptions } from '../write/write.js';
+import { TocGetInput, TocInfo, TocConfigureInput, TocUpdateInput, TocRemoveInput, TocMutationResult, TocListQuery, TocListResult, TocMarkEntryInput, TocUnmarkEntryInput, TocListEntriesQuery, TocListEntriesResult, TocGetEntryInput, TocEntryInfo, TocEditEntryInput, TocEntryMutationResult } from './toc.types.js';
+export interface TocApi {
+    list(query?: TocListQuery): TocListResult;
+    get(input: TocGetInput): TocInfo;
+    configure(input: TocConfigureInput, options?: MutationOptions): TocMutationResult;
+    update(input: TocUpdateInput, options?: MutationOptions): TocMutationResult;
+    remove(input: TocRemoveInput, options?: MutationOptions): TocMutationResult;
+    markEntry(input: TocMarkEntryInput, options?: MutationOptions): TocEntryMutationResult;
+    unmarkEntry(input: TocUnmarkEntryInput, options?: MutationOptions): TocEntryMutationResult;
+    listEntries(query?: TocListEntriesQuery): TocListEntriesResult;
+    getEntry(input: TocGetEntryInput): TocEntryInfo;
+    editEntry(input: TocEditEntryInput, options?: MutationOptions): TocEntryMutationResult;
+}
+export type TocAdapter = TocApi;
+export declare function executeTocList(adapter: TocAdapter, query?: TocListQuery): TocListResult;
+export declare function executeTocGet(adapter: TocAdapter, input: TocGetInput): TocInfo;
+export declare function executeTocConfigure(adapter: TocAdapter, input: TocConfigureInput, options?: MutationOptions): TocMutationResult;
+export declare function executeTocUpdate(adapter: TocAdapter, input: TocUpdateInput, options?: MutationOptions): TocMutationResult;
+export declare function executeTocRemove(adapter: TocAdapter, input: TocRemoveInput, options?: MutationOptions): TocMutationResult;
+export declare function executeTocMarkEntry(adapter: TocAdapter, input: TocMarkEntryInput, options?: MutationOptions): TocEntryMutationResult;
+export declare function executeTocUnmarkEntry(adapter: TocAdapter, input: TocUnmarkEntryInput, options?: MutationOptions): TocEntryMutationResult;
+export declare function executeTocListEntries(adapter: TocAdapter, query?: TocListEntriesQuery): TocListEntriesResult;
+export declare function executeTocGetEntry(adapter: TocAdapter, input: TocGetEntryInput): TocEntryInfo;
+export declare function executeTocEditEntry(adapter: TocAdapter, input: TocEditEntryInput, options?: MutationOptions): TocEntryMutationResult;

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

@@ -0,0 +1,247 @@
+import { BaseNodeInfo, BlockNodeAddress } from '../types/base.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+import { ReceiptFailure } from '../types/receipt.js';
+export interface TocAddress {
+    kind: 'block';
+    nodeType: 'tableOfContents';
+    nodeId: string;
+}
+/** Configurable source switches. */
+export interface TocSourceConfig {
+    /** Outline heading level range from \o switch. */
+    outlineLevels?: {
+        from: number;
+        to: number;
+    };
+    /** Whether to use applied paragraph outline level (\u switch). */
+    useAppliedOutlineLevel?: boolean;
+    /** TC field identifier filter (\f switch). Only TC fields with this identifier are collected. */
+    tcFieldIdentifier?: string;
+    /** TC field level range filter (\l switch). Only TC fields within this range are collected. */
+    tcFieldLevels?: {
+        from: number;
+        to: number;
+    };
+}
+/** Configurable display switches. */
+export interface TocDisplayConfig {
+    /** Make TOC entries hyperlinks (\h switch). */
+    hyperlinks?: boolean;
+    /** Hide tab leader and page numbers in web layout view (\z switch). */
+    hideInWebView?: boolean;
+    /** Omit page numbers for specified levels (\n switch). */
+    omitPageNumberLevels?: {
+        from: number;
+        to: number;
+    };
+    /** Separator character between entry text and page number (\p switch). */
+    separator?: string;
+    /** Whether page numbers are included. Convenience projection of the \n switch. */
+    includePageNumbers?: boolean;
+    /** Tab leader style between entry text and page number. */
+    tabLeader?: 'none' | 'dot' | 'hyphen' | 'underscore' | 'middleDot';
+    /** Whether TOC entry page numbers use right-aligned tab stops. Stored as a PM node attribute (not a field switch). */
+    rightAlignPageNumbers?: boolean;
+}
+/** Round-tripped but not configurable via toc.configure. */
+export interface TocPreservedSwitches {
+    /** Custom styles from \t switch. */
+    customStyles?: Array<{
+        styleName: string;
+        level: number;
+    }>;
+    /** Bookmark name from \b switch. */
+    bookmarkName?: string;
+    /** Caption type from \a switch. */
+    captionType?: string;
+    /** SEQ field identifier from \c switch. */
+    seqFieldIdentifier?: string;
+    /** Separator for SEQ/chapter numbers from \d switch. */
+    chapterSeparator?: string;
+    /** Chapter number source from \s switch. */
+    chapterNumberSource?: string;
+    /** Preserve tab entries from \w switch. */
+    preserveTabEntries?: boolean;
+    /** Completely unrecognized switches stored verbatim. */
+    rawExtensions?: string[];
+}
+/** Full parsed switch model used internally by the parser/serializer. */
+export interface TocSwitchConfig {
+    source: TocSourceConfig;
+    display: TocDisplayConfig;
+    preserved: TocPreservedSwitches;
+}
+/** Patch for toc.configure: only configurable fields, all optional. */
+export type TocConfigurePatch = TocSourceConfig & TocDisplayConfig;
+export interface TableOfContentsProperties {
+    instruction: string;
+    sourceConfig: TocSourceConfig;
+    displayConfig: TocDisplayConfig;
+    preservedSwitches: TocPreservedSwitches;
+    entryCount: number;
+}
+export interface TableOfContentsNodeInfo extends BaseNodeInfo {
+    nodeType: 'tableOfContents';
+    kind: 'block';
+    properties: TableOfContentsProperties;
+}
+export interface TocDomain {
+    address: TocAddress;
+    instruction: string;
+    sourceConfig: TocSourceConfig;
+    displayConfig: TocDisplayConfig;
+    preserved: TocPreservedSwitches;
+    entryCount: number;
+}
+export type TocListQuery = {
+    limit?: number;
+    offset?: number;
+};
+export type TocListResult = DiscoveryOutput<TocDomain>;
+export interface TocGetInput {
+    target: TocAddress;
+}
+export type TocInfo = TableOfContentsNodeInfo;
+export interface TocConfigureInput {
+    target: TocAddress;
+    patch: TocConfigurePatch;
+}
+export interface TocUpdateInput {
+    target: TocAddress;
+    /** Update mode. 'all' rebuilds from sources; 'pageNumbers' updates only page numbers. */
+    mode?: 'all' | 'pageNumbers';
+}
+export interface TocRemoveInput {
+    target: TocAddress;
+}
+export interface TocMutationSuccess {
+    success: true;
+    toc: TocAddress;
+}
+export interface TocMutationFailure {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type TocMutationResult = TocMutationSuccess | TocMutationFailure;
+export type TocCreateLocation = {
+    kind: 'documentStart';
+} | {
+    kind: 'documentEnd';
+} | {
+    kind: 'before';
+    target: BlockNodeAddress;
+} | {
+    kind: 'after';
+    target: BlockNodeAddress;
+};
+export interface CreateTableOfContentsInput {
+    at?: TocCreateLocation;
+    /**
+     * Optional raw TOC field instruction to preserve non-default switch shapes
+     * such as custom-style mappings (`\\t`) or omitted default switches.
+     * When provided, the adapter parses this instruction as the base TOC config
+     * before applying any config patch overrides.
+     */
+    instruction?: string;
+    config?: TocConfigurePatch;
+}
+export interface CreateTableOfContentsSuccess {
+    success: true;
+    toc: TocAddress;
+}
+export interface CreateTableOfContentsFailure {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type CreateTableOfContentsResult = CreateTableOfContentsSuccess | CreateTableOfContentsFailure;
+/** Address for a single TC field node in the document. */
+export interface TocEntryAddress {
+    kind: 'inline';
+    nodeType: 'tableOfContentsEntry';
+    /** Public ID (FNV-1a hash of instruction + position, revision-scoped). */
+    nodeId: string;
+}
+/** Insertion target for toc.markEntry: anchored to a paragraph. */
+export interface TocEntryInsertionTarget {
+    kind: 'inline-insert';
+    /** Insert TC field adjacent to a block-addressed paragraph. */
+    anchor: {
+        nodeType: 'paragraph';
+        /** Target paragraph's sdBlockId. */
+        nodeId: string;
+    };
+    /** Where within the paragraph to insert. Default: 'end'. */
+    position?: 'start' | 'end';
+}
+export interface TocMarkEntryInput {
+    target: TocEntryInsertionTarget;
+    /** Entry text: required (v1: explicit text only). */
+    text: string;
+    /** TC \l switch level. Default: 1. */
+    level?: number;
+    /** TC \f switch table identifier. */
+    tableIdentifier?: string;
+    /** TC \n switch: omit page number for this entry. Default: false. */
+    omitPageNumber?: boolean;
+}
+export interface TocUnmarkEntryInput {
+    target: TocEntryAddress;
+}
+export interface TocListEntriesQuery {
+    /** Filter by TC \f value. */
+    tableIdentifier?: string;
+    /** Filter by level range. */
+    levelRange?: {
+        from: number;
+        to: number;
+    };
+    limit?: number;
+    offset?: number;
+}
+export interface TocGetEntryInput {
+    target: TocEntryAddress;
+}
+export interface TocEditEntryInput {
+    target: TocEntryAddress;
+    patch: {
+        text?: string;
+        level?: number;
+        tableIdentifier?: string;
+        omitPageNumber?: boolean;
+    };
+}
+export interface TocEntryProperties {
+    /** Raw TC instruction string. */
+    instruction: string;
+    /** Entry display text. */
+    text: string;
+    /** TOC level (from \l switch, default 1). */
+    level: number;
+    /** Table identifier from \f switch, if present. */
+    tableIdentifier?: string;
+    /** Whether page number is omitted (\n switch). */
+    omitPageNumber: boolean;
+}
+export interface TocEntryInfo {
+    nodeType: 'tableOfContentsEntry';
+    kind: 'inline';
+    properties: TocEntryProperties;
+}
+export interface TocEntryDomain {
+    address: TocEntryAddress;
+    instruction: string;
+    text: string;
+    level: number;
+    tableIdentifier?: string;
+    omitPageNumber: boolean;
+}
+export type TocListEntriesResult = DiscoveryOutput<TocEntryDomain>;
+export interface TocEntryMutationSuccess {
+    success: true;
+    entry: TocEntryAddress;
+}
+export interface TocEntryMutationFailure {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type TocEntryMutationResult = TocEntryMutationSuccess | TocEntryMutationFailure;

package/dist/document-api/src/track-changes/track-changes.d.ts

@@ -0,0 +1,177 @@
+import { Receipt, TrackChangeInfo, TrackChangesListQuery, TrackChangesListResult } from '../types/index.js';
+import { StoryLocator } from '../types/story.types.js';
+import { TextCoordinateSpace, TextTarget } from '../types/address.js';
+import { RevisionGuardOptions } from '../write/write.js';
+export type TrackChangesListInput = TrackChangesListQuery;
+export interface TrackChangesGetInput {
+    id: string;
+    /** Story containing the tracked change. Omit for body (backward compatible). */
+    story?: StoryLocator;
+}
+export interface TrackChangesAcceptInput {
+    id: string;
+    /** Story containing the tracked change. Omit for body (backward compatible). */
+    story?: StoryLocator;
+}
+export interface TrackChangesRejectInput {
+    id: string;
+    /** Story containing the tracked change. Omit for body (backward compatible). */
+    story?: StoryLocator;
+}
+export interface TrackChangesAcceptAllInput {
+    story?: StoryLocator | 'all';
+}
+export interface TrackChangesRejectAllInput {
+    story?: StoryLocator | 'all';
+}
+export interface TrackChangesRangeInput {
+    range: TextTarget;
+    story?: StoryLocator;
+    /** Coordinate space of the TextTarget offsets. Omitted preserves legacy tracked-space behavior. */
+    coordinateSpace?: TextCoordinateSpace;
+}
+export type ReviewDecideTargetSide = 'insert' | 'inserted' | 'delete' | 'deleted' | 'source' | 'destination';
+export type ReviewDecideIdTargetSide = 'insert' | 'inserted' | 'delete' | 'deleted';
+/**
+ * Tracked-move pairing assertion for a decide target. Callers that resolved an
+ * ambiguous shape (e.g. surface guesses a paragraph delete+insert might be a
+ * move) can ask the decide adapter to verify the projection before applying
+ * the decision. `'pair'` asserts the resolved entry must be a paired move;
+ * `'source'` / `'destination'` further narrow to a specific half. When the
+ * assertion does not hold the adapter fails closed with an explicit failure
+ * code instead of silently treating the target as a non-move decision.
+ */
+export type ReviewDecideTargetMoveRole = 'pair' | 'source' | 'destination';
+export interface ReviewDecideRangeTargetOptions {
+    /**
+     * Optional logical overlap selector for callers that already resolved an
+     * ambiguous overlap surface. The adapter owns interpretation.
+     */
+    overlap?: string;
+    /** Optional revision side for paired replacement or move targets. */
+    side?: ReviewDecideTargetSide;
+    /** Optional story containing the range. */
+    story?: StoryLocator;
+    /** Compatibility alias used by older range callers; interpretation is adapter-owned. */
+    part?: string;
+}
+export type ReviewDecideTextRangeTarget = ReviewDecideRangeTargetOptions & {
+    kind: 'range';
+    range: TextTarget;
+    /** Coordinate space of `range`. Omitted preserves legacy tracked-space behavior. */
+    coordinateSpace?: TextCoordinateSpace;
+};
+export type ReviewDecideLogicalRangeTarget = ReviewDecideRangeTargetOptions & {
+    kind: 'range';
+    range: {
+        anchor: string;
+        relativeStart: number;
+        relativeEnd: number;
+    };
+};
+/** Semantic target for {@link ReviewDecideInput}. */
+export type ReviewDecideTarget = {
+    kind: 'id';
+    id: string;
+    story?: StoryLocator;
+    side?: ReviewDecideIdTargetSide;
+    moveRole?: ReviewDecideTargetMoveRole;
+} | {
+    /** Resolve several whole logical changes in one atomic history unit. */
+    kind: 'ids';
+    ids: string[];
+} | ReviewDecideTextRangeTarget | ReviewDecideLogicalRangeTarget | {
+    kind: 'all';
+    story?: StoryLocator | 'all';
+};
+/** Legacy compatibility shapes accepted by the validator. */
+export type LegacyReviewDecideTarget = {
+    id: string;
+    story?: StoryLocator;
+    moveRole?: ReviewDecideTargetMoveRole;
+} | {
+    scope: 'all';
+    story?: StoryLocator | 'all';
+};
+export type ReviewDecisionTarget = ReviewDecideTarget | LegacyReviewDecideTarget;
+export interface ReviewDecideInput {
+    decision: 'accept' | 'reject';
+    target: ReviewDecideTarget | LegacyReviewDecideTarget;
+    /**
+     * Backward-compatible alias for `options.expectedRevision`. Explicit options
+     * take precedence when both are supplied.
+     */
+    expectedRevision?: string;
+}
+/**
+ * Internal canonical decide target — the legacy shapes have been promoted to
+ * `{ kind: 'id' }` / `{ kind: 'all' }`. Adapters consume this normalized
+ * form so the kernel side does not need to re-handle legacy aliases.
+ */
+export interface ReviewDecideRangeInput {
+    decision: 'accept' | 'reject';
+    target: ReviewDecideTarget;
+}
+export interface TrackChangesAdapter {
+    /** List tracked changes matching the given query. */
+    list(input?: TrackChangesListInput): TrackChangesListResult;
+    /** Retrieve full information for a single tracked change. */
+    get(input: TrackChangesGetInput): TrackChangeInfo;
+    /**
+     * Apply an accept / reject decision against the document. By-id, range,
+     * routes by-id, range, and bulk targets through this single entrypoint;
+     * legacy `accept` / `reject` / `acceptAll` / `rejectAll` adapter methods
+     * remain as compatibility shims until callers migrate.
+     */
+    decide?(input: ReviewDecideRangeInput, options?: RevisionGuardOptions): Receipt;
+    /** Accept a tracked change, applying it to the document. */
+    accept(input: TrackChangesAcceptInput, options?: RevisionGuardOptions): Receipt;
+    /** Reject a tracked change, reverting it from the document. */
+    reject(input: TrackChangesRejectInput, options?: RevisionGuardOptions): Receipt;
+    /** Accept all tracked changes matching the requested bulk filter. */
+    acceptAll(input: TrackChangesAcceptAllInput, options?: RevisionGuardOptions): Receipt;
+    /** Reject all tracked changes matching the requested bulk filter. */
+    rejectAll(input: TrackChangesRejectAllInput, options?: RevisionGuardOptions): Receipt;
+    /**
+     * Compatibility range entrypoint for adapters that predate the canonical
+     * `decide` method but can still resolve TextTarget range decisions.
+     */
+    decideRange?(input: {
+        decision: 'accept' | 'reject';
+    } & TrackChangesRangeInput, options?: RevisionGuardOptions): Receipt;
+}
+/** Public surface for trackChanges on DocumentApi. */
+export interface TrackChangesApi {
+    list(input?: TrackChangesListInput): TrackChangesListResult;
+    get(input: TrackChangesGetInput): TrackChangeInfo;
+    decide(input: ReviewDecideInput, options?: RevisionGuardOptions): Receipt;
+}
+/**
+ * Execute wrappers below are the canonical interception point for input
+ * normalization and validation before delegating to the adapter.
+ */
+export declare function executeTrackChangesList(adapter: TrackChangesAdapter, input?: TrackChangesListInput): TrackChangesListResult;
+export declare function executeTrackChangesGet(adapter: TrackChangesAdapter, input: TrackChangesGetInput): TrackChangeInfo;
+/**
+ * Executes the consolidated `trackChanges.decide` operation by routing to the
+ * appropriate adapter method based on the discriminated input.
+ *
+ * Accepting/rejecting changes is a resolution action, not a content mutation -
+ * changeMode and dryRun are not applicable, so this accepts
+ * {@link RevisionGuardOptions} rather than `MutationOptions`.
+ *
+ * Validates the canonical discriminated target shape
+ * (`{ kind: 'id' | 'ids' | 'range' | 'all' }`) and transparently promotes the
+ * legacy `{ id, story? }` / `{ scope: 'all' }` shapes. Adapters that
+ * implement the new {@link TrackChangesAdapter.decide} entrypoint receive
+ * the normalized canonical input; older adapters that only expose
+ * accept/reject/acceptAll/rejectAll still work for id targets without a side
+ * selector and all targets.
+ */
+export declare function executeTrackChangesDecide(adapter: TrackChangesAdapter, rawInput: ReviewDecideInput, options?: RevisionGuardOptions): Receipt;
+/**
+ * Validate and normalize a `trackChanges.decide` input into the canonical
+ * `{ kind: 'id' | 'ids' | 'range' | 'all' }` target shape. Exposed for adapters /
+ * tests that need to share the same validation surface.
+ */
+export declare function validateReviewDecideInput(rawInput: ReviewDecideInput): ReviewDecideRangeInput;

package/dist/document-api/src/types/adapter-result.d.ts

@@ -0,0 +1,10 @@
+import { ReceiptFailure } from './receipt.js';
+/**
+ * Shared failure shape for optional adapter namespace mutation results.
+ * Per-entity success types vary (different property names for entity addresses),
+ * but all failure types share this identical shape.
+ */
+export interface AdapterMutationFailure {
+    success: false;
+    failure: ReceiptFailure;
+}

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

@@ -0,0 +1,169 @@
+import { BlockNodeType } from './base.js';
+import { StoryLocator } from './story.types.js';
+import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
+export type Range = {
+    /** Inclusive start offset (0-based, UTF-16 code units). */
+    start: number;
+    /** Exclusive end offset (0-based, UTF-16 code units). */
+    end: number;
+};
+/**
+ * Paragraph-local coordinate space used by text offsets.
+ *
+ * `visible` is the default and counts rendered document text. `tracked` is
+ * additive metadata for ranges that intentionally include deletion-side tracked
+ * text such as `<w:delText>`.
+ */
+export type TextCoordinateSpace = 'visible' | 'tracked';
+export type TextAddress = {
+    kind: 'text';
+    blockId: string;
+    range: Range;
+    /** Story containing this text. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+/**
+ * A single anchored text segment within one block.
+ *
+ * Unlike {@link TextAddress} (used for mutation inputs), TextSegment is a
+ * lightweight component of a {@link TextTarget}: it carries no `kind`
+ * discriminant because the parent TextTarget already provides it.
+ */
+export type TextSegment = {
+    blockId: string;
+    range: Range;
+};
+/**
+ * Multi-segment text target returned by comment read operations.
+ *
+ * A single comment can span multiple discontinuous text ranges (e.g. when Word
+ * applies the same comment ID across separate marked runs or across blocks).
+ * TextTarget faithfully represents all anchored segments in document order.
+ *
+ * Invariants:
+ * - `segments` is non-empty (at least one segment).
+ * - Segments are sorted in document order.
+ * - Segment bounds are valid integers (start >= 0, start <= end).
+ */
+export type TextTarget = {
+    kind: 'text';
+    segments: [TextSegment, ...TextSegment[]];
+    /** Story containing this text target. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+/**
+ * Block node types valid as `nodeEdge` selection anchors.
+ *
+ * Excludes:
+ * - `tableRow`, `tableCell`: row/column semantics out of scope
+ * - `listItem`: derived from paragraph attrs, no distinct PM wrapper node
+ */
+export type SelectionEdgeNodeType = Exclude<BlockNodeType, 'tableRow' | 'tableCell' | 'listItem'>;
+export declare const SELECTION_EDGE_NODE_TYPES: readonly ["paragraph", "heading", "table", "tableOfContents", "sdt", "image"];
+/** Block node address valid as a `nodeEdge` selection anchor. */
+export type SelectionEdgeNodeAddress = {
+    kind: 'block';
+    nodeType: SelectionEdgeNodeType;
+    nodeId: string;
+    /** Story containing this node. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+/**
+ * A point within a document selection.
+ *
+ * - `text`: A character offset within a specific block's flattened text model.
+ * - `nodeEdge`: The boundary of a block-level node (before or after).
+ */
+export type SelectionPoint = {
+    kind: 'text';
+    blockId: string;
+    offset: number;
+    /** Story containing this point. Omit for body (backward compatible). */ story?: StoryLocator;
+} | {
+    kind: 'nodeEdge';
+    node: SelectionEdgeNodeAddress;
+    edge: 'before' | 'after';
+};
+/**
+ * A contiguous document selection: the canonical public target for the core
+ * selection-mutation family (`delete`, `replace`, `format.apply`, `mutations.apply`).
+ *
+ * Other range-targeted APIs (comments, hyperlinks) continue to use `TextAddress`.
+ */
+export type SelectionTarget = {
+    kind: 'selection';
+    start: SelectionPoint;
+    end: SelectionPoint;
+    /** Story containing this selection. Omit for body (backward compatible). */
+    story?: StoryLocator;
+    /**
+     * Coordinate space for text endpoint offsets. Omitted means `visible`.
+     * Present as `tracked` for targets that include deletion-side tracked text,
+     * including additive search matches and live review selections.
+     */
+    coordinateSpace?: TextCoordinateSpace;
+};
+/** Discriminated input for direct operations: either an explicit target or a ref string. */
+export type TargetLocator = {
+    target: SelectionTarget;
+    ref?: undefined;
+} | {
+    ref: string;
+    target?: undefined;
+};
+/** Delete behavior mode. */
+export type DeleteBehavior = 'selection' | 'exact';
+export type EntityType = 'comment' | 'trackedChange';
+export type CommentAddress = {
+    kind: 'entity';
+    entityType: 'comment';
+    /**
+     * Comment navigation is currently body-scoped only.
+     *
+     * Unlike bookmark and tracked-change navigation, `navigateTo()` does not yet
+     * accept a `story` locator for comments.
+     */
+    entityId: string;
+};
+export type TrackedChangeAddress = {
+    kind: 'entity';
+    entityType: 'trackedChange';
+    entityId: string;
+    /** Story containing this tracked change. Omit for body (backward compatible). */
+    story?: StoryLocator;
+    /** Preferred rendered page instance for repeated stories such as headers and footers. */
+    pageIndex?: number;
+};
+export type EntityAddress = CommentAddress | TrackedChangeAddress;
+/**
+ * Address for navigating to a block-level element by its node ID.
+ *
+ * The `nodeId` maps to `paraId` (from OOXML) when available, with fallback
+ * to `sdBlockId` (session-scoped). Use the value returned by Document API
+ * queries (e.g. `query.match`, `find`, `getNode`) as the `nodeId`.
+ *
+ * When `nodeType` is omitted, the lookup searches across all block types.
+ *
+ * Block navigation is currently body-scoped only. For non-body stories such
+ * as headers, footers, footnotes, and endnotes, `navigateTo()` currently
+ * supports story-aware bookmark and tracked-change targets instead.
+ */
+export type BlockNavigationAddress = {
+    kind: 'block';
+    nodeId: string;
+    nodeType?: SelectionEdgeNodeType;
+};
+/**
+ * Union of all address types accepted by `navigateTo()`.
+ *
+ * Supports navigation to:
+ * - Blocks by `nodeId` in the body story
+ * - Bookmarks by `name`, optionally scoped to a `story`
+ * - Comments by `entityId` in the body story
+ * - Tracked changes by `entityId`, optionally scoped to a `story`
+ *
+ * Story-aware navigation is currently supported for bookmarks and tracked
+ * changes. Block and comment targets remain body-only until the runtime gains
+ * equivalent non-body resolution paths.
+ */
+export type NavigableAddress = BlockNavigationAddress | BookmarkAddress | CommentAddress | TrackedChangeAddress;