sheetom 0.1.0-rc.9 → 0.1.0

package/dist/index.d.cts

@@ -1,6 +1,30 @@
 //#region src/diagnostics.d.ts
 /** Stable machine-readable codes emitted by opt-in mutation diagnostics. */
-type SheetOMDiagnosticCode = "INVALID_PRIORITY" | "INVALID_PROPERTY_VALUE" | "UNSUPPORTED_SHORTHAND_VALUE";
+type SheetOMMutationDiagnosticCode = "INVALID_PRIORITY" | "INVALID_PROPERTY_VALUE" | "UNSUPPORTED_SHORTHAND_VALUE";
+type SheetOMSerializationDiagnosticCode = "UNREPRESENTABLE_PENDING_SHORTHAND";
+type SheetOMDiagnosticCode = SheetOMMutationDiagnosticCode | SheetOMSerializationDiagnosticCode;
+/** A structured explanation for an ignored mutation. */
+interface SheetOMMutationDiagnostic {
+  code: SheetOMMutationDiagnosticCode;
+  severity: "warning";
+  operation: "setProperty";
+  message: string;
+  property: string;
+  input: string;
+  location: null;
+}
+/** A structured explanation for a best-effort serialization recovery. */
+interface SheetOMSerializationDiagnostic {
+  code: SheetOMSerializationDiagnosticCode;
+  severity: "warning";
+  operation: "serialize";
+  message: string;
+  property: string;
+  input: "";
+  location: null;
+  conflictingLonghands: readonly string[];
+}
+type SheetOMDiagnostic = SheetOMMutationDiagnostic | SheetOMSerializationDiagnostic;
 //#endregion
 //#region src/generated/css-style-declaration-properties.d.ts
 /** Named CSS properties supported by the pinned Chromium compatibility baseline. */
@@ -728,17 +752,36 @@ interface SheetOMResourceBudget {
   maxDeclarationsPerBlock?: number;
 }
 //#endregion
+//#region src/serialization-error.d.ts
+type SheetOMSerializationErrorCode = "UNREPRESENTABLE_PENDING_SHORTHAND";
+/** A reparsable stylesheet cannot faithfully represent the current CSSOM state. */
+declare class SheetOMSerializationError extends Error {
+  readonly code: SheetOMSerializationErrorCode;
+  readonly shorthand: string;
+  readonly conflictingLonghands: readonly string[];
+  constructor(shorthand: string, conflictingLonghands: readonly string[], options?: ErrorOptions);
+}
+//#endregion
 //#region src/index.d.ts
-/** A structured explanation for an ignored or recovered mutation. */
-interface SheetOMDiagnostic {
-  code: SheetOMDiagnosticCode;
-  severity: "warning";
-  operation: "setProperty";
-  message: string;
+/** One ordered declaration mutation executed by SheetOM's engine extension. */
+type CSSDeclarationMutation = {
+  kind: "set";
   property: string;
-  input: string;
-  location: null;
-}
+  value: string | null;
+  priority?: string | null;
+} | {
+  kind: "remove";
+  property: string;
+};
+/** The result at the matching index of an ordered declaration mutation batch. */
+type CSSDeclarationMutationResult = {
+  kind: "set";
+  accepted: boolean;
+  diagnostic: SheetOMDiagnostic | null;
+} | {
+  kind: "remove";
+  value: string;
+};
 /** Options for a constructed SheetOM stylesheet. */
 interface CSSStyleSheetOptions {
   baseURL?: string;
@@ -954,6 +997,8 @@ declare class CSSStyleDeclaration {
   getPropertyValue(name: string): string;
   getPropertyPriority(name: string): string;
   setProperty(name: string, value: string | null, priority?: string): void;
+  /** Apply ordered declaration mutations through one engine boundary crossing. */
+  applyMutations(mutations: readonly CSSDeclarationMutation[]): CSSDeclarationMutationResult[];
   removeProperty(name: string): string;
 }
 /** A live `@font-face` descriptor rule. */
@@ -1126,11 +1171,13 @@ declare class CSSStyleSheet {
   replace(cssText: string): Promise<CSSStyleSheet>;
   /** Serialize current state as reparsable CSS without mutating live objects. */
   serialize(): string;
-  /** Drain opt-in mutation diagnostics without affecting CSSOM behavior. */
+  /** Serialize current state only when its CSS semantics can be preserved exactly. */
+  serializeStrict(): string;
+  /** Drain opt-in mutation and serialization diagnostics without affecting CSSOM behavior. */
   takeDiagnostics(): SheetOMDiagnostic[];
 }
 /** Forgivingly parse an existing regular stylesheet without loading imports. */
 declare function parseStyleSheet(cssText: string, options?: ParseStyleSheetOptions): CSSStyleSheet;
 //#endregion
-export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSStyleSheetOptions, CSSSupportsRule, CSSViewTransitionRule, FunctionParameter, MediaList, ParseStyleSheetOptions, SheetOMDiagnostic, type SheetOMDiagnosticCode, type SheetOMResourceBudget, parseStyleSheet };
+export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSDeclarationMutation, CSSDeclarationMutationResult, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSStyleSheetOptions, CSSSupportsRule, CSSViewTransitionRule, FunctionParameter, MediaList, ParseStyleSheetOptions, type SheetOMDiagnostic, type SheetOMDiagnosticCode, type SheetOMMutationDiagnostic, type SheetOMMutationDiagnosticCode, type SheetOMResourceBudget, type SheetOMSerializationDiagnostic, type SheetOMSerializationDiagnosticCode, SheetOMSerializationError, type SheetOMSerializationErrorCode, parseStyleSheet };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,6 +1,30 @@
 //#region src/diagnostics.d.ts
 /** Stable machine-readable codes emitted by opt-in mutation diagnostics. */
