sheetom 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SheetOM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# 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.
+
+It is intended for server-side stylesheet editing and serialization. It does
+not implement the DOM, cascade, selector matching, layout, or computed styles.
+
+## 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:
+
+```sh
+npm install sheetom@next
+```
+
+`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:
+
+```sh
+deno run --node-modules-dir=manual --allow-ffi --allow-sys app.ts
+```
+
+SheetOM exports browser-named classes but never modifies `globalThis`.
+
+## Use
+
+```ts
+import { CSSStyleRule, CSSStyleSheet, parseStyleSheet } from "sheetom";
+
+const sheet = new CSSStyleSheet({ diagnostics: true });
+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");
+}
+
+console.log(sheet.serialize());
+
+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.
+
+## Recovered values and safe serialization
+
+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`:
+
+```ts
+const sheet = new CSSStyleSheet();
+sheet.insertRule(".card {}");
+
+const rule = sheet.cssRules[0] as CSSStyleRule;
+rule.style.setProperty("padding", "72px var(--space, var(--space,");
+
+rule.style.getPropertyValue("padding");
+// "72px var(--space, var(--space,"
+
+rule.style.cssText;
+// "padding: 72px var(--space, var(--space,;"
+
+sheet.serialize();
+// reparsable CSS with the missing syntax repaired
+```
+
+Invalid `setProperty` values and priorities are atomic no-ops, matching browser
+behavior. Opt into mutation diagnostics with `{ diagnostics: true }` and drain
+them using `takeDiagnostics()`.
+
+## API scope
+
+- `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
+
+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.
+
+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.
+
+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.
+
+## Security and resource boundaries
+
+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.
+
+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.
+
+## Development
+
+```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
+```
+
+`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`.
+
+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.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+## Supported releases
+
+Before 1.0, only the latest published `0.x` minor and its active prereleases receive security fixes.
+
+## Reporting a vulnerability
+
+Use GitHub's **Report a vulnerability** form in the repository Security tab. Do not open a public issue for a suspected vulnerability.
+
+Reports should include the affected SheetOM version, impact, reproduction steps, and any known mitigations. You can expect an initial acknowledgement within seven days when practical, but this is a maintainer response target rather than a contractual service-level agreement.
+
+SheetOM parses and serializes CSS but is not a sanitizer. It does not fetch resources or execute CSS; callers are responsible for validating untrusted output before it crosses a rendering boundary.

package/compatibility/WPT-LICENSE.md

@@ -0,0 +1,15 @@
+# The 3-Clause BSD License
+
+Copyright © web-platform-tests contributors
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+This text is copied from Web Platform Tests revision
+`54f8f933629e7c010ae98a246729af01f8abcda5`. SheetOM records every adapted
+scenario's exact source path and subtest title in `wpt-mappings.json`.

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

