superdoc 2.2.0 → 2.3.0

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

@@ -0,0 +1,89 @@
+import { StoryLocator } from './story.types.js';
+export type NodeKind = 'block' | 'inline';
+export declare const NODE_KINDS: readonly ["block", "inline"];
+export type NodeType = 'paragraph' | 'heading' | 'listItem' | 'table' | 'tableRow' | 'tableCell' | 'tableOfContents' | 'run' | 'bookmark' | 'comment' | 'hyperlink' | 'footnoteRef' | 'endnoteRef' | 'crossRef' | 'indexEntry' | 'citation' | 'authorityEntry' | 'sequenceField' | 'tab' | 'lineBreak' | 'image' | 'sdt';
+export declare const NODE_TYPES: readonly ["paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak"];
+/**
+ * Node types that can appear in block context.
+ * Note: 'sdt' and 'image' can appear in both block and inline contexts.
+ */
+export type BlockNodeType = Extract<NodeType, 'paragraph' | 'heading' | 'listItem' | 'table' | 'tableRow' | 'tableCell' | 'tableOfContents' | 'image' | 'sdt'>;
+export declare const BLOCK_NODE_TYPES: readonly ["paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt"];
+/**
+ * Block node types that `blocks.delete` can target in this release.
+ * Excludes `tableRow` and `tableCell` (row/column semantics are out of scope).
+ */
+export type DeletableBlockNodeType = Exclude<BlockNodeType, 'tableRow' | 'tableCell' | 'tableOfContents' | 'image'>;
+export declare const DELETABLE_BLOCK_NODE_TYPES: readonly ["paragraph", "heading", "listItem", "table", "sdt"];
+/**
+ * Node types that can appear in inline context.
+ * Note: 'sdt' and 'image' can appear in both block and inline contexts.
+ */
+export type InlineNodeType = Extract<NodeType, 'run' | 'bookmark' | 'comment' | 'hyperlink' | 'sdt' | 'image' | 'footnoteRef' | 'endnoteRef' | 'crossRef' | 'indexEntry' | 'citation' | 'authorityEntry' | 'sequenceField' | 'tab' | 'lineBreak'>;
+export declare const INLINE_NODE_TYPES: readonly ["run", "bookmark", "comment", "hyperlink", "sdt", "image", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak"];
+export type Position = {
+    blockId: string;
+    /**
+     * 0-based offset into the block's flattened text representation.
+     *
+     * - Text runs contribute their character length.
+     * - Leaf inline nodes (images, tabs, etc.) contribute a single placeholder character.
+     * - Transparent inline wrappers (hyperlinks, bookmarks, etc.) contribute only their inner text.
+     */
+    offset: number;
+};
+export type InlineAnchor = {
+    start: Position;
+    end: Position;
+};
+export type BlockNodeAddress = {
+    kind: 'block';
+    nodeType: BlockNodeType;
+    nodeId: string;
+    /** Story containing this block. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+export type TableAddress = {
+    kind: 'block';
+    nodeType: 'table';
+    nodeId: string;
+};
+export type TableRowAddress = {
+    kind: 'block';
+    nodeType: 'tableRow';
+    nodeId: string;
+};
+export type TableCellAddress = {
+    kind: 'block';
+    nodeType: 'tableCell';
+    nodeId: string;
+};
+export type TableOrRowAddress = TableAddress | TableRowAddress;
+export type TableOrCellAddress = TableAddress | TableCellAddress;
+export type DeletableBlockNodeAddress = {
+    kind: 'block';
+    nodeType: DeletableBlockNodeType;
+    nodeId: string;
+    /** Story containing this block. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+export type InlineNodeAddress = {
+    kind: 'inline';
+    nodeType: InlineNodeType;
+    anchor: InlineAnchor;
+    /** Story containing this inline node. Omit for body (backward compatible). */
+    story?: StoryLocator;
+};
+export type NodeAddress = BlockNodeAddress | InlineNodeAddress;
+export type NodeSummary = {
+    label?: string;
+    text?: string;
+};
+export interface BaseNodeInfo {
+    nodeType: NodeType;
+    kind: NodeKind;
+    summary?: NodeSummary;
+    text?: string;
+    /** Child nodes. Typed as BaseNodeInfo[] to avoid circular imports; narrow via `nodeType`. */
+    nodes?: BaseNodeInfo[];
+}

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

@@ -0,0 +1,190 @@
+import { BlockNodeType, BlockNodeAddress, DeletableBlockNodeAddress } from './base.js';
+import { AffectedRef, AffectedRefRemapping, Receipt, ReceiptFailure, ReceiptInsert, TextRangeShift } from './receipt.js';
+import { StoryLocator } from './story.types.js';
+import { ParagraphNumbering } from './paragraph.types.js';
+export interface BlockListEntry {
+    ordinal: number;
+    nodeId: string;
+    nodeType: BlockNodeType;
+    textPreview: string | null;
+    /** Full flattened block text when requested via BlocksListInput.includeText. */
+    text?: string | null;
+    isEmpty: boolean;
+    /** Named paragraph style ID (e.g. 'Normal', 'Heading1'). */
+    styleId?: string | null;
+    /** Font family from the block's first text run. */
+    fontFamily?: string;
+    /** Font size from the block's first text run. */
+    fontSize?: number;
+    /** True if the block's text is bold. */
+    bold?: boolean;
+    /** True if the block's text is underlined. */
+    underline?: boolean;
+    /** Text color when explicitly set in the document. */
+    color?: string;
+    /** Paragraph alignment. */
+    alignment?: string;
+    /** Heading level (1-6). Only for headings. */
+    headingLevel?: number;
+    /**
+     * Numbering reference (`numId` + `level`) for numbered blocks, sourced from the
+     * block's direct numbering properties (`w:numPr`). Present for numbered
+     * headings and numbered paragraphs alike, so a numbered-heading sequence can be
+     * discovered here even though those blocks resolve as `heading`, not `listItem`.
+     * Absent for non-numbered blocks. Distinct from the list-rendering
+     * marker/ordinal exposed on list items.
+     */
+    paragraphNumbering?: ParagraphNumbering;
+    /** Resolved list marker, hierarchy, and kind for list items. */
+    numbering?: {
+        marker: string;
+        path: number[];
+        kind: 'ordered' | 'bullet';
+    };
+    /** Ref handle targeting the block's full text. Pass to superdoc_format or superdoc_edit. */
+    ref?: string;
+}
+export interface BlocksListInput {
+    offset?: number;
+    limit?: number;
+    nodeTypes?: BlockNodeType[];
+    /** Include full flattened text for each block. Omit to return textPreview only. */
+    includeText?: boolean;
+    /** Restrict block listing to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+}
+export interface BlocksListResult {
+    total: number;
+    blocks: BlockListEntry[];
+    revision: string;
+}
+export interface BlocksDeleteInput {
+    target: DeletableBlockNodeAddress;
+}
+export interface BlocksDeleteResult {
+    success: true;
+    deleted: DeletableBlockNodeAddress;
+    deletedBlock?: DeletedBlockSummary;
+    trackedChangeRefs?: ReceiptInsert[];
+    invalidatedRefs?: AffectedRef[];
+    affectedStories?: StoryLocator[];
+    textRangeShifts?: TextRangeShift[];
+    txId?: string;
+}
+export interface BlocksDeleteRangeInput {
+    start: BlockNodeAddress;
+    end: BlockNodeAddress;
+}
+export interface DeletedBlockSummary {
+    ordinal: number;
+    nodeId: string;
+    nodeType: string;
+    textPreview: string | null;
+}
+export interface BlocksSplitInput {
+    /** Paragraph-shaped block to split. Only `paragraph` / `heading` / `listItem` are supported. */
+    target: BlockNodeAddress;
+    /** Char offset inside the target paragraph in the declared coordinate space. */
+    offset: number;
+    /** Include deleted tracked text in the offset ruler. Defaults to `visible`. */
+    coordinateSpace?: 'visible' | 'tracked';
+}
+export interface BlocksSplitSuccessResult {
+    success: true;
+    /** Address of the new paragraph created by the split (the tail). */
+    inserted: BlockNodeAddress;
+    /**
+     * Address of the paragraph that was split (the head — it keeps the original
+     * id and the text before the offset). Optional/additive: consumers that
+     * splice retained layout projections need the receipt to state BOTH sides
+     * of the structural delta.
+     */
+    anchor?: BlockNodeAddress;
+    trackedChangeRefs?: ReceiptInsert[];
+    remappedRefs?: AffectedRefRemapping[];
+    affectedStories?: StoryLocator[];
+    textRangeShifts?: TextRangeShift[];
+    txId?: string;
+}
+export interface BlocksSplitFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type BlocksSplitResult = BlocksSplitSuccessResult | BlocksSplitFailureResult;
+export interface BlocksMergeInput {
+    /** First paragraph; receives the merged content. */
+    first: BlockNodeAddress;
+    /** Paragraph immediately after `first` in the same story. */
+    second: BlockNodeAddress;
+}
+export interface BlocksMergeSuccessResult {
+    success: true;
+    /** Address of the paragraph that was removed (the second paragraph). */
+    removed: BlockNodeAddress;
+    /**
+     * Caret offset at the paragraph join in the first paragraph's pre-merge
+     * visible coordinate space. Hosts should prefer this source-owned value
+     * over possibly stale painted text-length metadata when restoring the
+     * selection after a boundary merge.
+     */
+    joinOffset?: number;
+    /**
+     * Address of the paragraph that received the merged content (the first
+     * paragraph). Optional/additive — see BlocksSplitSuccessResult.anchor.
+     */
+    anchor?: BlockNodeAddress;
+    trackedChangeRefs?: ReceiptInsert[];
+    remappedRefs?: AffectedRefRemapping[];
+    affectedStories?: StoryLocator[];
+    textRangeShifts?: TextRangeShift[];
+    txId?: string;
+}
+export interface BlocksMergeFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type BlocksMergeResult = BlocksMergeSuccessResult | BlocksMergeFailureResult;
+export interface BlocksMoveInput {
+    /** Paragraph to move. */
+    source: BlockNodeAddress;
+    /** Destination anchor paragraph in the same story. */
+    destination: BlockNodeAddress;
+    /** Whether to place `source` before or after `destination`. */
+    placement: 'before' | 'after';
+}
+export interface BlocksMoveSuccessResult {
+    success: true;
+    /** Same `source` paragraph, now relocated. */
+    moved: BlockNodeAddress;
+    remappedRefs?: AffectedRefRemapping[];
+    affectedStories?: StoryLocator[];
+    /**
+     * Tracked-mode authoring (changeMode: 'tracked') emits paired move review
+     * entities. Each entry addresses the logical pair so callers can route the
+     * resulting review through `trackChanges.list/get/decide`. Direct-mode
+     * moves leave this field undefined.
+     */
+    trackedChangeRefs?: ReceiptInsert[];
+    txId?: string;
+}
+export interface BlocksMoveFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type BlocksMoveResult = BlocksMoveSuccessResult | BlocksMoveFailureResult;
+export type { Receipt };
+export interface BlocksDeleteRangeResult {
+    success: true;
+    deletedCount: number;
+    deletedBlocks: DeletedBlockSummary[];
+    revision: {
+        before: string;
+        after: string;
+    };
+    dryRun: boolean;
+    trackedChangeRefs?: ReceiptInsert[];
+    invalidatedRefs?: AffectedRef[];
+    affectedStories?: StoryLocator[];
+    textRangeShifts?: TextRangeShift[];
+    txId?: string;
+}

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

@@ -0,0 +1,216 @@
+import { AdapterMutationFailure } from './adapter-result.js';
+import { SelectionTarget } from './address.js';
+import { ReceiptFailure, ReceiptSuccess, ReviewWarning } from './receipt.js';
+import { StoryLocator } from './story.types.js';
+export declare const SUPERDOC_V2_CLIPBOARD_MIME = "application/x-superdoc-v2-fragment";
+export declare const SUPERDOC_V22_CLIPBOARD_MIME = "application/x-superdoc-v2-fragment-v2.2";
+export declare const SUPERDOC_V1_CLIPBOARD_MIME = "application/x-superdoc-slice";
+export declare const SUPERDOC_V2_CLIPBOARD_FRAGMENT_KIND = "superdoc.clipboard.fragment";
+export declare const SUPERDOC_V2_CLIPBOARD_FRAGMENT_VERSION = "v2.1";
+export declare const SUPERDOC_V22_CLIPBOARD_FRAGMENT_VERSION = "v2.2";
+export declare const MAX_V22_ASSET_DECODED_BYTES: number;
+export declare const MAX_V22_TOTAL_DECODED_BYTES: number;
+export declare const MAX_V22_ASSET_COUNT = 16;
+export declare const MAX_V22_IMAGE_REF_COUNT = 64;
+export declare const MAX_V22_PAYLOAD_BYTES: number;
+export type ClipboardSourceKind = 'superdoc-v2-fragment' | 'superdoc-v1-slice' | 'html' | 'rtf' | 'image' | 'file' | 'plain-text' | 'empty' | 'unknown';
+export type SDPasteUnsupportedReason = 'paste-empty' | 'paste-payload-too-large' | 'paste-depth-exceeded' | 'paste-source-unsupported' | 'paste-fragment-version-unsupported' | 'paste-no-faithful-representation' | 'paste-structure-unsupported' | 'paste-media-unsupported-type' | 'paste-media-bad-magic' | 'paste-media-too-large' | 'paste-tracked-structural-unsupported' | 'paste-cross-story-unsupported' | 'paste-target-unsupported' | 'paste-legacy-slice-unsupported' | 'paste-security-rejected';
+export interface ClipboardPayloadItem {
+    /** MIME type, for example `text/plain`, `text/html`, or `application/x-superdoc-v2-fragment`. */
+    type: string;
+    kind: 'string' | 'bytes';
+    data: string | Uint8Array;
+    name?: string;
+}
+export interface ClipboardPayload {
+    source?: ClipboardSourceKind | 'browser' | 'api';
+    items: readonly ClipboardPayloadItem[];
+}
+export type ClipboardFallbackPolicy = 'reject-rich' | 'plain-with-warning';
+export interface ClipboardParseOptions {
+    fallback?: ClipboardFallbackPolicy;
+    maxBytes?: number;
+    maxDepth?: number;
+}
+export interface SDPasteRunMarks {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    color?: string;
+    highlight?: string;
+    fontSizePt?: number;
+    fontFamily?: string;
+    verticalAlign?: 'baseline' | 'superscript' | 'subscript';
+}
+export interface SDPasteRun {
+    text: string;
+    marks?: SDPasteRunMarks;
+}
+export type SDPasteInline = {
+    kind: 'text';
+    text: string;
+    marks?: SDPasteRunMarks;
+} | {
+    kind: 'image';
+    assetId: string;
+    widthPx: number;
+    heightPx: number;
+    name?: string;
+    alt?: string;
+    title?: string;
+};
+export interface SDPasteParagraphBlock {
+    kind: 'paragraph';
+    runs: readonly SDPasteRun[];
+    inlines?: readonly SDPasteInline[];
+    styleRef?: string;
+    /** Portable built-in style intent; destination style identity remains local. */
+    semanticStyleRole?: 'default-paragraph' | 'title' | 'subtitle' | `heading-${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}`;
+    numbering?: {
+        numId: string;
+        ilvl: string;
+    };
+    /**
+     * Portable list membership intent. Without `numbering`, the kernel always
+     * materializes a fresh definition. With `numbering`, the existing identity
+     * is retained when the destination defines the same list kind; otherwise
+     * this intent is the cross-document fallback. `level` is zero-based and
+     * bounded to OOXML's nine list levels; omitted means level 0.
+     */
+    listIntent?: {
+        kind: 'bullet' | 'ordered';
+        level?: number;
+        /** True on the first block of a distinct adjacent portable list. */
+        startsNewList?: boolean;
+    };
+    /**
+     * Pre-validated direct `<w:pPr>` properties. Same-document copy carries the
+     * source paragraph's materialized properties for fidelity; external HTML
+     * paste may synthesize the supported portable subset (for example alignment).
+     * When present it wins over styleRef/numbering rendering, which remain
+     * derived alongside it for HTML flavors and older receivers. The kernel
+     * validates shape strictly and rejects section properties.
+     */
+    pPrXml?: string;
+    /**
+     * True when the block represents a COMPLETE source paragraph (the copy
+     * covered its paragraph mark). Complete paragraphs never merge into the
+     * paste anchor's paragraph, independent of whether they carry formatting.
+     */
+    complete?: boolean;
+}
+export interface SDPasteTableCell {
+    /** Cell content: paragraph blocks rendered through the shared paste renderer. */
+    blocks: readonly SDPasteParagraphBlock[];
+    /** Horizontal merge span (colspan). */
+    gridSpan?: number;
+    /** Direct cell shading fill as canonical hex RRGGBB. */
+    shadingColor?: string;
+    /** Direct cell padding in points. At least one side must be present. */
+    padding?: {
+        topPt?: number;
+        rightPt?: number;
+        bottomPt?: number;
+        leftPt?: number;
+    };
+}
+export interface SDPasteTableRow {
+    cells: readonly SDPasteTableCell[];
+}
+/**
+ * Table paste block: rendered as `w:tbl` with V1-parity defaults. Cell
+ * content is paragraph blocks only, so nested tables are impossible by
+ * construction; tracked-mode table paste rejects typed.
+ */
+export interface SDPasteTableBlock {
+    kind: 'table';
+    rows: readonly SDPasteTableRow[];
+}
+export type SDPasteBlock = SDPasteParagraphBlock | SDPasteTableBlock;
+export interface SDPasteAsset {
+    id: string;
+    mimeType: 'image/png' | 'image/jpeg';
+    bytes: Uint8Array;
+    name?: string;
+}
+export interface SDPasteAssetWire {
+    id: string;
+    mimeType: 'image/png' | 'image/jpeg';
+    data: string;
+}
+export interface SDPasteFragment {
+    kind: typeof SUPERDOC_V2_CLIPBOARD_FRAGMENT_KIND;
+    version: typeof SUPERDOC_V2_CLIPBOARD_FRAGMENT_VERSION | string;
+    blocks: readonly SDPasteBlock[];
+    assets?: readonly SDPasteAsset[];
+    diagnostics?: readonly ClipboardInsertDiagnostic[];
+}
+export interface ClipboardInsertDiagnostic {
+    severity: 'error' | 'warning' | 'info';
+    reason: SDPasteUnsupportedReason;
+    message: string;
+    sourceKind?: ClipboardSourceKind;
+    path?: Array<string | number>;
+}
+export interface ClipboardInsertPlanSummary {
+    sourceKind: ClipboardSourceKind;
+    blockCount: number;
+    assetCount: number;
+    imageRefCount: number;
+    plainFallback: boolean;
+}
+export interface ClipboardInsertPlan {
+    fragment: SDPasteFragment;
+    diagnostics: readonly ClipboardInsertDiagnostic[];
+    summary: ClipboardInsertPlanSummary;
+}
+export type ClipboardTarget = SelectionTarget | {
+    kind: 'block';
+    nodeId: string;
+    nodeType?: 'paragraph' | 'heading';
+    placement?: 'before' | 'after';
+    story?: StoryLocator;
+} | {
+    kind: 'documentEnd';
+    story?: StoryLocator;
+};
+export interface ClipboardInsertInput {
+    payload?: ClipboardPayload;
+    plan?: ClipboardInsertPlan;
+    fragment?: SDPasteFragment;
+    target?: ClipboardTarget;
+    changeMode?: 'direct' | 'tracked';
+    /** Preserve source formatting by default; match-destination is used by paste-and-match-style gestures. */
+    formattingMode?: 'preserve-source' | 'match-destination';
+    fallback?: ClipboardFallbackPolicy;
+}
+export interface ClipboardSerializeInput {
+    target?: ClipboardTarget;
+    includeHtml?: boolean;
+}
+export interface ClipboardInsertSuccess extends ReceiptSuccess {
+    plan: ClipboardInsertPlanSummary;
+    diagnostics: readonly ClipboardInsertDiagnostic[];
+}
+export type ClipboardInsertResult = ClipboardInsertSuccess | AdapterMutationFailure;
+export interface ClipboardParseFailure {
+    success: false;
+    failure: ReceiptFailure & {
+        details?: {
+            unsupportedReason?: SDPasteUnsupportedReason;
+            diagnostics?: readonly ClipboardInsertDiagnostic[];
+        };
+    };
+    diagnostics: readonly ClipboardInsertDiagnostic[];
+}
+export type ClipboardParseResult = {
+    success: true;
+    plan: ClipboardInsertPlan;
+    diagnostics: readonly ClipboardInsertDiagnostic[];
+} | ClipboardParseFailure;
+export interface ClipboardSerializeResult {
+    payload: ClipboardPayload;
+    plan: ClipboardInsertPlan;
+    warnings?: readonly ReviewWarning[];
+}

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

@@ -0,0 +1,17 @@
+import { BaseNodeInfo } from './base.js';
+export interface CommentNodeInfo extends BaseNodeInfo {
+    nodeType: 'comment';
+    kind: 'inline';
+    properties: CommentProperties;
+    bodyText?: string;
+    bodyNodes?: BaseNodeInfo[];
+}
+export type CommentStatus = 'open' | 'resolved';
+export interface CommentProperties {
+    commentId: string;
+    author?: string;
+    status?: CommentStatus;
+    createdAt?: string;
+    /** User-visible sidebar text */
+    commentText?: string;
+}

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

@@ -0,0 +1,56 @@
+import { TextAddress } from './address.js';
+import { BlockNodeAddress } from './base.js';
+import { ReceiptFailure, ReceiptInsert } from './receipt.js';
+import { StoryLocator } from './story.types.js';
+export type ParagraphCreateLocation = {
+    kind: 'documentStart';
+} | {
+    kind: 'documentEnd';
+} | {
+    kind: 'before';
+    target: BlockNodeAddress;
+} | {
+    kind: 'after';
+    target: BlockNodeAddress;
+};
+export interface CreateParagraphInput {
+    /** Target story for the new paragraph. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    at?: ParagraphCreateLocation;
+    text?: string;
+}
+export interface CreateParagraphSuccessResult {
+    success: true;
+    paragraph: BlockNodeAddress;
+    insertionPoint: TextAddress;
+    trackedChangeRefs?: ReceiptInsert[];
+    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    ref?: string;
+}
+export interface CreateParagraphFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type CreateParagraphResult = CreateParagraphSuccessResult | CreateParagraphFailureResult;
+export type HeadingCreateLocation = ParagraphCreateLocation;
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface CreateHeadingInput {
+    /** Target story for the new heading. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    level: HeadingLevel;
+    at?: HeadingCreateLocation;
+    text?: string;
+}
+export interface CreateHeadingSuccessResult {
+    success: true;
+    heading: BlockNodeAddress;
+    insertionPoint: TextAddress;
+    trackedChangeRefs?: ReceiptInsert[];
+    /** Stable ref handle for the created block. Pass directly to superdoc_format or superdoc_edit without searching. */
+    ref?: string;
+}
+export interface CreateHeadingFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type CreateHeadingResult = CreateHeadingSuccessResult | CreateHeadingFailureResult;

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

@@ -0,0 +1,99 @@
+/**
+ * Shared types and helpers for the standardized discovery envelope.
+ *
+ * All discovery operations (query.match, comments.list, trackChanges.list,
+ * lists.list, find) return a `DiscoveryResult<DiscoveryItem<TDomain>>` -
+ * a uniform envelope with pagination, revision tracking, and mutation-ready
+ * handles.
+ *
+ * See plans/master-api-unification-plan.md for design rationale.
+ */
+export type KnownTargetKind = 'text' | 'node' | 'list' | 'comment' | 'trackedChange' | 'table' | 'tableCell' | 'tableOfContents' | 'section' | 'sdt' | 'field';
+export type ExtensionTargetKind = `ext:${string}`;
+export type TargetKind = KnownTargetKind | ExtensionTargetKind;
+export type RefStability = 'stable' | 'ephemeral';
+export interface ResolvedHandle {
+    /** Mutation-ready ref string (e.g., V3 encoded ref, stable nodeId, 'comment:<id>'). */
+    ref: string;
+    /** Whether the ref survives across revisions. */
+    refStability: RefStability;
+    /** Semantic type of the target this handle points to. */
+    targetKind: TargetKind;
+}
+export interface PageInfo {
+    /** Maximum items requested per page. */
+    limit: number;
+    /** Zero-based offset into the total result set. */
+    offset: number;
+    /** Actual number of items returned in this page. Invariant: `returned === items.length`. */
+    returned: number;
+}
+/**
+ * A single discoverable entity with a mutation-ready handle and domain payload.
+ *
+ * `TDomain` carries the operation-specific fields (e.g., `snippet`, `address`,
+ * `blocks` for query.match; `status`, `text` for comments.list).
+ */
+export type DiscoveryItem<TDomain> = {
+    /** Deterministic identity, scoped to the evaluated revision. */
+    id: string;
+    /** Mutation-ready handle for chaining into `mutations.apply` or direct operations. */
+    handle: ResolvedHandle;
+} & TDomain;
+/**
+ * Standard discovery result envelope returned by all discovery operations.
+ *
+ * Provides revision tracking, total count, paginated items, and page metadata.
+ * The optional `TMeta` type parameter allows operation-specific metadata
+ * (e.g., `query.match` uses it for `effectiveResolved`). Defaults to `undefined`
+ * for operations that don't use it: backwards compatible.
+ */
+export interface DiscoveryResult<TItem, TMeta = undefined> {
+    /** Document revision at which the query was evaluated. */
+    evaluatedRevision: string;
+    /** Total number of matching entities (before pagination). */
+    total: number;
+    /** Paginated list of discovery items. */
+    items: TItem[];
+    /** Pagination metadata. Invariant: `page.returned === items.length`. */
+    page: PageInfo;
+    /** Operation-specific metadata. Present only when `TMeta` is specified. */
+    meta?: TMeta;
+}
+/**
+ * Convenience alias: `DiscoveryResult` wrapping `DiscoveryItem<TDomain>`.
+ *
+ * This is the return type of every standardized discovery operation.
+ */
+export type DiscoveryOutput<TDomain, TMeta = undefined> = DiscoveryResult<DiscoveryItem<TDomain>, TMeta>;
+/**
+ * Constructs a {@link ResolvedHandle}.
+ */
+export declare function buildResolvedHandle(ref: string, refStability: RefStability, targetKind: TargetKind): ResolvedHandle;
+/**
+ * Constructs a {@link DiscoveryItem} from an id, handle, and domain payload.
+ */
+export declare function buildDiscoveryItem<TDomain>(id: string, handle: ResolvedHandle, domain: TDomain): DiscoveryItem<TDomain>;
+/**
+ * Constructs a {@link DiscoveryResult} with invariant enforcement.
+ *
+ * @throws {Error} if `page.returned !== items.length`
+ */
+export declare function buildDiscoveryResult<TItem, TMeta = undefined>(params: {
+    evaluatedRevision: string;
+    total: number;
+    items: TItem[];
+    page: PageInfo;
+    meta?: TMeta;
+}): DiscoveryResult<TItem, TMeta>;
+/**
+ * Derives an apply-ready target from a discovery item, suitable for passing to
+ * `mutations.apply` step `where` clauses.
+ */
+export declare function toApplyTarget(item: DiscoveryItem<unknown>, evaluatedRevision: string): {
+    where: {
+        by: 'ref';
+        ref: string;
+    };
+    expectedRevision: string;
+};