superdoc 2.2.0 → 2.3.0

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

@@ -0,0 +1,47 @@
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+/** Word document protection modes from `w:edit` attribute values. */
+export type EditingRestrictionMode = 'none' | 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
+export interface EditingRestrictionState {
+    /** Active protection mode. `'none'` when `w:documentProtection` is absent. */
+    mode: EditingRestrictionMode;
+    /** Whether OOXML enforcement is on (`w:enforcement="1"`). */
+    enforced: boolean;
+    /**
+     * Whether the current engine version actively enforces this restriction
+     * in editing behavior. Engine-version-dependent: may change across
+     * releases as support for additional modes is added.
+     */
+    runtimeEnforced: boolean;
+    /** Whether verifier/hash fields are present (password was set). */
+    passwordProtected: boolean;
+    /** Whether `w:formatting="1"` restricts formatting changes. */
+    formattingRestricted: boolean;
+}
+export interface WriteProtectionState {
+    /** Whether `w:writeProtection` is present and active. */
+    enabled: boolean;
+    /** Whether verifier/hash fields are present on `w:writeProtection`. */
+    passwordProtected: boolean;
+}
+export interface DocumentProtectionState {
+    editingRestriction: EditingRestrictionState;
+    writeProtection: WriteProtectionState;
+    readOnlyRecommended: boolean;
+}
+export declare const DEFAULT_PROTECTION_STATE: DocumentProtectionState;
+/** Input for `protection.get`: empty object, no parameters needed. */
+export type ProtectionGetInput = Record<string, never> | undefined;
+/** Input for `protection.setEditingRestriction`. */
+export interface SetEditingRestrictionInput {
+    /** Only `'readOnly'` is accepted in v1. */
+    mode: 'readOnly';
+    /** Whether to restrict formatting changes. Defaults to false. */
+    formattingRestricted?: boolean;
+}
+/** Input for `protection.clearEditingRestriction`. */
+export type ClearEditingRestrictionInput = Record<string, never> | undefined;
+export interface ProtectionMutationSuccess {
+    success: true;
+    state: DocumentProtectionState;
+}
+export type ProtectionMutationResult = ProtectionMutationSuccess | AdapterMutationFailure;

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

@@ -0,0 +1,2 @@
+export type { RangeAnchor, DocumentEdgeAnchor, PointAnchor, RefBoundaryAnchor, ResolveRangeInput, ResolveRangeOutput, RangeBlockPreview, RangePreview, RangeResolverAdapter, ScrollIntoViewInput, ScrollIntoViewOutput, } from './ranges.types.js';
+export { executeResolveRange } from './resolve.js';

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