@@ -0,0 +1,70 @@
+{
+  "$schema": "../schemas/compatibility-report.schema.json",
+  "schemaVersion": 1,
+  "packageVersion": "0.1.0-rc.0",
+  "baseline": {
+    "wptCommit": "54f8f933629e7c010ae98a246729af01f8abcda5",
+    "lightningcss": "1.33.0",
+    "cssTree": "3.2.1",
+    "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": 3,
+    "divergences": 1,
+    "excluded": 0,
+    "unexplained": 0
+  },
+  "evidence": {
+    "operationFixtures": {
+      "passed": 4,
+      "total": 4
+    },
+    "nativeWpt": [
+      {
+        "engine": "chrome",
+        "version": "150.0.7871.128",
+        "sha256": "93b768eb22570bb5d0b2ce26ec3a6df1576f5bb410b0d9c4a59b7913326e8a5d",
+        "passed": 4,
+        "total": 4
+      },
+      {
+        "engine": "firefox",
+        "version": "153.0.3",
+        "sha256": "64d86d8096a586634b6522b010960d29a487fc40e33d8a419907f924b2633ca0",
+        "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.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."
+    }
+  ]
+}

package/compatibility/baselines/README.md

@@ -0,0 +1,3 @@
+# Compatibility baselines
+
+Release pull requests add one immutable, schema-validated `<version>.json` report here. `0.0.0` is an unpublished implementation version and intentionally has no report.

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

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/leo91000/sheetom/compatibility/schemas/compatibility-report.schema.json",
+  "title": "SheetOM Compatibility Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "packageVersion", "baseline", "summary", "evidence", "resolutions"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "packageVersion": { "type": "string" },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wptCommit", "lightningcss", "cssTree", "runtimes", "browsers"],
+      "properties": {
+        "wptCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "lightningcss": { "type": "string" },
+        "cssTree": { "type": "string" },
+        "runtimes": { "type": "object" },
+        "browsers": { "type": "object" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["passed", "divergences", "excluded", "unexplained"],
+      "properties": {
+        "passed": { "type": "integer", "minimum": 0 },
+        "divergences": { "type": "integer", "minimum": 0 },
+        "excluded": { "type": "integer", "minimum": 0 },
+        "unexplained": { "const": 0 }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operationFixtures", "nativeWpt"],
+      "properties": {
+        "operationFixtures": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["passed", "total"],
+          "properties": {
+            "passed": { "type": "integer", "minimum": 0 },
+            "total": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "nativeWpt": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["engine", "version", "sha256", "passed", "total"],
+            "properties": {
+              "engine": { "enum": ["chrome", "firefox", "safari"] },
+              "version": { "type": "string" },
+              "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+              "passed": { "type": "integer", "minimum": 0 },
+              "total": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    },
+    "resolutions": { "type": "array" }
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/leo91000/sheetom/compatibility/schemas/compatibility-resolutions.schema.json",
+  "title": "SheetOM Compatibility Resolutions",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "resolutions"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "resolutions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["fixtureId", "decision", "rationale", "expected"],
+        "properties": {
+          "fixtureId": { "type": "string" },
+          "decision": {
+            "enum": ["shared", "specification", "chromium-fallback", "scope-exclusion"]
+          },
+          "rationale": { "type": "string", "minLength": 1 },
+          "expected": { "type": "array" }
+        }
+      }
+    }
+  }
+}

package/compatibility/schemas/operation-fixture.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/leo91000/sheetom/compatibility/schemas/operation-fixture.schema.json",
+  "title": "SheetOM Operation Fixture",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "operations"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "provenanceIds": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/operation" }
+    }
+  },
+  "$defs": {
+    "boundaryValue": {
+      "oneOf": [
+        {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" },
+            { "type": "null" }
+          ]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["$type"],
+          "properties": {
+            "$type": {
+              "enum": [
+                "undefined",
+                "nan",
+                "positive-infinity",
+                "negative-infinity",
+                "bigint",
+                "symbol",
+                "throwing-string-coercion"
+              ]
+            },
+            "value": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "operation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["op", "target", "args"],
+      "properties": {
+        "op": { "type": "string" },
+        "target": { "type": "string" },
+        "handle": { "type": "string" },
+        "args": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/boundaryValue" }
+        },
+        "observe": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "return",
+              "exception",
+              "cssText",
+              "length",
+              "items",
+              "parentRule",
+              "parentStyleSheet",
+              "serialize"
+            ]
+          },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/compatibility/schemas/wpt-mappings.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/leo91000/sheetom/compatibility/schemas/wpt-mappings.schema.json",
+  "title": "SheetOM WPT mappings",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "wptCommit", "mappings", "tombstones"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "wptCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "mappings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "path", "subtest", "blobSha", "disposition", "coverage", "translation", "fixtureIds"],
+        "properties": {
+          "id": { "type": "string" },
+          "path": { "type": "string" },
+          "subtest": { "type": "string" },
+          "blobSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+          "disposition": { "enum": ["applicable", "partial", "excluded"] },
+          "coverage": { "enum": ["full", "partial", "none"] },
+          "translation": { "type": "string" },
+          "fixtureIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+          "reason": { "type": "string" },
+          "selectionNote": { "type": "string" }
+        }
+      }
+    },
+    "tombstones": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "path", "subtest", "reason"],
+        "properties": {
+          "id": { "type": "string" },
+          "path": { "type": "string" },
+          "subtest": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  }
+}