sheetom 0.1.0-rc.5 → 0.1.0-rc.7

package/README.md

@@ -1,28 +1,41 @@
 # SheetOM
 
 SheetOM is a mutable, browser-shaped CSS authoring object model for Node.js,
-Bun, and Deno. It uses Lightning CSS for property parsing and canonicalization
-while keeping declaration state and CSSOM serialization under its own control.
+Bun, and Deno. Its repository-owned Rust engine handles parsing,
+canonicalization, declaration state, and safe CSS serialization; JavaScript
+only owns the public WebIDL-shaped facade and live object identity.
 
 It is intended for server-side stylesheet editing and serialization. It does
 not implement the DOM, cascade, selector matching, layout, or computed styles.
 
 ## Install
 
-Install the current release candidate from the `next` dist-tag:
+Install the active release:
 
 ```sh
-npm install sheetom@next
+npm install sheetom
 ```
 
-`lightningcss`, `css-tree`, `cssstyle`, and the CSS Tools tokenizer are regular
-dependencies; consumers do not need to install peer dependencies or globals.
-SheetOM validates values before using `cssstyle` only as a static shorthand
-expander, and uses the tokenizer for lossless recovered-rule spans.
-
-Node.js 22 and 24 are tested on Linux x64, Windows x64, and macOS arm64. Bun
-1.3.1 and Deno 2.9.5 are tested on Linux x64. Deno must use a local
-`node_modules` directory and grant the native Lightning CSS binding FFI and
+After the first stable release, use `npm install sheetom@next` to opt into an
+active prerelease. Until then, the `latest` and `next` dist-tags both identify
+the active release candidate.
+
+The root package has no JavaScript runtime or peer dependencies and contains no
+native addon. It pins one matching `@sheetom/native-*` implementation as an
+optional dependency, so npm installs only the binary for the current operating
+system, CPU, and Linux libc. Installing with `--omit=optional` is unsupported
+and produces an explicit missing-binding error rather than a behavioral
+fallback. The native engine includes a pinned, locally maintained Lightning CSS
+source snapshot; consumers do not install a second parser, provide globals, or
+select a fallback engine.
+SheetOM owns observable-value serialization and shorthand expansion rather
+than delegating CSSOM state to a browser-DOM emulation package.
+
+Node.js 22 executes the exact published package on macOS arm64/x64, Windows
+arm64/x64/x86, Linux glibc arm64/ARMv7/x64/ppc64le/s390x, and Linux musl
+arm64/ARMv7/x64. Node.js 24 is additionally tested on Linux x64, Windows x64,
+and macOS arm64. Bun 1.3.1 and Deno 2.9.5 are tested on Linux x64. Deno must use a local
+`node_modules` directory and grant SheetOM's native binding FFI and
 system-information permissions:
 
 ```sh
@@ -31,6 +44,29 @@ deno run --node-modules-dir=manual --allow-ffi --allow-sys app.ts
 
 SheetOM exports browser-named classes but never modifies `globalThis`.
 
+Browser applications can install the separate, ESM-only WebAssembly backend:
+
+```sh
+npm install @sheetom/wasm
+```
+
+```ts
+import { createSheetOM } from "@sheetom/wasm";
+
+const { CSSStyleSheet } = await createSheetOM();
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(".card { color: red; }");
+```
+
+`createSheetOM()` resolves the `.wasm` file relative to its own module and
+shares concurrent default initialization within one JavaScript realm. Passing
+an explicit `URL`, `Response`, `ArrayBuffer`, or `WebAssembly.Module` creates
+an independent facade with distinct class identity. The WASM backend uses the
+same Rust parser, Engine ABI Identity, Resource Budget, and CSSOM facade as the
+native package; it is never an automatic fallback for a missing native addon.
+See [`@sheetom/wasm` usage](./packages/wasm/README.md) for server and worker
+requirements.
+
 ## Use
 
 ```ts
@@ -42,7 +78,7 @@ sheet.replaceSync(".card { width: 12px; }");
 const rule = sheet.cssRules[0];
 if (rule instanceof CSSStyleRule) {
   rule.style.setProperty("padding", "8px 16px");
-  Reflect.set(rule.style, "backgroundColor", "rebeccapurple");
+  rule.style.setProperty("background-color", "rebeccapurple");
 }
 
 console.log(sheet.serialize());
