sheetom 0.1.0-rc.1 → 0.1.0-rc.2

package/README.md

@@ -96,7 +96,10 @@ block remote resources, or make valid hostile CSS safe to render.
 
 Invalid `setProperty` values and priorities are atomic no-ops, matching browser
 behavior. Opt into mutation diagnostics with `{ diagnostics: true }` and drain
-them using `takeDiagnostics()`.
+them using `takeDiagnostics()`. `SheetOMDiagnostic.code` is a stable string
+union. Diagnostics retain the complete rejected input until drained; when
+processing untrusted or very large input, callers should leave diagnostics off
+or drain them promptly to bound memory use.
 
 ## API scope
 
@@ -153,8 +156,13 @@ npm run pack:test
 
 `npm test` runs unit, deterministic fuzz, and local Chromium projects. Use
 `npm run test:browser:matrix` on a machine with all Playwright dependencies to
-run Chromium, Firefox, and WebKit. `npm run docs:build` generates the TypeDoc
-reference under `site/api`.
+run Chromium, Firefox, and WebKit. The browser matrix also runs a deterministic,
+grammar-oriented declaration differential; any minimized mismatch must become
+an immutable Operation Fixture with an explicit Compatibility Resolution.
+`npm run docs:build` generates the TypeDoc reference under `site/api`. The benchmark gates both a 10,000-rule stress case
+and a publisher-shaped reference workload with one shared stylesheet, 20 page
+stylesheets, nested layers/media, distributed mutations, and two idempotent
+serialization passes.
 
 Only the latest published `0.x` minor and its active prereleases receive fixes
 before 1.0. During `0.x`, observable compatibility corrections and interface

