superdoc 2.2.1 → 2.3.0

package/dist/document-api/src/styles/apply.d.ts

@@ -0,0 +1,142 @@
+import { ReceiptFailure } from '../types/receipt.js';
+import { StylesChannel } from './registry.js';
+import { StylesGetCatalogInput, StylesGetCatalogResult } from './catalog.js';
+/** Tri-state for OOXML boolean style properties. */
+export type StylesBooleanState = 'on' | 'off' | 'inherit';
+export type StylesNumberState = number | 'inherit';
+export type StylesEnumState = string | 'inherit';
+export type StylesObjectState = Record<string, unknown> | 'inherit';
+export type StylesArrayState = unknown[] | 'inherit';
+/** Patch for run-channel properties (docDefaults/w:rPrDefault/w:rPr). */
+export interface StylesRunPatch {
+    bold?: boolean;
+    boldCs?: boolean;
+    italic?: boolean;
+    iCs?: boolean;
+    smallCaps?: boolean;
+    strike?: boolean;
+    dstrike?: boolean;
+    emboss?: boolean;
+    imprint?: boolean;
+    outline?: boolean;
+    shadow?: boolean;
+    vanish?: boolean;
+    webHidden?: boolean;
+    specVanish?: boolean;
+    snapToGrid?: boolean;
+    noProof?: boolean;
+    fontSize?: number;
+    fontSizeCs?: number;
+    letterSpacing?: number;
+    kern?: number;
+    position?: number;
+    w?: number;
+    textTransform?: string;
+    vertAlign?: string;
+    em?: string;
+    effect?: string;
+    fontFamily?: Record<string, unknown>;
+    color?: Record<string, unknown>;
+    underline?: Record<string, unknown>;
+    borders?: Record<string, unknown>;
+    shading?: Record<string, unknown>;
+    lang?: Record<string, unknown>;
+    eastAsianLayout?: Record<string, unknown>;
+    fitText?: Record<string, unknown>;
+}
+/** Patch for paragraph-channel properties (docDefaults/w:pPrDefault/w:pPr). */
+export interface StylesParagraphPatch {
+    keepLines?: boolean;
+    keepNext?: boolean;
+    widowControl?: boolean;
+    contextualSpacing?: boolean;
+    pageBreakBefore?: boolean;
+    suppressAutoHyphens?: boolean;
+    suppressLineNumbers?: boolean;
+    suppressOverlap?: boolean;
+    mirrorIndents?: boolean;
+    wordWrap?: boolean;
+    kinsoku?: boolean;
+    overflowPunct?: boolean;
+    topLinePunct?: boolean;
+    autoSpaceDE?: boolean;
+    autoSpaceDN?: boolean;
+    adjustRightInd?: boolean;
+    rightToLeft?: boolean;
+    snapToGrid?: boolean;
+    outlineLvl?: number;
+    justification?: string;
+    textAlignment?: string;
+    textDirection?: string;
+    textboxTightWrap?: string;
+    spacing?: Record<string, unknown>;
+    indent?: Record<string, unknown>;
+    shading?: Record<string, unknown>;
+    numberingProperties?: Record<string, unknown>;
+    framePr?: Record<string, unknown>;
+    borders?: Record<string, unknown>;
+    tabStops?: unknown[];
+}
+export interface StylesTargetResolution {
+    scope: 'docDefaults';
+    channel: StylesChannel;
+    xmlPart: 'word/styles.xml';
+    xmlPath: string;
+}
+export interface StylesApplyRunInput {
+    target: {
+        scope: 'docDefaults';
+        channel: 'run';
+    };
+    patch: StylesRunPatch;
+}
+export interface StylesApplyParagraphInput {
+    target: {
+        scope: 'docDefaults';
+        channel: 'paragraph';
+    };
+    patch: StylesParagraphPatch;
+}
+export type StylesApplyInput = StylesApplyRunInput | StylesApplyParagraphInput;
+export interface StylesApplyOptions {
+    dryRun?: boolean;
+    expectedRevision?: string;
+}
+export type StylesStateMap = Record<string, StylesBooleanState | StylesNumberState | StylesEnumState | StylesObjectState | StylesArrayState>;
+export interface StylesApplyReceiptSuccess {
+    success: true;
+    changed: boolean;
+    resolution: StylesTargetResolution;
+    dryRun: boolean;
+    before: StylesStateMap;
+    after: StylesStateMap;
+}
+export interface StylesApplyReceiptFailure {
+    success: false;
+    resolution: StylesTargetResolution;
+    failure: ReceiptFailure;
+}
+export type StylesApplyReceipt = StylesApplyReceiptSuccess | StylesApplyReceiptFailure;
+export interface StylesAdapter {
+    apply(input: StylesApplyRunInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyParagraphInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
+    /** Read the normalized style catalogue. See `styles/catalog.ts`. */
+    getCatalog?(input?: StylesGetCatalogInput): StylesGetCatalogResult;
+}
+export interface NormalizedStylesApplyOptions {
+    dryRun: boolean;
+    expectedRevision: string | undefined;
+}
+export interface StylesApi {
+    apply(input: StylesApplyRunInput, options?: StylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyParagraphInput, options?: StylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyInput, options?: StylesApplyOptions): StylesApplyReceipt;
+    /** Read the normalized style catalogue for discovery and quick-gallery UI. */
+    getCatalog(input?: StylesGetCatalogInput): StylesGetCatalogResult;
+}
+/**
+ * Executes `styles.apply` using the provided adapter.
+ * Validates input and options, then delegates to the adapter.
+ */
+export declare function executeStylesApply(adapter: StylesAdapter, input: StylesApplyInput, options?: StylesApplyOptions): StylesApplyReceipt;

package/dist/document-api/src/styles/catalog.d.ts

@@ -0,0 +1,154 @@
+/**
+ * `styles.getCatalog`: read-only style catalogue projection.
+ *
+ * The catalogue is the stable, normalized, editor-neutral view of the styles
+ * available in a document. It is the SDK / CLI / MCP / custom-UI integration
+ * point for style discovery, and the source the built-in toolbar and the
+ * future Styles pane consume.
+ *
+ * This module owns only the public contract types, input validation, and the
+ * execution entry point. The runtime projection is produced by the v2 adapter
+ * (which compiles a Word style model from package parts and calls the shared
+ * style-model projector); the raw style-engine shapes never reach this public
+ * surface.
+ *
+ * `DocumentInfo.styles` is a usage summary and intentionally stays separate
+ * from this available-style catalogue.
+ *
+ * Engine-agnostic: no ProseMirror, Yjs, or converter imports.
+ */
+/** Catalogue view selector. `inUse` lists styles referenced by document content. */
+export type StyleCatalogView = 'quickGallery' | 'recommended' | 'currentDocument' | 'all' | 'inUse';
+/** Normalized style kind. `linked` is a deduplicated paragraph/character pair. */
+export type StyleCatalogItemType = 'paragraph' | 'character' | 'linked' | 'table' | 'numbering' | 'unknown';
+/** Type filter values accepted on input (the concrete, requestable kinds). */
+export type StyleCatalogFilterType = Exclude<StyleCatalogItemType, 'unknown'>;
+/** Where a catalogue item originated. */
+export type StyleProvenance = 'authored' | 'default-floor' | 'latent';
+export type StyleCatalogDiagnosticSeverity = 'info' | 'warning' | 'error';
+/** Status of a backing OOXML package part. */
+export type StyleSourcePartStatus = 'present' | 'missing' | 'malformed';
+/**
+ * Usage-scan availability. `unsupported` when usage was not requested;
+ * `complete` when the full document was scanned; `partial` when the body story
+ * was scanned but secondary stories (headers/footers/comments/footnotes/endnotes)
+ * were deferred; `failed` when the body story could not be scanned and usage is
+ * unavailable.
+ */
+export type StyleCatalogUsageStatus = 'unsupported' | 'complete' | 'partial' | 'failed';
+/** Preview-resolution availability. `available` once previews were requested and resolved. */
+export type StyleCatalogPreviewStatus = 'unsupported' | 'available';
+/** Whether the requested `view` is supported in this pass. */
+export type StyleCatalogViewStatus = 'supported' | 'unsupported';
+export declare const STYLE_CATALOG_VIEWS: readonly StyleCatalogView[];
+export declare const STYLE_CATALOG_FILTER_TYPES: readonly StyleCatalogFilterType[];
+export interface StyleCatalogItemVisibility {
+    /** Belongs in the Word-style quick gallery (Home-tab Styles gallery). */
+    quickGallery: boolean;
+    /** Belongs in the pane "Recommended" view. */
+    recommended: boolean;
+    /** Belongs in the pane "All styles" view. */
+    all: boolean;
+    /** Hard-hidden or semi-hidden, so it should not surface in quick UI. */
+    effectivelyHidden: boolean;
+}
+/** Optional usage rollup. Present when `includeUsage` (or the `inUse` view) is requested. */
+export interface StyleCatalogItemUsage {
+    used: boolean;
+    paragraphCount?: number;
+    runCount?: number;
+    tableCount?: number;
+    numberingCount?: number;
+}
+/** Optional resolved preview tokens. Present when `includePreview` is requested. */
+export interface StyleCatalogItemPreview {
+    available: boolean;
+    css?: Record<string, string | number>;
+    unsupportedReason?: string;
+}
+/** One normalized style. Linked paragraph/character pairs are deduplicated. */
+export interface StyleCatalogItem {
+    id: string;
+    name: string;
+    aliases: string[];
+    type: StyleCatalogItemType;
+    custom: boolean;
+    builtin: boolean;
+    default: boolean;
+    basedOn: string | null;
+    next: string | null;
+    link: string | null;
+    priority: number | null;
+    qFormat: boolean;
+    hidden: boolean;
+    semiHidden: boolean;
+    unhideWhenUsed: boolean;
+    locked: boolean;
+    provenance: StyleProvenance;
+    visibility: StyleCatalogItemVisibility;
+    usage?: StyleCatalogItemUsage;
+    preview?: StyleCatalogItemPreview;
+}
+export interface StyleCatalogDefaults {
+    paragraphStyleId: string | null;
+    characterStyleId: string | null;
+    tableStyleId: string | null;
+}
+export interface StyleCatalogDiagnostic {
+    severity: StyleCatalogDiagnosticSeverity;
+    code: string;
+    part?: string;
+    message: string;
+}
+/**
+ * Per-source status so consumers can fail closed. A `missing` or `malformed`
+ * styles part still yields a default-floor catalogue with provenance, rather
+ * than guessing.
+ */
+export interface StyleCatalogSourceStatus {
+    styles: StyleSourcePartStatus;
+    settings: StyleSourcePartStatus;
+    usage: StyleCatalogUsageStatus;
+    preview: StyleCatalogPreviewStatus;
+    view: StyleCatalogViewStatus;
+}
+export interface StylesGetCatalogInput {
+    /** Which list to return as `items`. Defaults to `all`. */
+    view?: StyleCatalogView;
+    /** Restrict items to these style kinds. */
+    types?: StyleCatalogFilterType[];
+    /** Include hard-hidden / semi-hidden styles. Defaults to false. */
+    includeHidden?: boolean;
+    /** Include latent-only style metadata as `provenance: 'latent'`. Defaults to false. */
+    includeLatent?: boolean;
+    /** Request per-style usage counts (body-story scan; secondary stories deferred). */
+    includeUsage?: boolean;
+    /** Request resolved style previews (small UI-safe CSS tokens). */
+    includePreview?: boolean;
+    /** Include diagnostics on the result. Defaults to true. */
+    includeDiagnostics?: boolean;
+}
+export interface StylesGetCatalogResult {
+    version: 'style-catalog/v1';
+    /** Opaque catalogue revision token, or null when the runtime omits one. */
+    revision: string | null;
+    /** The view that `items` reflects (echoes the requested view). */
+    view: StyleCatalogView;
+    defaults: StyleCatalogDefaults;
+    /** The list selected by `view`, after `types` / `includeHidden` filtering. */
+    items: StyleCatalogItem[];
+    /** The full available style set, after `types` / `includeHidden` filtering. */
+    styles: StyleCatalogItem[];
+    sourceStatus: StyleCatalogSourceStatus;
+    diagnostics: StyleCatalogDiagnostic[];
+}
+export interface StylesGetCatalogAdapter {
+    getCatalog(input?: StylesGetCatalogInput): StylesGetCatalogResult;
+}
+/** Validates `styles.getCatalog` input. `undefined` is a valid (default) call. */
+export declare function validateStylesGetCatalogInput(input?: StylesGetCatalogInput): void;
+/**
+ * Executes `styles.getCatalog` using the provided adapter.
+ * Validates input, then delegates to the adapter.
+ */
+export declare function executeStylesGetCatalog(adapter: Partial<StylesGetCatalogAdapter> | null | undefined, input?: StylesGetCatalogInput): StylesGetCatalogResult;

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

@@ -0,0 +1,14 @@
+/**
+ * Barrel re-export for styles/ submodules.
+ *
+ * Public surface only: internal validation/schema helpers are not exposed.
+ */
+export type { ValueSchema, StylesChannel, MergeStrategy, PropertyDefinition } from './registry.js';
+export { PROPERTY_REGISTRY, ALLOWED_KEYS_BY_CHANNEL, EXCLUDED_KEYS, XML_PATH_BY_CHANNEL, getPropertyDefinition, ST_VERTICAL_ALIGN_RUN, ST_EM, ST_TEXT_ALIGNMENT, ST_TEXT_DIRECTION, ST_TEXTBOX_TIGHT_WRAP, ST_TEXT_TRANSFORM, ST_JUSTIFICATION, } from './registry.js';
+export { toJsonSchema, buildPatchSchema, buildStateSchema } from './schema.js';
+export type { StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyInput, StylesApplyOptions, StylesStateMap, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, StylesApplyReceipt, StylesAdapter, NormalizedStylesApplyOptions, StylesApi, } from './apply.js';
+export { executeStylesApply } from './apply.js';
+export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, } from './catalog.js';
+export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalog, validateStylesGetCatalogInput, } from './catalog.js';
+export type { PatchKeyClassification } from './validation.js';
+export { validateValue, classifyPatchKey } from './validation.js';