-type SheetOMDiagnosticCode = "INVALID_PRIORITY" | "INVALID_PROPERTY_VALUE" | "UNSUPPORTED_SHORTHAND_VALUE";
+type SheetOMMutationDiagnosticCode = "INVALID_PRIORITY" | "INVALID_PROPERTY_VALUE" | "UNSUPPORTED_SHORTHAND_VALUE";
+type SheetOMSerializationDiagnosticCode = "UNREPRESENTABLE_PENDING_SHORTHAND";
+type SheetOMDiagnosticCode = SheetOMMutationDiagnosticCode | SheetOMSerializationDiagnosticCode;
+/** A structured explanation for an ignored mutation. */
+interface SheetOMMutationDiagnostic {
+  code: SheetOMMutationDiagnosticCode;
+  severity: "warning";
+  operation: "setProperty";
+  message: string;
+  property: string;
+  input: string;
+  location: null;
+}
+/** A structured explanation for a best-effort serialization recovery. */
+interface SheetOMSerializationDiagnostic {
+  code: SheetOMSerializationDiagnosticCode;
+  severity: "warning";
+  operation: "serialize";
+  message: string;
+  property: string;
+  input: "";
+  location: null;
+  conflictingLonghands: readonly string[];
+}
+type SheetOMDiagnostic = SheetOMMutationDiagnostic | SheetOMSerializationDiagnostic;
 //#endregion
 //#region src/generated/css-style-declaration-properties.d.ts
 /** Named CSS properties supported by the pinned Chromium compatibility baseline. */
@@ -728,17 +752,36 @@ interface SheetOMResourceBudget {
   maxDeclarationsPerBlock?: number;
 }
 //#endregion
+//#region src/serialization-error.d.ts
+type SheetOMSerializationErrorCode = "UNREPRESENTABLE_PENDING_SHORTHAND";
+/** A reparsable stylesheet cannot faithfully represent the current CSSOM state. */
+declare class SheetOMSerializationError extends Error {
+  readonly code: SheetOMSerializationErrorCode;
+  readonly shorthand: string;
+  readonly conflictingLonghands: readonly string[];
+  constructor(shorthand: string, conflictingLonghands: readonly string[], options?: ErrorOptions);
+}
+//#endregion
 //#region src/index.d.ts
