superdoc 2.2.0 → 2.3.0

package/dist/document-api/src/contract/reference-aliases.d.ts

@@ -0,0 +1,19 @@
+import { OperationId } from './types.js';
+import { ReferenceGroupKey } from './operation-definitions.js';
+/**
+ * Convenience API aliases that are intentionally not canonical contract operations.
+ *
+ * These aliases exist on the runtime `DocumentApi` surface, but each one routes
+ * to a canonical operation ID for schema/contract purposes.
+ */
+export interface ReferenceAliasDefinition {
+    /** Public runtime member path (for example, `format.bold`). */
+    memberPath: string;
+    /** Canonical operation ID the alias delegates to. */
+    canonicalOperationId: OperationId;
+    /** Reference namespace where this alias should be listed. */
+    referenceGroup: ReferenceGroupKey;
+    /** Short customer-facing description used in generated docs. */
+    description: string;
+}
+export declare const REFERENCE_OPERATION_ALIASES: readonly ReferenceAliasDefinition[];

package/dist/document-api/src/contract/reference-doc-map.d.ts

@@ -0,0 +1,12 @@
+import { ReferenceGroupKey } from './operation-definitions.js';
+import { OperationId } from './types.js';
+export type { ReferenceGroupKey } from './operation-definitions.js';
+export interface ReferenceOperationGroupDefinition {
+    key: ReferenceGroupKey;
+    title: string;
+    description: string;
+    pagePath: string;
+    operations: readonly OperationId[];
+}
+export declare const OPERATION_REFERENCE_DOC_PATH_MAP: Record<OperationId, string>;
+export declare const REFERENCE_OPERATION_GROUPS: readonly ReferenceOperationGroupDefinition[];

package/dist/document-api/src/contract/schemas.d.ts

@@ -0,0 +1,35 @@
+import { OperationId } from './types.js';
+type JsonSchema = Record<string, unknown>;
+/** JSON Schema descriptors for a single operation's input, output, and result variants. */
+export interface OperationSchemaSet {
+    /** Schema describing the operation's accepted input payload. */
+    input: JsonSchema;
+    /** Schema describing the full output (success | failure union for mutations). */
+    output: JsonSchema;
+    /** Schema describing only the success branch of a mutation result. */
+    success?: JsonSchema;
+    /** Schema describing only the failure branch of a mutation result. */
+    failure?: JsonSchema;
+}
+/** Top-level contract envelope containing versioned operation schemas. */
+export interface InternalContractSchemas {
+    /** JSON Schema dialect URI (e.g. `https://json-schema.org/draft/2020-12/schema`). */
+    $schema: string;
+    /** Semantic version of the document-api contract these schemas describe. */
+    contractVersion: string;
+    /** Shared schema definitions referenced by `$ref` in operation schemas. */
+    $defs?: Record<string, JsonSchema>;
+    /** Per-operation schema sets keyed by {@link OperationId}. */
+    operations: Record<OperationId, OperationSchemaSet>;
+}
+/**
+ * Builds the complete set of JSON Schema definitions for every document-api operation.
+ *
+ * Validates that every {@link OperationId} has a corresponding schema entry and
+ * that no unknown operations are present.
+ *
+ * @returns A versioned {@link InternalContractSchemas} envelope.
+ * @throws {Error} If any operation is missing a schema or an unknown operation is found.
+ */
+export declare function buildInternalContractSchemas(): InternalContractSchemas;
+export {};

package/dist/document-api/src/contract/step-op-catalog.d.ts