package/dist/document-api/src/styles/registry.d.ts

@@ -0,0 +1,43 @@
+import { ST_UNDERLINE_VALUES } from '../inline-semantics/token-sets.js';
+export declare const ST_VERTICAL_ALIGN_RUN: readonly ["superscript", "subscript", "baseline"];
+export declare const ST_EM: readonly ["none", "dot", "comma", "circle", "sesame"];
+export declare const ST_TEXT_ALIGNMENT: readonly ["top", "center", "baseline", "bottom", "auto"];
+export declare const ST_TEXT_DIRECTION: readonly ["lrTb", "tbRl", "btLr", "lrTbV", "tbRlV", "tbLrV"];
+export declare const ST_TEXTBOX_TIGHT_WRAP: readonly ["none", "allLines", "firstAndLastLine", "firstLineOnly", "lastLineOnly"];
+export declare const ST_TEXT_TRANSFORM: readonly ["uppercase", "none"];
+export declare const ST_JUSTIFICATION: readonly ["left", "center", "right", "justify", "distribute"];
+export { ST_UNDERLINE_VALUES };
+/** Recursive schema AST describing the shape of a property value. */
+export type ValueSchema = {
+    kind: 'boolean';
+} | {
+    kind: 'integer';
+    min?: number;
+    max?: number;
+} | {
+    kind: 'enum';
+    values: readonly string[];
+} | {
+    kind: 'string';
+} | {
+    kind: 'object';
+    children: Record<string, ValueSchema>;
+} | {
+    kind: 'array';
+    item: ValueSchema;
+};
+export type StylesChannel = 'run' | 'paragraph';
+export type MergeStrategy = 'replace' | 'shallowMerge' | 'edgeMerge';
+export interface PropertyDefinition {
+    key: string;
+    channel: StylesChannel;
+    schema: ValueSchema;
+    mergeStrategy: MergeStrategy;
+}
+export declare const PROPERTY_REGISTRY: PropertyDefinition[];
+/** Allowed patch keys per channel, derived from the registry. */
+export declare const ALLOWED_KEYS_BY_CHANNEL: Record<StylesChannel, Set<string>>;
+/** Lookup a property definition by key and channel. */
+export declare function getPropertyDefinition(key: string, channel: StylesChannel): PropertyDefinition | undefined;
+export declare const EXCLUDED_KEYS: Record<StylesChannel, Map<string, string>>;
+export declare const XML_PATH_BY_CHANNEL: Record<StylesChannel, string>;