@@ -0,0 +1,121 @@
+import { SelectionTarget, SelectionPoint, TextAddress, TextTarget, EntityAddress } from '../types/address.js';
+import { BlockNodeType } from '../types/base.js';
+import { StoryLocator } from '../types/story.types.js';
+/** Anchor at the absolute start or end of the document body. */
+export type DocumentEdgeAnchor = {
+    kind: 'document';
+    edge: 'start' | 'end';
+};
+/** Anchor at an explicit selection point (text offset or node boundary). */
+export type PointAnchor = {
+    kind: 'point';
+    point: SelectionPoint;
+};
+/** Anchor derived from an existing ref's start or end boundary. */
+export type RefBoundaryAnchor = {
+    kind: 'ref';
+    ref: string;
+    boundary: 'start' | 'end';
+};
+/**
+ * A range endpoint: one of three deterministic anchor forms.
+ *
+ * - `document`: absolute document boundary (start/end of body)
+ * - `point`: explicit `SelectionPoint` (text offset or node edge)
+ * - `ref`: boundary of an existing ref from `query.match` or `ranges.resolve`
+ */
+export type RangeAnchor = DocumentEdgeAnchor | PointAnchor | RefBoundaryAnchor;
+export interface ResolveRangeInput {
+    /** Start endpoint of the range. */
+    start: RangeAnchor;
+    /** End endpoint of the range. */
+    end: RangeAnchor;
+    /** Optional expected revision for consistency checking. */
+    expectedRevision?: string;
+    /** Story to resolve the range against. Defaults to body when absent. */
+    in?: StoryLocator;
+}
+/** Per-block preview metadata within the resolved range. */
+export interface RangeBlockPreview {
+    nodeId: string;
+    nodeType: BlockNodeType;
+    textPreview: string;
+}
+/** Preview metadata for the resolved range. */
+export interface RangePreview {
+    /** Concatenated text content across the range (truncated if large). */
+    text: string;
+    /** Whether the text was truncated. */
+    truncated: boolean;
+    /** Per-block preview entries in document order. */
+    blocks: RangeBlockPreview[];
+}
+export interface ResolveRangeOutput {
+    /** The document revision at which the range was evaluated. */
+    evaluatedRevision: string;
+    /** Handle metadata for the resolved range. */
+    handle: {
+        /**
+         * Text ref encoding the resolved range when current mutation consumers can
+         * use it as a target for delete, replace, or format operations.
+         *
+         * `null` when the resolved range is not mutation-ready as a ref. Callers
+         * must check `handle.ref !== null` and/or `coversFullTarget` before passing
+         * the handle to mutation operations.
+         */
+        ref: string | null;
+        refStability: 'ephemeral';
+        /**
+         * Whether `handle.ref` faithfully covers the exact same range as `target`.
+         *
+         * `true`: the ref encodes the full range; using it for delete/replace/format
+         * produces the same result as operating directly on the target.
+         *
+         * `false`: the resolved range is not currently exposed as a mutation-ready
+         * ref. `handle.ref` may be `null`; callers that need to mutate the range
+         * should use another supported target form or re-resolve a narrower range.
+         */
+        coversFullTarget: boolean;
+    };
+    /** Transparent selection target for inspection, logging, and debugging. */
+    target: SelectionTarget;
+    /** Preview metadata describing the content within the range. */
+    preview: RangePreview;
+}
+/**
+ * Adapter that the document engine implements for `ranges.resolve`.
+ *
+ * The document-api layer handles validation; the adapter performs the
+ * actual ProseMirror-level resolution and ref encoding.
+ */
+export interface RangeResolverAdapter {
+    resolve(input: ResolveRangeInput): ResolveRangeOutput;
+}
+/**
+ * Input for `ui.viewport.scrollIntoView`: scrolls the editor
+ * viewport so the given target is visible. Handles paginated,
+ * virtualized layouts by mounting the target page if it isn't yet in
+ * the DOM.
+ */
+export interface ScrollIntoViewInput {
+    /**
+     * The target to scroll to. Accepts:
+     * - {@link TextAddress}: single-block text range
+     * - {@link TextTarget}: multi-segment text target
+     * - {@link EntityAddress}: reference to a comment or tracked change by id
+     *   (e.g. `{ kind: 'entity', entityType: 'trackedChange', entityId: 'tc_123' }`)
+     */
+    target: TextAddress | TextTarget | EntityAddress;
+    /** Alignment within the viewport. Defaults to `'center'`. */
+    block?: 'start' | 'center' | 'end' | 'nearest';
+    /** Scroll behavior. Defaults to `'smooth'`. */
+    behavior?: 'auto' | 'smooth';
+}
+/**
+ * Result of `ui.viewport.scrollIntoView`. `success: false` when the
+ * target couldn't be resolved or a page failed to mount within the
+ * navigation timeout.
+ */
+export interface ScrollIntoViewOutput {
+    success: boolean;
+}

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

@@ -0,0 +1,2 @@
+import { ResolveRangeInput, ResolveRangeOutput, RangeResolverAdapter } from './ranges.types.js';
+export declare function executeResolveRange(adapter: RangeResolverAdapter, input: ResolveRangeInput): ResolveRangeOutput;

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

