superdoc 2.24.0-next.8 → 2.24.0

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

@@ -0,0 +1,160 @@
+import { ReceiptFailure } from '../types/receipt.js';
+import { SDHighlightColor } from '../types/sd-props.js';
+import { StylesParagraphPatch, StylesRunPatch, StylesStateMap } from './apply.js';
+/**
+ * Run properties of a named style.
+ *
+ * A superset of {@link StylesRunPatch}: the four properties Word forbids in
+ * `w:docDefaults` and allows on a `w:style` are reachable here and nowhere
+ * else. `rtl` in particular is the property that makes a run right-to-left, so
+ * without it no right-to-left style could be authored through this API.
+ */
+export interface StyleRunPatch extends StylesRunPatch {
+    /** `w:cs` — treat the run as complex-script. */
+    cs?: boolean;
+    /** `w:rtl` — right-to-left run. */
+    rtl?: boolean;
+    /** `w:oMath` — the run is part of an equation. */
+    oMath?: boolean;
+    /** `w:highlight` — one of the closed `ST_HighlightColor` tokens. */
+    highlight?: SDHighlightColor;
+}
+/** What to do when a style with this `id`, or this `name`, already exists. */
+export type StyleConflictPolicy = 'fail' | 'replace';
+interface StylesCreateCommon {
+    /** `w:styleId`. Named `id` to match {@link StyleCatalogItem.id} on read. */
+    id: string;
+    /** `w:name`. */
+    name: string;
+    /** `w:basedOn`. `null` states "based on nothing" explicitly. */
+    basedOn?: string | null;
+    /** `w:aliases`, one entry per alias. */
+    aliases?: string[];
+    /** `w:uiPriority`. Named `priority` to match the catalogue on read. */
+    priority?: number | null;
+    /** `w:qFormat` — offer the style in Word's quick gallery. */
+    qFormat?: boolean;
+    /** `w:hidden`. */
+    hidden?: boolean;
+    /** `w:semiHidden`. */
+    semiHidden?: boolean;
+    /** `w:unhideWhenUsed`. */
+    unhideWhenUsed?: boolean;
+    /** `w:locked`. */
+    locked?: boolean;
+    /**
+     * `w:customStyle`. Defaults to `true`, which is what a style authored
+     * through this API is. Setting it `false` on a style whose name is not a
+     * built-in makes Word treat the name as one and re-label or hide the style.
+     */
+    custom?: boolean;
+    /** Defaults to `'fail'`. */
+    conflictPolicy?: StyleConflictPolicy;
+}
+export interface StylesCreateParagraphInput extends StylesCreateCommon {
+    type: 'paragraph';
+    /** `w:next`. May name the style being created. */
+    next?: string | null;
+    /** `w:style/w:pPr`. */
+    paragraph?: StylesParagraphPatch;
+    /** `w:style/w:rPr`. */
+    run?: StyleRunPatch;
+}
+export interface StylesCreateCharacterInput extends StylesCreateCommon {
+    type: 'character';
+    /** A character style has no following-paragraph style. */
+    next?: never;
+    /** A character style has no paragraph properties. */
+    paragraph?: never;
+    /** `w:style/w:rPr`. */
+    run?: StyleRunPatch;
+}
+export type StylesCreateInput = StylesCreateParagraphInput | StylesCreateCharacterInput;
+export interface StylesCreateOptions {
+    dryRun?: boolean;
+    expectedRevision?: string;
+}
+export interface NormalizedStylesCreateOptions {
+    dryRun: boolean;
+    expectedRevision: string | undefined;
+}
+export interface StylesCreateResolution {
+    scope: 'style';
+    id: string;
+    type: 'paragraph' | 'character';
+    xmlPart: string;
+    /**
+     * Literal, not `string`: `styles.apply` pins its two paths in the published
+     * schema and exports them as constants for the adapter to bind to. Without
+     * the narrowing an adapter could report the more specific
+     * `w:styles/w:style[@w:styleId='X']`, type-check, and then fail the schema.
+     */
+    xmlPath: typeof STYLE_XML_PATH;
+}
+/** The `w:style` element path. Predicate-free, like `XML_PATH_BY_CHANNEL`. */
+export declare const STYLE_XML_PATH = "w:styles/w:style";
+/**
+ * Per-channel state, unlike {@link StylesApplyReceipt}'s flat map.
+ *
+ * `styles.apply` can be flat because `resolution.channel` says which channel
+ * the map describes. One `w:style` carries both at once, and `snapToGrid`,
+ * `shading` and `borders` exist on both — `borders` with genuinely different
+ * shapes (`w:bdr`, one border, against `w:pBdr`, six edges). Folded together
+ * they would be indistinguishable.
+ */
+export interface StyleChannelState {
+    paragraph: StylesStateMap | null;
+    run: StylesStateMap | null;
+}
+export interface StylesCreateReceiptSuccess {
+    success: true;
+    /** `false` when the definition already matched the input. */
+    changed: boolean;
+    /**
+     * `false` when an existing style was redefined under `conflictPolicy:
+     * 'replace'`. `created: true` implies `changed: true`. Under `dryRun` it
+     * describes what the call would have done.
+     *
+     * `ReceiptSuccess.inserted` / `updated` are deliberately not used: they take
+     * `EntityAddress`, and a style definition is not addressable as a document
+     * entity.
+     */
+    created: boolean;
+    resolution: StylesCreateResolution;
+    dryRun: boolean;
+    /** `null` when the style did not exist. */
+    before: StyleChannelState | null;
+    after: StyleChannelState;
+}
+export interface StylesCreateReceiptFailure {
+    success: false;
+    failure: ReceiptFailure;
+}
+export type StylesCreateReceipt = StylesCreateReceiptSuccess | StylesCreateReceiptFailure;
+export interface StylesCreateAdapter {
+    create(input: StylesCreateInput, options: NormalizedStylesCreateOptions): StylesCreateReceipt;
+}
+export interface StylesCreateApi {
+    create(input: StylesCreateInput, options?: StylesCreateOptions): StylesCreateReceipt;
+}
+/**
+ * Validates the shape of `styles.create` input.
+ *
+ * Deliberately shallow on identifiers: `id` is checked for "non-empty string"
+ * and nothing more, exactly as `styles.paragraph.setStyleRef` checks the same
+ * field. `w:styleId` is an `ST_String`, real documents carry ids with spaces,
+ * and a stricter rule here would mean `setStyleRef` could apply a style that
+ * `styles.create` cannot express.
+ */
+export declare function validateStylesCreateInput(input: unknown): asserts input is StylesCreateInput;
+export declare function validateStylesCreateOptions(options: unknown): void;
+/**
+ * Executes `styles.create` using the provided adapter.
+ *
+ * Fails closed when the host engine has no `create` hook, the same way
+ * `executeStylesGetCatalog` does for its optional catalogue hook — input is
+ * validated first, so a malformed call is reported as malformed rather than as
+ * an unavailable capability.
+ */
+export declare function executeStylesCreate(adapter: Partial<StylesCreateAdapter> | null | undefined, input: StylesCreateInput, options?: StylesCreateOptions): StylesCreateReceipt;
+export {};

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

