superdoc 2.2.0 → 2.3.0

package/dist/document-api/src/metadata/anchored-metadata.types.d.ts

@@ -0,0 +1,175 @@
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+import { SelectionTarget } from '../types/address.js';
+/**
+ * Stable opaque identifier for an anchored-metadata entry. Lives in the
+ * anchor SDT's `w:tag` (ECMA-376 Part 1 §17.5.2.34) and links the anchor
+ * to the payload entry in the namespaced Custom XML Data Storage Part.
+ *
+ * Consumers may supply their own id at `attach` time (e.g. their own
+ * citation id); otherwise the adapter generates one. Ids are opaque
+ * strings — SuperDoc does not assume GUID or URN shape.
+ */
+export type AnchoredMetadataId = string;
+/**
+ * Where to place a new anchored-metadata entry in the document. v1
+ * supports a single paragraph text range only — the adapter wraps that
+ * range in a hidden inline SDT whose `w:tag` carries the id.
+ *
+ * v1 constraints (enforced at the contract layer):
+ *   - both `start` and `end` must be `{ kind: 'text' }` — `nodeEdge`
+ *     endpoints are not accepted.
+ *   - both endpoints must share the same `blockId` — cross-paragraph
+ *     spans are not accepted.
+ *
+ * Block-level, image, and table-cell anchors are out of scope for v1.
+ * Consumers who need them can fall back to the underlying primitives
+ * (`contentControls.*` + `customXml.parts.*`).
+ *
+ * Type alias of `SelectionTarget` — kept distinct for documentation; the
+ * resolver path is shared with the rest of the Document API.
+ */
+export type MetadataTarget = SelectionTarget;
+/**
+ * Caller-owned JSON payload. Any JSON-serializable value: object, array,
+ * string, number, boolean, or null. SuperDoc serializes the payload via
+ * `JSON.stringify` and stores it as an escaped text node inside a
+ * SuperDoc-owned `<ref id="..." encoding="json">…</ref>` element.
+ *
+ * The payload is opaque to other XML tools reading the DOCX package:
+ * VBA / Office.js readers see one text node of escaped JSON, not a
+ * structural XML tree. Consumers who need a Word-readable XML payload
+ * should use `customXml.parts.*` directly.
+ */
+export type AnchoredMetadataPayload = unknown;
+export interface AnchoredMetadataAttachInput {
+    /**
+     * Text range to anchor the metadata to. v1: same-paragraph text range
+     * (see {@link MetadataTarget} constraints).
+     */
+    target: MetadataTarget;
+    /**
+     * Logical namespace for the metadata set, e.g. `'urn:harvey:citations:1'`.
+     * SuperDoc writes this as the `xmlns` of the `<refs>` element in the
+     * backing Custom XML Data Storage Part. All entries sharing a namespace
+     * share one part on disk.
+     *
+     * Not to be confused with `<ds:schemaRef ds:uri>` — v1 does not write
+     * schemaRefs.
+     */
+    namespace: string;
+    /**
+     * Caller's payload (any JSON-serializable value). Stored opaquely inside
+     * a SuperDoc-owned `<ref id="..." encoding="json">…</ref>` envelope.
+     */
+    payload: AnchoredMetadataPayload;
+    /**
+     * Optional caller-chosen id. When omitted, the adapter generates one.
+     * Must be unique within the document — attach fails with
+     * `INVALID_INPUT` if an id collides with an existing entry.
+     */
+    id?: AnchoredMetadataId;
+}
+export interface AnchoredMetadataListInput {
+    /**
+     * Filter by logical namespace — matches the `xmlns` of the backing
+     * Storage Part's `<refs>` root.
+     */
+    namespace?: string;
+    /**
+     * Filter to entries whose resolved anchor range overlaps `within`. Useful
+     * for "what metadata is on this paragraph / selection" queries that would
+     * otherwise require listing every entry and resolving it.
+     *
+     * Mirrors the `hyperlinks.list({ within })` precedent. Same v1 target
+     * constraints as {@link MetadataTarget}: text-range only.
+     */
+    within?: SelectionTarget;
+    /**
+     * When true, include only entries whose SDT anchor currently resolves
+     * in the document body.
+     */
+    resolvedOnly?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface AnchoredMetadataGetInput {
+    id: AnchoredMetadataId;
+}
+export interface AnchoredMetadataUpdateInput {
+    id: AnchoredMetadataId;
+    /**
+     * Replace the entry's payload. Any JSON-serializable value. Replace
+     * semantics — no merge / JSON-patch.
+     */
+    payload: AnchoredMetadataPayload;
+}
+export interface AnchoredMetadataRemoveInput {
+    id: AnchoredMetadataId;
+}
+export interface AnchoredMetadataResolveInput {
+    id: AnchoredMetadataId;
+}
+/**
+ * Light view of an entry returned by `list()`. Carries identity and the
+ * package coordinates of its backing storage part, but NOT the payload —
+ * fetch via `get()` when needed.
+ */
+export interface AnchoredMetadataSummary {
+    id: AnchoredMetadataId;
+    namespace: string;
+    /** Package-relative path of the backing Storage Part. */
+    partName: string;
+    /** Whether the corresponding SDT anchor currently exists in the document. */
+    anchorStatus: 'resolved' | 'orphan';
+}
+export type AnchoredMetadataInfo = AnchoredMetadataSummary & {
+    /**
+     * The caller's payload, deserialized from the stored JSON envelope.
+     * SuperDoc reads the text content of `<ref id="..." encoding="json">`
+     * and `JSON.parse`s it before returning; consumers see the same shape
+     * they passed to `attach`.
+     */
+    payload: AnchoredMetadataPayload;
+};
+/**
+ * Where an entry's anchor currently lives in the document. Returned by
+ * `resolve()`. `target` is the SelectionTarget that spans the anchor's
+ * content — consumers can pass it to other read or mutation operations
+ * (selection, comment.add, etc.).
+ */
+export interface AnchoredMetadataResolveInfo {
+    id: AnchoredMetadataId;
+    target: SelectionTarget;
+}
+export interface AnchoredMetadataAttachSuccess {
+    success: true;
+    /** The id assigned to the new entry (caller-supplied or generated). */
+    id: AnchoredMetadataId;
+    namespace: string;
+    partName: string;
+}
+export type AnchoredMetadataAttachResult = AnchoredMetadataAttachSuccess | AdapterMutationFailure;
+/**
+ * Successful mutation outcome for update / remove.
+ *
+ * `remove` strips both the anchor content control (wrapper only, content
+ * stays in the document) and the payload entry, in that order. When the
+ * backing Storage Part has no remaining entries, the part itself is
+ * removed.
+ *
+ * In v1 these writes are sequenced, not transactional. The anchor lives
+ * in ProseMirror doc state and the payload lives in the OOXML package:
+ * two different state systems with no shared commit primitive. The
+ * adapter resolves the target up-front so the common failure mode
+ * (`TARGET_NOT_FOUND`) fails before any state change, but a crash
+ * strictly between the PM dispatch and the customXml write can leave a
+ * dangling payload entry. A future revision may add cross-state
+ * compensation.
+ */
+export interface AnchoredMetadataMutationSuccess {
+    success: true;
+    id: AnchoredMetadataId;
+}
+export type AnchoredMetadataMutationResult = AnchoredMetadataMutationSuccess | AdapterMutationFailure;
+export type AnchoredMetadataListResult = DiscoveryOutput<AnchoredMetadataSummary>;

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

@@ -0,0 +1,84 @@
+import { MutationOptions } from '../write/write.js';
+import { ParagraphMutationResult, ParagraphsSetStyleInput, ParagraphsSetStyleRefInput, ParagraphsClearStyleInput, ParagraphsResetDirectFormattingInput, ParagraphsSetAlignmentInput, ParagraphsClearAlignmentInput, ParagraphsSetIndentationInput, ParagraphsClearIndentationInput, ParagraphsSetSpacingInput, ParagraphsClearSpacingInput, ParagraphsSetKeepOptionsInput, ParagraphsSetOutlineLevelInput, ParagraphsSetFlowOptionsInput, ParagraphsSetTabStopInput, ParagraphsClearTabStopInput, ParagraphsClearAllTabStopsInput, ParagraphsSetBorderInput, ParagraphsClearBorderInput, ParagraphsSetShadingInput, ParagraphsClearShadingInput, ParagraphsSetMarkRunPropsInput, ParagraphsSetDirectionInput, ParagraphsClearDirectionInput, ParagraphsSetNumberingInput } from './paragraphs.types.js';
+export type { ParagraphTarget, ParagraphBlockType, ParagraphMutationResult, ParagraphMutationSuccess, ParagraphMutationFailure, MutationResolution, ParagraphAlignment, TabStopAlignment, TabStopLeader, BorderSide, ClearBorderSide, LineRule, ParagraphsSetStyleInput, ParagraphSemanticStyleRole, ParagraphsSetStyleRefInput, ParagraphsClearStyleInput, ParagraphsResetDirectFormattingInput, ParagraphsSetAlignmentInput, ParagraphsClearAlignmentInput, ParagraphsSetIndentationInput, ParagraphsClearIndentationInput, ParagraphsSetSpacingInput, ParagraphsClearSpacingInput, ParagraphsSetKeepOptionsInput, ParagraphsSetOutlineLevelInput, ParagraphsSetFlowOptionsInput, ParagraphsSetTabStopInput, ParagraphsClearTabStopInput, ParagraphsClearAllTabStopsInput, ParagraphsSetBorderInput, ParagraphsClearBorderInput, ParagraphsSetShadingInput, ParagraphsClearShadingInput, ParagraphsSetMarkRunPropsInput, ParagraphsSetDirectionInput, ParagraphsClearDirectionInput, ParagraphsSetNumberingInput, ParagraphDirection, AlignmentPolicy, } from './paragraphs.types.js';
+export { PARAGRAPH_ALIGNMENTS, TAB_STOP_ALIGNMENTS, TAB_STOP_LEADERS, BORDER_SIDES, CLEAR_BORDER_SIDES, LINE_RULES, PARAGRAPH_DIRECTIONS, ALIGNMENT_POLICIES, } from './paragraphs.types.js';
+export interface ParagraphsAdapter {
+    setStyle(input: ParagraphsSetStyleInput, options?: MutationOptions): ParagraphMutationResult;
+    setStyleRef(input: ParagraphsSetStyleRefInput, options?: MutationOptions): ParagraphMutationResult;
+    clearStyle(input: ParagraphsClearStyleInput, options?: MutationOptions): ParagraphMutationResult;
+    resetDirectFormatting(input: ParagraphsResetDirectFormattingInput, options?: MutationOptions): ParagraphMutationResult;
+    setAlignment(input: ParagraphsSetAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+    clearAlignment(input: ParagraphsClearAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+    setIndentation(input: ParagraphsSetIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+    clearIndentation(input: ParagraphsClearIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+    setSpacing(input: ParagraphsSetSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+    clearSpacing(input: ParagraphsClearSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+    setKeepOptions(input: ParagraphsSetKeepOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+    setOutlineLevel(input: ParagraphsSetOutlineLevelInput, options?: MutationOptions): ParagraphMutationResult;
+    setFlowOptions(input: ParagraphsSetFlowOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+    setTabStop(input: ParagraphsSetTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+    clearTabStop(input: ParagraphsClearTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+    clearAllTabStops(input: ParagraphsClearAllTabStopsInput, options?: MutationOptions): ParagraphMutationResult;
+    setBorder(input: ParagraphsSetBorderInput, options?: MutationOptions): ParagraphMutationResult;
+    clearBorder(input: ParagraphsClearBorderInput, options?: MutationOptions): ParagraphMutationResult;
+    setShading(input: ParagraphsSetShadingInput, options?: MutationOptions): ParagraphMutationResult;
+    clearShading(input: ParagraphsClearShadingInput, options?: MutationOptions): ParagraphMutationResult;
+    setMarkRunProps?(input: ParagraphsSetMarkRunPropsInput, options?: MutationOptions): ParagraphMutationResult;
+    setDirection(input: ParagraphsSetDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+    clearDirection(input: ParagraphsClearDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+    setNumbering(input: ParagraphsSetNumberingInput, options?: MutationOptions): ParagraphMutationResult;
+}
+/** Public API surface for `format.paragraph.*`: direct paragraph formatting. */
+export interface ParagraphFormatApi {
+    resetDirectFormatting(input: ParagraphsResetDirectFormattingInput, options?: MutationOptions): ParagraphMutationResult;
+    setAlignment(input: ParagraphsSetAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+    clearAlignment(input: ParagraphsClearAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+    setIndentation(input: ParagraphsSetIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+    clearIndentation(input: ParagraphsClearIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+    setSpacing(input: ParagraphsSetSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+    clearSpacing(input: ParagraphsClearSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+    setKeepOptions(input: ParagraphsSetKeepOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+    setOutlineLevel(input: ParagraphsSetOutlineLevelInput, options?: MutationOptions): ParagraphMutationResult;
+    setFlowOptions(input: ParagraphsSetFlowOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+    setTabStop(input: ParagraphsSetTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+    clearTabStop(input: ParagraphsClearTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+    clearAllTabStops(input: ParagraphsClearAllTabStopsInput, options?: MutationOptions): ParagraphMutationResult;
+    setBorder(input: ParagraphsSetBorderInput, options?: MutationOptions): ParagraphMutationResult;
+    clearBorder(input: ParagraphsClearBorderInput, options?: MutationOptions): ParagraphMutationResult;
+    setShading(input: ParagraphsSetShadingInput, options?: MutationOptions): ParagraphMutationResult;
+    clearShading(input: ParagraphsClearShadingInput, options?: MutationOptions): ParagraphMutationResult;
+    setMarkRunProps(input: ParagraphsSetMarkRunPropsInput, options?: MutationOptions): ParagraphMutationResult;
+    setDirection(input: ParagraphsSetDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+    clearDirection(input: ParagraphsClearDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+    setNumbering(input: ParagraphsSetNumberingInput, options?: MutationOptions): ParagraphMutationResult;
+}
+/** Public API surface for `styles.paragraph.*`: Word-like paragraph style application operations. */
+export interface ParagraphStylesApi {
+    setStyle(input: ParagraphsSetStyleInput, options?: MutationOptions): ParagraphMutationResult;
+    setStyleRef(input: ParagraphsSetStyleRefInput, options?: MutationOptions): ParagraphMutationResult;
+    clearStyle(input: ParagraphsClearStyleInput, options?: MutationOptions): ParagraphMutationResult;
+}
+export declare function executeParagraphsSetStyle(adapter: ParagraphsAdapter, input: ParagraphsSetStyleInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetStyleRef(adapter: ParagraphsAdapter, input: ParagraphsSetStyleRefInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearStyle(adapter: ParagraphsAdapter, input: ParagraphsClearStyleInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsResetDirectFormatting(adapter: ParagraphsAdapter, input: ParagraphsResetDirectFormattingInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetAlignment(adapter: ParagraphsAdapter, input: ParagraphsSetAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearAlignment(adapter: ParagraphsAdapter, input: ParagraphsClearAlignmentInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetIndentation(adapter: ParagraphsAdapter, input: ParagraphsSetIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearIndentation(adapter: ParagraphsAdapter, input: ParagraphsClearIndentationInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetSpacing(adapter: ParagraphsAdapter, input: ParagraphsSetSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearSpacing(adapter: ParagraphsAdapter, input: ParagraphsClearSpacingInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetKeepOptions(adapter: ParagraphsAdapter, input: ParagraphsSetKeepOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetOutlineLevel(adapter: ParagraphsAdapter, input: ParagraphsSetOutlineLevelInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetFlowOptions(adapter: ParagraphsAdapter, input: ParagraphsSetFlowOptionsInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetTabStop(adapter: ParagraphsAdapter, input: ParagraphsSetTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearTabStop(adapter: ParagraphsAdapter, input: ParagraphsClearTabStopInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearAllTabStops(adapter: ParagraphsAdapter, input: ParagraphsClearAllTabStopsInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetBorder(adapter: ParagraphsAdapter, input: ParagraphsSetBorderInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearBorder(adapter: ParagraphsAdapter, input: ParagraphsClearBorderInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetShading(adapter: ParagraphsAdapter, input: ParagraphsSetShadingInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearShading(adapter: ParagraphsAdapter, input: ParagraphsClearShadingInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetMarkRunProps(adapter: ParagraphsAdapter, input: ParagraphsSetMarkRunPropsInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetDirection(adapter: ParagraphsAdapter, input: ParagraphsSetDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsClearDirection(adapter: ParagraphsAdapter, input: ParagraphsClearDirectionInput, options?: MutationOptions): ParagraphMutationResult;
+export declare function executeParagraphsSetNumbering(adapter: ParagraphsAdapter, input: ParagraphsSetNumberingInput, options?: MutationOptions): ParagraphMutationResult;

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

@@ -0,0 +1,214 @@
+import { BlockNodeAddress } from '../types/base.js';
+import { ReceiptFailure, ReceiptInsert } from '../types/receipt.js';
+import { SDRunProps } from '../types/sd-props.js';
+export type ParagraphBlockType = 'paragraph' | 'heading' | 'listItem';
+export type ParagraphTarget = BlockNodeAddress & {
+    nodeType: ParagraphBlockType;
+};
+export interface MutationResolution {
+    target: ParagraphTarget;
+}
+export interface ParagraphMutationSuccess {
+    success: true;
+    target: ParagraphTarget;
+    resolution: MutationResolution;
+    /** Logical tracked-change entities created or revised by this mutation. */
+    trackedChangeRefs?: ReceiptInsert[];
+}
+export interface ParagraphMutationFailure {
+    success: false;
+    failure: ReceiptFailure;
+    resolution?: MutationResolution;
+}
+export type ParagraphMutationResult = ParagraphMutationSuccess | ParagraphMutationFailure;
+export declare const PARAGRAPH_ALIGNMENTS: readonly ["left", "center", "right", "justify"];
+export type ParagraphAlignment = (typeof PARAGRAPH_ALIGNMENTS)[number];
+export declare const TAB_STOP_ALIGNMENTS: readonly ["left", "center", "right", "decimal", "bar", "clear"];
+export type TabStopAlignment = (typeof TAB_STOP_ALIGNMENTS)[number];
+export declare const TAB_STOP_LEADERS: readonly ["none", "dot", "hyphen", "underscore", "heavy", "middleDot"];
+export type TabStopLeader = (typeof TAB_STOP_LEADERS)[number];
+export declare const BORDER_SIDES: readonly ["top", "bottom", "left", "right", "between", "bar"];
+export type BorderSide = (typeof BORDER_SIDES)[number];
+export declare const CLEAR_BORDER_SIDES: readonly ["top", "bottom", "left", "right", "between", "bar", "all"];
+export type ClearBorderSide = (typeof CLEAR_BORDER_SIDES)[number];
+export declare const LINE_RULES: readonly ["auto", "exact", "atLeast"];
+export type LineRule = (typeof LINE_RULES)[number];
+export type ParagraphSemanticStyleRole = {
+    kind: 'defaultParagraph';
+} | {
+    kind: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+} | {
+    kind: 'title';
+} | {
+    kind: 'subtitle';
+};
+/** paragraphs.setStyle — concrete catalog identity or semantic intent. */
+export type ParagraphsSetStyleInput = {
+    target: ParagraphTarget;
+} & ({
+    styleId: string;
+    role?: never;
+} | {
+    styleId?: never;
+    role: ParagraphSemanticStyleRole;
+});
+/** paragraphs.setStyleRef — changes only the pStyle reference, without clearing run formatting */
+export interface ParagraphsSetStyleRefInput {
+    target: ParagraphTarget;
+    styleId: string;
+}
+/** paragraphs.clearStyle */
+export interface ParagraphsClearStyleInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.resetDirectFormatting */
+export interface ParagraphsResetDirectFormattingInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.setAlignment */
+export interface ParagraphsSetAlignmentInput {
+    target: ParagraphTarget;
+    alignment: ParagraphAlignment;
+}
+/** paragraphs.clearAlignment */
+export interface ParagraphsClearAlignmentInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.setIndentation */
+export interface ParagraphsSetIndentationInput {
+    target: ParagraphTarget;
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+}
+/** paragraphs.clearIndentation */
+export interface ParagraphsClearIndentationInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.setSpacing */
+export interface ParagraphsSetSpacingInput {
+    target: ParagraphTarget;
+    before?: number;
+    after?: number;
+    line?: number;
+    lineRule?: LineRule;
+}
+/** paragraphs.clearSpacing */
+export interface ParagraphsClearSpacingInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.setKeepOptions */
+export interface ParagraphsSetKeepOptionsInput {
+    target: ParagraphTarget;
+    keepNext?: boolean;
+    keepLines?: boolean;
+    widowControl?: boolean;
+}
+/** paragraphs.setOutlineLevel */
+export interface ParagraphsSetOutlineLevelInput {
+    target: ParagraphTarget;
+    outlineLevel: number | null;
+}
+/** paragraphs.setFlowOptions */
+export interface ParagraphsSetFlowOptionsInput {
+    target: ParagraphTarget;
+    contextualSpacing?: boolean;
+    pageBreakBefore?: boolean;
+    suppressAutoHyphens?: boolean;
+    /** `w:autoSpaceDE` — auto-space between East-Asian and Latin text. */
+    autoSpaceDE?: boolean;
+    /** `w:autoSpaceDN` — auto-space between East-Asian text and numbers. */
+    autoSpaceDN?: boolean;
+    /** `w:adjustRightInd` — auto-adjust right indent for East-Asian grids. */
+    adjustRightInd?: boolean;
+    /** `w:snapToGrid` — snap the paragraph to the document grid. */
+    snapToGrid?: boolean;
+}
+/** paragraphs.setTabStop */
+export interface ParagraphsSetTabStopInput {
+    target: ParagraphTarget;
+    position: number;
+    alignment: TabStopAlignment;
+    leader?: TabStopLeader;
+}
+/** paragraphs.clearTabStop */
+export interface ParagraphsClearTabStopInput {
+    target: ParagraphTarget;
+    position: number;
+}
+/** paragraphs.clearAllTabStops */
+export interface ParagraphsClearAllTabStopsInput {
+    target: ParagraphTarget;
+}
+/** paragraphs.setBorder */
+export interface ParagraphsSetBorderInput {
+    target: ParagraphTarget;
+    side: BorderSide;
+    style: string;
+    color?: string;
+    size?: number;
+    space?: number;
+}
+/** paragraphs.clearBorder */
+export interface ParagraphsClearBorderInput {
+    target: ParagraphTarget;
+    side: ClearBorderSide;
+}
+/** paragraphs.setMarkRunProps */
+export interface ParagraphsSetMarkRunPropsInput {
+    target: ParagraphTarget;
+    /**
+     * Paragraph-mark run properties (`w:pPr/w:rPr`). Stored through the same
+     * internal shape used by structured paragraph materialization, so values
+     * round-trip through `paragraph.props.markRunProps`.
+     */
+    markRunProps: SDRunProps;
+}
+/** paragraphs.setShading */
+export interface ParagraphsSetShadingInput {
+    target: ParagraphTarget;
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}
+/** paragraphs.clearShading */
+export interface ParagraphsClearShadingInput {
+    target: ParagraphTarget;
+}
+export declare const PARAGRAPH_DIRECTIONS: readonly ["ltr", "rtl"];
+export type ParagraphDirection = (typeof PARAGRAPH_DIRECTIONS)[number];
+export declare const ALIGNMENT_POLICIES: readonly ["preserve", "matchDirection"];
+export type AlignmentPolicy = (typeof ALIGNMENT_POLICIES)[number];
+/** paragraphs.setDirection */
+export interface ParagraphsSetDirectionInput {
+    target: ParagraphTarget;
+    direction: ParagraphDirection;
+    alignmentPolicy?: AlignmentPolicy;
+}
+/** paragraphs.clearDirection */
+export interface ParagraphsClearDirectionInput {
+    target: ParagraphTarget;
+}
+/**
+ * format.paragraph.setNumbering
+ *
+ * Attaches numbering (`w:numPr`) to an existing paragraph-shaped block so a
+ * heading or paragraph can join an existing numbered sequence (the numbered-
+ * heading legal-clause pattern). The underlying paragraph node and its style are
+ * unchanged, though the doc-api block subtype may re-resolve afterward (a
+ * numbered plain paragraph becomes a listItem; a heading stays a heading).
+ * Numbering is a paragraph property (ECMA-376 §17.3.1.19), so this lives under
+ * `format.paragraph.*` rather than `lists.*`.
+ */
+export interface ParagraphsSetNumberingInput {
+    target: ParagraphTarget;
+    /**
+     * Positive numbering instance id (`w:numId`). numId 0 is the OOXML
+     * no-numbering sentinel and is rejected.
+     */
+    numId: number;
+    /** Numbering level (`w:ilvl`), 0-8. Defaults to 0 when omitted. */
+    level?: number;
+}

package/dist/document-api/src/permission-ranges/permission-ranges.d.ts

@@ -0,0 +1,15 @@
+import { MutationOptions } from '../write/write.js';
+import { PermissionRangesListInput, PermissionRangesListResult, PermissionRangesGetInput, PermissionRangeInfo, PermissionRangesCreateInput, PermissionRangesRemoveInput, PermissionRangesUpdatePrincipalInput, PermissionRangeMutationResult, PermissionRangeRemoveResult } from './permission-ranges.types.js';
+export interface PermissionRangesApi {
+    list(input?: PermissionRangesListInput): PermissionRangesListResult;
+    get(input: PermissionRangesGetInput): PermissionRangeInfo;
+    create(input: PermissionRangesCreateInput, options?: MutationOptions): PermissionRangeMutationResult;
+    remove(input: PermissionRangesRemoveInput, options?: MutationOptions): PermissionRangeRemoveResult;
+    updatePrincipal(input: PermissionRangesUpdatePrincipalInput, options?: MutationOptions): PermissionRangeMutationResult;
+}
+export type PermissionRangesAdapter = PermissionRangesApi;
+export declare function executePermissionRangesList(adapter: PermissionRangesAdapter, input?: PermissionRangesListInput): PermissionRangesListResult;
+export declare function executePermissionRangesGet(adapter: PermissionRangesAdapter, input: PermissionRangesGetInput): PermissionRangeInfo;
+export declare function executePermissionRangesCreate(adapter: PermissionRangesAdapter, input: PermissionRangesCreateInput, options?: MutationOptions): PermissionRangeMutationResult;
+export declare function executePermissionRangesRemove(adapter: PermissionRangesAdapter, input: PermissionRangesRemoveInput, options?: MutationOptions): PermissionRangeRemoveResult;
+export declare function executePermissionRangesUpdatePrincipal(adapter: PermissionRangesAdapter, input: PermissionRangesUpdatePrincipalInput, options?: MutationOptions): PermissionRangeMutationResult;

package/dist/document-api/src/permission-ranges/permission-ranges.types.d.ts

@@ -0,0 +1,49 @@
+import { Position } from '../types/base.js';
+import { SelectionTarget } from '../types/address.js';
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+export type PermissionRangePrincipal = {
+    kind: 'everyone';
+} | {
+    kind: 'editor';
+    id: string;
+};
+export type PermissionRangeKind = 'inline' | 'block';
+export interface PermissionRangeInfo {
+    id: string;
+    principal: PermissionRangePrincipal;
+    kind: PermissionRangeKind;
+    start: Position;
+    end: Position;
+}
+export interface PermissionRangesListInput {
+    limit?: number;
+    offset?: number;
+}
+export interface PermissionRangesGetInput {
+    id: string;
+}
+export interface PermissionRangesCreateInput {
+    /** Target range for the new permission markers. Uses the standard selection target model. */
+    target: SelectionTarget;
+    principal: PermissionRangePrincipal;
+    id?: string;
+}
+export interface PermissionRangesRemoveInput {
+    id: string;
+}
+export interface PermissionRangesUpdatePrincipalInput {
+    id: string;
+    principal: PermissionRangePrincipal;
+}
+export interface PermissionRangeMutationSuccess {
+    success: true;
+    range: PermissionRangeInfo;
+}
+export interface PermissionRangeRemoveSuccess {
+    success: true;
+    id: string;
+}
+export type PermissionRangeMutationResult = PermissionRangeMutationSuccess | AdapterMutationFailure;
+export type PermissionRangeRemoveResult = PermissionRangeRemoveSuccess | AdapterMutationFailure;
+export type PermissionRangesListResult = DiscoveryOutput<PermissionRangeInfo>;

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

@@ -0,0 +1,73 @@
+export interface PlanCaptureRefMarker {
+    kind: 'capture-ref';
+    captureKey: string;
+    /** Dotted lookup path into the captured value (supports array indices and `length`). */
+    path?: string;
+    /** Structural filter applied to an array at `path`; may nest further markers. */
+    where?: unknown;
+    /** Index into the (filtered) array; negative counts from the end. */
+    occurrence?: number;
+    /** Dotted lookup applied after `where`/`occurrence` selection. */
+    selectPath?: string;
+}
+export interface PlanProjectTextOffsetMarker {
+    kind: 'project-text-offset';
+    rawText: string;
+    rawOffset: number;
+    publicText: string | PlanCaptureRefMarker;
+}
+export interface PlanExecuteEntryExpect {
+    /** `false` marks the entry as an expected failure. */
+    success?: boolean;
+    failureCode?: string;
+    failureMessageIncludes?: string;
+    allowFailureMessageIncludes?: string;
+}
+export interface PlanExecuteEntry {
+    operationId: string;
+    input?: unknown;
+    options?: unknown;
+    captureAs?: string;
+    expect?: PlanExecuteEntryExpect;
+}
+export interface PlanExecuteInput {
+    entries: PlanExecuteEntry[];
+    /** Capture keys to return to the client, or '*' for the full capture map. */
+    captureReturns?: '*' | string[];
+}
+export type PlanEntryReceiptStatus = 'passed' | 'allowed-failure' | 'expected-failure';
+export interface PlanEntryReceipt {
+    entryIndex: number;
+    operationId: string;
+    status: PlanEntryReceiptStatus;
+    captureAs: string | null;
+    error?: string;
+}
+export interface PlanExecuteFailure {
+    entryIndex: number;
+    operationId: string;
+    message: string;
+}
+export interface PlanExecuteResult {
+    receipts: PlanEntryReceipt[];
+    captures: Record<string, unknown>;
+    failure?: PlanExecuteFailure;
+}
+export interface PlanApi<TExecuteResult = PlanExecuteResult> {
+    /**
+     * Execute a compiled run of operation entries with host-side capture
+     * resolution. Capture state persists across `plan.execute` calls within the
+     * same document session, so chunked plans share one capture space.
+     */
+    execute(input: PlanExecuteInput): TExecuteResult;
+}
+type DynamicInvoke = (operationId: string, input: unknown, options: unknown) => unknown;
+type AsyncDynamicInvoke = (operationId: string, input: unknown, options: unknown) => PromiseLike<unknown>;
+/**
+ * Build the `plan` namespace bound to one document session's dynamic dispatch.
+ * The capture map lives in this closure, so it persists across chunked
+ * `plan.execute` calls for the lifetime of the owning DocumentApi instance.
+ */
+export declare function createPlanApi(invoke: AsyncDynamicInvoke): PlanApi<Promise<PlanExecuteResult>>;
+export declare function createPlanApi(invoke: DynamicInvoke): PlanApi;
+export {};

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

@@ -0,0 +1,11 @@
+import { MutationOptions } from '../write/write.js';
+import { DocumentProtectionState, ProtectionGetInput, SetEditingRestrictionInput, ClearEditingRestrictionInput, ProtectionMutationResult } from './protection.types.js';
+export interface ProtectionApi {
+    get(input?: ProtectionGetInput): DocumentProtectionState;
+    setEditingRestriction(input: SetEditingRestrictionInput, options?: MutationOptions): ProtectionMutationResult;
+    clearEditingRestriction(input?: ClearEditingRestrictionInput, options?: MutationOptions): ProtectionMutationResult;
+}
+export type ProtectionAdapter = ProtectionApi;
+export declare function executeProtectionGet(adapter: ProtectionAdapter, _input?: ProtectionGetInput): DocumentProtectionState;
+export declare function executeSetEditingRestriction(adapter: ProtectionAdapter, input: SetEditingRestrictionInput, options?: MutationOptions): ProtectionMutationResult;
+export declare function executeClearEditingRestriction(adapter: ProtectionAdapter, _input?: ClearEditingRestrictionInput, options?: MutationOptions): ProtectionMutationResult;