package/dist/document-api/src/styles/schema.d.ts

@@ -0,0 +1,9 @@
+import { ValueSchema, StylesChannel } from './registry.js';
+type JsonSchema = Record<string, unknown>;
+/** Converts a ValueSchema AST node to a JSON Schema object. */
+export declare function toJsonSchema(schema: ValueSchema): JsonSchema;
+/** Builds a JSON Schema for the patch object of a given channel. */
+export declare function buildPatchSchema(channel: StylesChannel): JsonSchema;
+/** Builds a JSON Schema for the before/after state map covering all registry keys. */
+export declare function buildStateSchema(): JsonSchema;
+export {};

package/dist/document-api/src/styles/validation.d.ts

@@ -0,0 +1,38 @@
+import { ValueSchema, StylesChannel } from './registry.js';
+/**
+ * Validates a value against a ValueSchema AST node.
+ *
+ * @param path - Dot-delimited path for error messages (e.g. "patch.borders.top.size")
+ * @param value - The value to validate
+ * @param schema - The schema to validate against
+ */
+export declare function validateValue(path: string, value: unknown, schema: ValueSchema): void;
+export type StylesApplyInputShape = {
+    target: {
+        scope: 'docDefaults';
+        channel: StylesChannel;
+    };
+    patch: Record<string, unknown>;
+};
+export declare function validateStylesApplyInput(input: unknown): asserts input is StylesApplyInputShape;
+export declare function validateStylesApplyOptions(options: unknown): void;
+/** Discriminated union returned by `classifyPatchKey`. */
+export type PatchKeyClassification = {
+    status: 'valid';
+} | {
+    status: 'excluded';
+    reason: string;
+} | {
+    status: 'cross_channel';
+    ownerChannel: StylesChannel;
+} | {
+    status: 'unknown';
+};
+/**
+ * Classifies a patch key relative to a given channel.
+ *
+ * Returns a discriminated union so callers can switch on `status` instead of
+ * nesting conditionals across excluded-key maps, allowed-key sets, and
+ * cross-channel lookups.
+ */
+export declare function classifyPatchKey(key: string, channel: StylesChannel): PatchKeyClassification;

