superdoc 2.27.0 → 2.28.0-next.1

package/dist/chunks/{create-super-doc-ui-cHUUipYM.es.js → create-super-doc-ui-B29zw5qD.es.js}

@@ -2458,6 +2458,69 @@ function createDialogWorkflow(editor, options, onSuccess) {
 	};
 }
 //#endregion
+//#region src/public/ui/style-match-patch.ts
+var STYLE_MATCH_KEYS = [
+	["bold", "bold"],
+	["italic", "italic"],
+	["underline", "underline"],
+	["color", "color"],
+	["fontSize", "fontSize"],
+	["rFonts", "fontFamily"]
+];
+var STYLE_MATCH_READ_KEYS = [...STYLE_MATCH_KEYS.map(([readKey]) => readKey), "rStyle"];
+function buildStyleMatchPatch(effective, direct, options) {
+	const patch = {};
+	const characterStyle = direct.properties.rStyle;
+	const hasCharacterStyle = characterStyle != null && characterStyle.state !== "unset";
+	for (const [readKey, styleKey] of STYLE_MATCH_KEYS) {
+		const read = effective.properties[readKey];
+		if (read?.state !== "uniform") continue;
+		if (options.selectionUsesStyle && !hasCharacterStyle && direct.properties[readKey]?.state === "unset") continue;
+		patch[styleKey] = toStyleValue(readKey, read.value);
+	}
+	return patch;
+}
+function toStyleValue(key, value) {
+	switch (key) {
+		case "bold":
+		case "italic": return value === true;
+		case "underline": return underlineValue(value);
+		case "color": return typeof value === "string" && value.length > 0 ? { val: value.replace(/^#/, "") } : null;
+		case "fontSize": return typeof value === "number" && Number.isFinite(value) ? Math.round(value * 2) : null;
+		case "rFonts": return fontsValue(value);
+		default: return null;
+	}
+}
+function underlineValue(value) {
+	if (value === true) return { val: "single" };
+	if (!value || typeof value !== "object") return { val: "none" };
+	const underline = value;
+	const result = { val: typeof underline.style === "string" && underline.style ? underline.style : "single" };
+	if (typeof underline.color === "string") result.color = underline.color;
+	if (typeof underline.themeColor === "string") result.themeColor = underline.themeColor;
+	return result;
+}
+var FONT_SLOTS = {
+	ascii: "ascii",
+	hAnsi: "hAnsi",
+	eastAsia: "eastAsia",
+	cs: "cs",
+	asciiTheme: "asciiTheme",
+	hAnsiTheme: "hAnsiTheme",
+	eastAsiaTheme: "eastAsiaTheme",
+	csTheme: "cstheme",
+	hint: "hint"
+};
+function fontsValue(value) {
+	if (!value || typeof value !== "object") return null;
+	const result = {};
+	for (const [slot, styleSlot] of Object.entries(FONT_SLOTS)) {
+		const font = value[slot];
+		if (typeof font === "string" && font.length > 0) result[styleSlot] = font;
+	}
+	return Object.keys(result).length > 0 ? result : null;
+}
+//#endregion
 //#region src/public/ui/format-painter-helpers.js
 /**
 * Maps SDRunProps field names to InlineRunPatch field names.
@@ -7099,7 +7162,7 @@ function createSuperDocUI(options) {
 			failureCount: retryingSameToken ? prev.failureCount ?? 0 : 0,
 			retryAtMs: 0
 		});
-		Promise.resolve(raw).then((resolved) => {
+		const settled = Promise.resolve(raw).then((resolved) => {
 			const entry = asyncReads.get(key);
 			if (!entry || entry.inflightToken !== token) return;
 			asyncReads.set(key, {
@@ -7138,6 +7201,7 @@ function createSuperDocUI(options) {
 			const retryAtMs = Date.now() + retryDelayMs;
 			asyncReads.set(key, {
 				...entry,
+				settled: void 0,
 				inflightToken: null,
 				failedToken: token,
 				failureCount,
@@ -7145,6 +7209,8 @@ function createSuperDocUI(options) {
 			});
 			scheduleAsyncReadFailureRetry(retryAtMs);
 		});
+		const entry = asyncReads.get(key);
+		if (entry?.inflightToken === token) entry.settled = settled;
 		return null;
 	};
 	/**
@@ -14730,6 +14796,92 @@ function createSuperDocUI(options) {
 			}
 		}, 120);
 	};
+	const updateStyleToMatchSelection = (input) => {
+		const mode = readDocumentMode();
+		if (mode === "viewing") return failedReceipt("The document is read-only.", "DOCUMENT_READONLY");
+		if (mode === "suggesting") return failedReceipt("A style definition cannot be changed as a tracked suggestion.", "PRECONDITION_FAILED");
+		const sourceToken = contentToken();
+		const readPositionKey = () => {
+			const snapshot = readHostSelectionSnapshot();
+			if (!snapshot) return null;
+			return JSON.stringify({
+				story: snapshot.story,
+				tableCells: snapshot.tableCells,
+				points: ["anchor", "focus"].map((side) => {
+					const point = snapshot[side];
+					return point ? [
+						point.blockId,
+						point.blockOffset,
+						point.trackedBlockOffset,
+						point.story,
+						point.inlineAffinity,
+						point.outsideContentControl,
+						point.visualCaret
+					] : null;
+				})
+			});
+		};
+		const requestedPosition = readPositionKey();
+		const stale = failedReceipt("The selection or document changed while reading its style.", "REVISION_MISMATCH");
+		return readSelectionInfoFresh().then((selection) => {
+			const selectionToken = selectionKey(selection);
+			const isCurrent = () => !disposed && contentToken() === sourceToken && readPositionKey() === requestedPosition && selectionKey(state.selection) === selectionToken && readDocumentMode() === mode;
+			if (!isCurrent()) return stale;
+			const active = computeActiveParagraphStyle(selection, getStyleCatalog().cache).style;
+			const story = storyLocatorSignature(selectionStory(selection));
+			const keys = [styleCatalogReadKey({ includePreview: true }), ...selectionBlockIds(selection).map((id) => `node:${story}:${id}`)];
+			const unreadable = failedReceipt("The selection formatting could not be read.", "PRECONDITION_FAILED");
+			const run = (active) => {
+				if (keys.some((key) => {
+					const entry = asyncReads.get(key);
+					return entry && (!entry.hasSettled || entry.token !== sourceToken || entry.failedToken === sourceToken);
+				})) return unreadable;
+				const styleId = input?.styleId ?? active.styleId;
+				if (!styleId) return failedReceipt("Choose a style to update: the selection does not have a single paragraph style.", "INVALID_TARGET");
+				const doc = getDoc();
+				const readSelection = resolveDocOperation(doc, "format.readSelection");
+				const apply = resolveDocOperation(doc, "styles.apply");
+				if (!readSelection || !apply) return failedReceipt("Updating a style to match the selection is unavailable.");
+				let reads;
+				try {
+					reads = [readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "effective"
+					}), readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "direct"
+					})];
+				} catch {
+					return unreadable;
+				}
+				return Promise.all(reads).then(([effective, direct]) => {
+					if (!isCurrent()) return stale;
+					const patch = buildStyleMatchPatch(effective, direct, { selectionUsesStyle: !active.mixed && active.styleId === styleId });
+					if (Object.keys(patch).length === 0) return failedReceipt("The selection already matches the style.", "NO_OP");
+					const fallback = failedReceipt("Updating the style failed.");
+					return safeCall(() => settleWorkflowReceipt(apply({
+						target: {
+							scope: "style",
+							styleId,
+							channel: "run"
+						},
+						patch
+					}), fallback), fallback);
+				}, () => unreadable);
+			};
+			const pending = keys.flatMap((key) => {
+				const entry = asyncReads.get(key);
+				return entry?.inflightToken === sourceToken && entry.settled ? [entry.settled] : [];
+			});
+			if (pending.length === 0) return run(active);
+			return Promise.all(pending).then(() => {
+				if (!isCurrent()) return stale;
+				return run(computeActiveParagraphStyle(selection, getStyleCatalog().cache).style);
+			});
+		});
+	};
 	const stylesSub = sliceHandle((s) => s.styles);
 	const stylesSnap = snapshotHandle(stylesSub);
 	const styles = {
@@ -14742,7 +14894,8 @@ function createSuperDocUI(options) {
 			return readStyleCatalogLive(options).value;
 		},
 		getQuickGallery: () => stylesSub.get().quickGallery,
-		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style
+		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style,
+		updateToMatchSelection: (input) => updateStyleToMatchSelection(input)
 	};
 	const openWatermarkSurface = hostMethod(superdoc, "openSurface");
 	const watermark = createWatermarkController({

package/dist/chunks/{create-super-doc-ui-DpVh2nQH.cjs → create-super-doc-ui-D1eOhAjv.cjs}

@@ -2459,6 +2459,69 @@ function createDialogWorkflow(editor, options, onSuccess) {
 	};
 }
 //#endregion
+//#region src/public/ui/style-match-patch.ts
+var STYLE_MATCH_KEYS = [
+	["bold", "bold"],
+	["italic", "italic"],
+	["underline", "underline"],
+	["color", "color"],
+	["fontSize", "fontSize"],
+	["rFonts", "fontFamily"]
+];
+var STYLE_MATCH_READ_KEYS = [...STYLE_MATCH_KEYS.map(([readKey]) => readKey), "rStyle"];
+function buildStyleMatchPatch(effective, direct, options) {
+	const patch = {};
+	const characterStyle = direct.properties.rStyle;
+	const hasCharacterStyle = characterStyle != null && characterStyle.state !== "unset";
+	for (const [readKey, styleKey] of STYLE_MATCH_KEYS) {
+		const read = effective.properties[readKey];
+		if (read?.state !== "uniform") continue;
+		if (options.selectionUsesStyle && !hasCharacterStyle && direct.properties[readKey]?.state === "unset") continue;
+		patch[styleKey] = toStyleValue(readKey, read.value);
+	}
+	return patch;
+}
+function toStyleValue(key, value) {
+	switch (key) {
+		case "bold":
+		case "italic": return value === true;
+		case "underline": return underlineValue(value);
+		case "color": return typeof value === "string" && value.length > 0 ? { val: value.replace(/^#/, "") } : null;
+		case "fontSize": return typeof value === "number" && Number.isFinite(value) ? Math.round(value * 2) : null;
+		case "rFonts": return fontsValue(value);
+		default: return null;
+	}
+}
+function underlineValue(value) {
+	if (value === true) return { val: "single" };
+	if (!value || typeof value !== "object") return { val: "none" };
+	const underline = value;
+	const result = { val: typeof underline.style === "string" && underline.style ? underline.style : "single" };
+	if (typeof underline.color === "string") result.color = underline.color;
+	if (typeof underline.themeColor === "string") result.themeColor = underline.themeColor;
+	return result;
+}
+var FONT_SLOTS = {
+	ascii: "ascii",
+	hAnsi: "hAnsi",
+	eastAsia: "eastAsia",
+	cs: "cs",
+	asciiTheme: "asciiTheme",
+	hAnsiTheme: "hAnsiTheme",
+	eastAsiaTheme: "eastAsiaTheme",
+	csTheme: "cstheme",
+	hint: "hint"
+};
+function fontsValue(value) {
+	if (!value || typeof value !== "object") return null;
+	const result = {};
+	for (const [slot, styleSlot] of Object.entries(FONT_SLOTS)) {
+		const font = value[slot];
+		if (typeof font === "string" && font.length > 0) result[styleSlot] = font;
+	}
+	return Object.keys(result).length > 0 ? result : null;
+}
+//#endregion
 //#region src/public/ui/format-painter-helpers.js
 /**
 * Maps SDRunProps field names to InlineRunPatch field names.
@@ -7100,7 +7163,7 @@ function createSuperDocUI(options) {
 			failureCount: retryingSameToken ? prev.failureCount ?? 0 : 0,
 			retryAtMs: 0
 		});
-		Promise.resolve(raw).then((resolved) => {
+		const settled = Promise.resolve(raw).then((resolved) => {
 			const entry = asyncReads.get(key);
 			if (!entry || entry.inflightToken !== token) return;
 			asyncReads.set(key, {
@@ -7139,6 +7202,7 @@ function createSuperDocUI(options) {
 			const retryAtMs = Date.now() + retryDelayMs;
 			asyncReads.set(key, {
 				...entry,
+				settled: void 0,
 				inflightToken: null,
 				failedToken: token,
 				failureCount,
@@ -7146,6 +7210,8 @@ function createSuperDocUI(options) {
 			});
 			scheduleAsyncReadFailureRetry(retryAtMs);
 		});
+		const entry = asyncReads.get(key);
+		if (entry?.inflightToken === token) entry.settled = settled;
 		return null;
 	};
 	/**
@@ -14731,6 +14797,92 @@ function createSuperDocUI(options) {
 			}
 		}, 120);
 	};
+	const updateStyleToMatchSelection = (input) => {
+		const mode = readDocumentMode();
+		if (mode === "viewing") return failedReceipt("The document is read-only.", "DOCUMENT_READONLY");
+		if (mode === "suggesting") return failedReceipt("A style definition cannot be changed as a tracked suggestion.", "PRECONDITION_FAILED");
+		const sourceToken = contentToken();
+		const readPositionKey = () => {
+			const snapshot = readHostSelectionSnapshot();
+			if (!snapshot) return null;
+			return JSON.stringify({
+				story: snapshot.story,
+				tableCells: snapshot.tableCells,
+				points: ["anchor", "focus"].map((side) => {
+					const point = snapshot[side];
+					return point ? [
+						point.blockId,
+						point.blockOffset,
+						point.trackedBlockOffset,
+						point.story,
+						point.inlineAffinity,
+						point.outsideContentControl,
+						point.visualCaret
+					] : null;
+				})
+			});
+		};
+		const requestedPosition = readPositionKey();
+		const stale = failedReceipt("The selection or document changed while reading its style.", "REVISION_MISMATCH");
+		return readSelectionInfoFresh().then((selection) => {
+			const selectionToken = selectionKey(selection);
+			const isCurrent = () => !disposed && contentToken() === sourceToken && readPositionKey() === requestedPosition && selectionKey(state.selection) === selectionToken && readDocumentMode() === mode;
+			if (!isCurrent()) return stale;
+			const active = computeActiveParagraphStyle(selection, getStyleCatalog().cache).style;
+			const story = storyLocatorSignature(selectionStory(selection));
+			const keys = [styleCatalogReadKey({ includePreview: true }), ...selectionBlockIds(selection).map((id) => `node:${story}:${id}`)];
+			const unreadable = failedReceipt("The selection formatting could not be read.", "PRECONDITION_FAILED");
+			const run = (active) => {
+				if (keys.some((key) => {
+					const entry = asyncReads.get(key);
+					return entry && (!entry.hasSettled || entry.token !== sourceToken || entry.failedToken === sourceToken);
+				})) return unreadable;
+				const styleId = input?.styleId ?? active.styleId;
+				if (!styleId) return failedReceipt("Choose a style to update: the selection does not have a single paragraph style.", "INVALID_TARGET");
+				const doc = getDoc();
+				const readSelection = resolveDocOperation(doc, "format.readSelection");
+				const apply = resolveDocOperation(doc, "styles.apply");
+				if (!readSelection || !apply) return failedReceipt("Updating a style to match the selection is unavailable.");
+				let reads;
+				try {
+					reads = [readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "effective"
+					}), readSelection({
+						selection: "current",
+						keys: STYLE_MATCH_READ_KEYS,
+						view: "direct"
+					})];
+				} catch {
+					return unreadable;
+				}
+				return Promise.all(reads).then(([effective, direct]) => {
+					if (!isCurrent()) return stale;
+					const patch = buildStyleMatchPatch(effective, direct, { selectionUsesStyle: !active.mixed && active.styleId === styleId });
+					if (Object.keys(patch).length === 0) return failedReceipt("The selection already matches the style.", "NO_OP");
+					const fallback = failedReceipt("Updating the style failed.");
+					return safeCall(() => settleWorkflowReceipt(apply({
+						target: {
+							scope: "style",
+							styleId,
+							channel: "run"
+						},
+						patch
+					}), fallback), fallback);
+				}, () => unreadable);
+			};
+			const pending = keys.flatMap((key) => {
+				const entry = asyncReads.get(key);
+				return entry?.inflightToken === sourceToken && entry.settled ? [entry.settled] : [];
+			});
+			if (pending.length === 0) return run(active);
+			return Promise.all(pending).then(() => {
+				if (!isCurrent()) return stale;
+				return run(computeActiveParagraphStyle(selection, getStyleCatalog().cache).style);
+			});
+		});
+	};
 	const stylesSub = sliceHandle((s) => s.styles);
 	const stylesSnap = snapshotHandle(stylesSub);
 	const styles = {
@@ -14743,7 +14895,8 @@ function createSuperDocUI(options) {
 			return readStyleCatalogLive(options).value;
 		},
 		getQuickGallery: () => stylesSub.get().quickGallery,
-		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style
+		getActiveParagraphStyle: () => computeActiveParagraphStyle(state.selection, getStyleCatalog().cache).style,
+		updateToMatchSelection: (input) => updateStyleToMatchSelection(input)
 	};
 	const openWatermarkSurface = hostMethod(superdoc, "openSurface");
 	const watermark = createWatermarkController({

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.27.0",
+	superdocVersion: "2.28.0-next.1",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.27.0",
+	superdocVersion: "2.28.0-next.1",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/contract/operation-definitions.d.ts

@@ -42,7 +42,7 @@ export declare const OPERATION_DEFINITIONS: {
     };
     readonly 'styles.apply': {
         readonly memberPath: "styles.apply";
-        readonly description: "Apply document-level default style changes to the active Style Definitions part. Targets docDefaults run and paragraph channels with set-style patch semantics.";
+        readonly description: "Apply style changes to the active Style Definitions part. Targets docDefaults run and paragraph channels, or the run properties of an existing named paragraph style (scope \"style\"), with set-style patch semantics. Redefining a named style updates every paragraph that references it; its linked character style receives the same patch, null removes a property so the style inherits it again, and an object value replaces that property whole.";
         readonly expectedResult: "Returns a StylesApplyReceipt with per-channel success/failure details for each property change.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
@@ -2523,7 +2523,7 @@ export declare const OPERATION_DEFINITIONS: {
     readonly 'contentControls.validateWordCompatibility': {
         readonly memberPath: "contentControls.validateWordCompatibility";
         readonly description: "Validate a content control for Word compatibility issues.";
-        readonly expectedResult: "Returns a compatibility result with diagnostics.";
+        readonly expectedResult: "Returns read-only diagnostics for incompatible content structure and metadata or configuration issues. `compatible` is false only when a diagnostic has error severity; warnings leave it true.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
         readonly referenceDocPath: "content-controls/validate-word-compatibility.mdx";

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

@@ -64,7 +64,7 @@ import { CaptionsApi, CaptionsAdapter } from './captions/captions.js';
 import { FieldsApi, FieldsAdapter } from './fields/fields.js';
 import { CitationsApi, CitationsAdapter } from './citations/citations.js';
 import { AuthoritiesApi, AuthoritiesAdapter } from './authorities/authorities.js';
-export type { TemporaryMutationInput, TemporaryMutationHandleInput, TemporaryMutationCommitInput, TemporaryMutationReplaceInput, TemporaryMutationReceipt, TemporaryMutationMetadata, TemporaryMutationOperation, TemporaryOperationResultTarget, } from './types/temporary-mutation.js';
+export type { TemporaryMutationInput, TemporaryMutationHandleInput, TemporaryMutationCommitInput, TemporaryMutationReplaceInput, TemporaryMutationReceipt, TemporaryMutationMetadata, TemporaryMutationOperation, TemporaryOperationResultTarget, TemporaryOperationEffects, } from './types/temporary-mutation.js';
 export * from './types/index.js';
 export * from './contract/index.js';
 export * from './capabilities/capabilities.js';
@@ -116,10 +116,10 @@ export type { FormatReadSelectionAdapter, FormatReadSelectionInput, FormatReadSe
 export type { InlineRunPatch, InlineRunPatchKey, InlinePropertyStorage, InlinePropertyType, InlinePropertyCarrier, InlinePropertyRegistryEntry, UnderlinePatch, ShadingPatch, BorderPatch, FitTextPatch, LangPatch, RFontsPatch, EastAsianLayoutPatch, StylisticSetPatch, } from './format/inline-run-patch.js';
 export { CLEAR_INLINE_FORMATTING_KEYS, INLINE_PROPERTY_REGISTRY, INLINE_PROPERTY_KEY_SET, INLINE_PROPERTY_BY_KEY, INLINE_PROPERTY_KEYS_BY_STORAGE, validateInlineRunPatch, buildInlineRunPatchSchema, } from './format/inline-run-patch.js';
 export { PROPERTY_REGISTRY, EXCLUDED_KEYS, ALLOWED_KEYS_BY_CHANNEL, getPropertyDefinition, toJsonSchema, buildPatchSchema, buildStateSchema, } from './styles/index.js';
-export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './styles/index.js';
+export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyStyleRunInput, StylesStyleRunPatch, StylesDocDefaultsResolution, StylesStyleResolution, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './styles/index.js';
 export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalog, validateStylesGetCatalogInput, executeStylesGetTheme, validateStylesGetThemeInput, } from './styles/index.js';
 export type { StylesScope, StyleRunPatch, StyleConflictPolicy, StyleChannelState, StylesCreateAdapter, StylesCreateApi, StylesCreateInput, StylesCreateParagraphInput, StylesCreateCharacterInput, StylesCreateOptions, NormalizedStylesCreateOptions, StylesCreateResolution, StylesCreateReceipt, StylesCreateReceiptSuccess, StylesCreateReceiptFailure, } from './styles/index.js';
-export { STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, STYLE_XML_PATH, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, validatePatchObject, } from './styles/index.js';
+export { STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, STYLE_XML_PATH, STYLE_RUN_XML_PATH, validateStylesApplyInput, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, validatePatchObject, } from './styles/index.js';
 export type { TemplatesAdapter, TemplatesApi, TemplatesApplyInput, TemplatesApplyOptions, TemplatesApplySource, TemplatesApplySourcePath, TemplatesApplySourceBase64, TemplateBodyPolicy, TemplateScope, NormalizedTemplatesApplyOptions, TemplateScopeReport, TemplateSkipReason, TemplateScopeSkip, TemplateUnsupportedItem, TemplateChangeKind, TemplateChangedPart, TemplateIdMapping, TemplateApplyWarning, TemplatesApplySourceInfo, TemplatesApplyReceiptSuccess, TemplatesApplyFailureCode, TemplatesApplyReceiptFailure, TemplatesApplyReceipt, } from './templates/index.js';
 export { executeTemplatesApply } from './templates/index.js';
 export type { CreateAdapter, CreateApi } from './create/create.js';

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

@@ -1,6 +1,7 @@
 import { ReceiptFailure } from '../types/receipt.js';
 import { StylesChannel } from './registry.js';
 import { StylesGetCatalogInput, StylesGetCatalogResult } from './catalog.js';
+import { StyleRunPatch } from './create.js';
 import { StylesGetThemeInput, StylesGetThemeResult } from './theme.js';
 /** Tri-state for OOXML boolean style properties. */
 export type StylesBooleanState = 'on' | 'off' | 'inherit';
@@ -78,12 +79,22 @@ export interface StylesParagraphPatch {
     borders?: Record<string, unknown>;
     tabStops?: unknown[];
 }
-export interface StylesTargetResolution {
+export interface StylesDocDefaultsResolution {
     scope: 'docDefaults';
     channel: StylesChannel;
     xmlPart: string;
     xmlPath: string;
 }
+export interface StylesStyleResolution {
+    scope: 'style';
+    styleId: string;
+    channel: 'run';
+    xmlPart: string;
+    xmlPath: typeof STYLE_RUN_XML_PATH;
+    linkedStyleId?: string;
+}
+export type StylesTargetResolution = StylesDocDefaultsResolution | StylesStyleResolution;
+export declare const STYLE_RUN_XML_PATH = "w:styles/w:style/w:rPr";
 export interface StylesApplyRunInput {
     target: {
         scope: 'docDefaults';
@@ -98,7 +109,18 @@ export interface StylesApplyParagraphInput {
     };
     patch: StylesParagraphPatch;
 }
-export type StylesApplyInput = StylesApplyRunInput | StylesApplyParagraphInput;
+export type StylesStyleRunPatch = {
+    [K in keyof StyleRunPatch]?: StyleRunPatch[K] | null;
+};
+export interface StylesApplyStyleRunInput {
+    target: {
+        scope: 'style';
+        styleId: string;
+        channel: 'run';
+    };
+    patch: StylesStyleRunPatch;
+}
+export type StylesApplyInput = StylesApplyRunInput | StylesApplyParagraphInput | StylesApplyStyleRunInput;
 export interface StylesApplyOptions {
     dryRun?: boolean;
     expectedRevision?: string;
@@ -121,6 +143,7 @@ export type StylesApplyReceipt = StylesApplyReceiptSuccess | StylesApplyReceiptF
 export interface StylesAdapter {
     apply(input: StylesApplyRunInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyParagraphInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyStyleRunInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     /** Read the normalized style catalogue. See `styles/catalog.ts`. */
     getCatalog?(input?: StylesGetCatalogInput): StylesGetCatalogResult;
@@ -134,6 +157,7 @@ export interface NormalizedStylesApplyOptions {
 export interface StylesApi {
     apply(input: StylesApplyRunInput, options?: StylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyParagraphInput, options?: StylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyStyleRunInput, options?: StylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyInput, options?: StylesApplyOptions): StylesApplyReceipt;
     /** Read the normalized style catalogue for discovery and quick-gallery UI. */
     getCatalog(input?: StylesGetCatalogInput): StylesGetCatalogResult;

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

@@ -6,8 +6,8 @@
 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 { StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyStyleRunInput, StylesStyleRunPatch, StylesDocDefaultsResolution, StylesStyleResolution, StylesApplyInput, StylesApplyOptions, StylesStateMap, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, StylesApplyReceipt, StylesAdapter, NormalizedStylesApplyOptions, StylesApi, } from './apply.js';
+export { STYLE_RUN_XML_PATH, executeStylesApply } from './apply.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';
@@ -15,4 +15,4 @@ export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalo
 export type { StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './theme.js';
 export { executeStylesGetTheme, validateStylesGetThemeInput } from './theme.js';
 export type { PatchKeyClassification } from './validation.js';
-export { validateValue, classifyPatchKey, validatePatchObject } from './validation.js';
+export { validateValue, classifyPatchKey, validatePatchObject, validateStylesApplyInput } from './validation.js';

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

@@ -10,7 +10,9 @@ export declare function toJsonSchema(schema: ValueSchema): JsonSchema;
  * a schema that advertised them on `docDefaults` would describe an input the
  * validator rejects.
  */
-export declare function buildPatchSchema(channel: StylesChannel, scope?: StylesScope): JsonSchema;
+export declare function buildPatchSchema(channel: StylesChannel, scope?: StylesScope, options?: {
+    nullable?: boolean;
+}): JsonSchema;
 /**
  * Builds a JSON Schema for the before/after state map of a given scope.
  *

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

@@ -13,6 +13,13 @@ export type StylesApplyInputShape = {
         channel: StylesChannel;
     };
     patch: Record<string, unknown>;
+} | {
+    target: {
+        scope: 'style';
+        styleId: string;
+        channel: 'run';
+    };
+    patch: Record<string, unknown>;
 };
 export declare function validateStylesApplyInput(input: unknown): asserts input is StylesApplyInputShape;
 export declare function validateStylesApplyOptions(options: unknown): void;
@@ -36,12 +43,6 @@ export type PatchKeyClassification = {
  * cross-channel lookups.
  */
 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;
+export declare function validatePatchObject(patch: Record<string, unknown>, channel: StylesChannel, scope: StylesScope, field: string, options?: {
+    allowNull?: boolean;
+}): void;

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

@@ -173,27 +173,34 @@ export type DomainStep = {
 };
 export type MutationStep = TextRewriteStep | TextInsertStep | TextDeleteStep | StyleApplyStep | StructuralInsertStep | StructuralReplaceStep | AssertStep | DomainStep | ReviewMutationStep;
 export type { ChangeMode } from '../write/write.js';
+type MutationPlanAttribution = {
+    changeMode: 'direct';
+    author?: never;
+} | {
+    changeMode: 'tracked';
+    author?: {
+        name: string;
+    };
+};
 export type MutationsApplyInput = {
     /** Target story for the mutation plan. Omit for body (backward compatible). */
     in?: StoryLocator;
     expectedRevision?: string;
     atomic: true;
-    changeMode: ChangeMode;
     steps: MutationStep[];
-};
+} & MutationPlanAttribution;
 export type MutationsPreviewInput = {
     /** Target story for the mutation preview. Omit for body (backward compatible). */
     in?: StoryLocator;
     expectedRevision?: string;
     atomic: true;
-    changeMode: ChangeMode;
     steps: MutationStep[];
     /** Optional page over verbose resolved-target details. Defaults to the first 100 targets. */
     detail?: {
         offset?: number;
         limit?: number;
     };
-};
+} & MutationPlanAttribution;
 /** Maximum number of steps per mutation plan. */
 export declare const MAX_PLAN_STEPS = 200;
 /**

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

@@ -1,5 +1,5 @@
 import { DocumentApiSurface } from '../index.js';
-import { ReceiptFailureResult, ReceiptSuccess } from './receipt.js';
+import { ReceiptEntity, ReceiptFailureResult, ReceiptSuccess } from './receipt.js';
 import { PlainTextInsertInput } from '../insert/insert.js';
 import { ParagraphTextReplaceInput, ReplaceMutationOptions, TextReplaceInput } from '../replace/replace.js';
 import { MutationOptions, TrackedTextMutationOptions } from '../write/write.js';
@@ -74,11 +74,15 @@ export interface TemporaryMutationMetadata {
     tag: string;
     onNativeEdit?: 'cancel' | 'preserve';
 }
+export type TemporaryOperationEffects = Partial<Record<string, {
+    inserted: ReceiptEntity[];
+}>>;
 export type TemporaryMutationReceipt = (ReceiptSuccess & {
     temporary: TemporaryMutationMetadata;
     revision: {
         before: string;
         after: string;
     };
+    operationEffects?: TemporaryOperationEffects;
 }) | ReceiptFailureResult;
 export {};