sheetom 0.1.0-rc.9 → 0.1.0

package/README.md

@@ -64,6 +64,31 @@ Constructed sheets strip `@import` during replacement. `parseStyleSheet()` is a
 SheetOM extension for existing regular stylesheets and preserves valid imports
 without fetching them.
 
+Compilers can apply all known mutations for one rule with one engine crossing
+and still receive one acceptance result per operation:
+
+```ts
+function applyCompilerDeclarations(rule: CSSStyleRule, dynamicWidth: string) {
+  const results = rule.style.applyMutations([
+    { kind: "set", property: "display", value: "grid" },
+    { kind: "set", property: "width", value: dynamicWidth },
+    { kind: "remove", property: "margin-left" },
+  ]);
+
+  for (const result of results) {
+    if (result.kind === "set" && !result.accepted) {
+      console.warn(result.diagnostic);
+    }
+  }
+}
+```
+
+Operations run in order through the same validation and shorthand/longhand
+state machine as individual calls. Group one batch per declaration block;
+never combine values into declaration text. Batch results already include
+rejection diagnostics, so high-volume callers can leave the sheet diagnostic
+queue disabled unless they also need diagnostics from other APIs.
+
 ## Browser recovery, safe output
 
 Browsers accept some CSS using end-of-input recovery and expose the incomplete
@@ -94,6 +119,13 @@ sheet.serialize();
 | `style.cssText` | Browser-compatible declaration text, including measured recovery quirks. |
 | `rule.cssText` | Browser-compatible text for the current rule. |
 | `sheet.serialize()` | Deterministic, reparsable CSS for a complete stylesheet. |
+| `sheet.serializeStrict()` | Exact-only output that rejects CSSOM states CSS text cannot represent faithfully. |
+
+Pending-substitution shorthands survive later longhand edits in reparsable
+output. If an imperative priority combination cannot be represented exactly,
+`serialize()` emits a local best-effort result and an opt-in structured
+diagnostic rather than blocking the whole stylesheet. Use `serializeStrict()`
+when approximation is unacceptable.
 
 Invalid property values and priorities are atomic no-ops: the previous state
 survives unchanged. Static shorthands are stored as canonical longhands, so

package/dist/index.cjs

@@ -28,9 +28,9 @@ let node_url = require("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;
@@ -114,16 +114,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));
 	}
@@ -155,9 +186,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);
@@ -173,19 +254,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;
@@ -377,13 +502,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;
@@ -497,7 +629,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;
@@ -1150,19 +1283,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;
@@ -1207,13 +1353,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. */
@@ -1702,26 +1876,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 {
@@ -1732,7 +1903,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 {
@@ -2127,9 +2298,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);
@@ -2180,6 +2355,7 @@ exports.CSSStyleSheet = CSSStyleSheet;
 exports.CSSSupportsRule = CSSSupportsRule;
 exports.CSSViewTransitionRule = CSSViewTransitionRule;
 exports.MediaList = MediaList;
+exports.SheetOMSerializationError = SheetOMSerializationError;
 exports.parseStyleSheet = parseStyleSheet;
 
 //# sourceMappingURL=index.cjs.map