sheetom 0.1.0-rc.10 → 0.1.0-rc.11

package/README.md

@@ -119,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: 2,
-	sheetomVersion: "0.1.0-rc.10",
-	syntaxEngineSetSha256: "97cf2484af7f77edc3810d68f317136dc4d4eee78312a7f9726b9d0acc694351"
+	abiVersion: 3,
+	sheetomVersion: "0.1.0-rc.11",
+	syntaxEngineSetSha256: "8c274f05005d475082dbc0ec0c3b6056cb78043f008ed4c813f49fc5a8a2b250"
 });
 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));
 	}
@@ -223,13 +254,27 @@ 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;
@@ -240,7 +285,29 @@ var NativeDeclarationBlock = class {
 		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";
 }
@@ -562,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;
@@ -1227,7 +1295,20 @@ var CSSStyleDeclaration = class {
 			(ruleDiagnostics.get(this.parentRule) ?? ignoreDiagnostic)(diagnostic);
 			return diagnostic;
 		};
-		this.#block = new NativeDeclarationBlock(reportDeclarationDiagnostic, parentRule instanceof CSSFontFaceRule ? "font-face" : parentRule instanceof CSSFunctionDeclarations ? "function" : "style", ruleResourceBudgets.get(parentRule) ?? defaultResourceBudget, () => declarationSerializationDepth(parentRule));
+		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, 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;
@@ -1305,8 +1386,8 @@ var CSSStyleDeclaration = class {
 		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. */
@@ -1795,23 +1876,23 @@ function replaceGroupingRules(group, rules) {
 function attachRuleTree(rule, parentRule, parentStyleSheet) {
 	ruleTree.attach(rule, parentRule, parentStyleSheet);
 }
-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 {
@@ -1822,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 {
@@ -2219,7 +2300,11 @@ var CSSStyleSheet = class {
 	serialize() {
 		return safeSerializer.serializeMany(this.#rules);
 	}
-	/** Drain opt-in mutation diagnostics without affecting CSSOM behavior. */
+	/** Serialize current state only when its CSS semantics can be preserved exactly. */
+	serializeStrict() {
+		return strictSerializer.serializeMany(this.#rules);
+	}
+	/** Drain opt-in mutation and serialization diagnostics without affecting CSSOM behavior. */
 	takeDiagnostics() {
 		if (!this.#diagnostics) return [];
 		return this.#diagnostics.splice(0);
@@ -2270,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