@@ -0,0 +1,30 @@
+import { TextMutationReceipt, TextMutationRange, ReceiptEffects, SDMutationReceipt, SelectionTarget, MutationResolutionTarget } from './types/index.js';
+/**
+ * Wraps a TextMutationReceipt into an SDMutationReceipt at the public API boundary.
+ *
+ * - Success/failure semantics are preserved.
+ * - Resolution is passed through directly (both use TextAddress).
+ * - Failure codes from the text pipeline are mapped to SDErrorCode.
+ */
+export declare function textReceiptToSDReceipt(receipt: TextMutationReceipt): SDMutationReceipt;
+/** Parameters for building a structural mutation receipt. */
+export interface StructuralReceiptParams {
+    target: MutationResolutionTarget;
+    range: TextMutationRange;
+    selectionTarget?: SelectionTarget;
+    /** Post-mutation created-content spans (inserted blocks / text). */
+    effects?: ReceiptEffects;
+}
+/**
+ * Builds an SDMutationReceipt for structural (block-level) mutations.
+ *
+ * Unlike {@link textReceiptToSDReceipt} which converts from the internal
+ * text pipeline, this constructs a receipt directly: preserving the
+ * original `BlockNodeAddress` target instead of normalizing it to a
+ * synthetic `TextAddress`.
+ */
+export declare function buildStructuralReceipt(success: true, params: StructuralReceiptParams): SDMutationReceipt;
+export declare function buildStructuralReceipt(success: false, params: StructuralReceiptParams, failure: {
+    code: string;
+    message: string;
+}): SDMutationReceipt;

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

@@ -0,0 +1,24 @@
+import { MutationOptions } from '../types/mutation-plan.types.js';
+import { SelectionTarget, TargetLocator } from '../types/address.js';
+import { SDMutationReceipt } from '../types/sd-contract.js';
+import { SDReplaceInput } from '../types/structural-input.js';
+import { StoryLocator } from '../types/story.types.js';
+import { SelectionMutationAdapter } from '../selection-mutation.js';
+import { WriteAdapter } from '../write/write.js';
+/** Text replacement input: uses SelectionTarget / ref. */
+export type TextReplaceInput = TargetLocator & {
+    target?: SelectionTarget;
+    ref?: string;
+    text: string;
+    /** Target a specific document story (body, header, footer, footnote, endnote). */
+    in?: StoryLocator;
+};
+/**
+ * Input payload for the `doc.replace` operation.
+ *
+ * Discrimination: presence of `content` (structural) vs `text` (text replacement).
+ */
+export type ReplaceInput = TextReplaceInput | SDReplaceInput;
+/** Returns true when the input uses the structural SDFragment shape. */
+export declare function isStructuralReplaceInput(input: ReplaceInput): input is SDReplaceInput;
+export declare function executeReplace(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: ReplaceInput, options?: MutationOptions): SDMutationReceipt;

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