package/dist/document-api/src/tables/color-formats.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Single source of truth for the table-color regex used by both:
+ *   - the schema-time validator (a string pattern in `contract/schemas.ts`)
+ *   - the runtime executor validator (a compiled RegExp in `tables/tables.ts`)
+ *
+ * Accepts canonical `RRGGBB` and `auto`, plus loose forms `#RRGGBB`, `RGB`,
+ * and `#RGB`. Adapters call `normalizeColorInput` to canonicalize before
+ * storage, so any of these forms round-trips to uppercase `RRGGBB`.
+ */
+export declare const TABLE_COLOR_PATTERN_SOURCE = "^(#?([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})|auto)$";
+/** Compiled once for runtime use. */
+export declare const TABLE_COLOR_PATTERN: RegExp;

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

@@ -0,0 +1,83 @@
+import { MutationOptions } from '../write/write.js';
+import { TablesApplyStyleInput, TablesSetBordersInput, TablesSetCellPaddingInput, TablesSetLayoutInput, TablesSetTableOptionsInput } from '../types/table-operations.types.js';
+type RowLocatorInput = {
+    target?: unknown;
+    nodeId?: unknown;
+    rowIndex?: unknown;
+};
+/**
+ * Validation options for the row locator.
+ *
+ * `allowAppendShorthand`: when true, a table-level locator (target/nodeId
+ * pointing at a table) with NEITHER `rowIndex` NOR `position` is accepted —
+ * the caller's adapter is expected to compute "below the last row". Used by
+ * `tables.insertRow`. All other row ops require `rowIndex` when targeting a
+ * table; pass this as `false` (the default) for them.
+ */
+interface RowLocatorOptions {
+    allowAppendShorthand?: boolean;
+}
+type CellOrTableScopedCellLocatorInput = {
+    target?: unknown;
+    nodeId?: unknown;
+    rowIndex?: unknown;
+    columnIndex?: unknown;
+};
+/**
+ * Returns `true` when the input carries non-`undefined` row + column coordinates,
+ * meaning it can participate in table-scoped cell targeting.
+ *
+ * This is the validation-time check for coordinate presence. Adapter-level
+ * resolution may still refine ambiguous `nodeId` handoffs by resolved node
+ * type so payloads like `TableCellInfo` from `tables.getCells()` continue to
+ * work as direct cell locators.
+ */
+export declare function hasTableScopedCellCoordinates(input: CellOrTableScopedCellLocatorInput): boolean;
+/**
+ * Normalizes legacy `atRowIndex` to canonical `rowIndex` for tables.split.
+ *
+ * Accepts either name, prefers `rowIndex` when both match, and rejects
+ * conflicting dual-name input. Returns the input unchanged when only
+ * `rowIndex` is present.
+ */
+export declare function normalizeTablesSplitInput<T extends {
+    rowIndex?: number;
+}>(input: T): T;
+/**
+ * Execute a table operation that uses the standard locator (target/nodeId).
+ * Validates the locator and normalizes MutationOptions.
+ */
+export declare function executeTableLocatorOp<TInput extends {
+    target?: unknown;
+    nodeId?: unknown;
+}, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions): TResult;
+export declare function executeTablesSetLayoutOp<TResult>(adapter: (input: TablesSetLayoutInput, options?: MutationOptions) => TResult, input: TablesSetLayoutInput, options?: MutationOptions): TResult;
+export declare function executeRowLocatorOp<TInput extends RowLocatorInput, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions, rowLocatorOptions?: RowLocatorOptions): TResult;
+export declare function executeCellOrTableScopedCellLocatorOp<TInput extends CellOrTableScopedCellLocatorInput, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions): TResult;
+/**
+ * Execute a document-level table mutation (no locator validation needed).
+ * Only normalizes MutationOptions.
+ */
+export declare function executeDocumentLevelTableOp<TInput, TResult>(adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions): TResult;
+/**
+ * Validate and execute `tables.applyStyle`.
+ */
+export declare function executeTablesApplyStyle<TResult>(operationName: string, adapter: (input: TablesApplyStyleInput, options?: MutationOptions) => TResult, input: TablesApplyStyleInput, options?: MutationOptions): TResult;
+/**
+ * Validate and execute `tables.setBorders`.
+ */
+export declare function executeTablesSetBorders<TResult>(operationName: string, adapter: (input: TablesSetBordersInput, options?: MutationOptions) => TResult, input: TablesSetBordersInput, options?: MutationOptions): TResult;
+/**
+ * Validate and execute `tables.setTableOptions`.
+ */
+export declare function executeTablesSetTableOptions<TResult>(operationName: string, adapter: (input: TablesSetTableOptionsInput, options?: MutationOptions) => TResult, input: TablesSetTableOptionsInput, options?: MutationOptions): TResult;
+/**
+ * Validate and execute `tables.setCellPadding`.
+ *
+ * Partial side updates are accepted and preserve omitted sides, but at least
+ * one of `topPt`, `rightPt`, `bottomPt`, or `leftPt` must be present. An
+ * all-omitted call is rejected so the direct typed API agrees with the schema's
+ * any-of side requirement (and the adapter never authors an empty `w:tcMar`).
+ */
+export declare function executeTablesSetCellPadding<TResult>(operationName: string, adapter: (input: TablesSetCellPaddingInput, options?: MutationOptions) => TResult, input: TablesSetCellPaddingInput, options?: MutationOptions): TResult;
+export {};