package/compatibility/baselines/0.1.0-rc.2.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "../schemas/compatibility-report.schema.json",
+  "schemaVersion": 2,
+  "packageVersion": "0.1.0-rc.2",
+  "baseline": {
+    "wptCommit": "54f8f933629e7c010ae98a246729af01f8abcda5",
+    "syntaxEngineSet": {
+      "lightningcss": "1.33.0",
+      "cssTree": "3.2.1",
+      "cssstyle": "6.2.0",
+      "cssTokenizer": "4.0.0"
+    },
+    "runtimes": {
+      "node": "v24.18.0",
+      "bun": "1.3.1",
+      "deno": "2.9.5"
+    },
+    "browsers": {
+      "chromium": "151.0.7922.34 (revision 1234)",
+      "firefox": "153.0 (revision 1538)",
+      "webkit": "26.5 (revision 2336)"
+    }
+  },
+  "summary": {
+    "passed": 6,
+    "divergences": 7,
+    "excluded": 0,
+    "unexplained": 0
+  },
+  "evidence": {
+    "operationFixtures": {
+      "passed": 13,
+      "total": 13,
+      "sha256": "7909f90571b8d6595d18b006bb4f2c5337cca9d413084558e913e760be45a3aa",
+      "adapters": [
+        {
+          "adapter": "sheetom",
+          "passed": 13,
+          "total": 13
+        },
+        {
+          "adapter": "chromium",
+          "passed": 13,
+          "total": 13
+        },
+        {
+          "adapter": "firefox",
+          "passed": 13,
+          "total": 13
+        },
+        {
+          "adapter": "webkit",
+          "passed": 13,
+          "total": 13
+        }
+      ]
+    },
+    "nativeWpt": [
+      {
+        "engine": "chrome",
+        "version": "150.0.7871.128",
+        "sha256": "3f66a5f324bb9023cdd4b168e780640700449f22f28ca378eca91504b7d68e3f",
+        "passed": 4,
+        "total": 4
+      },
+      {
+        "engine": "firefox",
+        "version": "153.0.3",
+        "sha256": "e5f88e3431f602dc29fd8dbd79667bef33930ee7f87ee6d2069f17126421a230",
+        "passed": 4,
+        "total": 4
+      }
+    ]
+  },
+  "resolutions": [
+    {
+      "fixtureId": "declarations.basic-set-property",
+      "decision": "shared",
+      "rationale": "The observable declaration state is shared by the pinned browser engines."
+    },
+    {
+      "fixtureId": "declarations.malformed-padding",
+      "decision": "chromium-fallback",
+      "rationale": "CSS Syntax accepts the EOF-recovered value; Chromium preserves the unclosed observable spelling while Firefox materializes closing parentheses."
+    },
+    {
+      "fixtureId": "declarations.modern-color-canonicalization",
+      "decision": "shared",
+      "rationale": "The pinned browser engines expose modern rgb syntax through the shared legacy rgba serialization in CSSStyleDeclaration."
+    },
+    {
+      "fixtureId": "declarations.typed-eof-recovery",
+      "decision": "chromium-fallback",
+      "rationale": "Typed property values expose the Chromium/WebKit canonical serialization after CSS Syntax EOF recovery; Firefox retains quotes around the recovered font-family string."
+    },
+    {
+      "fixtureId": "declarations.quoted-font-family",
+      "decision": "chromium-fallback",
+      "rationale": "Chromium and WebKit remove unnecessary quotes around a simple font-family while Firefox retains them; SheetOM follows the measured Chromium fallback."
+    },
+    {
+      "fixtureId": "declarations.custom-property-eof-recovery",
+      "decision": "chromium-fallback",
+      "rationale": "Chromium retains unclosed custom-property token structures, removes EOF comments, and replaces an escaped EOF with U+FFFD."
+    },
+    {
+      "fixtureId": "declarations.custom-property-priority-replacement",
+      "decision": "chromium-fallback",
+      "rationale": "Chromium and Firefox replace the existing custom-property priority when setProperty is called without a priority, while WebKit retains !important; SheetOM follows the measured Chromium fallback."
+    },
+    {
+      "fixtureId": "declarations.pending-substitution-eof-recovery",
+      "decision": "chromium-fallback",
+      "rationale": "Chromium retains the unclosed pending-substitution spelling while applying lexical EOF recovery such as comment removal."
+    },
+    {
+      "fixtureId": "declarations.setproperty-null-undefined",
+      "decision": "shared",
+      "rationale": "The four adapted WPT subtests define the shared null and undefined conversion behavior."
+    },
+    {
+      "fixtureId": "declarations.required-arguments",
+      "decision": "shared",
+      "rationale": "Required WebIDL arguments throw TypeError before string conversion in the pinned browser engines."
+    },
+    {
+      "fixtureId": "declarations.set-property-multiple-declarations",
+      "decision": "shared",
+      "rationale": "A setProperty value is parsed independently and cannot escape into another declaration; invalid input leaves the previous declaration unchanged."
+    },
+    {
+      "fixtureId": "declarations.escaped-custom-property-name",
+      "decision": "shared",
+      "rationale": "Custom-property method arguments retain their logical names and cssText escapes those names only when serializing CSS syntax."
+    },
+    {
+      "fixtureId": "integration.weweb-authoring-tree",
+      "decision": "chromium-fallback",
+      "rationale": "The standard rule-tree operations and detachment identity are shared; the recovered padding spelling follows the existing Chromium fallback resolution."
+    }
+  ]
+}

package/compatibility/schemas/compatibility-report.schema.json

@@ -7,16 +7,27 @@
   "required": ["schemaVersion", "packageVersion", "baseline", "summary", "evidence", "resolutions"],
   "properties": {
     "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "enum": [1, 2] },
     "packageVersion": { "type": "string" },
     "baseline": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["wptCommit", "lightningcss", "cssTree", "runtimes", "browsers"],
+      "required": ["wptCommit", "runtimes", "browsers"],
       "properties": {
         "wptCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
         "lightningcss": { "type": "string" },
         "cssTree": { "type": "string" },
+        "syntaxEngineSet": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["lightningcss", "cssTree", "cssstyle", "cssTokenizer"],
+          "properties": {
+            "lightningcss": { "type": "string" },
+            "cssTree": { "type": "string" },
+            "cssstyle": { "type": "string" },
+            "cssTokenizer": { "type": "string" }
+          }
+        },
         "runtimes": { "type": "object" },
         "browsers": { "type": "object" }
       }
@@ -80,5 +91,36 @@
       }
     },
     "resolutions": { "type": "array" }