@@ -0,0 +1,26 @@
+import { OperationId } from './types.js';
+export type StepOpDomain = 'assert' | 'text' | 'format' | 'create' | 'tables' | 'structural' | 'internal';
+export type StepOpSurface = 'public' | 'internal';
+export interface StepOpCatalogEntry<OpId extends string = string, Domain extends StepOpDomain = StepOpDomain, Surface extends StepOpSurface = StepOpSurface> {
+    opId: OpId;
+    domain: Domain;
+    surface: Surface;
+    description: string;
+    referenceOperationId?: OperationId;
+}
+declare const STEP_OP_CATALOG_UNFROZEN: readonly [StepOpCatalogEntry<"assert", "assert", StepOpSurface>, StepOpCatalogEntry<"text.rewrite", "text", StepOpSurface>, StepOpCatalogEntry<"text.insert", "text", StepOpSurface>, StepOpCatalogEntry<"text.delete", "text", StepOpSurface>, StepOpCatalogEntry<"format.apply", "format", StepOpSurface>, StepOpCatalogEntry<"create.paragraph", "create", StepOpSurface>, StepOpCatalogEntry<"create.heading", "create", StepOpSurface>, StepOpCatalogEntry<"create.table", "create", StepOpSurface>, StepOpCatalogEntry<"tables.delete", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.clearContents", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.move", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.split", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.convertFromText", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.convertToText", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setLayout", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.insertRow", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.deleteRow", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.moveRow", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setRowHeight", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.distributeRows", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setRowOptions", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.insertColumn", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.deleteColumn", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setColumnWidth", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.distributeColumns", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.insertCell", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.deleteCell", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.mergeCells", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.unmergeCells", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.splitCell", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setCellProperties", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.sort", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setAltText", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setStyle", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.clearStyle", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setStyleOption", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setBorder", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.clearBorder", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.applyBorderPreset", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setShading", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.clearShading", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setTablePadding", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setCellPadding", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.setCellSpacing", "tables", StepOpSurface>, StepOpCatalogEntry<"tables.clearCellSpacing", "tables", StepOpSurface>, StepOpCatalogEntry<"structural.insert", "structural", StepOpSurface>, StepOpCatalogEntry<"structural.replace", "structural", StepOpSurface>, StepOpCatalogEntry<"domain.command", "internal", "internal">];
+export declare const STEP_OP_CATALOG: readonly StepOpCatalogEntry[];
+export type MutationStepOpId = (typeof STEP_OP_CATALOG_UNFROZEN)[number]['opId'];
+type InternalStepOpCatalogEntry = Extract<(typeof STEP_OP_CATALOG_UNFROZEN)[number], {
+    surface: 'internal';
+}>;
+type InternalMutationStepOpId = InternalStepOpCatalogEntry['opId'];
+export type PublicMutationStepOpId = Exclude<MutationStepOpId, InternalMutationStepOpId>;
+declare const PUBLIC_STEP_OP_CATALOG_UNFROZEN: readonly StepOpCatalogEntry<PublicMutationStepOpId, StepOpDomain, "public">[];
+export type PublicStepOpCatalogEntry = (typeof PUBLIC_STEP_OP_CATALOG_UNFROZEN)[number];
+export declare const PUBLIC_STEP_OP_CATALOG: readonly StepOpCatalogEntry[];
+export declare const KNOWN_MUTATION_STEP_OP_IDS: readonly MutationStepOpId[];
+export declare const PUBLIC_MUTATION_STEP_OP_IDS: readonly PublicMutationStepOpId[];
+export declare function isKnownMutationStepOp(opId: string): opId is MutationStepOpId;
+export declare function isPublicMutationStepOp(opId: string): opId is PublicMutationStepOpId;
+export {};

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

@@ -0,0 +1,31 @@
+import { OperationId } from './operation-definitions.js';
+import { CommandStaticMetadata } from './metadata-types.js';
+export { OPERATION_IDEMPOTENCY_VALUES, type OperationIdempotency, PRE_APPLY_THROW_CODES, type PreApplyThrowCode, type CommandThrowPolicy, type CommandStaticMetadata, } from './metadata-types.js';
+export { type OperationId, OPERATION_IDS, SINGLETON_OPERATION_IDS, NAMESPACED_OPERATION_IDS, } from './operation-definitions.js';
+export declare const CONTRACT_VERSION = "0.1.0";
+export declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export type CommandCatalog = {
+    readonly [K in OperationId]: CommandStaticMetadata;
+};
+/**
+ * Checks whether a string matches the syntactic format of an operation ID
+ * (`camelCase`, `namespace.camelCase`, or `group.subgroup.camelCase`).
+ *
+ * @param operationId - The string to validate.
+ * @returns `true` if the string matches the expected format.
+ */
+export declare function isValidOperationIdFormat(operationId: string): boolean;
+/**
+ * Type-guard that narrows a string to the {@link OperationId} union.
+ *
+ * @param operationId - The string to check.
+ * @returns `true` if the string is a known operation ID.
+ */
+export declare function isOperationId(operationId: string): operationId is OperationId;
+/**
+ * Asserts that a string is a valid, known {@link OperationId}.
+ *
+ * @param operationId - The string to assert.
+ * @throws {Error} If the string is not a recognised operation ID.
+ */
+export declare function assertOperationId(operationId: string): asserts operationId is OperationId;

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

@@ -0,0 +1,27 @@
+import { MutationOptions } from '../write/write.js';
+import { CreateParagraphInput, CreateParagraphResult, CreateHeadingInput, CreateHeadingResult } from '../types/create.types.js';
+import { CreateTableInput, CreateTableResult } from '../types/table-operations.types.js';
+import { CreateSectionBreakInput, CreateSectionBreakResult } from '../sections/sections.types.js';
+import { CreateTableOfContentsInput, CreateTableOfContentsResult } from '../toc/toc.types.js';
+import { CreateImageInput, CreateImageResult } from '../images/images.types.js';
+import { CreateContentControlInput, ContentControlMutationResult } from '../content-controls/content-controls.types.js';
+export interface CreateApi {
+    paragraph(input: CreateParagraphInput, options?: MutationOptions): CreateParagraphResult;
+    heading(input: CreateHeadingInput, options?: MutationOptions): CreateHeadingResult;
+    table(input: CreateTableInput, options?: MutationOptions): CreateTableResult;
+    sectionBreak(input: CreateSectionBreakInput, options?: MutationOptions): CreateSectionBreakResult;
+    tableOfContents(input: CreateTableOfContentsInput, options?: MutationOptions): CreateTableOfContentsResult;
+    image(input: CreateImageInput, options?: MutationOptions): CreateImageResult;
+    contentControl(input: CreateContentControlInput, options?: MutationOptions): ContentControlMutationResult;
+}
+export type CreateAdapter = CreateApi;
+export declare function normalizeCreateParagraphInput(input: CreateParagraphInput): CreateParagraphInput;
+export declare function executeCreateParagraph(adapter: CreateAdapter, input: CreateParagraphInput, options?: MutationOptions): CreateParagraphResult;
+export declare function normalizeCreateHeadingInput(input: CreateHeadingInput): CreateHeadingInput;
+export declare function executeCreateHeading(adapter: CreateAdapter, input: CreateHeadingInput, options?: MutationOptions): CreateHeadingResult;
+export declare function normalizeCreateTableInput(input: CreateTableInput): CreateTableInput;
+export declare function executeCreateTable(adapter: CreateAdapter, input: CreateTableInput, options?: MutationOptions): CreateTableResult;
+export declare function normalizeCreateSectionBreakInput(input: CreateSectionBreakInput): CreateSectionBreakInput;
+export declare function executeCreateSectionBreak(adapter: CreateAdapter, input: CreateSectionBreakInput, options?: MutationOptions): CreateSectionBreakResult;
+export declare function normalizeCreateTableOfContentsInput(input: CreateTableOfContentsInput): CreateTableOfContentsInput;
+export declare function executeCreateTableOfContents(adapter: CreateAdapter, input: CreateTableOfContentsInput, options?: MutationOptions): CreateTableOfContentsResult;

package/dist/document-api/src/cross-refs/cross-refs.d.ts

@@ -0,0 +1,15 @@
+import { MutationOptions } from '../write/write.js';
+import { CrossRefGetInput, CrossRefInfo, CrossRefInsertInput, CrossRefRebuildInput, CrossRefRemoveInput, CrossRefMutationResult, CrossRefListInput, CrossRefsListResult } from './cross-refs.types.js';
+export interface CrossRefsApi {
+    list(query?: CrossRefListInput): CrossRefsListResult;
+    get(input: CrossRefGetInput): CrossRefInfo;
+    insert(input: CrossRefInsertInput, options?: MutationOptions): CrossRefMutationResult;
+    rebuild(input: CrossRefRebuildInput, options?: MutationOptions): CrossRefMutationResult;
+    remove(input: CrossRefRemoveInput, options?: MutationOptions): CrossRefMutationResult;
+}
+export type CrossRefsAdapter = CrossRefsApi;
+export declare function executeCrossRefsList(adapter: CrossRefsAdapter, query?: CrossRefListInput): CrossRefsListResult;
+export declare function executeCrossRefsGet(adapter: CrossRefsAdapter, input: CrossRefGetInput): CrossRefInfo;
+export declare function executeCrossRefsInsert(adapter: CrossRefsAdapter, input: CrossRefInsertInput, options?: MutationOptions): CrossRefMutationResult;
+export declare function executeCrossRefsRebuild(adapter: CrossRefsAdapter, input: CrossRefRebuildInput, options?: MutationOptions): CrossRefMutationResult;
+export declare function executeCrossRefsRemove(adapter: CrossRefsAdapter, input: CrossRefRemoveInput, options?: MutationOptions): CrossRefMutationResult;

package/dist/document-api/src/cross-refs/cross-refs.types.d.ts

@@ -0,0 +1,68 @@
+import { InlineAnchor } from '../types/base.js';
+import { TextTarget } from '../types/address.js';
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+export interface CrossRefAddress {
+    kind: 'inline';
+    nodeType: 'crossRef';
+    anchor: InlineAnchor;
+}
+export type CrossRefTarget = {
+    kind: 'bookmark';
+    name: string;
+} | {
+    kind: 'heading';
+    nodeId: string;
+} | {
+    kind: 'note';
+    noteId: string;
+} | {
+    kind: 'caption';
+    nodeId: string;
+} | {
+    kind: 'numberedItem';
+    nodeId: string;
+} | {
+    kind: 'styledParagraph';
+    styleName: string;
+    direction?: 'before' | 'after';
+};
+export type CrossRefDisplay = 'content' | 'pageNumber' | 'noteNumber' | 'labelAndNumber' | 'aboveBelow' | 'numberOnly' | 'numberFullContext' | 'styledContent' | 'styledPageNumber';
+export interface CrossRefListInput {
+    limit?: number;
+    offset?: number;
+}
+export interface CrossRefGetInput {
+    target: CrossRefAddress;
+}
+export interface CrossRefRemoveInput {
+    target: CrossRefAddress;
+}
+export interface CrossRefRebuildInput {
+    target: CrossRefAddress;
+}
+export interface CrossRefInsertInput {
+    at: TextTarget;
+    target: CrossRefTarget;
+    display: CrossRefDisplay;
+}
+export interface CrossRefInfo {
+    address: CrossRefAddress;
+    target: CrossRefTarget;
+    display: CrossRefDisplay;
+    resolvedText: string;
+    instruction: string;
+}
+export interface CrossRefDomain {
+    address: CrossRefAddress;
+    target: CrossRefTarget;
+    display: CrossRefDisplay;
+    resolvedText: string;
+    instruction: string;
+}
+export interface CrossRefMutationSuccess {
+    success: true;
+    crossRef: CrossRefAddress;
+}
+export type CrossRefMutationResult = CrossRefMutationSuccess | AdapterMutationFailure;
+export type CrossRefsListResult = DiscoveryOutput<CrossRefDomain>;

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

@@ -0,0 +1,19 @@
+import { MutationOptions } from '../write/write.js';
+import { CustomXmlPartsCreateInput, CustomXmlPartsCreateResult, CustomXmlPartsGetInput, CustomXmlPartsListInput, CustomXmlPartsListResult, CustomXmlPartsMutationResult, CustomXmlPartsPatchInput, CustomXmlPartsRemoveInput, CustomXmlPartInfo } from './customXml.types.js';
+export interface CustomXmlPartsApi {
+    list(query?: CustomXmlPartsListInput): CustomXmlPartsListResult;
+    get(input: CustomXmlPartsGetInput): CustomXmlPartInfo | null;
+    create(input: CustomXmlPartsCreateInput, options?: MutationOptions): CustomXmlPartsCreateResult;
+    patch(input: CustomXmlPartsPatchInput, options?: MutationOptions): CustomXmlPartsMutationResult;
+    remove(input: CustomXmlPartsRemoveInput, options?: MutationOptions): CustomXmlPartsMutationResult;
+}
+export type CustomXmlPartsAdapter = CustomXmlPartsApi;
+export interface CustomXmlApi {
+    parts: CustomXmlPartsApi;
+}
+export type CustomXmlAdapter = CustomXmlApi;
+export declare function executeCustomXmlPartsList(adapter: CustomXmlPartsAdapter, query?: CustomXmlPartsListInput): CustomXmlPartsListResult;
+export declare function executeCustomXmlPartsGet(adapter: CustomXmlPartsAdapter, input: CustomXmlPartsGetInput): CustomXmlPartInfo | null;
+export declare function executeCustomXmlPartsCreate(adapter: CustomXmlPartsAdapter, input: CustomXmlPartsCreateInput, options?: MutationOptions): CustomXmlPartsCreateResult;
+export declare function executeCustomXmlPartsPatch(adapter: CustomXmlPartsAdapter, input: CustomXmlPartsPatchInput, options?: MutationOptions): CustomXmlPartsMutationResult;
+export declare function executeCustomXmlPartsRemove(adapter: CustomXmlPartsAdapter, input: CustomXmlPartsRemoveInput, options?: MutationOptions): CustomXmlPartsMutationResult;

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

@@ -0,0 +1,148 @@
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+/**
+ * Stable identifier for a Custom XML Data Storage Part.
+ *
+ * Maps to the `<ds:datastoreItem ds:itemID>` GUID in the part's Properties
+ * Part (ECMA-376 Part 1 §22.5.2.1). Format is a literal `ST_Guid` with
+ * braces: `"{A67AC88A-A164-4ADE-8889-8826CE44DE6E}"`.
+ *
+ * Absent when a Storage Part has no Properties Part (foreign producers
+ * sometimes ship one without the other; the spec allows it). In that
+ * case, use `{ partName }` to target the part instead.
+ */
+export type CustomXmlPartId = string;
+/**
+ * Target shape for read/patch/remove operations.
+ *
+ * Most callers will use `{ id }` (the itemID GUID). The `{ partName }`
+ * variant exists for Storage Parts that have no Properties Part — those
+ * have no itemID and can only be addressed by their file path inside
+ * the OOXML package.
+ *
+ * Scope: `partName` accepts Word-style Storage Part paths only —
+ * `customXml/itemN.xml` for integer `N`. Foreign-named Storage Parts
+ * (which ECMA-376 §15.2.5 permits) are not in v1; see the implementation
+ * note on the converter's `listCustomXmlStoragePartNames`. Foreign-named
+ * *Properties Parts* paired via rels are fully supported on the read side.
+ */
+export type CustomXmlPartTarget = {
+    id: CustomXmlPartId;
+} | {
+    partName: string;
+};
+export interface CustomXmlPartsListInput {
+    /**
+     * Filter by the XML namespace of the Storage Part's root element
+     * (e.g. `<harveyRefs xmlns="urn:harvey:refs:1"/>` → `'urn:harvey:refs:1'`).
+     *
+     * Distinct from `schemaRef`: this is what the *data* declares; schemaRef
+     * is what the Properties Part declares as the associated XML schema's
+     * target namespace. Often they match, but the spec does not require it.
+     */
+    rootNamespace?: string;
+    /**
+     * Filter by one of the part's `<ds:schemaRef ds:uri>` values
+     * (ECMA-376 Part 1 §22.5.2.2). Matches if any declared schemaRef equals
+     * this URI.
+     */
+    schemaRef?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CustomXmlPartsGetInput {
+    target: CustomXmlPartTarget;
+}
+export interface CustomXmlPartsCreateInput {
+    /**
+     * Well-formed XML for the Storage Part's body. Anything that is legal
+     * `application/xml` is acceptable; consumers control the schema entirely.
+     */
+    content: string;
+    /**
+     * Optional list of XML schema target namespaces to declare in the
+     * Properties Part (`<ds:schemaRef ds:uri>`).
+     *
+     * Per ECMA-376 §22.5.2.3, three states are distinct:
+     *   - omitted (`undefined`)  → no `<ds:schemaRefs>` element emitted;
+     *                              consumers may infer the schema from the
+     *                              content's namespace.
+     *   - empty array (`[]`)     → `<ds:schemaRefs/>` is emitted explicitly,
+     *                              meaning "no schemas should be used to
+     *                              validate this part."
+     *   - populated array        → `<ds:schemaRefs>` with one `<ds:schemaRef>`
+     *                              per URI.
+     *
+     * The Properties Part itself is always emitted (with a fresh itemID),
+     * so `id` is discoverable on readback regardless of `schemaRefs`.
+     */
+    schemaRefs?: string[];
+}
+export interface CustomXmlPartsPatchInput {
+    target: CustomXmlPartTarget;
+    /** Replace the Storage Part's content. Must be well-formed XML. */
+    content?: string;
+    /**
+     * Replace the Properties Part's `<ds:schemaRefs>` set with this list.
+     * Pass `[]` to write an explicit empty `<ds:schemaRefs/>` (ECMA-376
+     * §22.5.2.3 "no schemas should be used"). Omit the field entirely to
+     * leave the existing schemaRefs untouched.
+     */
+    schemaRefs?: string[];
+}
+export interface CustomXmlPartsRemoveInput {
+    target: CustomXmlPartTarget;
+}
+/**
+ * Lightweight view of a Custom XML Part returned by `list()`. Does NOT
+ * carry `content` — parts can be large; fetch the full record via `get()`
+ * when needed.
+ */
+export interface CustomXmlPartSummary {
+    /** itemID GUID; absent when no Properties Part exists. */
+    id?: CustomXmlPartId;
+    /**
+     * Package-relative path of the Storage Part, e.g. `"customXml/item1.xml"`.
+     * v1 scope: Word-style `customXml/itemN.xml` only.
+     */
+    partName: string;
+    /** Package-relative path of the Properties Part, when present. */
+    propsPartName?: string;
+    /**
+     * XML namespace URI of the Storage Part's root element, parsed from
+     * `content`. Absent when the root element has no namespace.
+     */
+    rootNamespace?: string;
+    /** Values from `<ds:schemaRef ds:uri>` in the Properties Part. */
+    schemaRefs: string[];
+}
+export type CustomXmlPartInfo = CustomXmlPartSummary & {
+    /** Full serialized XML body of the Storage Part. */
+    content: string;
+};
+export interface CustomXmlPartsCreateSuccess {
+    success: true;
+    /** Generated itemID GUID for the newly created part. */
+    id: CustomXmlPartId;
+    partName: string;
+    propsPartName: string;
+}
+export type CustomXmlPartsCreateResult = CustomXmlPartsCreateSuccess | AdapterMutationFailure;
+export interface CustomXmlPartsMutationSuccess {
+    success: true;
+    /** Identifier the operation acted on (mirrors the resolved input target). */
+    target: CustomXmlPartTarget;
+    /**
+     * The resolved itemID GUID of the affected part, when one exists.
+     *
+     * `patch` may need to mint a fresh GUID — e.g. when `schemaRefs` is
+     * patched onto a Storage Part that didn't previously have a Properties
+     * Part. In that case the caller targeted by `partName` but now has an
+     * id they can use for subsequent operations; this field surfaces it.
+     *
+     * For `remove`, the field is omitted because the part is gone.
+     */
+    id?: CustomXmlPartId;
+}
+export type CustomXmlPartsMutationResult = CustomXmlPartsMutationSuccess | AdapterMutationFailure;
+export type CustomXmlPartsListResult = DiscoveryOutput<CustomXmlPartSummary>;

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

@@ -0,0 +1,20 @@
+import { SelectionTarget, DeleteBehavior, TargetLocator } from '../types/address.js';
+import { TextMutationReceipt } from '../types/receipt.js';
+import { MutationOptions } from '../types/mutation-plan.types.js';
+import { StoryLocator } from '../types/story.types.js';
+import { SelectionMutationAdapter } from '../selection-mutation.js';
+export type DeleteInput = TargetLocator & {
+    /** Explicit selection target. Exactly one of `target` or `ref` is required. */
+    target?: SelectionTarget;
+    /** Mutation-ready ref from `query.match` or `find`. */
+    ref?: string;
+    /**
+     * Delete behavior mode.
+     * - `'selection'` (default): expand to block edges when boundary blocks are fully covered.
+     * - `'exact'`: delete only the exact resolved range.
+     */
+    behavior?: DeleteBehavior;
+    /** Target a specific document story (body, header, footer, footnote, endnote). */
+    in?: StoryLocator;
+};
+export declare function executeDelete(adapter: SelectionMutationAdapter, input: DeleteInput, options?: MutationOptions): TextMutationReceipt;

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

@@ -0,0 +1,14 @@
+import { DiffSnapshot, DiffPayload, DiffApplyResult, DiffCompareInput, DiffApplyInput, DiffApplyOptions } from './diff.types.js';
+export interface DiffAdapter {
+    capture(): DiffSnapshot;
+    compare(input: DiffCompareInput): DiffPayload;
+    apply(input: DiffApplyInput, options?: DiffApplyOptions): DiffApplyResult;
+}
+export interface DiffApi {
+    capture(): DiffSnapshot;
+    compare(input: DiffCompareInput): DiffPayload;
+    apply(input: DiffApplyInput, options?: DiffApplyOptions): DiffApplyResult;
+}
+export declare function executeDiffCapture(adapter: DiffAdapter): DiffSnapshot;
+export declare function executeDiffCompare(adapter: DiffAdapter, input: DiffCompareInput): DiffPayload;
+export declare function executeDiffApply(adapter: DiffAdapter, input: DiffApplyInput, options?: DiffApplyOptions): DiffApplyResult;

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

@@ -0,0 +1,83 @@
+/**
+ * Public types for the snapshot-based document diff contract.
+ *
+ * These types are engine-agnostic wrappers around opaque engine payloads.
+ * The `payload` field in both DiffSnapshot and DiffPayload is engine-owned
+ * and must not be inspected by consumers.
+ */
+/** Identifier for the engine adapter that produced the opaque payload. */
+export type DiffEngineId = 'superdoc-v2';
+/** Declares which document components are included in a snapshot or diff. */
+export interface DiffCoverage {
+    body: true;
+    comments: boolean;
+    styles: boolean;
+    numbering: boolean;
+    headerFooters: boolean;
+}
+/** Versioned, fingerprinted snapshot of a document's diffable state. */
+export interface DiffSnapshot {
+    version: 'sd-diff-snapshot/v1' | 'sd-diff-snapshot/v2';
+    engine: DiffEngineId;
+    fingerprint: string;
+    coverage: DiffCoverage;
+    /** Opaque engine-owned snapshot data. Do not inspect or modify. */
+    payload: Record<string, unknown>;
+}
+/** Coarse change summary for a diff payload. */
+export interface DiffSummary {
+    hasChanges: boolean;
+    changedComponents: Array<'body' | 'comments' | 'styles' | 'numbering' | 'headerFooters' | 'parts'>;
+    body: {
+        hasChanges: boolean;
+    };
+    comments: {
+        hasChanges: boolean;
+    };
+    styles: {
+        hasChanges: boolean;
+    };
+    numbering: {
+        hasChanges: boolean;
+    };
+    headerFooters: {
+        hasChanges: boolean;
+    };
+    parts: {
+        hasChanges: boolean;
+    };
+}
+/** Versioned diff payload describing changes from a base to a target document. */
+export interface DiffPayload {
+    version: 'sd-diff-payload/v1' | 'sd-diff-payload/v2';
+    engine: DiffEngineId;
+    baseFingerprint: string;
+    targetFingerprint: string;
+    coverage: DiffCoverage;
+    summary: DiffSummary;
+    /** Opaque engine-owned diff data. Do not inspect or modify. */
+    payload: Record<string, unknown>;
+}
+/** Result metadata returned after applying a diff. */
+export interface DiffApplyResult {
+    appliedOperations: number;
+    baseFingerprint: string;
+    targetFingerprint: string;
+    coverage: DiffCoverage;
+    summary: DiffSummary;
+    diagnostics: string[];
+}
+/** Input for `diff.compare`. */
+export interface DiffCompareInput {
+    targetSnapshot: DiffSnapshot;
+}
+/** Input for `diff.apply`. */
+export interface DiffApplyInput {
+    diff: DiffPayload;
+}
+/** How body content changes are applied. */
+export type DiffChangeMode = 'direct' | 'tracked';
+/** Options for `diff.apply`. Omitted `changeMode` applies story content directly. */
+export interface DiffApplyOptions {
+    changeMode?: DiffChangeMode;
+}

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

@@ -0,0 +1,3 @@
+export type { DiffAdapter, DiffApi } from './diff.js';
+export { executeDiffCapture, executeDiffCompare, executeDiffApply } from './diff.js';
+export type { DiffSnapshot, DiffPayload, DiffApplyResult, DiffSummary, DiffCoverage, DiffEngineId, DiffCompareInput, DiffApplyInput, DiffApplyOptions, DiffChangeMode, } from './diff.types.js';

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

@@ -0,0 +1,11 @@
+/**
+ * Structured validation error thrown by document-api execute* functions.
+ *
+ * Consumers should prefer checking `error.code` over `instanceof` for resilience
+ * across package boundaries and bundling scenarios.
+ */
+export declare class DocumentApiValidationError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}

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

@@ -0,0 +1,10 @@
+import { ExportToDocxInput, ExportToDocxResult, SDExportMode } from './export.types.js';
+export interface ExportAdapter {
+    toDocx(input: {
+        mode: SDExportMode;
+    }): ExportToDocxResult;
+}
+export interface ExportApi {
+    toDocx(input?: ExportToDocxInput): ExportToDocxResult;
+}
+export declare function executeExportToDocx(adapter: ExportAdapter | undefined, input?: ExportToDocxInput): ExportToDocxResult;

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

@@ -0,0 +1,40 @@
+import { ReviewWarning } from '../types/receipt.js';
+/** Canonical tracked-change export modes accepted by every public export surface. */
+export declare const SD_EXPORT_MODES: readonly ["review-preserving", "final", "original"];
+/**
+ * Tracked-change export mode.
+ *
+ * - `review-preserving` (default): keep open tracked changes as Word revision
+ *   markup so the saved document is still reviewable.
+ * - `final`: resolve every open tracked change as accepted.
+ * - `original`: resolve every open tracked change as rejected.
+ */
+export type SDExportMode = (typeof SD_EXPORT_MODES)[number];
+/** Default mode for modeful DOCX export. */
+export declare const DEFAULT_SD_EXPORT_MODE: SDExportMode;
+/** Input for `export.toDocx`. */
+export interface ExportToDocxInput {
+    /** Tracked-change export mode. Defaults to `review-preserving`. */
+    mode?: SDExportMode;
+}
+/** Structured degradation report for an export. */
+export interface ExportToDocxReport {
+    /**
+     * Allowed, non-load-bearing degradation warnings produced while projecting
+     * the document for the requested mode (for example a tracked replacement
+     * exported as Word delete+insert). Forbidden semantic loss never reaches
+     * this lane — those failures fail closed before bytes are produced.
+     */
+    warnings: ReviewWarning[];
+}
+/** Result of `export.toDocx`. */
+export interface ExportToDocxResult {
+    /** The mode the export was produced under. */
+    mode: SDExportMode;
+    /** Byte length of the exported DOCX package. */
+    byteLength: number;
+    /** Base64-encoded exported DOCX package bytes. */
+    contentBase64: string;
+    /** Degradation report for the export. */
+    report: ExportToDocxReport;
+}

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

@@ -0,0 +1,15 @@
+import { ExtractResult } from '../types/extract.types.js';
+export type ExtractInput = Record<string, never>;
+/**
+ * Engine-specific adapter that provides document content extraction.
+ */
+export interface ExtractAdapter {
+    /**
+     * Extract all document content with stable IDs for RAG pipelines.
+     */
+    extract(input: ExtractInput): ExtractResult;
+}
+/**
+ * Execute an extract operation through the provided adapter.
+ */
+export declare function executeExtract(adapter: ExtractAdapter, input: ExtractInput): ExtractResult;

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

@@ -0,0 +1,15 @@
+import { MutationOptions } from '../write/write.js';
+import { FieldGetInput, FieldInfo, FieldInsertInput, FieldRebuildInput, FieldRemoveInput, FieldMutationResult, FieldListInput, FieldsListResult } from './fields.types.js';
+export interface FieldsApi {
+    list(query?: FieldListInput): FieldsListResult;
+    get(input: FieldGetInput): FieldInfo;
+    insert(input: FieldInsertInput, options?: MutationOptions): FieldMutationResult;
+    rebuild(input: FieldRebuildInput, options?: MutationOptions): FieldMutationResult;
+    remove(input: FieldRemoveInput, options?: MutationOptions): FieldMutationResult;
+}
+export type FieldsAdapter = FieldsApi;
+export declare function executeFieldsList(adapter: FieldsAdapter, query?: FieldListInput): FieldsListResult;
+export declare function executeFieldsGet(adapter: FieldsAdapter, input: FieldGetInput): FieldInfo;
+export declare function executeFieldsInsert(adapter: FieldsAdapter, input: FieldInsertInput, options?: MutationOptions): FieldMutationResult;
+export declare function executeFieldsRebuild(adapter: FieldsAdapter, input: FieldRebuildInput, options?: MutationOptions): FieldMutationResult;
+export declare function executeFieldsRemove(adapter: FieldsAdapter, input: FieldRemoveInput, options?: MutationOptions): FieldMutationResult;