sheetom 0.1.0-rc.0 → 0.1.0-rc.10

package/README.md

@@ -1,39 +1,36 @@
 # 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.
+**A browser-compatible, mutable CSSOM for JavaScript outside the browser.**
 
-It is intended for server-side stylesheet editing and serialization. It does
-not implement the DOM, cascade, selector matching, layout, or computed styles.
+SheetOM lets build tools, publishers, and server applications parse, inspect,
+mutate, and serialize stylesheets with familiar browser APIs. It preserves
+browser recovery behavior for malformed-but-accepted CSS while still producing
+deterministic, reparsable stylesheet output.
+
+- Browser-shaped `CSSStyleSheet`, rules, and declarations
+- Transactional `setProperty()` behavior and correct shorthand/longhand state
+- Forgiving whole-sheet parsing without a DOM or global installation
+- One repository-owned Rust engine for native and WebAssembly backends
+- ESM, CommonJS, TypeScript, Node.js, Bun, Deno, browsers, and workers
+
+SheetOM focuses on the **Authoring CSSOM**. It does not implement the cascade,
+selector matching, layout, computed styles, fetching, or DOM attachment.
 
 ## Install
 
-SheetOM is not published yet. The first registry release will be
-`0.1.0-rc.0` under the `next` dist-tag after the complete conformance gate
-passes. Once published:
+For Node.js, Bun, or Deno:
 
 ```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
-system-information permissions:
+For browsers and compatible JavaScript isolates:
 
 ```sh
-deno run --node-modules-dir=manual --allow-ffi --allow-sys app.ts
+npm install @sheetom/wasm
 ```
 
-SheetOM exports browser-named classes but never modifies `globalThis`.
-
-## Use
+## Quick start
 
 ```ts
 import { CSSStyleRule, CSSStyleSheet, parseStyleSheet } from "sheetom";
@@ -43,33 +40,68 @@ 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.padding = "8px 16px";
+  rule.style.backgroundColor = "rebeccapurple";
+  rule.style.setProperty("--card-gap", "12px");
 }
 
 console.log(sheet.serialize());
 
-const existing = parseStyleSheet('@import "theme.css"; .card { color: red; }', {
-  href: "https://example.com/assets/app.css",
-});
+const existing = parseStyleSheet(
+  '@import "theme.css"; .card { color: red; }',
+  { href: "https://example.com/assets/app.css" },
+);
+
 console.log(existing.cssRules.length); // 2
 ```
 
-Constructed sheets follow browser replacement behavior and strip `@import`.
-`parseStyleSheet` creates a regular authoring sheet and preserves valid imports
-without loading them.
+Named CSS properties are typed and assignable directly. Use `setProperty()`
+when a property name is dynamic, custom, or hyphenated. `CSSStyleSheet` is the
+only public CSSOM constructor; rules and declarations come from a sheet, just
+as they do in browsers.
 
-## Recovered values and safe serialization
+Constructed sheets strip `@import` during replacement. `parseStyleSheet()` is a
+SheetOM extension for existing regular stylesheets and preserves valid imports
+without fetching them.
 
-SheetOM distinguishes the browser-facing CSSOM text from safe output. Chromium
-accepts some values using CSS Syntax end-of-input recovery while preserving the
-unclosed input in `getPropertyValue()` and `cssText`:
+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
+spelling through CSSOM. SheetOM keeps that observable behavior separate from
+whole-sheet output:
 
 ```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");
@@ -79,76 +111,105 @@ rule.style.cssText;
 // "padding: 72px var(--space, var(--space,;"
 
 sheet.serialize();
-// reparsable CSS with the missing syntax repaired
+// reparsable CSS with the missing syntax safely confined and repaired
+```
+
+| Surface | Purpose |
+| --- | --- |
+| `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. |
+
+Invalid property values and priorities are atomic no-ops: the previous state
+survives unchanged. Static shorthands are stored as canonical longhands, so
+editing and then removing one longhand cannot accidentally reactivate an old
+shorthand value.
+
+Reparsable output prevents malformed input from leaking into a following
+declaration or rule. It is not a CSS sanitizer, URL policy, CSP, or rendering
+sandbox.
+
+## Native and WebAssembly runtimes
+
+The `sheetom` package contains the JavaScript facade and selects one exact
+`@sheetom/native-*` optional package for the current platform. It installs no
+JavaScript parser dependency, downloads no binary at install time, and never
+falls back to a different engine. Omitting optional dependencies is unsupported
+and fails explicitly.
+
+| Runtime | Entry point | Notes |
+| --- | --- | --- |
+| Node.js 22+ | `sheetom` | ESM and CommonJS; prebuilt native packages for macOS, Windows, GNU Linux, and musl Linux targets. |
+| Bun | `sheetom` | Tested through the npm package on Linux x64. |
+| Deno | `sheetom` | Uses npm resolution and requires native FFI/system permissions. |
+| Browsers and workers | `@sheetom/wasm` | ESM-only asynchronous factory; no WASI or global installation. |
+
+Deno example:
+
+```sh
+deno run --node-modules-dir=manual --allow-ffi --allow-sys app.ts
 ```
 