@@ -53,6 +89,11 @@ const existing = parseStyleSheet('@import "theme.css"; .card { color: red; }', {
 console.log(existing.cssRules.length); // 2
 ```
 
+`setProperty()` is the standard, fully typed way to set a declaration,
+especially when its name is dynamic. Browser-style camelCase assignments such
+as `rule.style.backgroundColor = "rebeccapurple"` work at runtime, but the
+current TypeScript declarations do not enumerate every named CSS property.
+
 Constructed sheets follow browser replacement behavior and strip `@import`.
 `parseStyleSheet` creates a regular authoring sheet and preserves valid imports
 without loading them.
@@ -60,15 +101,18 @@ without loading them.
 ## Recovered values and reparsable serialization
 
 SheetOM distinguishes browser-facing CSSOM text from reparsable stylesheet
-output. Chromium
-accepts some values using CSS Syntax end-of-input recovery while preserving the
-unclosed input in `getPropertyValue()` and `cssText`:
+output. Chromium accepts some values using CSS Syntax end-of-input recovery
+while preserving the unclosed input in `getPropertyValue()` and `cssText`:
 
 ```ts
 const sheet = new CSSStyleSheet();
 sheet.insertRule(".card {}");
 
-const rule = sheet.cssRules[0] as CSSStyleRule;
+const rule = sheet.cssRules[0];
+if (!(rule instanceof CSSStyleRule)) {
+  throw new TypeError("Expected a style rule");
+}
+
 rule.style.setProperty("padding", "72px var(--space, var(--space,");
 
 rule.style.getPropertyValue("padding");
@@ -107,17 +151,24 @@ getters and `cssText` are synthesized only while the complete current longhand
 set has compatible values and priorities; genuinely deferred substitutions
 retain separate provenance until a longhand mutation breaks their group.
 
-The Chromium 151 compatibility baseline has exhaustive property breadth for all
-129 manifested multi-longhand shorthands. Grammar depth is a finite reviewed
-contract rather than a claim to implement every future CSS production: 23 codec
-profiles currently carry 92 positive and neighboring-negative branch cases,
-including cardinality, slash and comma lists, compound optional keywords,
-mutation atomicity, and safe round-trips. CI reprobes those cases against the
+The Chromium 151 compatibility baseline covers all 129 manifested
+multi-longhand shorthands. Grammar depth is a finite reviewed contract rather
+than a claim to implement every future CSS production: 24 codec profiles
+currently carry 96 positive and neighboring-negative branch cases, including
+cardinality, slash and comma lists, compound optional keywords, mutation
+atomicity, and reparsable round-trips. CI reprobes those cases against the
 pinned Chromium engine, and a release is blocked unless all 129 breadth seeds
-and all 92 reviewed branches pass exactly. The contracts and browser
+and all 96 reviewed branches pass exactly. The contracts and browser
 observations ship as audit evidence but are never imported as runtime value
 authority.
 
+Relative colors use the same typed engine rather than a text fallback. The
+pinned Chromium 151 and WPT corpus contains 1,146 accepted and 160 rejected
+branches across `rgb()`, `hsl()`, `hwb()`, Lab, LCH, predefined color spaces,
+channel calculations, missing components, and nested color functions. CI
+compares all 1,306 browser-facing getters in one batched browser session and
+also requires every accepted value to survive reparsable serialization.
+
 ## API scope
 
 - `CSSStyleSheet`, live `CSSRuleList`, `CSSRule`, and `MediaList`
@@ -126,6 +177,8 @@ authority.
 - import, font-face, page/margin, nested-declaration, and position-try rules
 - keyframes and mutable keyframe rules
 - counter-style descriptors and font-feature-value maps
+- custom `@function` parameters, return types, conditional groups, and live
+  function descriptors
 - live indexed and named `CSSStyleDeclaration`
 - `insertRule`, `deleteRule`, `replace`, and `replaceSync`
 - `parseStyleSheet` for forgiving regular-sheet parsing
@@ -136,12 +189,37 @@ SheetOM targets standards and shared browser behavior first, with Chromium
 behavior used only as the final measured divergence fallback. Versioned JSON
 Operation Fixtures execute through SheetOM and native browser adapters;
 applicable WPT subtests retain their pinned source path, title, and blob SHA.
-Every release ships its machine-readable Compatibility Report.
+Every release ships its machine-readable Compatibility Report. RC7-or-later
+reports distinguish native and WebAssembly backend evidence; the WASM dimension
+records direct HTTP, worker, bundler, memory-soak, and Publisher-shaped browser
+results instead of inferring them from the shared Rust engine.
 
 Modern or implementation-dependent value grammar is bounded by the checked-in
 [`Value Capability Corpus`](./compatibility/value-capabilities.json). Each
 measured family includes accepted and rejected neighboring cases; browser
 probing occurs only during conformance work and never at runtime.
+The corpus includes 94 CSS Math branches across number, integer, length,
+percentage, angle, and time contexts. It locks dimensional rejection,
+mixed-unit ordering, non-finite constants, function arity, CSSOM observable
+serialization, and atomic failure to Chromium 151.
+
+Computed-context number results are covered separately by the checked-in
+[`Number Result Math Corpus`](./compatibility/number-result-math-capabilities.json).
+It records 860 batched Chromium observations across all 70 accepting
+properties, including relative lengths, percentages, dynamic products and
+quotients, dimension-result neighbors, invalid dimensional multiplication,
+CSSOM expansion, declaration serialization, multi-item animations, slash
+sections, and contextual values in every position of `flex`, `grid`, columns,
+aspect ratios, and border-image families. Both direct and composite properties
+must pass mutation, `cssText`, safe round-trip, and atomic-rejection gates.
+
+Direct numeric and cross-dimension syntax is gated independently by the
+[`Numeric Property Contracts`](./compatibility/numeric-property-contracts.json).
+It crosses 57 number-, percentage-, length-, and legacy-number properties with
+11 accepted and rejected neighboring branches. The public binding must match
+Chromium for acceptance, observable values, `cssText`, indexed names, and
+invalid-mutation atomicity; the browser observations remain test evidence and
+are never loaded by the runtime.
 
 The corresponding shorthand depth evidence is split between the reviewed
 [`Grammar Branch Contracts`](./compatibility/shorthand-grammar-contracts.json)
@@ -160,36 +238,54 @@ advancing the Compatibility Baseline.
 
 SheetOM does not fetch `@import` targets or URLs and does not execute CSS. It is
 also not a sanitizer: valid authored URLs, imports, and browser features remain
-in serialized output. Callers must sanitize untrusted output before attaching
-it to a document or another rendering environment.
+in serialized output. Callers must apply their own content and resource policy
+before attaching untrusted output to a document or another rendering
+environment.
+
+Every sheet has a high default Resource Budget that is checked before native
+parsing or CSSOM mutation: 64 MiB of stylesheet source, 1 MiB per declaration
+value, syntax depth 4,096, one million rules, and 100,000 declarations per
+block. Exceeding a budget throws `RangeError` without changing the previous
+sheet or declaration state. Limits are UTF-8 byte counts where applicable and
+can be changed per sheet without affecting other sheets:
+
+```js
+const bounded = new CSSStyleSheet({
+  resourceBudget: {
+    maxStylesheetBytes: 8 * 1024 * 1024,
+    maxRuleCount: 100_000,
+  },
+});
+```
 
-The browser-shaped interface has no implicit input-size, nesting-depth, or
-mutation-count limits. Isolate or bound untrusted workloads according to your
-application's resource policy. See [SECURITY.md](./SECURITY.md) for private
-vulnerability reporting and supported-release policy.
+Resource Budgets protect the host process; they are not content policy,
+sanitization, or a rendering sandbox. See [the API contract](./docs/api.md) and
+[SECURITY.md](./SECURITY.md) for details.
 
 ## Development
 
 ```sh
-npm test
-npm run typecheck
-npm run build
-npm run conformance:validate
+npm run check
+npm run test:browser:matrix
+npm run test:differential
 npm run conformance:drift
 npm run fuzz
 npm run benchmark
-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. 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.
+`npm run check` covers types, public unit behavior, conformance documents, API
+documentation, build output, runtime artifacts, and the packed-package smoke
+test. Use `npm run test:browser:matrix` on a machine with all Playwright
+dependencies to run Chromium, Firefox, and WebKit. CI separately runs
+`npm run test:differential`, a deterministic, grammar-oriented declaration
+differential with native-browser reparsing witnesses. 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