diff --git a/.agents/skills/champ/SKILL.md b/.agents/skills/champ/SKILL.md index dc0875c..2096e7e 100644 --- a/.agents/skills/champ/SKILL.md +++ b/.agents/skills/champ/SKILL.md @@ -16,14 +16,16 @@ The subagent persona is a superstar senior SWE. They love concrete specification ## Subagent Workflow 1. **Pick a Task**: Select an uncompleted task from `PLAN.md`. Mark it as in progress `[/]` using the `plan-manager` skill if available. -2. **Red Phase**: Write a failing test in the appropriate test file (or create a new one) that demonstrates the missing feature or bug. -3. **Green Phase**: Implement the code in `src/` to make the test pass. -4. **Verify**: Run the test to ensure it passes. -5. **Preflight**: Run `pnpm run preflight` to ensure all tests pass and types are correct. -6. **Commit**: Commit the targeted changes with a human-readable, lowercase message describing the action. Do NOT use `git add .` or `git commit -a`. +2. **Diagnostic Cluster Triage (for WPT tasks)**: When tackling WPT conformance tasks, run `node scripts/wpt_cluster_failures.ts --spec=` to inspect top failure clusters and prioritize high-frequency patterns. +3. **Red Phase**: Write a failing test in the appropriate test file (or create a new one in `tests/`) that demonstrates the missing feature or bug. +4. **Green Phase**: Implement the code in `src/` to make the test pass, adding explicit spec anchor citations in comments. +5. **Verify**: Run the targeted test to ensure it passes. +6. **Preflight**: Run `pnpm run preflight` to ensure all tests pass and types/linters are 100% clean. +7. **Commit**: Commit the targeted changes with a human-readable, lowercase message describing the action. Do NOT use `git add .` or `git commit -a`. -## Constraints -- Follow the "Executable Specification" pattern with spec citations in comments. +## Constraints & Mandatory Standards +- **Mandatory Spec Anchor Citations**: You MUST cite the exact Bikeshed specification section and anchor in code comments for every implemented algorithm, branch, or validation rule (e.g. `// cssom-1 § 6.5.3 #insert-a-css-rule` or `// selectors-4 § 4.1 #forgiving-selector`). This maps our implementation directly to the normative standard and allows reviewers to verify correctness. +- **Consult Normative Specs First**: Actively inspect the normative `.bs` source files in `submodules/csswg-drafts/` and `submodules/css-houdini-drafts/` to understand spec algorithms and edge cases before implementing. - **File Editing**: Do NOT use bash redirection or scratch scripts for editing files. Use the specialized tools: `replace_file_content` for single contiguous edits, `multi_replace_file_content` for multiple non-contiguous edits, or `write_to_file` for new files. - **Subagent Reuse**: If a subagent with the appropriate role and context already exists from a previous task, prefer reusing it via `send_message` instead of invoking a new one. diff --git a/.agents/skills/coherence-auditor/SKILL.md b/.agents/skills/coherence-auditor/SKILL.md index b55d97a..0f9a858 100644 --- a/.agents/skills/coherence-auditor/SKILL.md +++ b/.agents/skills/coherence-auditor/SKILL.md @@ -25,15 +25,17 @@ Use this skill when you need to audit the consistency, link integrity, codebase - `README.md` - `PLAN.md` - `AGENTS.md` - - `API_BOUNDARIES.md` - `LOOP.md` - `MAINTENANCE.md` - - `contributing.md` + - `CONTRIBUTING.md` - Verify taxonomy, workflow, and abbreviation consistency across docs: - **Subagent Personas & Quality Loop**: Ensure references to `champ` (Developer), `codex_reviewer_cmd` (Reviewer), `Grizz` (Gatekeeper), and `scrutineer` (Spec Auditor) in `LOOP.md`, `AGENTS.md`, and `PLAN.md` match exact names and roles. - **Spec Modules & Submodule References**: Validate spec names (`CSSOM Level 1`, `CSS Syntax Level 3`, `CSS Values Level 4`, `CSS Nesting Level 1`, `CSS Typed OM Level 1 & 2`, `CSS Logical Properties Level 1`, `Houdini`) and their underlying submodule paths (`submodules/csswg-drafts/`, `submodules/css-houdini-drafts/`). - - **Architectural Constraints**: Ensure consistent documentation of `ParseHooks` (`src/parse-hooks.ts`) for circular dependency inversion, and `API_BOUNDARIES.md` for documented spec deviations. - - **Execution Rules & Scripts**: Enforce that documentation consistently specifies native Node execution (`node script.ts`, NOT `npx tsx` or `ts-node`) and valid npm scripts (`pnpm run preflight`, `pnpm run codegen`, `pnpm run maintain`, `pnpm test`). + - **Architecture & Spec Boundaries**: + - Audit `README.md § Architecture & Spec Boundaries` against actual codebase exports in `src/index.ts` and `tests/api-surface.test.ts`. + - Ensure documented standard CSSOM / Houdini interfaces, Bridge utilities, intentional spec deviations, and non-goals (e.g. no `getComputedStyle()`) are factually accurate, up to date, and omit no methods or deviations. + - Ensure consistent documentation of `ParseHooks` (`src/parse-hooks.ts`) for circular dependency inversion. + - **Execution Rules & Scripts**: Enforce that documentation consistently specifies native Node execution (`node script.ts`, NOT `npx tsx` or `ts-node`) and valid npm scripts (`pnpm run preflight`, `pnpm run codegen`, `pnpm run maintain`, `pnpm test`, `wpt:node:*`, `wpt:browser:*`). - Identify any contradictory claims, outdated API signatures, or conflicting guidelines between files. 2. **Codebase & Script Terminology Consistency Audit**: diff --git a/.agents/skills/coherence-auditor/scripts/validate_links.ts b/.agents/skills/coherence-auditor/scripts/validate_links.ts index 6eb8bed..de13856 100644 --- a/.agents/skills/coherence-auditor/scripts/validate_links.ts +++ b/.agents/skills/coherence-auditor/scripts/validate_links.ts @@ -15,10 +15,9 @@ const CANONICAL_DOCS = [ 'README.md', 'PLAN.md', 'AGENTS.md', - 'API_BOUNDARIES.md', 'LOOP.md', 'MAINTENANCE.md', - 'contributing.md', + 'CONTRIBUTING.md', ]; function getLineNumber(content: string, index: number): number { diff --git a/.npmignore b/.npmignore index e4d1500..34c0121 100644 --- a/.npmignore +++ b/.npmignore @@ -24,7 +24,6 @@ MAINTENANCE.md AGENTS.md CONTRIBUTING.md wpt-progress.md -wpt-typed-om-progress.md # Logs & temp files *.log @@ -33,4 +32,3 @@ wpt-typed-om-progress.md !pnpm-lock.yaml !pnpm-workspace.yaml -!API_BOUNDARIES.md diff --git a/AGENTS.md b/AGENTS.md index e30921a..3caed56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ Building a spec-compliant CSSOM (CSS Object Model) parser in pure TypeScript. - **Execution**: Run node scripts directly: `node script.ts`. Do NOT use `npx tsx` or `ts-node`. ## Spec References -We are building a spec-compliant implementation. Agents MUST adhere to the W3C specifications listed below, except where intentional deviations are documented in `API_BOUNDARIES.md` for pragmatism, performance, or Node.js compatibility. You are expected to actively consult these Bikeshed (`.bs`) source files to understand the normative algorithms and edge cases before implementing or auditing features. +We are building a spec-compliant implementation. Agents MUST adhere to the W3C specifications listed below, except where intentional deviations are documented in `README.md` for pragmatism, performance, or Node.js compatibility. You are expected to actively consult these Bikeshed (`.bs`) source files to understand the normative algorithms and edge cases before implementing or auditing features. Relevant Specifications: - CSSOM: `submodules/csswg-drafts/cssom-1/Overview.bs` @@ -39,7 +39,7 @@ To avoid circular dependencies between the core parser and the CSSOM/Typed OM la ### API Boundaries We intentionally deviate from some specifications for pragmatism, performance, or Node.js compatibility (e.g., providing synchronous versions of Houdini APIs). -- **Rule**: Before proposing refactors to align strictly with IDL, review `API_BOUNDARIES.md` to understand documented intentional deviations. +- **Rule**: Before proposing refactors to align strictly with IDL, review `README.md` to understand documented intentional deviations. ## Spec Evolution & Maintainability diff --git a/API_BOUNDARIES.md b/API_BOUNDARIES.md deleted file mode 100644 index 45add5b..0000000 --- a/API_BOUNDARIES.md +++ /dev/null @@ -1,86 +0,0 @@ -# API Boundaries - -This document outlines the boundaries between standard CSSOM specifications and custom extensions in this library. - -## 1. Standard CSSOM Layer (Legacy) -These APIs are defined in the [CSSOM-1](https://drafts.csswg.org/cssom-1/) specification. They are designed to mimic the standard browser APIs. - -### Interfaces -- `CSSStyleSheet` -- `CSSStyleRule` -- `CSSMediaRule` -- `CSSSupportsRule` -- `CSSFontFaceRule` -- `CSSPageRule` -- `CSSKeyframesRule` -- `CSSKeyframeRule` -- `CSSNamespaceRule` -- `CSSImportRule` -- `CSSStyleDeclaration` -- `MediaList` -- `StyleSheetList` -- `LinkStyle` - -### Deviations/Extensions -- **Constructors**: Standard CSSOM usually instantiates these via the DOM. We allow direct instantiation with parameters (e.g., `new CSSStyleSheet(rules)`) to make them usable in Node.js without a full browser environment. -- **Parsing**: Standard CSSOM does not expose static parsing methods on these classes. We use the `Parser` class (see below) to bridge this gap. -- **`CSSImportRule.styleSheet`**: Hardcoded to `null` because the library is a static, offline parser and does not perform network fetches or local I/O to load external imported stylesheets. - ---- - -## 2. Houdini Layer (Modern & Experimental) -These APIs are defined in newer Houdini drafts and are intended to expose lower-level parsing and typed values. - -### Specifications Followed -- **CSS Typed OM**: `submodules/css-houdini-drafts/css-typed-om/Overview.bs` -- **CSS Parser API**: Based on the [WICG CSS Parser API](https://github.com/WICG/css-parser-api) draft. - -### Interfaces & Methods -- `CSS.parseStylesheet()` -- `CSS.parseRuleList()` -- `CSS.parseRule()` -- `CSS.parseDeclarationList()` -- `CSS.parseDeclaration()` -- `CSS.parseValue()` -- `CSS.parseValueList()` -- `CSS.parseCommaValueList()` -- `CSSParserRule`, `CSSParserAtRule`, `CSSParserQualifiedRule` -- `CSSParserDeclaration`, `CSSParserBlock`, `CSSParserFunction` -- `CSSNumericValue`, `CSSUnitValue`, `CSSMathValue` (and subclasses) -- `CSSTransformValue`, `CSSTransformComponent` (and subclasses) -- `StylePropertyMap` (Read-Write and Read-Only) - -### Deviations/Extensions -- **String Boxing**: The spec defines `CSSToken` as `typedef (DOMString or CSSStyleValue or CSSParserValue) CSSToken;`. We box strings in `CSSParserToken` instead of allowing raw strings directly. -- **Synchronous Execution**: `parseRule` and `parseDeclarationList` are implemented synchronously instead of returning Promises. -- **Immutability**: Properties like `prelude`, `body`, and `args` are mutable arrays instead of `FrozenArray`. -- **Constructor Arguments**: The `body` parameter is mandatory in some constructors (e.g., `CSSParserQualifiedRule`) where the spec makes it optional. -- **Math Functions**: We support new math functions from CSS Values 4 (like `sin()`, `cos()`, `abs()`, etc.) via a custom `CSSMathFunction` class. Since the CSS Typed OM 1 spec only defines operators for `sum`, `product`, `negate`, `invert`, `min`, `max`, and `clamp`, `CSSMathFunction.operator` returns `'sum'` as a fallback for these new functions to satisfy the type system, which is a known spec gap. -- **WebIDL Dictionary Bindings**: In a browser, the WebIDL bindings layer automatically checks dictionary constraints (like checking that the `name` parameter in `CSS.registerProperty()` options is present and throwing a `TypeError`). In our headless Node runtime, we perform these validations manually in JavaScript. -- **`CSSTransformComponent` Inheritance**: In the CSS Typed OM Level 1 specification, `CSSTransformComponent` does not inherit from `CSSStyleValue`. However, to support properties like `translate` and `rotate` which reify directly to transform components, and to allow them to be returned from `CSSStyleValue.parseAll()` and `StylePropertyMap.get()` (which return `CSSStyleValue`), we make `CSSTransformComponent` extend `CSSStyleValue`. This matches the implementation in modern browsers (like Blink/Chrome). -- **Math Simplification & AST Structure Preservation**: In accordance with CSS Values 4 (Calculation Trees), we preserve the raw parsed AST structure of mathematical expressions in `CSSNumericValue.parse()` and `StylePropertyMap` parsing rather than performing eager simplification of compatible units (which is expected by older/Level 1 WPT tests). Eager simplification is deferred to computed-value time or manual `.simplify()` calls. - ---- - -## 3. Custom Bridge & Utility Layer -These APIs are NOT part of any W3C specification. They exist to make the library usable for static analysis, testing, and in non-browser environments. - -### Interfaces & Methods -- **`Parser` class static utilities**: - - `calculateSpecificity(selector)`: Calculates the specificity of a selector. - - `getCascadedStyle(element, rules)`: Calculates computed styles against a static DOM (like `linkedom`). - - `resolveVariables(style, property, envMap?)`: Expands `var()` and `env()` functions with fallbacks. -- **Standalone Utilities**: - - `tokenize(text)`: Exposes the low-level tokenizer. - - `serialize(ast)`: Exposes the low-level serializer. - - `StreamingTokenizer`: For memory-efficient streaming tokenization. - -## API Surface Verification -The public API surface area is locked down and verified by [api-surface.test.ts](./tests/api-surface.test.ts). Any additions or removals of public exports must be reflected in that test to ensure intentional API changes. - ---- - -## Guidelines for Maintainers -- When adding new features, clearly identify which layer they belong to. -- Prefer implementing standard APIs (Houdini or CSSOM) over custom ones whenever possible. -- Cite spec anchors in code comments for all standard implementations. diff --git a/LOOP.md b/LOOP.md index f986ce9..a1613d1 100644 --- a/LOOP.md +++ b/LOOP.md @@ -21,19 +21,24 @@ graph TD ### The Personas & Segregation of Duties 1. **The Orchestrator**: - * *Role*: Plans roadmaps (`PLAN.md`), updates progress logs (`wpt-progress.md`, `wpt-typed-om-progress.md`), and delegates tasks. + * *Role*: Plans roadmaps (`PLAN.md`), updates progress logs (`wpt-progress.md`), and delegates tasks. * *Constraint*: The Orchestrator **never writes code or runs manual fixes**. It coordinates subagents and enforces the gate transitions. 2. **The Developer (`champ`)**: - * *Role*: Implements features, writes tests, runs `pnpm run preflight`, and commits changes to git. - * *Constraint*: Naturally optimistic. Wants compilation and test runs to pass as quickly as possible. + * *Role*: Implements features, writes tests, runs `pnpm run preflight`, and commits changes to git following the [champ skill](file:///usr/local/google/home/paulirish/code/cssom/.agents/skills/champ/SKILL.md). + * *Standards*: + * **Spec Anchor Citations**: Must cite exact normative specification anchors in code comments (e.g. `// cssom-1 § 6.5.3 #insert-a-css-rule`) mapping implementation to standard algorithms. + * **Mandatory Pre/Post Cluster Triage & Delta Reconciliation**: When working on WPT conformance waves, start with `node scripts/wpt_cluster_failures.ts --spec=` to record the baseline failure cluster. After implementation, run `wpt_cluster_failures` again. If the test increase is noticeably smaller than the targeted cluster, the developer **MUST diagnose the top remaining failure cluster** and fix any near-miss harness/serialization gaps (e.g. computed color formatting) before declaring the phase complete. + * *Constraint*: Naturally optimistic. Wants compilation and test runs to pass as quickly as possible. 3. **The Reviewer (`codex_reviewer_cmd`)**: - * *Role*: Senior engineer persona. Has command execution permissions and runs `git show HEAD` to audit styling, typing, and safety. - * *Constraint*: Direct, factual, and zero-fluff. Rejects any lazy casts, hidden linter disables, or untested code paths. + * *Role*: Senior engineer persona. Has command execution permissions and runs `git show HEAD` to audit styling, typing, spec citations, and safety. + * *Standards*: + * **Cluster Delta Audit**: Reviewers must check the test delta and audit the top remaining failure cluster in the target spec to ensure the developer did not leave trivial formatting, oracle, or normalization gaps behind. + * *Constraint*: Direct, factual, and zero-fluff. Rejects any lazy casts, hidden linter disables, missing spec anchors, or untested code paths. 4. **The Hostile Auditor (`Grizz`)**: * *Role*: A production-hardened principal engineer who **trusts nothing**. - * *Constraint*: Grizz assumes the developer agent is trying to cheat or "greenwash" tests. He physically inspects the committed tests on disk and checks for linter config overrides, snapshot/regex sanitizers, or bypassed assertions. Grizz holds sole veto power over the final shipping gate. + * *Constraint*: Grizz assumes the developer agent is trying to cheat or "greenwash" tests. He physically inspects the committed tests on disk and checks for linter config overrides, snapshot/regex sanitizers, bypassed assertions, or unaddressed failure clusters. Grizz holds sole veto power over the final shipping gate. 5. **The Spec Auditor (`scrutineer`)**: - * *Role*: Validates implementation and test coverage directly against the normative Bikeshed specs (e.g. `submodules/csswg-drafts/**/*.bs`). + * *Role*: Validates implementation and test coverage directly against the normative Bikeshed specs in `submodules/` (e.g. `submodules/csswg-drafts/**/*.bs`). --- @@ -54,6 +59,7 @@ Since subagent definitions are session-specific and do not persist across conver - Reject silenced compiler warnings or linter overrides. - Reject snapshot sanitizers or regex output-censoring. - Ensure tests are strong and contain valid assertions. + - Conformance Delta Audit: Verify that the patch eliminated the target failure cluster without leaving trivial serialization / harness mismatches in the top remaining cluster. Format your response exactly as: # Code Review Report @@ -76,6 +82,7 @@ Since subagent definitions are session-specific and do not persist across conver 1. Suppressed eslint rules (e.g. `/* eslint-disable */` or `.oxlintrc.json` overrides). 2. Test modifications that mute assertions (e.g., empty try-catch blocks, mock bypasses, or adding tests to WPT sandbox excludes/knownFailures). 3. Output normalizers/regex-scrubbing that hides snapshot layout mismatches. + 4. Conformance Delta Audit: Verify that the patch actually eliminated the targeted failure cluster, and reject changes that leave obvious harness or serialization mismatches in the top remaining cluster. Be hostile and thorough. State "No blocking findings discovered" only if the code is 100% clean and correct. ``` @@ -94,7 +101,7 @@ Reviewers and Grizz MUST reject any of the following shortcuts: * No file-level `/* eslint-disable */`. * **Assertion & Test Sandbox Integrity**: * No test normalization/regex-scrubbing to hide layout or structural mismatches. Comparisons must be raw (e.g., `expect(actual).toEqual(expected)`). - * No adding of failing WPT sandbox tests to the `exclude` or `knownFailures` lists in `tests/fixtures/baselines/wpt-sandbox-known-failures.json` unless it represents a spec deviation documented in `API_BOUNDARIES.md`. + * No adding of failing WPT sandbox tests to the `exclude` or `knownFailures` lists in `tests/fixtures/baselines/wpt-sandbox-known-failures.json` unless it represents a spec deviation documented in `README.md`. * **Oracle Isolation**: * Do not modify the `submodules/` specs or test suites to make tests pass. diff --git a/MAINTENANCE.md b/MAINTENANCE.md index 50a3954..a532592 100644 --- a/MAINTENANCE.md +++ b/MAINTENANCE.md @@ -28,9 +28,9 @@ If you want to run the steps individually: **1. Update Submodules:** ```bash -pnpm run submodules:update +pnpm run submodules:upgrade ``` -This runs `git submodule update --init --recursive --remote`. +This runs `git submodule update --init --remote && pnpm run submodules:update` to pull remote updates and recursively initialize. **2. Generate Fixtures:** ```bash @@ -42,7 +42,7 @@ This runs `node scripts/extract_external_suites.ts`. ```bash pnpm test ``` -Or run the full preflight check (typecheck and test): +Or run the full preflight check (typecheck, linter, and tests): ```bash pnpm run preflight ``` @@ -59,7 +59,7 @@ When specifications are updated in the submodules, we need to ensure our impleme ## Spec Compliance Auditing via Subagents -To maintain high compliance at scale, we use specialized AI subagents to audit the codebase against the specifications. This process should be run periodically or when significant spec updates occur. +To maintain high compliance at scale, we use specialized AI subagents (such as `scrutineer`) to audit the codebase against the specifications. This process should be run periodically or when significant spec updates occur. ### Recommended Subagents @@ -71,11 +71,11 @@ When initiating an audit, spawn the following subagents with their specific role - **CSS Nesting & Variables Auditor**: Reads `css-nesting-1/Overview.bs` and `css-variables-1/Overview.bs`. Focuses on interleaved declarations and custom property handling. - **Media Queries Auditor**: Reads `mediaqueries-4/Overview.bs`. Focuses on media query list parsing and evaluation. - **CSS Logical Auditor**: Reads `css-logical-1/Overview.bs`. Focuses on logical properties shorthand serialization in `cssText`. -- **CSS Values & Typed OM Auditor**: Reads `css-values-4/Overview.bs` and `css-typed-om-1/Overview.bs`. Focuses on value representation and serialization. +- **CSS Values & Typed OM Auditor**: Reads `css-values-4/Overview.bs` and `submodules/css-houdini-drafts/css-typed-om/Overview.bs`. Focuses on value representation and serialization. #### 2. Edge Case Researchers - **CSS Spec Tricky Case Researcher**: Reads specs to identify complex error recovery scenarios or easily overlooked rules (e.g., EOF handling, unclosed constructs). -- **WPT Tricky Case Researcher**: Searches through `tests/web-platform-tests` to find specific tests that cover edge cases that might fail in naive implementations. +- **WPT Tricky Case Researcher**: Searches through `submodules/web-platform-tests` to find specific tests that cover edge cases that might fail in naive implementations. ### General Task for Auditors Every auditor should: diff --git a/PLAN.md b/PLAN.md index b5c09c1..9b8d16f 100644 --- a/PLAN.md +++ b/PLAN.md @@ -596,7 +596,7 @@ Objective: Resolve circular dependencies between `Parser` and `Typed OM` and loc ### Tasks - [x] **Resolve Circular Dependencies**: Used Dependency Inversion via `ParseHooks` to inject parser implementations into Typed OM classes. - [x] **API Lockdown**: Added `tests/api-surface.test.ts` to lock down the API surface. -- [x] **Documentation**: Documented spec boundaries in `API_BOUNDARIES.md`. +- [x] **Documentation**: Documented spec boundaries in `README.md`. ## Phase 34: Static Selector Matching Enhancements @@ -1396,11 +1396,11 @@ Objective: Build a Node-based VM sandbox runner using `linkedom` to execute brow - [x] **HTMLElement attributeStyleMap**: Define `HTMLElement.prototype.attributeStyleMap` and `Element.prototype.computedStyleMap()` getters using our `StylePropertyMap` wrapper. #### 2. Sandbox VM Execution Script [x] -- [x] **Runner script**: Create `scripts/run_wpt_sandbox.ts` to crawl selected WPT subfolders (like `css-typed-om/` and `css-properties-values-api/`), execute their internal script tags inside a `vm` context, mock `testharness.js` functions, and collect test results. -- [x] **Sandbox configuration**: Support a config file (`tests/wpt-sandbox-config.json`) defining allowlisted/skipped suites and baseline failures. +- [x] **Runner script**: Create `scripts/run_wpt_node.ts` to crawl selected WPT subfolders (like `css-typed-om/` and `css-properties-values-api/`), execute their internal script tags inside a `vm` context, mock `testharness.js` functions, and collect test results. +- [x] **Sandbox configuration**: Support a config file (`tests/wpt-node-config.json`) defining allowlisted/skipped suites and baseline failures. #### 3. Integrate into Preflight [x] -- [x] **Preflight hook**: Hook `scripts/run_wpt_sandbox.ts` into our node test run to enforce dynamic browser WPT checks. +- [x] **Preflight hook**: Hook `scripts/run_wpt_node.ts` into our node test run to enforce dynamic browser WPT checks. --- @@ -1454,7 +1454,7 @@ Objective: Implement the findings from our consolidated spec compliance report a #### 4. CSSOM [x] - [x] **CSSPageRule selectorText**: Convert to getter/setter with syntax validation and serialization normalization. -- [x] **CSSImportRule styleSheet doc**: Document `CSSImportRule.styleSheet` returning `null` in `API_BOUNDARIES.md`. +- [x] **CSSImportRule styleSheet doc**: Document `CSSImportRule.styleSheet` returning `null` in `README.md`. - [x] **CSSKeyframesRule methods**: Implement `appendRule`, `deleteRule`, and `findRule`. - [x] **Missing rules**: Add stub classes for `CSSCounterStyleRule` and `CSSFontFeatureValuesRule`. #### 5. Selectors & Specificity [x] @@ -1559,10 +1559,10 @@ Objective: Run WPT tests dynamically using a lightweight harness shim, eliminati Objective: Merge redundant WPT shims and DOM setups into a single, clean helper file (`tests/wpt-shim.ts`) and reuse it across both Node unit tests and the sandbox CLI script. ### Tasks -- [x] **Consolidate shims**: Move any unique shims from `scripts/run_wpt_sandbox.ts` (such as `promise_test()`, `assert_not_equals()`, `assert_array_equals()`, `assert_class_string()`, `assert_unreached()`) into `tests/wpt-shim.ts`. +- [x] **Consolidate shims**: Move any unique shims from `scripts/run_wpt_node.ts` (such as `promise_test()`, `assert_not_equals()`, `assert_array_equals()`, `assert_class_string()`, `assert_unreached()`) into `tests/wpt-shim.ts`. - [x] **Consolidate DOM setups**: Integrate the `HTMLStyleElement` `.sheet` mock patching from `the tests/wpt-sandbox-setup.ts` and the `ComputedStylePropertyMapReadOnly` class from it into `tests/wpt-shim.ts`. - [x] **Cleanup setup files**: Delete `the tests/wpt-global-setup.ts` and `the tests/wpt-sandbox-setup.ts` and update any imports. -- [x] **Refactor `scripts/run_wpt_sandbox.ts`**: Make `run_wpt_sandbox.ts` use the unified shims and prototype patches from `tests/wpt-shim.ts`. +- [x] **Refactor `scripts/run_wpt_node.ts`**: Make `run_wpt_node.ts` use the unified shims and prototype patches from `tests/wpt-shim.ts`. - [x] **Verify preflight**: Run `pnpm run preflight` to confirm both test suites and the CLI script compile and pass. --- @@ -1587,7 +1587,7 @@ Objective: Eliminate the verbose 9.5k line static JSON baseline configuration fi ### Tasks - [x] **Dynamic WPT crawling**: Update `tests/wpt-sandbox.test.ts` to crawl the `css-typed-om` directory dynamically at runtime instead of loading a static `include` array. -- [x] **Compact JSON Formatting**: Implement custom single-line-array serialization in `scripts/update_wpt_baseline.ts` to store each file's failures on a single line. +- [x] **Compact JSON Formatting**: Implement custom single-line-array serialization in `scripts/run_wpt_node_crawler.ts` (`--update-baseline`) to store each file's failures on a single line. - [x] **Dynamic exclusion**: Identify files that fail to initialize (syntax/load errors) and automatically populate them into the `exclude` list during baseline runs. - [x] **Verify preflight**: Run `pnpm run preflight` to confirm all 358 WPT test files run successfully in 9 seconds with the new compact JSON format (~335 lines). @@ -1662,7 +1662,7 @@ Objective: Implement missing CSS Typed OM classes (`CSSPositionValue`, `CSSTrans Objective: Automate conformance logging of WPT sandbox tests to track progress over time. ### Tasks -- [x] **Progress Tracking Script**: Create `scripts/update_wpt_progress.ts` to execute WPT sandbox tests and append current statistics to `wpt-typed-om-progress.md` only when they change. +- [x] **Progress Tracking Script**: Create `scripts/run_wpt_node_crawler.ts` (`--update-progress`) to execute WPT tests and append current statistics to `wpt-progress.md` only when they change. - [x] **Git Pre-commit Hook**: Implement `.git/hooks/pre-commit` to automatically run progress tracking and stage the updated log file when `src/typed-om.ts` changes. - [x] **Initialize Log**: Run the script and commit the initial baseline log (`5890/12150` passed, 48.48% pass rate). - [x] **Historical Backfill**: Backfill the progress log table with past test execution numbers from transcripts. @@ -1759,10 +1759,10 @@ Objective: Verify our WPT shim conformance against WPT's own unit tests, then sc - [x] Documented remaining 3 edge-case failures at the end of the roadmap (1 in `exceptional-cases.html` on late-registered test status, 2 in `exceptional-cases-timeouts.html` on timeouts). - [x] **Broad Spec Conformance Crawler Expansion**: - [x] Expand the WPT sandbox crawler to read and execute tests under other core specification directories: `cssom/`, `css-syntax/`, `css-nesting/`, `css-variables/`, `selectors/`, `mediaqueries/`. - - [x] Configure includes/excludes lists for these spec folders in `tests/wpt-sandbox-config.json`. + - [x] Configure includes/excludes lists for these spec folders in `tests/wpt-node-config.json`. - [x] **Unified Multi-Spec Progress Logging**: - [x] Create `wpt-progress.md` logging progress across multiple specs. - - [x] Update progress logging script (`scripts/update_wpt_progress.ts`) to run multiple spec folders, aggregate their test totals, and log progress using the following multi-column layout with spec totals in headers: + - [x] Update progress logging script (`scripts/run_wpt_node_crawler.ts`) to run multiple spec folders, aggregate their test totals, and log progress using the following multi-column layout with spec totals in headers: ```markdown | Date & Time (UTC) | Commit | Typed OM (12150) | CSSOM (600) | Nesting (120) | Syntax (350) | Selectors (500) | MQ (200) | Overall | Pass Rate | | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | @@ -1810,12 +1810,12 @@ Objective: Resolve unbaselined failures in the expanded specifications by comple - [x] Mock `document.fonts` inside `createWptContext` (resolves ~2 failures). - [x] Implement `document.implementation.createHTMLDocument` inside `patchWindowForTypedOM` in `tests/wpt-shim.ts` using `parseHTML` (resolves ~2 failures). - [x] **Unified Multi-Spec Baseline Configuration**: - - [x] Update `tests/wpt-sandbox.test.ts` to load all specifications and exclusions dynamically from `tests/wpt-sandbox-config.json` instead of hardcoding `css-typed-om`. + - [x] Update `tests/wpt-sandbox.test.ts` to load all specifications and exclusions dynamically from `tests/wpt-node-config.json` instead of hardcoding `css-typed-om`. - [x] Baseline all remaining layout engine limitations and ES Modules syntax issues to keep standard preflight checks green. - [x] **Memory Leak & CPU Performance Safety**: - [x] Guarded globally-shared linkedom prototypes (`Element.prototype`, `CSSStyleDeclaration.prototype`) with a recursion guard to prevent stack overflow/extreme CPU locks. - [x] Removed global `window` closure leaks inside `Node.prototype.appendChild` and `insertBefore` mocks by resolving contexts dynamically via `ownerDocument.defaultView`. - - [x] Implemented automatic worker-queue throttling inside `scripts/run_wpt_crawler.ts` using `os.loadavg()` and `os.freemem()` monitoring to prevent vm freeze. + - [x] Implemented automatic worker-queue throttling inside `scripts/run_wpt_node_crawler.ts` using `os.loadavg()` and `os.freemem()` monitoring to prevent vm freeze. - [x] Guarded heavy crawler runner in `tests/wpt-sandbox.test.ts` with `RUN_SANDBOX_WPT=true` env flag to keep normal preflight check memory footprint minimal. - [x] Replaced shell `exec` with direct binary `execFile` and injected a 3.5s `unref()` self-termination fail-safe timer in workers to stop background loops. - [x] Injected event loop yields (5ms between assertions, 20ms between task spawns) to lower CPU and memory footprint during crawler runs. @@ -1880,17 +1880,192 @@ Objective: Reach maximum pass rate in Chrome WPT suite by hardening Typed OM int --- -## Potential roadmap items +## Phase 80: WPT Multi-Spec Conformance Drive (Wave 1: Nesting & Variables) [x] + +Objective: Resolve high-frequency failure clusters in `css-nesting` and `css-variables` identified by failure cluster diagnostics. + +### Tasks +- [x] **CSSStyleSheet Lifecycle & Legacy Aliases**: + - Ensure `CSSStyleSheet.prototype.removeRule` and `addRule` aliases are available on all sheet instances in sandbox shims and CSSOM. + - Implement `CSS.supports(property, value)` and `CSS.supports(conditionText)` validation in `src/` and sandbox environment. +- [x] **URL Token Serialization in Custom Properties**: + - Preserve unescaped periods, slashes, colons, and hash tokens in `url()` serialization per WPT `url-token-serialization.html`. +- [x] **Whitespace & Fallback Serialization in CSS Variables**: + - Ensure whitespace preservation in custom property value tokens. + - Fix `var()` fallback parsing and serialization in `src/parser.ts` and `src/serializer.ts`. +- [x] **Verification**: + - Run `node scripts/wpt_cluster_failures.ts --spec=css-nesting` and verify pass rate jumps. + - Run `node scripts/wpt_cluster_failures.ts --spec=css-variables` and verify pass rate jumps. + - Run `pnpm run preflight` to ensure 0 regressions. + +--- -Objective: Explore long-term ideas for WPT conformance, prototype patching options, and parser shorthand completeness. +## Phase 81: WPT Multi-Spec Conformance Drive (Wave 2: Selectors & Forgiving Parsing) & Documentation [x] + +Objective: Drive WPT `selectors/` conformance (>3,100 tests) by implementing forgiving selector list parsing, complex pseudo-class arguments, and pseudo-element normalization in `src/SelectorParser.ts`, and expand public API documentation. + +**Spec References**: +- Selectors Level 4: `submodules/csswg-drafts/selectors-4/Overview.bs` +- CSS Syntax 3: `submodules/csswg-drafts/css-syntax-3/Overview.bs` + +### Tasks +- [x] **Diagnostic Failure Clustering on `selectors`**: + - Run `node scripts/wpt_cluster_failures.ts --spec=selectors` to identify top error patterns across the 3,103 tests. +- [x] **Forgiving Selector List Parsing (`:is()`, `:where()`)**: + - Implement forgiving parsing per Selectors 4 #forgiving-selector: invalid or unsupported selectors in the argument list do not invalidate the entire selector or the pseudo-class. +- [x] **Complex Pseudo-Class & Pseudo-Element Arguments**: + - Support `:nth-child(An+B of )` and `:nth-last-child(An+B of )` argument parsing and AST representation. + - Support relative selector parsing for `:has(> .child)` and pseudo-element argument validation. +- [x] **Selector Serialization & Normalization**: + - Ensure spec-compliant stringification of complex selector lists, combinators, and pseudo-class arguments. +- [x] **API Documentation & Architecture Consolidation**: + - Merge `API_BOUNDARIES.md` into `README.md` under a dedicated Architecture & Spec Boundaries section. + - Add comprehensive quickstarts for dual-path TS/ESM execution, CSSOM rule traversal, Typed OM math & units, and Houdini custom properties. + - Document `getComputedStyle` intentional non-goal and adopt `wpt:node` vs. `wpt:browser` taxonomy. +- [x] **Verification**: + - Run `node scripts/wpt_cluster_failures.ts --spec=selectors` and measure conformance improvement. + - Run `pnpm run preflight` to guarantee 0 regressions across all suites. + +--- -### Ideas +## Phase 82: WPT Multi-Spec Conformance Drive (Wave 3: CSSOM Core Conformance) [x] + +Objective: Drive WPT `css/cssom/` conformance (>770 tests) by hardening stylesheet insertion/deletion boundary rules, priority flag serialization, and rule hierarchy back-references in `src/CSSOM.ts` and `src/CSSStyleDeclaration.ts`. + +**Spec References**: +- CSSOM Level 1: `submodules/csswg-drafts/cssom-1/Overview.bs` + - § 6.5.3 Insert a CSS rule (`#insert-a-css-rule`) + - § 6.5.4 Remove a CSS rule (`#remove-a-css-rule`) + - § 6.7.1 CSSStyleDeclaration API (`#the-cssstyledeclaration-interface`) + - § 6.4 The CSSRule Interface (`#the-cssrule-interface`) + +### Tasks +- [x] **Diagnostic Failure Clustering on `cssom`**: + - Run `node scripts/wpt_cluster_failures.ts --spec=cssom` to identify top failure clusters across the 775 tests in `submodules/web-platform-tests/css/cssom`. +- [x] **Rule Index Boundary & Hierarchy Validation (`insertRule` / `deleteRule`)**: + - In `src/CSSOM.ts`, implement strict `IndexSizeError` (when index < 0 or > rules.length) and `HierarchyRequestError` (e.g. attempting to insert `@import` after style rules or `@namespace` rules) per CSSOM 1 § 6.5.3. + - Ensure `CSSRule.parentStyleSheet` and `CSSRule.parentRule` back-references are updated when rules are inserted or removed. +- [x] **Priority Flag & Serialization in `CSSStyleDeclaration`**: + - In `src/CSSStyleDeclaration.ts`, handle case-insensitive `"important"` priority values, whitespace handling, and normalize priority strings in `setProperty()`. + - Ensure canonical property name iteration order and `cssText` roundtripping. +- [x] **Verification**: + - Run `node scripts/wpt_cluster_failures.ts --spec=cssom` and verify conformance improvement. + - Run `pnpm run preflight` to guarantee 0 regressions across all suites. + +--- + +## Phase 83: WPT Multi-Spec Conformance Drive (Wave 3.5: CSSOM Rules, Serialization & `CSS.escape`) + +Objective: Push WPT `css/cssom/` conformance higher toward our practical ceiling (~68%-70%) by implementing `CSS.escape()`, `CSSStyleRule.selectorText` dynamic setter, specialized rule serializers (`@counter-style`, `@font-feature-values`, `@keyframes`), constructable stylesheet promise methods (`sheet.replace()`), and IDL test harness shims. + +**Spec References**: +- CSSOM Level 1: `submodules/csswg-drafts/cssom-1/Overview.bs` + - § 3 Utility APIs (`#css-escape-value`) + - § 6.4.1 CSSStyleRule (`#dom-cssstylerule-selectortext`) + - § 6.4.4 CSSKeyframeRule / CSSKeyframesRule + - § 6.4.5 CSSNamespaceRule + - § 6.5.1 Constructing CSSStyleSheet Objects (`#dom-cssstylesheet-replace`) +- CSS Counter Styles 3: `submodules/csswg-drafts/css-counter-styles-3/Overview.bs` +- CSS Fonts 4: `submodules/csswg-drafts/css-fonts-4/Overview.bs` + +### Tasks +- [x] **`CSS.escape()` Implementation**: + - Implement the official CSSOM § 3 string escaping algorithm in `src/CSSOM.ts` / `src/index.ts`, passing `escape.html` (9 tests). +- [x] **`CSSStyleRule.selectorText` Dynamic Setter**: + - In `src/CSSStyleRule.ts` / `src/CSSOM.ts`, implement the setter for `selectorText`: validate and re-parse the incoming selector text, updating internal rule AST or throwing `SyntaxError` on invalid input per § 6.4.1. +- [x] **Rule ASTs & `cssText` Serialization**: + - Implement full serialization for `CSSCounterStyleRule.cssText` (single-line format without unformatted linebreaks per CSS Counter Styles 3). + - Implement `CSSFontFeatureValuesRule` and `@font-feature-values` sub-rules. + - Implement `CSSNamespaceRule` and ensure `Object.prototype.toString.call(CSSNamespaceRule.prototype)` returns `"[object CSSNamespaceRule]"`. +- [x] **Constructable Stylesheet `replace()` & `replaceSync()`**: + - In `src/CSSStyleSheet.ts`, implement `replace(text)` returning a `Promise` that parses asynchronously, and `replaceSync(text)` with proper disallow-modification locks. +- [x] **WPT IDL Test Harness Shims**: + - In `tests/wpt-shim.ts`, implement `assert_idl_attribute` and `document.implementation.createDocument`. +- [x] **Verification**: + - Run: `node scripts/wpt_cluster_failures.ts --spec=cssom` and verify pass rate increases significantly. + - Run: `pnpm run preflight` to guarantee 0 regressions across all suites. + +--- + +## Phase 84: Static Selector Matcher (`matches(element, selector)`) & Declarative Cascade Oracle (`getCascadedStyle`) + +Objective: Implement a pure-AST static selector matcher and declarative cascade resolver to evaluate selector rules and custom properties against DOM elements, unlocking ~2,500+ WPT tests across `selectors`, `css-variables`, `css-nesting`, and `css-syntax` using a test-sandbox cascade oracle without polluting public Node.js APIs. + +**Spec References**: +- Selectors Level 4: `submodules/csswg-drafts/selectors-4/Overview.bs` + - § 3 Structure of Selectors + - § 4 Selector Specificity + - § 15 Match a Selector Against an Element (`#match-against-element`) + - § 16 Match a Selector Against a Tree (`#match-against-tree`) +- CSS Cascade Level 5: `submodules/csswg-drafts/css-cascade-5/Overview.bs` + - § 3 Cascading (`#cascading`) + - § 6 Cascade Sorting Order (`#cascade-sort`) + - § 7 Cascaded Values (`#cascaded-values`) +- CSS Variables Level 1: `submodules/csswg-drafts/css-variables-1/Overview.bs` + - § 3 Defining Custom Properties + - § 4 Resolving `var()` Functions + +### Tasks +- [x] **Pure-AST Static Selector Matcher (`src/matcher.ts`)**: + - Implement `matches(element: Element, selector: string | ComplexSelector): boolean` and `querySelectorAll(root: Element | Document, selector: string): Element[]`. + - Support compound selectors (type, class, id, attribute `[att=val]`, null namespace `[|att]`). + - Support combinators (child `>`, next-sibling `+`, subsequent-sibling `~`, descendant ` `). + - Support pseudo-classes (`:is()`, `:where()`, `:not()`, `:has()`, `:first-child`, `:last-child`, `:only-child`, `:first-of-type`, `:last-of-type`, `:nth-child(An+B of )`, `:dir()`, `:heading()`, `:has-slotted()`). +- [x] **Declarative Cascade Resolver (`src/cascade.ts`)**: + - Implement `getCascadedStyle(element: Element): CSSStyleDeclaration`: + - Collect all `CSSStyleRule`s across `element.ownerDocument.styleSheets` that match `element`. + - Sort matching declarations by **Origin/Importance**, **Cascade Layers (`@layer`)**, **Specificity** (`Specificity.compare()`), and **Source Order** per CSS Cascade 5 § 6. + - Merge with inline `element.style` declarations. + - Resolve custom property references (`var(--custom-prop, fallback)`). +- [x] **WPT Test Sandbox Integration (`tests/wpt-shim.ts`)**: + - Bind `win.getComputedStyle = (el) => getCascadedStyle(el)` exclusively inside `tests/wpt-shim.ts` as a declarative cascade oracle to satisfy WPT assertion checks without introducing API ambiguity in public package exports. +- [x] **Verification**: + - Run `node scripts/wpt_cluster_failures.ts --spec=selectors` and `node scripts/wpt_cluster_failures.ts --spec=css-variables` to verify dramatic pass rate jumps. + - Run `pnpm run preflight` to guarantee 0 regressions across all 197+ test suites. + +--- -#### 1. Spec-Compliance & API Surface Refinements +## Phase 85: Typed OM Standard Property Syntax Codegen & StylePropertyMap Validation + +Objective: Generate standard property syntax definitions for all 800+ CSS properties from `@webref/css` into `src/data/gen/standard-syntax.ts` to enforce spec-compliant Typed OM value validation in `StylePropertyMap.set()`, `CSSStyleValue.parse()`, and `CSSStyleValue.parseAll()`, unlocking ~5,000 WPT tests in `css-typed-om`. + +**Spec References**: +- CSS Typed OM 1: `submodules/css-houdini-drafts/css-typed-om/Overview.bs` + - § 2.2 CSSStyleValue.parse() & parseAll() (`#dom-cssstylevalue-parse`) + - § 3.2 StylePropertyMap (`#the-stylepropertymap`) +- CSS Properties & Values API: `submodules/css-houdini-drafts/css-properties-values-api/Overview.bs` + - § 3 Syntax Strings (`#syntax-strings`) + +### Tasks +- [x] **Property Syntax Codegen (`scripts/codegen/generate_standard_syntax.ts`)**: + - Read `node_modules/@webref/css/css.json` containing all 815 standard CSS properties. + - Convert standard W3C syntax expressions into Houdini-compliant syntax definitions (``, ``, ``, ``, ``, `