-/** A structured explanation for an ignored or recovered mutation. */
-interface SheetOMDiagnostic {
-  code: SheetOMDiagnosticCode;
-  severity: "warning";
-  operation: "setProperty";
-  message: string;
+/** One ordered declaration mutation executed by SheetOM's engine extension. */
+type CSSDeclarationMutation = {
+  kind: "set";
   property: string;
-  input: string;
-  location: null;
-}
+  value: string | null;
+  priority?: string | null;
+} | {
+  kind: "remove";
+  property: string;
+};
+/** The result at the matching index of an ordered declaration mutation batch. */
+type CSSDeclarationMutationResult = {
+  kind: "set";
+  accepted: boolean;
+  diagnostic: SheetOMDiagnostic | null;
+} | {
+  kind: "remove";
+  value: string;
+};
 /** Options for a constructed SheetOM stylesheet. */
 interface CSSStyleSheetOptions {
   baseURL?: string;
@@ -954,6 +997,8 @@ declare class CSSStyleDeclaration {
   getPropertyValue(name: string): string;
   getPropertyPriority(name: string): string;
   setProperty(name: string, value: string | null, priority?: string): void;
+  /** Apply ordered declaration mutations through one engine boundary crossing. */
+  applyMutations(mutations: readonly CSSDeclarationMutation[]): CSSDeclarationMutationResult[];
   removeProperty(name: string): string;
 }
 /** A live `@font-face` descriptor rule. */
@@ -1126,11 +1171,13 @@ declare class CSSStyleSheet {
   replace(cssText: string): Promise<CSSStyleSheet>;
   /** Serialize current state as reparsable CSS without mutating live objects. */
   serialize(): string;
-  /** Drain opt-in mutation diagnostics without affecting CSSOM behavior. */
+  /** Serialize current state only when its CSS semantics can be preserved exactly. */
+  serializeStrict(): string;
+  /** Drain opt-in mutation and serialization diagnostics without affecting CSSOM behavior. */
   takeDiagnostics(): SheetOMDiagnostic[];
 }
 /** Forgivingly parse an existing regular stylesheet without loading imports. */
 declare function parseStyleSheet(cssText: string, options?: ParseStyleSheetOptions): CSSStyleSheet;
 //#endregion
-export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSStyleSheetOptions, CSSSupportsRule, CSSViewTransitionRule, FunctionParameter, MediaList, ParseStyleSheetOptions, SheetOMDiagnostic, type SheetOMDiagnosticCode, type SheetOMResourceBudget, parseStyleSheet };
+export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSDeclarationMutation, CSSDeclarationMutationResult, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSStyleSheetOptions, CSSSupportsRule, CSSViewTransitionRule, FunctionParameter, MediaList, ParseStyleSheetOptions, type SheetOMDiagnostic, type SheetOMDiagnosticCode, type SheetOMMutationDiagnostic, type SheetOMMutationDiagnosticCode, type SheetOMResourceBudget, type SheetOMSerializationDiagnostic, type SheetOMSerializationDiagnosticCode, SheetOMSerializationError, type SheetOMSerializationErrorCode, parseStyleSheet };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,9 +4,9 @@ import { fileURLToPath } from "node:url";
 //#endregion
 //#region src/internal/engine-binding.ts
 const expectedEngineAbiIdentity = Object.freeze({
-	abiVersion: 1,
-	sheetomVersion: "0.1.0-rc.9",
-	syntaxEngineSetSha256: "2af7ec76ba46a3f20f74a90172a708afab5dcb20f45b658a4d975caed76dc855"
+	abiVersion: 3,
+	sheetomVersion: "0.1.0",
+	syntaxEngineSetSha256: "31990c26ede4e17c3a8941027f92b2be96a167984d0ab6529e724c3d6126be50"
 });
 var SheetOMEngineBindingError = class extends Error {
 	code;
@@ -90,16 +90,47 @@ function limitValue(value, name, fallback, maximum = maximumUnsignedLong) {
 	throw new RangeError(`${name} must be an integer between 0 and ${maximum}`);
 }
 //#endregion
+//#region src/serialization-error.ts
+/** A reparsable stylesheet cannot faithfully represent the current CSSOM state. */
+var SheetOMSerializationError = class extends Error {
+	code;
+	shorthand;
+	conflictingLonghands;
+	constructor(shorthand, conflictingLonghands, options) {
+		super(`SheetOM cannot serialize the pending ${shorthand} shorthand without changing its semantics.`, options);
+		this.name = "SheetOMSerializationError";
+		this.code = "UNREPRESENTABLE_PENDING_SHORTHAND";
+		this.shorthand = shorthand;
+		this.conflictingLonghands = Object.freeze([...conflictingLonghands]);
+	}
+};
+const unrepresentablePendingShorthandPattern = /^SHEETOM_UNREPRESENTABLE_PENDING_SHORTHAND: shorthand=([^;]+); conflicting=([a-z0-9,-]+)$/u;
+function serializationErrorFrom(error) {
+	if (!(error instanceof Error)) return null;
+	const match = unrepresentablePendingShorthandPattern.exec(error.message);
+	if (!match) return null;
+	const shorthand = match[1];
+	const conflicts = match[2];
+	if (!shorthand || !conflicts) return null;
+	return new SheetOMSerializationError(shorthand, conflicts.split(","), { cause: error });
+}
+function rethrowSerializationError(error) {
+	const serializationError = serializationErrorFrom(error);
+	if (serializationError) throw serializationError;
+}
+//#endregion
 //#region src/internal/native-declaration-block.ts
 /** Thin JS ownership boundary around the Rust declaration state machine. */
 var NativeDeclarationBlock = class {
 	#state;
 	#reportDiagnostic;
+	#reportSerializationDiagnostic;
 	#reservedNestingDepth;
 	#observableCache;
 	#serializationCache = /* @__PURE__ */ new Map();
-	constructor(reportDiagnostic, context = "style", resourceBudget = defaultResourceBudget, reservedNestingDepth = () => 0) {
+	constructor(reportDiagnostic, reportSerializationDiagnostic, context = "style", resourceBudget = defaultResourceBudget, reservedNestingDepth = () => 0) {
 		this.#reportDiagnostic = reportDiagnostic;
+		this.#reportSerializationDiagnostic = reportSerializationDiagnostic;
 		this.#reservedNestingDepth = reservedNestingDepth;
 		this.#state = engineBinding.createDeclarationState(context, ...nativeBudgetArguments(resourceBudget));
 	}
@@ -131,9 +162,59 @@ var NativeDeclarationBlock = class {
 			this.#invalidateSerialization();
 			return;
 		}
-		const normalizedName = name.startsWith("--") ? name : name.toLowerCase();
-		const [code, input] = outcome === "invalid-priority" ? ["INVALID_PRIORITY", priority] : outcome === "unsupported-shorthand" ? ["UNSUPPORTED_SHORTHAND_VALUE", value] : ["INVALID_PROPERTY_VALUE", value];
-		this.#reportDiagnostic(code, normalizedName, input);
+		this.#diagnosticForOutcome(outcome, name, value, priority);
+	}
+	applyMutations(mutations) {
+		const kinds = [];
+		const properties = [];
+		const values = [];
+		const priorities = [];
+		for (const mutation of mutations) {
+			kinds.push(mutation.kind === "set" ? 0 : 1);
+			properties.push(mutation.property);
+			values.push(mutation.kind === "set" ? mutation.value : "");
+			priorities.push(mutation.kind === "set" ? mutation.priority : "");
+		}
+		let outcomes;
+		try {
+			outcomes = this.#state.applyMutations(kinds, properties, values, priorities, this.#reservedNestingDepth());
+		} catch (error) {
+			rethrowResourceBudgetError(error);
+			throw error;
+		}
+		if (outcomes.length !== mutations.length) throw new Error("SheetOM engine returned an incomplete declaration mutation result.");
+		const results = [];
+		let mutated = false;
+		for (let index = 0; index < outcomes.length; index += 1) {
+			const mutation = mutations[index];
+			const outcome = outcomes[index];
+			if (!mutation || outcome === void 0) throw new Error("SheetOM engine returned a mismatched declaration mutation result.");
+			if (mutation.kind === "remove") {
+				mutated = true;
+				results.push({
+					kind: "remove",
+					value: outcome
+				});
+				continue;
+			}
+			if (outcome === "applied") {
+				mutated = true;
+				results.push({
+					kind: "set",
+					accepted: true,
+					diagnostic: null
+				});
+				continue;
+			}
+			if (!isEngineMutationOutcome(outcome)) throw new Error("SheetOM engine returned an invalid declaration mutation outcome.");
+			results.push({
+				kind: "set",
+				accepted: false,
+				diagnostic: this.#diagnosticForOutcome(outcome, mutation.property, mutation.value, mutation.priority)
+			});
+		}
+		if (mutated) this.#invalidateSerialization();
+		return results;
 	}
 	removeProperty(name) {
 		const removed = this.#state.removeProperty(name);
@@ -149,19 +230,63 @@ var NativeDeclarationBlock = class {
 		}
 		this.#invalidateSerialization();
 	}
-	serialize(safe, indent, separator) {
-		const cacheKey = `${safe ? "1" : "0"}\0${indent}\0${separator}`;
+	serialize(safe, indent, separator, strict = false) {
+		const cacheKey = `${safe ? "1" : "0"}${strict ? "1" : "0"}\0${indent}\0${separator}`;
 		const cached = this.#serializationCache.get(cacheKey);
-		if (cached !== void 0) return cached;
-		const serialized = this.#state.serializeFormatted(safe, indent, separator);
-		this.#serializationCache.set(cacheKey, serialized);
-		return serialized;
+		if (cached !== void 0) {
+			if (typeof cached === "string") return cached;
+			this.#reportSerializationIssues(cached.issues);
+			return cached.serialized;
+		}
+		let result;
+		try {
+			if (strict) result = this.#state.serializeFormatted(safe, indent, separator);
+			else result = parseResilientSerializationResult(this.#state.serializeFormattedResilient(safe, indent, separator));
+		} catch (error) {
+			rethrowResourceBudgetError(error);
+			rethrowSerializationError(error);
+			throw error;
+		}
+		this.#serializationCache.set(cacheKey, result);
+		if (typeof result === "string") return result;
+		this.#reportSerializationIssues(result.issues);
+		return result.serialized;
 	}
 	#invalidateSerialization() {
 		this.#observableCache = void 0;
 		this.#serializationCache.clear();
 	}
+	#diagnosticForOutcome(outcome, name, value, priority) {
+		const normalizedName = name.startsWith("--") ? name : name.toLowerCase();
+		const [code, input] = outcome === "invalid-priority" ? ["INVALID_PRIORITY", priority] : outcome === "unsupported-shorthand" ? ["UNSUPPORTED_SHORTHAND_VALUE", value] : ["INVALID_PROPERTY_VALUE", value];
+		return this.#reportDiagnostic(code, normalizedName, input);
+	}
+	#reportSerializationIssues(issues) {
+		for (const issue of issues) this.#reportSerializationDiagnostic(issue.shorthand, issue.conflictingLonghands);
+	}
 };