@@ -3,12 +3,16 @@
  *
  * 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 type { ValueSchema, StylesChannel, StylesScope, MergeStrategy, PropertyDefinition } from './registry.js';
+export { PROPERTY_REGISTRY, ALLOWED_KEYS_BY_CHANNEL, EXCLUDED_KEYS, STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, 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 type { StyleRunPatch, StyleConflictPolicy, StyleChannelState, StylesCreateParagraphInput, StylesCreateCharacterInput, StylesCreateInput, StylesCreateOptions, NormalizedStylesCreateOptions, StylesCreateResolution, StylesCreateReceiptSuccess, StylesCreateReceiptFailure, StylesCreateReceipt, StylesCreateAdapter, StylesCreateApi, } from './create.js';
+export { STYLE_XML_PATH, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, } from './create.js';
+export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, 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 { StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './theme.js';
+export { executeStylesGetTheme, validateStylesGetThemeInput } from './theme.js';
 export type { PatchKeyClassification } from './validation.js';
-export { validateValue, classifyPatchKey } from './validation.js';
+export { validateValue, classifyPatchKey, validatePatchObject } from './validation.js';

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

@@ -1,4 +1,4 @@
-import { ST_UNDERLINE_VALUES } from '../inline-semantics/token-sets.js';
+import { ST_HIGHLIGHT_VALUES, 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"];
@@ -6,7 +6,7 @@ export declare const ST_TEXT_DIRECTION: readonly ["lrTb", "tbRl", "btLr", "lrTbV
 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 };
+export { ST_HIGHLIGHT_VALUES, ST_UNDERLINE_VALUES };
 /** Recursive schema AST describing the shape of a property value. */
 export type ValueSchema = {
     kind: 'boolean';
@@ -41,3 +41,35 @@ export declare const ALLOWED_KEYS_BY_CHANNEL: Record<StylesChannel, Set<string>>
 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>;
+/**
+ * Where in `word/styles.xml` a patch is being written.
+ *
+ * The exclusion list is a property of the *destination*, not of the property:
+ * `w:rtl` is disallowed in `w:docDefaults` and perfectly legal on a named
+ * `w:style`. Before this split, `EXCLUDED_KEYS` was the docDefaults list and
+ * the only list, so every caller inherited a restriction that only one of
+ * them was subject to.
+ *
+ * `docDefaults` is unchanged and remains what `styles.apply` uses.
+ */
+export type StylesScope = 'docDefaults' | 'style';
+/**
+ * Keys excluded from a named `w:style`.
+ *
+ * Narrower than the docDefaults list on the run channel by exactly the four
+ * properties the style model reads back off a `w:style` (see the registry
+ * entries). `w:rPrChange` stays out because it is a revision-tracking wrapper
+ * around document content, and `w:rStyle` because the style model does not
+ * carry it on `StyleDefinition.runProperties`.
+ *
+ * The paragraph channel is unchanged: every key it excludes — `w:cnfStyle`,
+ * `w:divId`, `w:pPrChange`, `w:pStyle`, `w:pPr/w:rPr`, `w:sectPr` — is as
+ * out of place inside `w:style/w:pPr` as it is inside docDefaults. Run
+ * properties on a style live in `w:style/w:rPr`, which is the `run` channel
+ * here, not in `w:pPr/w:rPr`.
+ */
+export declare const STYLE_EXCLUDED_KEYS: Record<StylesChannel, Map<string, string>>;
+/** Exclusion lists by destination. Defaults everywhere are `docDefaults`. */
+export declare const EXCLUDED_KEYS_BY_SCOPE: Record<StylesScope, Record<StylesChannel, Map<string, string>>>;
+/** Human-readable destination, for validation messages. */
+export declare const SCOPE_LABEL: Record<StylesScope, string>;

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

@@ -1,9 +1,28 @@
-import { ValueSchema, StylesChannel } from './registry.js';
+import { ValueSchema, StylesChannel, StylesScope } 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;
+/**
+ * Builds a JSON Schema for the patch object of a given channel and scope.
+ *
+ * The scope filter is what keeps the published `styles.apply` schema honest:
+ * the registry now carries run properties that only a named style accepts, and
+ * a schema that advertised them on `docDefaults` would describe an input the
+ * validator rejects.
+ */
+export declare function buildPatchSchema(channel: StylesChannel, scope?: StylesScope): JsonSchema;
+/**
+ * Builds a JSON Schema for the before/after state map of a given scope.
+ *
+ * Scoped for the same reason `buildPatchSchema` is: a receipt cannot report
+ * state for a property the scope does not accept, and advertising one both
+ * misleads a contract-driven caller and loosens receipt validation, since these
+ * objects carry `additionalProperties: false`.
+ *
+ * `channel` narrows it further, for a receipt that reports the two channels
+ * separately. Omitted, both fold into one map — correct only where something
+ * else in the receipt says which channel it describes, as `styles.apply`'s
+ * `resolution.channel` does.
+ */
+export declare function buildStateSchema(scope?: StylesScope, channel?: StylesChannel): JsonSchema;
 export {};

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

@@ -0,0 +1,32 @@
+import { SDTheme } from '../types/sd-styles.js';
+import { StyleCatalogDiagnostic, StyleSourcePartStatus } from './catalog.js';
+/** `styles.getTheme` takes no options. */
+export type StylesGetThemeInput = Record<string, never>;
+/**
+ * Status of the package parts the theme is read from. A `missing` or
+ * `malformed` theme part still yields a theme: the default Office theme,
+ * labeled `source: 'fallback'`.
+ */
+export interface StylesThemeSourceStatus {
+    theme: StyleSourcePartStatus;
+    /** `word/settings.xml`, which carries `w:clrSchemeMapping`. */
+    settings: StyleSourcePartStatus;
+}
+export interface StylesGetThemeResult {
+    /** Always present. `source` says whether it is the document's own theme or the Office fallback. */
+    theme: SDTheme & {
+        source: 'document' | 'fallback';
+    };
+    sourceStatus: StylesThemeSourceStatus;
+    diagnostics: StyleCatalogDiagnostic[];
+}
+export interface StylesGetThemeAdapter {
+    getTheme(input?: StylesGetThemeInput): StylesGetThemeResult;
+}
+/** Validates `styles.getTheme` input. `undefined` and `{}` are the only valid calls. */
+export declare function validateStylesGetThemeInput(input?: StylesGetThemeInput): void;
+/**
+ * Executes `styles.getTheme` using the provided adapter.
+ * Validates input, then delegates to the adapter.
+ */
+export declare function executeStylesGetTheme(adapter: Partial<StylesGetThemeAdapter> | null | undefined, input?: StylesGetThemeInput): StylesGetThemeResult;

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

@@ -1,4 +1,4 @@
-import { ValueSchema, StylesChannel } from './registry.js';
+import { ValueSchema, StylesChannel, StylesScope } from './registry.js';
 /**
  * Validates a value against a ValueSchema AST node.
  *
@@ -35,4 +35,13 @@ export type PatchKeyClassification = {
  * nesting conditionals across excluded-key maps, allowed-key sets, and
  * cross-channel lookups.
  */
-export declare function classifyPatchKey(key: string, channel: StylesChannel): PatchKeyClassification;
+export declare function classifyPatchKey(key: string, channel: StylesChannel, scope?: StylesScope): PatchKeyClassification;
+/**
+ * Validates the keys and values of a patch object against one channel.
+ *
+ * Shared by `styles.apply` (scope `docDefaults`) and `styles.create` (scope
+ * `style`); `field` names the caller's own input path so the error points at
+ * `patch` or at `run` / `paragraph` rather than at whichever one happened to
+ * write this code.
+ */
+export declare function validatePatchObject(patch: Record<string, unknown>, channel: StylesChannel, scope: StylesScope, field: string): void;

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

@@ -3,19 +3,17 @@
  *
  * 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:
+ * body/story content. Source body content is never copied; `word/document.xml`
+ * is rewritten only to adopt section defaults. 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`.
+ *   singletons replace the target's. Source-only styles are imported; all
+ *   target-only styles are retained.
+ * - `numbering`: every source `w:abstractNum`/`w:num` is appended. Colliding
+ *   ids are remapped deterministically, and imported styles are rewritten to
+ *   the remapped ids. Re-applying the same source appends the definitions again.
  * - `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.
@@ -24,7 +22,8 @@
  *   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.
+ *   reallocated and references rewritten consistently. Re-applying the same
+ *   source imports the parts again under new names.
  * - `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`,
@@ -32,11 +31,10 @@
  *   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.
+ * Other source parts are never applied. `customXml` is reported as an
+ * out-of-scope skipped scope. `customXml`, `docProps`, comments, notes, people,
+ * glossary, signatures, embeddings, and body media are reported in
+ * `unsupportedItems`.
  *
  * Engine-agnostic contract + execution entry point. No ProseMirror/converter imports.
  */

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

@@ -116,6 +116,7 @@ export interface TocRemoveInput {
 }
 export interface TocMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     toc: TocAddress;
 }
 export interface TocMutationFailure {
@@ -147,6 +148,7 @@ export interface CreateTableOfContentsInput {
 }
 export interface CreateTableOfContentsSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     toc: TocAddress;
 }
 export interface CreateTableOfContentsFailure {
@@ -238,6 +240,7 @@ export interface TocEntryDomain {
 export type TocListEntriesResult = DiscoveryOutput<TocEntryDomain>;
 export interface TocEntryMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     entry: TocEntryAddress;
 }
 export interface TocEntryMutationFailure {

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

@@ -1,5 +1,5 @@
 import { BlockNodeType, BlockNodeAddress, DeletableBlockNodeAddress } from './base.js';
-import { AffectedRef, AffectedRefRemapping, Receipt, ReceiptFailure, ReceiptInsert, TextRangeShift } from './receipt.js';
+import { AffectedRef, AffectedRefRemapping, Receipt, ReceiptFailure, ReceiptInsert, ReceiptSuccess, TextRangeShift } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 import { ParagraphNumbering } from './paragraph.types.js';
 import { SDProjectionReviewMode } from './content-projection.js';
@@ -117,6 +117,7 @@ export interface BlocksDeleteInput {
 }
 export interface BlocksDeleteResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     deleted: DeletableBlockNodeAddress;
     deletedBlock?: DeletedBlockSummary;
     trackedChangeRefs?: ReceiptInsert[];
@@ -145,6 +146,7 @@ export interface BlocksSplitInput {
 }
 export interface BlocksSplitSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Address of the new paragraph created by the split (the tail). */
     inserted: BlockNodeAddress;
     /**
@@ -173,6 +175,7 @@ export interface BlocksMergeInput {
 }
 export interface BlocksMergeSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Address of the paragraph that was removed (the second paragraph). */
     removed: BlockNodeAddress;
     /**
@@ -208,6 +211,7 @@ export interface BlocksMoveInput {
 }
 export interface BlocksMoveSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Same `source` paragraph, now relocated. */
     moved: BlockNodeAddress;
     remappedRefs?: AffectedRefRemapping[];
@@ -229,6 +233,7 @@ export type BlocksMoveResult = BlocksMoveSuccessResult | BlocksMoveFailureResult
 export type { Receipt };
 export interface BlocksDeleteRangeResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     deletedCount: number;
     deletedBlocks: DeletedBlockSummary[];
     revision: {

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

@@ -1,7 +1,7 @@
 import { TextAddress } from './address.js';
 import { BlockNodeAddress } from './base.js';
 import { ResolvedHandle } from './discovery.js';
-import { ReceiptFailure, ReceiptInsert } from './receipt.js';
+import { ReceiptFailure, ReceiptInsert, ReceiptSuccess } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 export type ParagraphCreateLocation = {
     kind: 'documentStart';
@@ -29,6 +29,7 @@ export interface CreateParagraphInput {
 }
 export interface CreateParagraphSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     paragraph: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
@@ -95,6 +96,7 @@ export interface CreateHeadingInput {
 }
 export interface CreateHeadingSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     heading: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];

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

@@ -2,6 +2,7 @@ import { SDContentNode } from './sd-nodes.js';
 import { SDStyles, SDDocDefaults, SDTheme } from './sd-styles.js';
 import { SDNumberingCatalog, SDSection, SDReferenceCatalogs, SDAnnotations } from './sd-sections.js';
 import { SDDocumentMeta } from './sd-props.js';
+import { SDDiagnostic } from './sd-contract.js';
 /** Structural content payload for insert and replace operations. */
 export type SDFragment = SDContentNode | SDContentNode[];
 export interface SDDocument {
@@ -15,6 +16,8 @@ export interface SDDocument {
     referenceCatalogs?: SDReferenceCatalogs;
     annotations?: SDAnnotations;
     metadata?: SDDocumentMeta;
+    /** Missing, malformed or fallback package parts, and read options not honored yet. */
+    diagnostics?: SDDiagnostic[];
 }
 export declare const SD_CONTENT_NODE_KINDS: readonly ["paragraph", "heading", "list", "table", "toc", "index", "bibliography", "tableOfAuthorities", "break", "horizontalRule", "sectionBreak", "sectPr", "image", "drawing", "sdt", "customXml", "altChunk", "math", "field"];
 export type SDContentNodeKind = (typeof SD_CONTENT_NODE_KINDS)[number];

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

@@ -233,6 +233,8 @@ export type StructuralStepData = {
 export type StepOutcomeData = TextStepData | AssertStepData | DomainStepData | TableStepData | StructuralStepData;
 export type StepOutcome = {
     stepId: string;
+    /** Effective mode when all committed requests in this step used the same mode. */
+    appliedChangeMode?: ChangeMode;
     op: string;
     effect: StepEffect;
     matchCount: number;
@@ -241,6 +243,8 @@ export type StepOutcome = {
 };
 export type PlanReceipt = {
     success: true;
+    /** Effective mode when every committed step used the same mode. */
+    appliedChangeMode?: ChangeMode;
     revision: {
         before: string;
         after: string;

package/dist/document-api/src/types/query-match.types.d.ts

@@ -4,6 +4,7 @@ import { TextSelector, NodeSelector } from './query.js';
 import { DiscoveryItem, DiscoveryResult } from './discovery.js';
 import { InlineToggleDirective } from './style-policy.types.js';
 import { StoryLocator } from './story.types.js';
+import { StyleCatalogPreviewSources } from '../styles/catalog.js';
 export type CardinalityRequirement = 'any' | 'first' | 'exactlyOne' | 'all';
 /** Maximum total length for a match snippet (D11). */
 export declare const SNIPPET_MAX_LENGTH = 500;
@@ -27,12 +28,32 @@ export interface MatchDirectStyles {
     underline: InlineToggleDirective;
     strike: InlineToggleDirective;
 }
-/** Effective visual states: what the user sees after style cascade resolution. */
+/**
+ * Where an effective font or color came from: set as a literal value, or a
+ * theme reference (with tint/shade). Same vocabulary as catalog preview sources.
+ */
+export type MatchEffectiveSources = StyleCatalogPreviewSources;
+/**
+ * Effective visual states: what the user sees after style cascade resolution
+ * (direct run formatting, character style, paragraph style chain, table style,
+ * document defaults, theme). The optional values are present when the cascade
+ * resolved them; `meta.effectiveResolved` says whether it ran.
+ */
 export interface MatchEffectiveStyles {
     bold: boolean;
     italic: boolean;
     underline: boolean;
     strike: boolean;
+    /** 6-digit lowercase hex with `#` prefix. Theme colors are resolved, tint/shade applied. */
+    color?: string;
+    /** 6-digit lowercase hex with `#` prefix. */
+    highlight?: string;
+    /** Latin-track font family. Theme fonts are resolved to the theme's typeface. */
+    fontFamily?: string;
+    /** Font size in points, rounded to 1 decimal place. */
+    fontSizePt?: number;
+    /** Origin of `fontFamily` and `color`. A value without a source is absent. */
+    sources?: MatchEffectiveSources;
 }
 /**
  * Two-layer inline style state for a single run.
@@ -171,16 +192,33 @@ export type QueryMatchItem = DiscoveryItem<QueryMatchDomain>;
 export type TextMatchItem = DiscoveryItem<TextMatchDomain>;
 /** Node match item (blocks.length === 0). */
 export type NodeMatchItem = DiscoveryItem<NodeMatchDomain>;
+/**
+ * Why `styles.effective` could not be fully resolved for a match result.
+ *
+ * - `tracked-view-unresolved`: tracked-view matches (`includeDeletedText`) are not cascade-resolved.
+ * - `theme-fallback`: a theme font or color came from the default Office theme because the
+ *   document's theme part or color scheme is missing or unreadable.
+ * - `style-parts-unavailable`: the document's style parts were not loaded, so styles were not applied.
+ * - `run-projection-unavailable`: the matched text could not be split into runs.
+ */
+export type QueryMatchDiagnosticCode = 'tracked-view-unresolved' | 'theme-fallback' | 'style-parts-unavailable' | 'run-projection-unavailable';
+export interface QueryMatchDiagnostic {
+    code: QueryMatchDiagnosticCode;
+    message: string;
+}
 /**
  * Metadata for `query.match`: always present on the output envelope.
  *
- * - `effectiveResolved: true`: converter context was available; `styles.effective`
- *   on every run reflects full cascade resolution.
- * - `effectiveResolved: false`: converter context was unavailable (headless/non-DOCX);
- *   `styles.effective` is derived from `direct` only.
+ * - `effectiveResolved: true`: `styles.effective` on every run reflects full
+ *   style cascade and theme resolution.
+ * - `effectiveResolved: false`: at least one run was not fully resolved, or the
+ *   engine derives `styles.effective` from `direct` only. `diagnostics`, when
+ *   present, says why.
  */
 export interface QueryMatchMeta {
     effectiveResolved: boolean;
+    /** Reasons the result is not fully resolved. Absent when there are none. */
+    diagnostics?: QueryMatchDiagnostic[];
 }
 export interface QueryMatchInput {
     /** Selector for query.match. Text selectors may opt into deleted tracked text via `includeDeletedText`. */

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

@@ -2,6 +2,7 @@ import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, Tr
 import { BlockNodeAddress } from './base.js';
 import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
 import { StoryLocator } from './story.types.js';
+import { ChangeMode } from '../write/write.js';
 export type ReceiptInsert = TrackedChangeAddress;
 export type ReceiptEntity = EntityAddress;
 export type AffectedRef = TextAddress | BookmarkAddress | EntityAddress | BlockNavigationAddress;
@@ -109,6 +110,13 @@ export interface ReceiptEffects {
 }
 export type ReceiptSuccess = {
     success: true;
+    /**
+     * Mode in which this call's document content was committed. An edit folded
+     * into the author's existing insertion is tracked; auxiliary style and
+     * numbering definition writes do not change the content mode. Omitted for
+     * dry runs, no-ops, and operations that do not author reviewable content.
+     */
+    appliedChangeMode?: ChangeMode;
     /**
      * Convenience id for operations that create exactly one primary durable entity.
      * Generic consumers should prefer `inserted`; this field exists for simple

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

@@ -23,6 +23,8 @@ export interface SDError {
 export type MutationResolutionTarget = TextAddress | BlockNodeAddress | BodyStoryLocator;
 export interface SDMutationReceipt {
     success: boolean;
+    /** Effective content mode on a committed success; absent for no-op and dry-run calls. */
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Rich HTML/Markdown fidelity outcome, when this receipt came from a rich write. */
     outcome?: SDHtmlMarkdownOutcome;
     failure?: SDError;