@superdoc-dev/sdk 1.19.1 → 1.20.0

package/dist/agent/doc-snapshot.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Deterministic document snapshot.
+ *
+ * The workflow doc-index (see action-primitives/doc-index.ts) covers body blocks
+ * and lists. That coverage is too narrow for a real agent runtime — many
+ * editing tasks touch headers/footers, comments, tracked changes, sections,
+ * styles, content controls, fields, hyperlinks, bookmarks, images, or
+ * permission ranges. Selectors that target those surfaces must resolve from
+ * a snapshot that includes them, otherwise the agent has to either guess or
+ * silently fall back.
+ *
+ * This module builds a single read-only document snapshot in a deterministic
+ * sequence: each section is queried with explicit catalog operations, results
+ * are normalized into typed shapes, and selectors resolve against the same
+ * snapshot for the duration of one agent turn.
+ *
+ * The snapshot is intentionally side-effect free: it never mutates the
+ * document and never depends on inference. If an underlying operation
+ * returns `null`/empty, the corresponding section is recorded as empty
+ * rather than skipped, so consumers see a stable shape.
+ */
+import type { BoundDocApi } from '../generated/client.js';
+export type SnapshotBlock = {
+    ordinal: number;
+    nodeId: string;
+    nodeType: string;
+    text: string;
+    textPreview: string | null;
+    styleId?: string | null;
+    headingLevel?: number;
+    /**
+     * Computed numbering when the block participates in a numbering scheme.
+     * Legal clause numbers ("2.3.") usually live on numbered HEADINGS, not
+     * list nodes — this is how an agent sees them.
+     */
+    numbering?: {
+        marker: string | null;
+        path: number[] | null;
+        kind: string | null;
+    } | null;
+};
+export type SnapshotList = {
+    listId: string;
+    kind: 'ordered' | 'bullet' | string;
+    items: ReadonlyArray<{
+        nodeId: string;
+        ordinal: number;
+        level: number;
+        text: string;
+    }>;
+};
+export type SnapshotTable = {
+    nodeId: string;
+    ordinal: number;
+    rows: number;
+    columns: number;
+    cells: ReadonlyArray<{
+        rowIndex: number;
+        columnIndex: number;
+        text: string;
+        nodeId?: string;
+    }>;
+};
+export type SnapshotComment = {
+    id: string;
+    text: string;
+    status: string;
+    anchoredText?: string;
+    segments?: ReadonlyArray<{
+        blockId: string;
+        start: number;
+        end: number;
+    }>;
+};
+export type SnapshotTrackedChange = {
+    id: string;
+    type: string;
+    excerpt?: string;
+    author?: string;
+    date?: string;
+    story?: string;
+};
+export type SnapshotHeaderFooter = {
+    kind: 'header' | 'footer';
+    sectionId?: string;
+    sectionIndex?: number;
+    variant?: 'default' | 'first' | 'even' | string;
+    blocks: ReadonlyArray<SnapshotBlock>;
+};
+export type SnapshotSection = {
+    ordinal: number;
+    sectionId?: string;
+    startNodeId?: string;
+    endNodeId?: string;
+    pageSize?: {
+        width: number;
+        height: number;
+    };
+};
+export type SnapshotStyle = {
+    styleId: string;
+    name: string;
+    type?: string;
+    basedOn?: string;
+};
+export type SnapshotContentControl = {
+    id: string;
+    type?: string;
+    alias?: string;
+    tag?: string;
+    text?: string;
+};
+export type SnapshotField = {
+    id: string;
+    type?: string;
+    result?: string;
+};
+export type SnapshotHyperlink = {
+    id: string;
+    url: string;
+    display?: string;
+    nodeId?: string;
+};
+export type SnapshotBookmark = {
+    id: string;
+    name: string;
+    startNodeId?: string;
+    endNodeId?: string;
+};
+export type SnapshotPermissionRange = {
+    id: string;
+    startNodeId?: string;
+    endNodeId?: string;
+    editorOrEditorGroup?: string;
+};
+export type SnapshotImage = {
+    imageId: string;
+    nodeId?: string;
+    alt?: string;
+    caption?: string;
+};
+export type SnapshotDomain = 'blocks' | 'lists' | 'tables' | 'comments' | 'trackedChanges' | 'sections' | 'headerFooters' | 'styles' | 'contentControls' | 'fields' | 'hyperlinks' | 'bookmarks' | 'permissionRanges' | 'images';
+export type SnapshotDiagnostic = {
+    section: string;
+    message: string;
+};
+export type DocumentSnapshot = {
+    revision: string;
+    counts: {
+        blocks: number;
+        paragraphs: number;
+        headings: number;
+        tables: number;
+        lists: number;
+        images: number;
+        comments: number;
+        trackedChanges: number;
+        sections: number;
+        fields: number;
+        hyperlinks: number;
+        bookmarks: number;
+        contentControls: number;
+        permissionRanges: number;
+        styles: number;
+        headers: number;
+        footers: number;
+    };
+    blocks: readonly SnapshotBlock[];
+    lists: readonly SnapshotList[];
+    tables: readonly SnapshotTable[];
+    comments: readonly SnapshotComment[];
+    trackedChanges: readonly SnapshotTrackedChange[];
+    sections: readonly SnapshotSection[];
+    headerFooters: readonly SnapshotHeaderFooter[];
+    styles: readonly SnapshotStyle[];
+    contentControls: readonly SnapshotContentControl[];
+    fields: readonly SnapshotField[];
+    hyperlinks: readonly SnapshotHyperlink[];
+    bookmarks: readonly SnapshotBookmark[];
+    permissionRanges: readonly SnapshotPermissionRange[];
+    images: readonly SnapshotImage[];
+    diagnostics: readonly SnapshotDiagnostic[];
+};
+type SnapshotOptions = {
+    countsOnly?: boolean;
+    includeDomains?: readonly SnapshotDomain[];
+    blockNodeTypes?: readonly string[];
+    blockTextLimit?: number;
+    listLimit?: number;
+    tableLimit?: number;
+    commentLimit?: number;
+    trackedChangeLimit?: number;
+    /**
+     * Window into the block list. `blockOffset` is the 0-based index of the
+     * first block to return; `blockLimit` caps how many blocks come back. This
+     * is the primitive that makes large documents tractable: a 600-block /
+     * 38-page doc produces a ~58k-token full snapshot, so a reader pulls a
+     * bounded slice (e.g. offset 0, limit 40) per window instead of the whole
+     * thing. `counts.blocks` / `blocks[].ordinal` still reflect absolute
+     * positions so selectors and the next window line up.
+     */
+    blockOffset?: number;
+    blockLimit?: number;
+    /**
+     * Drop empty paragraphs/list-items from the returned blocks. A real DOCX is
+     * ~40% empty spacer paragraphs that carry full JSON overhead but no reading
+     * value; omitting them roughly halves the blocks payload for a reading pass.
+     * Ordinals are preserved, so the gaps are visible and selectors still work.
+     */
+    omitEmptyBlocks?: boolean;
+    /**
+     * Omit the duplicated `textPreview` field (it equals `text` whenever the
+     * block text is not truncated). Pure payload savings for readers that use
+     * `text`.
+     */
+    dropTextPreview?: boolean;
+};
+/**
+ * Build a deterministic snapshot of a document. The snapshot uses only
+ * read-mode operations from the generated contract — it never mutates state,
+ * and any individual section that fails is captured as a diagnostic so the
+ * rest of the snapshot remains usable.
+ */
+export declare function buildDocumentSnapshot(doc: BoundDocApi, options?: SnapshotOptions): Promise<DocumentSnapshot>;
+/**
+ * Structured ambiguity error returned when multiple candidates match a
+ * selector and the plan required uniqueness.
+ */
+export declare class AmbiguousSelectorError extends Error {
+    readonly code: "AMBIGUOUS_SELECTOR";
+    readonly candidates: ReadonlyArray<{
+        nodeId: string;
+        description: string;
+    }>;
+    constructor(message: string, candidates: ReadonlyArray<{
+        nodeId: string;
+        description: string;
+    }>);
+}
+/**
+ * Resolve a deterministic selector against the snapshot. Returns the matching
+ * block ids in document order. Selectors that target entities return
+ * entity-domain matches by id.
+ */
+export declare function resolveSnapshotSelector(snapshot: DocumentSnapshot, selector: import('./ir.js').AgentSelector): readonly string[];
+export {};
+//# sourceMappingURL=doc-snapshot.d.ts.map

package/dist/agent/doc-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-snapshot.d.ts","sourceRoot":"","sources":["../../src/agent/doc-snapshot.ts"],"names":[],"mappings":"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"}