+function parseResilientSerializationResult(output) {
+	const serialized = output[0];
+	if (serialized === void 0 || output.length % 2 === 0) throw new Error("SheetOM engine returned an invalid resilient serialization result.");
+	if (output.length === 1) return serialized;
+	const issues = [];
+	for (let index = 1; index < output.length; index += 2) {
+		const shorthand = output[index];
+		const conflicts = output[index + 1];
+		if (!shorthand || !conflicts) throw new Error("SheetOM engine returned an incomplete resilient serialization issue.");
+		issues.push({
+			shorthand,
+			conflictingLonghands: Object.freeze(conflicts.split(","))
+		});
+	}
+	return {
+		serialized,
+		issues
+	};
+}
+function isEngineMutationOutcome(value) {
+	return value === "invalid-name" || value === "invalid-priority" || value === "invalid-value" || value === "unsupported-shorthand";
+}
 function toUnsignedLong$1(value) {
 	const numeric = Number(value);
 	if (!Number.isFinite(numeric) || numeric === 0) return 0;
@@ -353,13 +478,20 @@ var Serializer = class {
 		this.#describe = describe;
 	}
 	serialize(node) {
+		return this.serializeMany([node]);
+	}
+	serializeMany(nodes) {
 		const chunks = [];
-		const pending = [{
-			kind: "node",
-			node,
-			depth: 0,
-			child: false
-		}];
+		const pending = [];
+		for (let index = nodes.length - 1; index >= 0; index -= 1) {
+			const node = nodes[index];
+			if (node) pending.push({
+				kind: "node",
+				node,
+				depth: 0,
+				child: false
+			});
+		}
 		while (pending.length > 0) {
 			const frame = pending.pop();
 			if (!frame) continue;
@@ -473,7 +605,8 @@ const ruleTree = new RuleTree((rule, parentRule, parentStyleSheet) => {
 		parentStyleSheet
 	});
 }, (rule) => rule.parentStyleSheet);
-const safeSerializer = new Serializer(describeRuleSafe);
+const safeSerializer = new Serializer((rule) => describeRuleSafe(rule, false));
+const strictSerializer = new Serializer((rule) => describeRuleSafe(rule, true));
 let activeConstructionResourceBudget = defaultResourceBudget;
 function constructWithResourceBudget(factory, resourceBudget) {
 	const previous = activeConstructionResourceBudget;
@@ -1126,19 +1259,32 @@ var CSSStyleDeclaration = class {
 		this.parentRule = parentRule;
 		lockOwnProperties(this, "parentRule");
 		const reportDeclarationDiagnostic = (code, property, input) => {
-			const priority = code === "INVALID_PRIORITY";
-			const unsupportedShorthand = code === "UNSUPPORTED_SHORTHAND_VALUE";
-			(ruleDiagnostics.get(this.parentRule) ?? ignoreDiagnostic)({
+			const diagnostic = {
 				code,
 				severity: "warning",
 				operation: "setProperty",
-				message: priority ? `The mutation was ignored because ${input} is not a valid priority.` : unsupportedShorthand ? `The value was ignored because the shorthand codec for ${property} cannot expand it.` : `The value was ignored because it is invalid for ${property}.`,
+				message: code === "INVALID_PRIORITY" ? `The mutation was ignored because ${input} is not a valid priority.` : code === "UNSUPPORTED_SHORTHAND_VALUE" ? `The value was ignored because the shorthand codec for ${property} cannot expand it.` : `The value was ignored because it is invalid for ${property}.`,
 				property,
 				input,
 				location: null
-			});
+			};
+			(ruleDiagnostics.get(this.parentRule) ?? ignoreDiagnostic)(diagnostic);
+			return diagnostic;
+		};
+		const reportSerializationDiagnostic = (shorthand, conflictingLonghands) => {
+			const diagnostic = {
+				code: "UNREPRESENTABLE_PENDING_SHORTHAND",
+				severity: "warning",
+				operation: "serialize",
+				message: `The pending ${shorthand} shorthand required a best-effort recovery during serialization.`,
+				property: shorthand,
+				input: "",
+				location: null,
+				conflictingLonghands: Object.freeze([...conflictingLonghands])
+			};
+			(ruleDiagnostics.get(this.parentRule) ?? ignoreDiagnostic)(diagnostic);
 		};
-		this.#block = new NativeDeclarationBlock(reportDeclarationDiagnostic, parentRule instanceof CSSFontFaceRule ? "font-face" : parentRule instanceof CSSFunctionDeclarations ? "function" : "style", ruleResourceBudgets.get(parentRule) ?? defaultResourceBudget, () => declarationSerializationDepth(parentRule));
+		this.#block = new NativeDeclarationBlock(reportDeclarationDiagnostic, reportSerializationDiagnostic, parentRule instanceof CSSFontFaceRule ? "font-face" : parentRule instanceof CSSFunctionDeclarations ? "function" : "style", ruleResourceBudgets.get(parentRule) ?? defaultResourceBudget, () => declarationSerializationDepth(parentRule));
 		return new Proxy(this, {
 			get(target, property) {
 				if (typeof property === "string" && arrayIndexPattern.test(property)) return target.item(Number(property)) || void 0;
@@ -1183,13 +1329,41 @@ var CSSStyleDeclaration = class {
 		const stringPriority = priority === null ? "" : `${priority}`;
 		this.#block.setProperty(stringName, stringValue, stringPriority);
 	}
+	/** Apply ordered declaration mutations through one engine boundary crossing. */
+	applyMutations(mutations) {
+		requireArguments(arguments.length, 1, "CSSStyleDeclaration", "applyMutations");
+		if (!Array.isArray(mutations)) throw new TypeError("CSSStyleDeclaration.applyMutations requires an array.");
+		const normalized = [];
+		for (let index = 0; index < mutations.length; index += 1) {
+			const mutation = mutations[index];
+			if (typeof mutation !== "object" || mutation === null) throw new TypeError(`Declaration mutation at index ${index} must be an object.`);
+			if (mutation.kind !== "set" && mutation.kind !== "remove") throw new TypeError(`Declaration mutation at index ${index} has an invalid kind.`);
+			if (typeof mutation.property !== "string") throw new TypeError(`Declaration mutation at index ${index} requires a string property.`);
+			if (mutation.kind === "remove") {
+				normalized.push({
+					kind: "remove",
+					property: mutation.property
+				});
+				continue;
+			}
+			if (typeof mutation.value !== "string" && mutation.value !== null) throw new TypeError(`Declaration mutation at index ${index} requires a string or null value.`);
+			if (mutation.priority !== void 0 && mutation.priority !== null && typeof mutation.priority !== "string") throw new TypeError(`Declaration mutation at index ${index} requires a string priority.`);
+			normalized.push({
+				kind: "set",
+				property: mutation.property,
+				value: mutation.value ?? "",
+				priority: mutation.priority ?? ""
+			});
+		}
+		return this.#block.applyMutations(normalized);
+	}
 	removeProperty(name) {
 		requireArguments(arguments.length, 1, "CSSStyleDeclaration", "removeProperty");
 		return this.#block.removeProperty(`${name}`);
 	}
 	/** @internal */
-	serializeSafe(indent) {
-		return this.#block.serialize(true, indent, "\n");
+	serializeSafe(indent, strict = false) {
+		return this.#block.serialize(true, indent, "\n", strict);
 	}
 };
 /** A live `@font-face` descriptor rule. */
@@ -1678,26 +1852,23 @@ function replaceGroupingRules(group, rules) {
 function attachRuleTree(rule, parentRule, parentStyleSheet) {
 	ruleTree.attach(rule, parentRule, parentStyleSheet);
 }
-function serializeRuleSafe(rule) {
-	return safeSerializer.serialize(rule);
-}
-function describeRuleSafe(rule) {
+function describeRuleSafe(rule, strict) {
 	if (rule instanceof CSSStyleRule) return {
 		kind: "block",
 		header: rule.selectorText,
-		declarations: rule.style.serializeSafe("  "),
+		declarations: rule.style.serializeSafe("  ", strict),
 		children: ruleTree.children(rule)
 	};
 	if (rule instanceof CSSNestedDeclarations || rule instanceof CSSFunctionDeclarations) return {
 		kind: "declarations",
-		declarations: rule.style.serializeSafe("")
+		declarations: rule.style.serializeSafe("", strict)
 	};
 	if (rule instanceof CSSFontFaceRule || rule instanceof CSSMarginRule || rule instanceof CSSPositionTryRule || rule instanceof CSSKeyframeRule) {
 		const blockIndex = rule.cssText.indexOf("{");
 		return {
 			kind: "block",
 			header: rule.cssText.slice(0, blockIndex).trimEnd(),
-			declarations: rule.style.serializeSafe("  ")
+			declarations: rule.style.serializeSafe("  ", strict)
 		};
 	}
 	if (rule instanceof CSSKeyframesRule) return {
@@ -1708,7 +1879,7 @@ function describeRuleSafe(rule) {
 	if (rule instanceof CSSPageRule) return {
 		kind: "block",
 		header: `@page${rule.selectorText === "" ? "" : ` ${rule.selectorText}`}`,
-		declarations: rule.style.serializeSafe("  "),
+		declarations: rule.style.serializeSafe("  ", strict),
 		children: ruleTree.children(rule)
 	};
 	if (!(rule instanceof CSSGroupingRule)) return {
@@ -2103,9 +2274,13 @@ var CSSStyleSheet = class {
 	}
 	/** Serialize current state as reparsable CSS without mutating live objects. */
 	serialize() {
-		return this.#rules.map(serializeRuleSafe).join("");
+		return safeSerializer.serializeMany(this.#rules);
+	}
+	/** Serialize current state only when its CSS semantics can be preserved exactly. */
+	serializeStrict() {
+		return strictSerializer.serializeMany(this.#rules);
 	}
-	/** Drain opt-in mutation diagnostics without affecting CSSOM behavior. */
+	/** Drain opt-in mutation and serialization diagnostics without affecting CSSOM behavior. */
 	takeDiagnostics() {
 		if (!this.#diagnostics) return [];
 		return this.#diagnostics.splice(0);
@@ -2123,6 +2298,6 @@ function parseStyleSheet(cssText, options = {}) {
 	return sheet;
 }
 //#endregion
-export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSSupportsRule, CSSViewTransitionRule, MediaList, parseStyleSheet };
+export { CSSConditionRule, CSSContainerRule, CSSCounterStyleRule, CSSFontFaceRule, CSSFontFeatureValuesMap, CSSFontFeatureValuesRule, CSSFontPaletteValuesRule, CSSFunctionDeclarations, CSSFunctionDescriptors, CSSFunctionRule, CSSGroupingRule, CSSImportRule, CSSKeyframeRule, CSSKeyframesRule, CSSLayerBlockRule, CSSLayerStatementRule, CSSMarginRule, CSSMediaRule, CSSNamespaceRule, CSSNestedDeclarations, CSSPageRule, CSSPositionTryRule, CSSPropertyRule, CSSRule, CSSRuleList, CSSScopeRule, CSSStartingStyleRule, CSSStyleDeclaration, CSSStyleRule, CSSStyleSheet, CSSSupportsRule, CSSViewTransitionRule, MediaList, SheetOMSerializationError, parseStyleSheet };
 
 //# sourceMappingURL=index.js.map