-Invalid `setProperty` values and priorities are atomic no-ops, matching browser
-behavior. Opt into mutation diagnostics with `{ diagnostics: true }` and drain
-them using `takeDiagnostics()`.
+WebAssembly example:
 
-## API scope
+```ts
+import { createSheetOM } from "@sheetom/wasm";
 
-- `CSSStyleSheet`, live `CSSRuleList`, `CSSRule`, and `MediaList`
-- nested `CSSStyleRule`, `CSSGroupingRule`, and `CSSConditionRule`
-- media, supports, container, layer, scope, and starting-style rules
-- import, font-face, page/margin, nested-declaration, and position-try rules
-- keyframes and mutable keyframe rules
-- counter-style descriptors and font-feature-value maps
-- live indexed and named `CSSStyleDeclaration`
-- `insertRule`, `deleteRule`, `replace`, and `replaceSync`
-- `parseStyleSheet` for forgiving regular-sheet parsing
-- browser-facing `cssText` and reparsable `serialize()` output
-- generic retention of read-only metadata rules and experimental/future rules
+const { CSSStyleSheet } = await createSheetOM();
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(".card { color: red; }");
+```
 
-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.
+The native and WebAssembly packages execute the same Rust engine and verify an
+exact engine ABI identity before exposing CSSOM objects. `createSheetOM()`
+shares default initialization within one JavaScript realm; passing an explicit
+`URL`, `Response`, `ArrayBuffer`, or `WebAssembly.Module` creates an isolated
+facade with its own class identity.
 
-See [the behavioral API reference](./docs/api.md) for return, exception,
-identity, and detachment contracts. Maintainers use the separately reviewed
-[release procedure](./docs/releasing.md); Changesets never publishes by itself.
+## Compatibility contract
 
-The checked-in ordinary-property manifest was generated against Chromium
-151.0.7922.34. Run `npm run generate:properties` only when intentionally
-advancing the Compatibility Baseline.
+SheetOM tests complete observable state—not only whether serialized CSS looks
+similar. Its versioned evidence covers getters, `cssText`, indexed property
+order, priorities, invalid-mutation atomicity, live identity, shorthand
+sequences, recovery, native-browser reparsing, subprocess crash safety,
+grammar-oriented fuzzing, and Publisher-shaped performance workloads.
 
-## Security and resource boundaries
+Standards and shared browser behavior take precedence. When browser engines
+genuinely differ, SheetOM records the result and follows the pinned Chromium
+baseline as its final fallback. Browser observations and WPT mappings remain
+test evidence; they are never imported as runtime authority.
 
-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.
+See [Compatibility](./docs/compatibility.md) for the exact promise, evidence,
+and exclusions.
 
-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 limits and diagnostics
 
-## Development
+Each sheet has configurable limits for stylesheet bytes, declaration-value
+bytes, syntax depth, rule count, and declarations per block. A limit violation
+throws `RangeError` before mutation. These budgets protect the host process;
+they are not content policy.
 
-```sh
-npm test
-npm run typecheck
-npm run build
-npm run conformance:validate
-npm run conformance:drift
-npm run fuzz
-npm run benchmark
-npm run pack:test
+Mutation diagnostics are opt-in:
+
+```ts
+const sheet = new CSSStyleSheet({ diagnostics: true });
+// ...mutate the sheet...
+const diagnostics = sheet.takeDiagnostics();
 ```
 
-`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`.
+Diagnostics retain rejected inputs until drained. Leave them disabled or drain
+them promptly when handling untrusted or unusually large source.
+
+## Documentation
 
-Only the latest published `0.x` minor and its active prereleases receive fixes
-before 1.0. During `0.x`, observable compatibility corrections and interface
-breaks require a new minor version and migration note; patches remain backward
-compatible.
+- [API behavior](./docs/api.md)
+- [Architecture](https://github.com/leo91000/sheetom/blob/main/docs/architecture.md)
+- [Compatibility](https://github.com/leo91000/sheetom/blob/main/docs/compatibility.md)
+- [Contributing](https://github.com/leo91000/sheetom/blob/main/CONTRIBUTING.md)
+- [Release process](https://github.com/leo91000/sheetom/blob/main/docs/releasing.md)
+- [Architecture decisions](https://github.com/leo91000/sheetom/blob/main/docs/adr/README.md)
+- [Security policy](./SECURITY.md)
 
 ## License
 
-MIT
+MIT. Vendored parser sources retain their upstream licenses and provenance.