-  }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "schemaVersion": { "const": 1 } } },
+      "then": {
+        "properties": {
+          "baseline": {
+            "type": "object",
+            "required": ["lightningcss", "cssTree"],
+            "properties": {
+              "lightningcss": { "type": "string" },
+              "cssTree": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "schemaVersion": { "const": 2 } } },
+      "then": {
+        "properties": {
+          "baseline": {
+            "type": "object",
+            "required": ["syntaxEngineSet"],
+            "properties": {
+              "syntaxEngineSet": { "type": "object" }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

package/dist/index.cjs

@@ -1975,6 +1975,87 @@ function expandStaticShorthand(name, parsed, important) {
 	return records;
 }
 //#endregion
+//#region src/internal/observable-value-codec.ts
+const closingToken = /* @__PURE__ */ new Map([
+	[_csstools_css_tokenizer.TokenType.Function, {
+		token: _csstools_css_tokenizer.TokenType.CloseParen,
+		text: ")"
+	}],
+	[_csstools_css_tokenizer.TokenType.OpenParen, {
+		token: _csstools_css_tokenizer.TokenType.CloseParen,
+		text: ")"
+	}],
+	[_csstools_css_tokenizer.TokenType.OpenSquare, {
+		token: _csstools_css_tokenizer.TokenType.CloseSquare,
+		text: "]"
+	}],
+	[_csstools_css_tokenizer.TokenType.OpenCurly, {
+		token: _csstools_css_tokenizer.TokenType.CloseCurly,
+		text: "}"
+	}]
+]);
+function escapedString(value, quote) {
+	return value.replace(/\\/g, "\\\\").replace(new RegExp(quote, "g"), `\\${quote}`);
+}
+function retainedToken(token) {
+	if (token[0] === _csstools_css_tokenizer.TokenType.Comment || token[0] === _csstools_css_tokenizer.TokenType.EOF) return "";
+	const details = token[4];
+	if (token[0] === _csstools_css_tokenizer.TokenType.Ident && token[1].endsWith("\\") && details && "value" in details && `${details.value}`.endsWith("�")) return `${token[1].slice(0, -1)}�`;
+	if (token[0] === _csstools_css_tokenizer.TokenType.URL && token[1].endsWith("\\") && details && "value" in details) return `url(${details.value})`;
+	if (token[0] === _csstools_css_tokenizer.TokenType.String && token[1].endsWith("\\") && details && "value" in details) {
+		const quote = token[1][0] ?? "\"";
+		return `${quote}${escapedString(`${details.value}`, quote)}${quote}`;
+	}
+	return token[1];
+}
+function recoverTokenText(input) {
+	let parseError = false;
+	const tokens = (0, _csstools_css_tokenizer.tokenize)({ css: input }, { onParseError: () => {
+		parseError = true;
+	} });
+	const stack = [];
+	let retained = "";
+	let closed = "";
+	let removedComment = false;
+	for (const token of tokens) {
+		if (token[0] === _csstools_css_tokenizer.TokenType.EOF) continue;
+		if (token[0] === _csstools_css_tokenizer.TokenType.Comment) {
+			removedComment = true;
+			continue;
+		}
+		const text = retainedToken(token);
+		retained += text;
+		closed += text;
+		const closing = closingToken.get(token[0]);
+		if (closing) {
+			stack.push(closing);
+			continue;
+		}
+		if (stack.at(-1)?.token === token[0]) stack.pop();
+		if (token[0] === _csstools_css_tokenizer.TokenType.URL && !text.endsWith(")")) closed += ")";
+		if (token[0] !== _csstools_css_tokenizer.TokenType.String) continue;
+		const quote = token[1][0];
+		if (quote && !text.endsWith(quote)) closed += quote;
+	}
+	for (let index = stack.length - 1; index >= 0; index -= 1) closed += stack[index]?.text ?? "";
+	return {
+		closed: closed.trim(),
+		recovered: parseError || removedComment || stack.length > 0,
+		retained: retained.trim()
+	};
+}
+/** Produces browser-facing text without changing acceptance or reparsable output. */
+function serializeObservableValue({ name, input, safeValue, category }) {
+	const recovered = recoverTokenText(input.trim());
+	if (category !== "typed") return recovered.retained;
+	if (name === "font-family") return safeValue;
+	const oracle = new cssstyle.CSSStyleDeclaration();
+	oracle.setProperty(name, recovered.closed);
+	const canonicalValue = oracle.getPropertyValue(name);
+	if (canonicalValue !== "") return canonicalValue;
+	return recovered.recovered ? recovered.closed : input.trim();
+}
+//#endregion
 //#region src/internal/value-gate.ts
 const encoder$1 = new TextEncoder();
 const decoder$1 = new TextDecoder();
@@ -2285,7 +2366,14 @@ function parsePropertyValue(name, observableValue) {
 		if (css_tree.ident.decode(serializedDeclaration.property) !== name) return null;
 		const valueLocation = serializedDeclaration.value.loc;
 		const safeValue = valueLocation ? serialized.slice(valueLocation.start.offset, valueLocation.end.offset) : css_tree.generate(serializedDeclaration.value);
-		const trimmedObservableValue = canonicalizeBrowserValue(name, canonicalizeLeadingDecimal(observableValue.trim()));
+		const observableCategory = name.startsWith("--") ? "custom" : pendingSubstitution ? "pending-substitution" : "typed";
+		const serializedObservableValue = serializeObservableValue({
+			name,
+			input: observableValue,
+			safeValue: safeValue.trim(),
+			category: observableCategory
+		});
+		const trimmedObservableValue = canonicalizeBrowserValue(name, observableCategory === "typed" ? canonicalizeLeadingDecimal(serializedObservableValue) : serializedObservableValue);
 		const normalizedSafeValue = canonicalizeBrowserValue(name, safeValue.trim());
 		return {
 			observableValue: trimmedObservableValue === "0" && zeroLengthProperties.has(name) ? "0px" : trimmedObservableValue,
@@ -2541,6 +2629,28 @@ function normalizeConditionalPrelude(name, value) {
 		return value;
 	}
 }
+function parseContainerPrelude(value) {
+	try {
+		const parsed = css_tree.parse(`@container ${value} {}`);
+		const rule = parsed.type === "StyleSheet" ? parsed.children.first : null;
+		if (rule?.type !== "Atrule" || rule.name.toLowerCase() !== "container") return null;
+		if (rule.prelude?.type !== "AtrulePrelude") return null;
+		const children = rule.prelude.children.toArray();
+		const first = children[0];
+		const name = first?.type === "Identifier" ? first.name : "";
+		const queryNodes = name === "" ? children : children.slice(1);
+		if (queryNodes.length === 0) return null;
+		const query = queryNodes.map((node) => css_tree.generate(node)).join(" ").replace(/:\s*/g, ": ").replace(/\s*(<=|>=|=|<|>)\s*/g, " $1 ");
+		if (query === "") return null;
+		return {
+			conditionText: name === "" ? query : `${name} ${query}`,
+			name,
+			query
+		};
+	} catch {
+		return null;
+	}
+}
 function splitMediaQueries(value) {
 	const queries = [];
 	let start = 0;
@@ -2697,11 +2807,11 @@ var CSSContainerRule = class extends CSSConditionRule {
 	containerName;
 	containerQuery;
 	constructor(conditionText) {
-		const normalizedCondition = normalizeConditionalPrelude("container", conditionText);
+		const parsed = parseContainerPrelude(conditionText);
+		const normalizedCondition = parsed?.conditionText ?? conditionText.trim();
 		super(0, normalizedCondition);
-		const openingParenthesis = normalizedCondition.indexOf("(");
-		this.containerName = openingParenthesis === -1 ? "" : normalizedCondition.slice(0, openingParenthesis).trim();
-		this.containerQuery = openingParenthesis === -1 ? normalizedCondition : normalizedCondition.slice(openingParenthesis).trim();
+		this.containerName = parsed?.name ?? "";
+		this.containerQuery = parsed?.query ?? normalizedCondition;
 		lockOwnProperties(this, "containerName", "containerQuery");
 	}
 	get cssText() {