@@ -0,0 +1,42 @@
+import { MutationOptions } from '../write/write.js';
+import { DocumentMutationResult, SectionMutationResult, SectionsClearHeaderFooterRefInput, SectionsClearPageBordersInput, SectionsGetInput, SectionsListQuery, SectionsListResult, SectionsSetBreakTypeInput, SectionsSetColumnsInput, SectionsSetHeaderFooterMarginsInput, SectionsSetHeaderFooterRefInput, SectionsSetLineNumberingInput, SectionsSetLinkToPreviousInput, SectionsSetOddEvenHeadersFootersInput, SectionsSetPageBordersInput, SectionsSetPageMarginsInput, SectionsSetPageNumberingInput, SectionsSetPageSetupInput, SectionsSetSectionDirectionInput, SectionsSetTitlePageInput, SectionsSetVerticalAlignInput, SectionInfo } from './sections.types.js';
+export type { DocumentMutationResult, SectionAddress, SectionMutationResult, SectionBreakType, SectionHeaderFooterKind, SectionHeaderFooterVariant, SectionPageNumberingChapterSeparator, SectionsClearHeaderFooterRefInput, SectionsClearPageBordersInput, SectionsGetInput, SectionsListQuery, SectionsListResult, SectionsSetBreakTypeInput, SectionsSetColumnsInput, SectionsSetHeaderFooterMarginsInput, SectionsSetHeaderFooterRefInput, SectionsSetLineNumberingInput, SectionsSetLinkToPreviousInput, SectionsSetOddEvenHeadersFootersInput, SectionsSetPageBordersInput, SectionsSetPageMarginsInput, SectionsSetPageNumberingInput, SectionsSetPageSetupInput, SectionsSetSectionDirectionInput, SectionsSetTitlePageInput, SectionsSetVerticalAlignInput, SectionInfo, SectionTargetInput, } from './sections.types.js';
+export interface SectionsAdapter {
+    list(query?: SectionsListQuery): SectionsListResult;
+    get(input: SectionsGetInput): SectionInfo;
+    setBreakType(input: SectionsSetBreakTypeInput, options?: MutationOptions): SectionMutationResult;
+    setPageMargins(input: SectionsSetPageMarginsInput, options?: MutationOptions): SectionMutationResult;
+    setHeaderFooterMargins(input: SectionsSetHeaderFooterMarginsInput, options?: MutationOptions): SectionMutationResult;
+    setPageSetup(input: SectionsSetPageSetupInput, options?: MutationOptions): SectionMutationResult;
+    setColumns(input: SectionsSetColumnsInput, options?: MutationOptions): SectionMutationResult;
+    setLineNumbering(input: SectionsSetLineNumberingInput, options?: MutationOptions): SectionMutationResult;
+    setPageNumbering(input: SectionsSetPageNumberingInput, options?: MutationOptions): SectionMutationResult;
+    setTitlePage(input: SectionsSetTitlePageInput, options?: MutationOptions): SectionMutationResult;
+    setOddEvenHeadersFooters(input: SectionsSetOddEvenHeadersFootersInput, options?: MutationOptions): DocumentMutationResult;
+    setVerticalAlign(input: SectionsSetVerticalAlignInput, options?: MutationOptions): SectionMutationResult;
+    setSectionDirection(input: SectionsSetSectionDirectionInput, options?: MutationOptions): SectionMutationResult;
+    setHeaderFooterRef(input: SectionsSetHeaderFooterRefInput, options?: MutationOptions): SectionMutationResult;
+    clearHeaderFooterRef(input: SectionsClearHeaderFooterRefInput, options?: MutationOptions): SectionMutationResult;
+    setLinkToPrevious(input: SectionsSetLinkToPreviousInput, options?: MutationOptions): SectionMutationResult;
+    setPageBorders(input: SectionsSetPageBordersInput, options?: MutationOptions): SectionMutationResult;
+    clearPageBorders(input: SectionsClearPageBordersInput, options?: MutationOptions): SectionMutationResult;
+}
+export type SectionsApi = SectionsAdapter;
+export declare function executeSectionsList(adapter: SectionsAdapter, query?: SectionsListQuery): SectionsListResult;
+export declare function executeSectionsGet(adapter: SectionsAdapter, input: SectionsGetInput): SectionInfo;
+export declare function executeSectionsSetBreakType(adapter: SectionsAdapter, input: SectionsSetBreakTypeInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetPageMargins(adapter: SectionsAdapter, input: SectionsSetPageMarginsInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetHeaderFooterMargins(adapter: SectionsAdapter, input: SectionsSetHeaderFooterMarginsInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetPageSetup(adapter: SectionsAdapter, input: SectionsSetPageSetupInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetColumns(adapter: SectionsAdapter, input: SectionsSetColumnsInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetLineNumbering(adapter: SectionsAdapter, input: SectionsSetLineNumberingInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetPageNumbering(adapter: SectionsAdapter, input: SectionsSetPageNumberingInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetTitlePage(adapter: SectionsAdapter, input: SectionsSetTitlePageInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetOddEvenHeadersFooters(adapter: SectionsAdapter, input: SectionsSetOddEvenHeadersFootersInput, options?: MutationOptions): DocumentMutationResult;
+export declare function executeSectionsSetVerticalAlign(adapter: SectionsAdapter, input: SectionsSetVerticalAlignInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetSectionDirection(adapter: SectionsAdapter, input: SectionsSetSectionDirectionInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetHeaderFooterRef(adapter: SectionsAdapter, input: SectionsSetHeaderFooterRefInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsClearHeaderFooterRef(adapter: SectionsAdapter, input: SectionsClearHeaderFooterRefInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetLinkToPrevious(adapter: SectionsAdapter, input: SectionsSetLinkToPreviousInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsSetPageBorders(adapter: SectionsAdapter, input: SectionsSetPageBordersInput, options?: MutationOptions): SectionMutationResult;
+export declare function executeSectionsClearPageBorders(adapter: SectionsAdapter, input: SectionsClearPageBordersInput, options?: MutationOptions): SectionMutationResult;

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

@@ -0,0 +1,236 @@
+import { BlockNodeAddress, ReceiptFailure } from '../types/index.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+export type SectionAddress = {
+    kind: 'section';
+    sectionId: string;
+};
+export type SectionTargetInput = {
+    target: SectionAddress;
+};
+export type SectionBreakType = 'continuous' | 'nextPage' | 'evenPage' | 'oddPage';
+export type SectionHeaderFooterKind = 'header' | 'footer';
+/**
+ * Word models odd-page variants via the default header/footer reference when
+ * even/odd mode is enabled, so the API keeps this enum aligned with OOXML refs.
+ */
+export type SectionHeaderFooterVariant = 'default' | 'first' | 'even';
+export type SectionOrientation = 'portrait' | 'landscape';
+export type SectionVerticalAlign = 'top' | 'center' | 'bottom' | 'both';
+export type SectionDirection = 'ltr' | 'rtl';
+export type SectionLineNumberRestart = 'continuous' | 'newPage' | 'newSection';
+export type SectionPageNumberingFormat = 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman' | 'numberInDash';
+export type SectionPageNumberingChapterSeparator = 'hyphen' | 'period' | 'colon' | 'emDash' | 'enDash';
+export interface SectionPageMargins {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    gutter?: number;
+}
+export interface SectionHeaderFooterMargins {
+    header?: number;
+    footer?: number;
+}
+export interface SectionPageSetup {
+    width?: number;
+    height?: number;
+    orientation?: SectionOrientation;
+    paperSize?: string;
+}
+export interface SectionColumns {
+    count?: number;
+    gap?: number;
+    equalWidth?: boolean;
+}
+export interface SectionLineNumbering {
+    enabled: boolean;
+    countBy?: number;
+    start?: number;
+    distance?: number;
+    restart?: SectionLineNumberRestart;
+}
+export interface SectionPageNumbering {
+    start?: number;
+    format?: SectionPageNumberingFormat;
+    chapterStyle?: number;
+    chapterSeparator?: SectionPageNumberingChapterSeparator;
+}
+export interface SectionHeaderFooterRefs {
+    default?: string;
+    first?: string;
+    even?: string;
+}
+export interface SectionBorderSpec {
+    style?: string;
+    size?: number;
+    space?: number;
+    color?: string;
+    shadow?: boolean;
+    frame?: boolean;
+}
+export interface SectionPageBorders {
+    display?: 'allPages' | 'firstPage' | 'notFirstPage';
+    offsetFrom?: 'page' | 'text';
+    zOrder?: 'front' | 'back';
+    top?: SectionBorderSpec;
+    right?: SectionBorderSpec;
+    bottom?: SectionBorderSpec;
+    left?: SectionBorderSpec;
+}
+export interface SectionRangeDomain {
+    startParagraphIndex: number;
+    endParagraphIndex: number;
+}
+export interface SectionDomain {
+    address: SectionAddress;
+    index: number;
+    range: SectionRangeDomain;
+    breakType?: SectionBreakType;
+    pageSetup?: SectionPageSetup;
+    margins?: SectionPageMargins;
+    headerFooterMargins?: SectionHeaderFooterMargins;
+    columns?: SectionColumns;
+    lineNumbering?: SectionLineNumbering;
+    pageNumbering?: SectionPageNumbering;
+    titlePage?: boolean;
+    oddEvenHeadersFooters?: boolean;
+    verticalAlign?: SectionVerticalAlign;
+    sectionDirection?: SectionDirection;
+    headerRefs?: SectionHeaderFooterRefs;
+    footerRefs?: SectionHeaderFooterRefs;
+    pageBorders?: SectionPageBorders;
+}
+export type SectionInfo = SectionDomain;
+export interface SectionsListQuery {
+    limit?: number;
+    offset?: number;
+}
+export interface SectionsGetInput {
+    address: SectionAddress;
+}
+export type SectionsListResult = DiscoveryOutput<SectionDomain>;
+export interface SectionMutationSuccessResult {
+    success: true;
+    section: SectionAddress;
+}
+export interface SectionMutationFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type SectionMutationResult = SectionMutationSuccessResult | SectionMutationFailureResult;
+/**
+ * Mutation receipt for document-scoped section settings operations that do not
+ * target a specific section address.
+ */
+export interface DocumentMutationSuccessResult {
+    success: true;
+}
+export type DocumentMutationResult = DocumentMutationSuccessResult | SectionMutationFailureResult;
+export interface CreateSectionBreakSuccessResult {
+    success: true;
+    section: SectionAddress;
+    /**
+     * Present only when the break is represented as a dedicated paragraph.
+     * Attached breaks omit this field because the boundary is carried by the
+     * preceding paragraph's sectPr rather than a new blank block.
+     */
+    breakParagraph?: BlockNodeAddress;
+}
+export interface CreateSectionBreakFailureResult {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type CreateSectionBreakResult = CreateSectionBreakSuccessResult | CreateSectionBreakFailureResult;
+export type SectionBreakCreateLocation = {
+    kind: 'documentStart';
+} | {
+    kind: 'documentEnd';
+} | {
+    kind: 'before';
+    target: BlockNodeAddress;
+} | {
+    kind: 'after';
+    target: BlockNodeAddress;
+};
+export type SectionBreakRepresentation = 'asNewParagraph' | 'attachToPreviousParagraph';
+export interface CreateSectionBreakInput {
+    at?: SectionBreakCreateLocation;
+    breakType?: SectionBreakType;
+    pageMargins?: SectionPageMargins;
+    headerFooterMargins?: SectionHeaderFooterMargins;
+    /**
+     * Controls how the section break materializes in OOXML.
+     *
+     * - `asNewParagraph` (default): emit a dedicated carrier `<w:p><w:pPr><w:sectPr/></w:pPr></w:p>` just before the existing final body section.
+     * - `attachToPreviousParagraph`: inline the new `<w:sectPr>` into the previous paragraph's `<w:pPr>` so that paragraph becomes the last paragraph of the new section.
+     */
+    representation?: SectionBreakRepresentation;
+}
+export interface SectionsSetBreakTypeInput extends SectionTargetInput {
+    breakType: SectionBreakType;
+}
+export interface SectionsSetPageMarginsInput extends SectionTargetInput {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    gutter?: number;
+}
+export interface SectionsSetHeaderFooterMarginsInput extends SectionTargetInput {
+    header?: number;
+    footer?: number;
+}
+export interface SectionsSetPageSetupInput extends SectionTargetInput {
+    width?: number;
+    height?: number;
+    orientation?: SectionOrientation;
+    paperSize?: string;
+}
+export interface SectionsSetColumnsInput extends SectionTargetInput {
+    count?: number;
+    gap?: number;
+    equalWidth?: boolean;
+}
+export interface SectionsSetLineNumberingInput extends SectionTargetInput {
+    enabled: boolean;
+    countBy?: number;
+    start?: number;
+    distance?: number;
+    restart?: SectionLineNumberRestart;
+}
+export interface SectionsSetPageNumberingInput extends SectionTargetInput {
+    start?: number;
+    format?: SectionPageNumberingFormat;
+    chapterStyle?: number;
+    chapterSeparator?: SectionPageNumberingChapterSeparator;
+}
+export interface SectionsSetTitlePageInput extends SectionTargetInput {
+    enabled: boolean;
+}
+export interface SectionsSetOddEvenHeadersFootersInput {
+    enabled: boolean;
+}
+export interface SectionsSetVerticalAlignInput extends SectionTargetInput {
+    value: SectionVerticalAlign;
+}
+export interface SectionsSetSectionDirectionInput extends SectionTargetInput {
+    direction: SectionDirection;
+}
+export interface SectionsSetHeaderFooterRefInput extends SectionTargetInput {
+    kind: SectionHeaderFooterKind;
+    variant: SectionHeaderFooterVariant;
+    refId: string;
+}
+export interface SectionsClearHeaderFooterRefInput extends SectionTargetInput {
+    kind: SectionHeaderFooterKind;
+    variant: SectionHeaderFooterVariant;
+}
+export interface SectionsSetLinkToPreviousInput extends SectionTargetInput {
+    kind: SectionHeaderFooterKind;
+    variant: SectionHeaderFooterVariant;
+    linked: boolean;
+}
+export interface SectionsSetPageBordersInput extends SectionTargetInput {
+    borders: SectionPageBorders;
+}
+export type SectionsClearPageBordersInput = SectionTargetInput;

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

@@ -0,0 +1,23 @@
+import { SelectionCurrentInput, SelectionInfo } from './selection.types.js';
+export type { SelectionCurrentInput, SelectionInfo } from './selection.types.js';
+/**
+ * Engine-specific adapter for the selection API.
+ */
+export interface SelectionAdapter {
+    /** Read the editor's current selection. */
+    current(input: SelectionCurrentInput): SelectionInfo;
+}
+/**
+ * Public selection API exposed on `editor.doc.selection`.
+ */
+export interface SelectionApi {
+    /**
+     * Read the editor's current selection as a portable {@link SelectionInfo}.
+     *
+     * Use to drive custom UIs (toolbars, sidebars, popovers) without
+     * reaching into ProseMirror internals. For comment-target construction,
+     * pass the resulting `target` directly to `comments.create`.
+     */
+    current(input?: SelectionCurrentInput): SelectionInfo;
+}
+export declare function executeSelectionCurrent(adapter: SelectionAdapter, input?: SelectionCurrentInput): SelectionInfo;

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

@@ -0,0 +1,85 @@
+import { SelectionTarget, TextTarget } from '../types/address.js';
+/**
+ * Input for `selection.current`: reads the editor's current selection.
+ *
+ * Purely a read operation; does not modify the document. `selection.current`
+ * always reflects the live editor selection in whichever story currently
+ * holds focus (body, header, footer). Story scoping is not a query
+ * parameter here; if a consumer needs a read of a specific story, focus
+ * must be set there first.
+ */
+export interface SelectionCurrentInput {
+    /**
+     * When `true`, the `text` field of `SelectionInfo` is populated with the
+     * quoted text of the selection (useful for comment composers and search).
+     * Omit or set `false` to skip text extraction for performance.
+     */
+    includeText?: boolean;
+}
+/**
+ * Canonical shape of the editor's current selection, projected into the
+ * Document API's text-address model. This is the primitive consumers use
+ * to build custom comments UIs, floating toolbars, mention popovers, etc.
+ *
+ * Unlike PM's `Selection` (positional and private), `SelectionInfo` is
+ * portable across rendering backends and stable across layout changes.
+ */
+export interface SelectionInfo {
+    /** True when the selection is empty (cursor only, no range). */
+    empty: boolean;
+    /**
+     * The selection anchored to text content, or `null` when the selection
+     * is not in text (empty document, node selection, no focus, etc.).
+     *
+     * `TextTarget.segments` may contain multiple entries when the selection
+     * spans multiple blocks. Pass the whole target to `comments.create` -
+     * it resolves multi-segment targets to a single PM range spanning the
+     * full selection.
+     */
+    target: TextTarget | null;
+    /**
+     * Explicit selection envelope for the current live selection, or `null` when
+     * the runtime cannot project one truthfully.
+     *
+     * Unlike {@link target}, this preserves caret/range endpoints in the public
+     * selection-target model the write APIs consume directly.
+     */
+    selectionTarget?: SelectionTarget | null;
+    /**
+     * Active marks at the caret or across the selection. Names are
+     * ProseMirror mark type names (e.g. `'bold'`, `'italic'`, `'link'`).
+     * Use these to drive toolbar active-state rendering.
+     *
+     * `activeMarks` uses **intersection** semantics: a name is present
+     * only when every character in the selection carries that mark. This
+     * matches Word/Google Docs toolbar behavior.
+     */
+    activeMarks: string[];
+    /**
+     * Comment IDs whose `commentMark` overlaps any part of the current
+     * selection (or covers the caret when empty). Use to drive a
+     * floating "comment here" hint, highlight the active sidebar card,
+     * or disable a "new comment" button when the selection already
+     * covers an existing comment.
+     *
+     * **Union** semantics: an id is present when *any* character in the
+     * selection carries that comment, not when every character does.
+     * Multiple overlapping comments produce multiple ids.
+     */
+    activeCommentIds: string[];
+    /**
+     * Tracked-change IDs whose `trackInsert` / `trackDelete` /
+     * `trackFormat` mark overlaps any part of the current selection.
+     * Same union semantics as {@link activeCommentIds}.
+     *
+     * Use to drive review-sidebar highlighting and next/previous
+     * navigation without resolving every change individually via
+     * `trackChanges.list()`.
+     */
+    activeChangeIds: string[];
+    /**
+     * Quoted text of the selection. Populated only when `includeText: true`.
+     * Undefined otherwise.
+     */
+    text?: string;
+}

package/dist/document-api/src/selection-mutation.d.ts

@@ -0,0 +1,46 @@
+import { SelectionTarget, DeleteBehavior, TargetLocator } from './types/address.js';
+import { TextMutationReceipt } from './types/receipt.js';
+import { MutationOptions } from './types/mutation-plan.types.js';
+import { InlineRunPatch } from './format/inline-run-patch.js';
+import { StoryLocator } from './types/story.types.js';
+export type SelectionDeleteRequest = TargetLocator & {
+    kind: 'delete';
+    target?: SelectionTarget;
+    ref?: string;
+    behavior: DeleteBehavior;
+    /** Story locator threaded from the operation input's `in` field. */
+    in?: StoryLocator;
+};
+export type SelectionReplaceRequest = TargetLocator & {
+    kind: 'replace';
+    target?: SelectionTarget;
+    ref?: string;
+    text: string;
+    /** Story locator threaded from the operation input's `in` field. */
+    in?: StoryLocator;
+};
+export type SelectionInsertRequest = TargetLocator & {
+    kind: 'insert';
+    target?: SelectionTarget;
+    ref?: string;
+    text: string;
+    /** Story locator threaded from the operation input's `in` field. */
+    in?: StoryLocator;
+};
+export type SelectionFormatRequest = TargetLocator & {
+    kind: 'format';
+    target?: SelectionTarget;
+    ref?: string;
+    inline: InlineRunPatch;
+    /** Story locator threaded from the operation input's `in` field. */
+    in?: StoryLocator;
+};
+export type SelectionMutationRequest = SelectionDeleteRequest | SelectionReplaceRequest | SelectionInsertRequest | SelectionFormatRequest;
+/**
+ * Adapter that the plan engine implements for selection-based mutations.
+ * Delete, replace-text, insert-with-locator, and format.apply go through this
+ * single interface.
+ */
+export interface SelectionMutationAdapter {
+    execute(request: SelectionMutationRequest, options?: MutationOptions): TextMutationReceipt;
+}