package/dist/document-api/src/templates/apply.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `templates.apply`: source-authoritative template adoption (SD-3247).
+ *
+ * Adopts a source DOCX's template **style system and reusable template assets**
+ * onto the currently open document while preserving the open document's
+ * body/story content (`word/document.xml` is never replaced). This is template
+ * adoption, not a blind substrate transplant. The adoption semantics are:
+ *
+ * - `styles`: source-authoritative overlap. For a `styleId` defined in both
+ *   documents the source definition wins **in place** under the original id
+ *   (no `*-tmpl` rename). The source `w:docDefaults` and `w:latentStyles`
+ *   singletons replace the target's. Source-only styles are imported; target-only
+ *   styles still required by preserved content are retained.
+ * - `numbering`: reconciled as a dependency graph (not a flat append / blind
+ *   replace). The `w:num`/`w:abstractNum` graph required by imported
+ *   numbering-bearing styles is imported, colliding ids are remapped
+ *   deterministically, and references are rewritten coherently in both
+ *   `numbering.xml` and `styles.xml`.
+ * - `settings`: bounded reconciliation — layout/style-affecting settings (e.g.
+ *   default tab stop) are adopted; identity/workflow settings (`rsid*`, `docId`,
+ *   protection/revision state, `attachedTemplate`) are preserved.
+ * - `theme`, `fontTable`, `webSettings`: whole-part adoption.
+ * - `headersFooters`: **all** source `header*.xml` / `footer*.xml` parts are
+ *   imported as reusable template assets (even ones the page-1 governing
+ *   section does not reference), together with their `.rels` and transitive
+ *   media closure; colliding part names / relationship ids / media names are
+ *   reallocated and references rewritten consistently.
+ * - `sectionDefaults`: the source `w:sectPr` that governs page 1 is adopted as
+ *   the current document's active/final section-default model. On multi-section
+ *   targets, its header/footer visibility model (`headerReference`,
+ *   `footerReference`, `w:titlePg`) is also propagated across the earlier
+ *   sections without overwriting their own page geometry. Intermediate / later
+ *   source sections are not imported.
+ *
+ * Selected non-body package sidecars (`customXml`, `docProps/custom.xml`,
+ * comments, notes, people, keymap customizations, and `settings.xml.rels`) are
+ * imported when present so reconstructed content can reuse the source package
+ * substrate faithfully. Source body content, glossary, signatures, embeddings,
+ * and body media remain out of scope and are reported, never applied.
+ *
+ * Engine-agnostic contract + execution entry point. No ProseMirror/converter imports.
+ */
+export type TemplatesApplySourcePath = {
+    kind: 'path';
+    path: string;
+};
+export type TemplatesApplySourceBase64 = {
+    kind: 'base64';
+    data: string;
+    filename?: string;
+};
+export type TemplatesApplySource = TemplatesApplySourcePath | TemplatesApplySourceBase64;
+export type TemplateBodyPolicy = 'preserve';
+export type TemplateScope = 'styles' | 'numbering' | 'settings' | 'theme' | 'fontTable' | 'webSettings' | 'headersFooters' | 'sectionDefaults';
+export interface TemplatesApplyInput {
+    source: TemplatesApplySource;
+    bodyPolicy?: TemplateBodyPolicy;
+}
+export interface TemplatesApplyOptions {
+    dryRun?: boolean;
+    expectedRevision?: string | number;
+}
+export interface NormalizedTemplatesApplyOptions {
+    dryRun: boolean;
+    expectedRevision: string | undefined;
+}
+export interface TemplateScopeReport {
+    scope: TemplateScope;
+    part: string;
+    detail?: string;
+}
+export type TemplateSkipReason = 'NOT_PRESENT_IN_SOURCE' | 'OUT_OF_SCOPE' | 'NO_CHANGE' | 'CAPABILITY_UNAVAILABLE';
+export interface TemplateScopeSkip {
+    scope: string;
+    part?: string;
+    reason: TemplateSkipReason;
+    message: string;
+}
+export interface TemplateUnsupportedItem {
+    part: string;
+    category: string;
+    reason: string;
+}
+export type TemplateChangeKind = 'created' | 'replaced' | 'merged' | 'imported';
+export interface TemplateChangedPart {
+    part: string;
+    scope: TemplateScope | 'package';
+    change: TemplateChangeKind;
+}
+export interface TemplateIdMapping {
+    kind: 'style' | 'numbering' | 'relationship';
+    from: string;
+    to: string;
+}
+export interface TemplateApplyWarning {
+    code: string;
+    message: string;
+}
+export interface TemplatesApplySourceInfo {
+    kind: 'path' | 'base64';
+    fingerprint: string;
+    partCount: number;
+}
+export interface TemplatesApplyReceiptSuccess {
+    success: true;
+    changed: boolean;
+    dryRun: boolean;
+    bodyPolicy: 'preserve';
+    source: TemplatesApplySourceInfo;
+    detectedScopes: TemplateScopeReport[];
+    appliedScopes: TemplateScopeReport[];
+    skippedScopes: TemplateScopeSkip[];
+    unsupportedItems: TemplateUnsupportedItem[];
+    changedParts: TemplateChangedPart[];
+    idMappings: {
+        styles?: TemplateIdMapping[];
+        numbering?: TemplateIdMapping[];
+        relationships?: TemplateIdMapping[];
+    };
+    warnings: TemplateApplyWarning[];
+}
+export type TemplatesApplyFailureCode = 'UNSUPPORTED_SOURCE' | 'INVALID_PACKAGE' | 'CAPABILITY_UNAVAILABLE' | 'UNSUPPORTED_TEMPLATE_CONTENT';
+export interface TemplatesApplyReceiptFailure {
+    success: false;
+    failure: {
+        code: TemplatesApplyFailureCode;
+        message: string;
+    };
+}
+export type TemplatesApplyReceipt = TemplatesApplyReceiptSuccess | TemplatesApplyReceiptFailure;
+export interface TemplatesAdapter {
+    /**
+     * Adopt a source package's template substrate. Returns a Promise: the source
+     * package is loaded asynchronously (JSZip), so the receipt resolves after the
+     * async OPC read + mutation work completes. Pre-apply guards (converter
+     * availability, `expectedRevision`) still throw synchronously before any
+     * Promise is returned — see `throws.preApply` in the contract metadata.
+     */
+    apply(input: TemplatesApplyInput, options: NormalizedTemplatesApplyOptions): Promise<TemplatesApplyReceipt>;
+}
+export interface TemplatesApi {
+    /**
+     * Apply detected template substrate from a source DOCX onto the open document.
+     *
+     * Must be awaited: source acquisition and OPC/ZIP package loading are async.
+     * Synchronous input validation and pre-apply preconditions still throw before
+     * the returned Promise is created.
+     */
+    apply(input: TemplatesApplyInput, options?: TemplatesApplyOptions): Promise<TemplatesApplyReceipt>;
+}
+/**
+ * Execute `templates.apply`.
+ *
+ * Input validation and option normalization run synchronously, so invalid
+ * input and other `throws.preApply` cases still throw synchronously (before any
+ * Promise is created). The successful/receipt-returning path is async: the
+ * adapter loads the source package via the async OPC reader and resolves a
+ * {@link TemplatesApplyReceipt}.
+ */
+export declare function executeTemplatesApply(adapter: TemplatesAdapter, input: TemplatesApplyInput, options?: TemplatesApplyOptions): Promise<TemplatesApplyReceipt>;

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

@@ -0,0 +1,7 @@
+/**
+ * Barrel re-export for templates/ submodule.
+ *
+ * Public surface only: internal validation helpers are not exposed.
+ */
+export type { TemplatesApplySourcePath, TemplatesApplySourceBase64, TemplatesApplySource, TemplateBodyPolicy, TemplateScope, TemplatesApplyInput, TemplatesApplyOptions, NormalizedTemplatesApplyOptions, TemplateScopeReport, TemplateSkipReason, TemplateScopeSkip, TemplateUnsupportedItem, TemplateChangeKind, TemplateChangedPart, TemplateIdMapping, TemplateApplyWarning, TemplatesApplySourceInfo, TemplatesApplyReceiptSuccess, TemplatesApplyFailureCode, TemplatesApplyReceiptFailure, TemplatesApplyReceipt, TemplatesAdapter, TemplatesApi, } from './apply.js';
+export { executeTemplatesApply } from './apply.js';