Imported from mizchi/crater (AGENTS.md). Install upstream with npx skills add mizchi/crater. Copyright stays with the author.

Project Agents.md Guide

This is a MoonBit project.

Project Structure

• MoonBit packages are organized per directory, for each directory, there is a moon.pkg.json file listing its dependencies. Each package has its files and blackbox test files (common, ending in _test.mbt) and whitebox test files (ending in _wbtest.mbt).

• In the toplevel directory, this is a moon.mod.json file listing about the module and some meta information.

Coding convention

• MoonBit code is organized in block style, each block is separated by ///|, the order of each block is irrelevant. In some refactorings, you can process block by block independently.

• Try to keep deprecated blocks in file called deprecated.mbt in each directory.

Tooling

• moon fmt is used to format your code properly.

• moon info is used to update the generated interface of the package, each package has a generated interface file .mbti, it is a brief formal description of the package. If nothing in .mbti changes, this means your change does not bring the visible changes to the external package users, it is typically a safe refactoring.

• In the last step, run moon info && moon fmt to update the interface and format the code. Check the diffs of .mbti file to see if the changes are expected.

• Run moon test to check the test is passed. MoonBit supports snapshot testing, so when your changes indeed change the behavior of the code, you should run moon test --update to update the snapshot.

• You can run moon check to check the code is linted correctly.

• When writing tests, you are encouraged to use inspect and run moon test --update to update the snapshots, only use assertions like assert_eq when you are in some loops where each snapshot may vary. You can use moon coverage analyze > uncovered.log to see which parts of your code are not covered by tests.

Test System

WPT (Web Platform Tests)

Browser compatibility tests using actual WPT test files from web-platform-tests.

Location:

• Test files: wpt-tests/css-flexbox/ (HTML format)
• Tools: scripts/fetch-wpt.ts, scripts/wpt-runner.ts

Commands:

# Fetch WPT tests (from GitHub)
npm run wpt:fetch -- css-flexbox
npm run wpt:fetch -- css-flexbox --limit 50
npm run wpt:fetch -- --all
npm run wpt:fetch -- --list     # Show available modules

# Run WPT comparison tests (requires Puppeteer)
npm run wpt -- wpt-tests/css-flexbox/align-content-horiz-001a.html
npm run wpt -- wpt-tests/css-flexbox/*.html

How it works:

1. Fetches HTML tests from WPT repository
2. Inlines external CSS, removes test scripts
3. Renders in Puppeteer (browser) and Crater
4. Compares layout trees (position, size)
5. Reports mismatches with tolerance

Available CSS modules:

• css-flexbox - Flexbox tests
• css-display, css-box, css-sizing
• css-align, css-position, css-overflow

WPT DOM Tests

DOM API compatibility tests using WPT testharness.js.

Location:

• Test files: wpt/dom/nodes/ (HTML format, from WPT submodule)
• Runner: scripts/wpt-dom-runner.ts

Commands:

# Run all WPT DOM tests
just wpt-dom-all

# Run specific test
just wpt-dom wpt/dom/nodes/Document-createElement.html

# Run tests matching pattern
just wpt-dom "Document-*"

WebDriver BiDi Tests (Planned)

WebDriver BiDi protocol compliance tests for Playwright integration.

Location:

• Test files: wpt/webdriver/tests/bidi/ (planned)
• Runner: scripts/wpt-webdriver-runner.ts (planned)

Quality Contracts (pkspec)

specs/crater.pkl is the master quality contract for Crater. TODO.md is a navigation index into it. Open GitHub issues are the bug / fix tracker, and link back to a scenario.

Workflow when you add work

1. Survey current state — pkspec spec --goals specs/crater.pkl specs/tasks.Test.pkl lists per-goal coverage; pkspec spec --next ranks unimplemented scenarios by priority.
2. Add a new scenario — append to specs/crater.pkl with reviewStatus = "draft" and link the source in description (See GitHub issue #N / Source: TODO Now (P0)). Draft scenarios don't require an implementing test, so spec-check stays green.
3. Approve a scenario — when an implementing test lands, add specRef { "scenario.id" } to a test in specs/tasks.Test.pkl, then flip reviewStatus = "approved". pkf run spec-check validates the link.
4. Sync TODO.md — when a scenario is reified or approved, remove or move the matching row. Don't let TODO.md and the scenarios drift.

Goals (priority order)

• goal.local-gates (90) — pkfire task discoverability
• goal.spec-contracts (80) — pkspec coverage is mechanically checked
• goal.css-compat (75) — per-module WPT CSS baselines
• goal.dom-compat (70) — DOM / Shadow DOM / Web Components surface
• goal.protocol-compat (65) — WebDriver BiDi / Playwright / CDP
• goal.paint-accuracy (60) — Luna VRT / WPT VRT / paint fixtures
• goal.diagnostic-api (55, draft) — paint tree diff / computed style / selector-scoped rendering
• goal.ci-efficiency (50) — affected gating / cache hit / shard wall time
• goal.release-safety (40) — workspace publish order

Commands

pkf run spec-check                                             # approved scenarios are linked
pkf run spec-lint                                              # Goal / Scenario references
pkf run spec-test                                              # executable wiring smoke tests
pkspec spec --goals specs/crater.pkl specs/tasks.Test.pkl      # per-goal coverage summary
pkspec spec --next  specs/crater.pkl specs/tasks.Test.pkl      # next-action ranking

Reify rule of thumb

• Module-level WPT residual → reuse the existing compat.css-*-baseline scenario. File a separate bug.* scenario only when the residual outlasts the baseline rollout.
• New API surface (BiDi commands, CLI flags, JS exports) → diagnostic.* or protocol.* scenario.
• Multi-PR workstream → file a scenario from day one so each PR has a backlink in its description.
• One-shot operational tweak (refactor, changelog template, dep bump) → leave in the "Not reified" section of TODO.md. Don't pollute pkspec with single-touch chores.

Scenario name constraint

Scenario name must match ^[a-zA-Z0-9_][a-zA-Z0-9_:.\-/ ]*$ — no +, (, ), etc. Use plain prose (flexbox min_width with justify-content centers correctly).

Project Goals

Milestone 1: Preact Compatibility

Ensure Preact can run on Crater's DOM implementation:

• Complete DOM API coverage for Preact's requirements
• Event handling (click, input, change, etc.)
• Component lifecycle support
• Virtual DOM reconciliation compatibility

Validation:

• just test-preact - Run Preact test suite against Crater

Milestone 2: Playwright Integration

Enable browser automation via WebDriver BiDi:

• Implement WebDriver BiDi protocol binding
• Support core Playwright operations (navigation, clicks, inputs)
• Pass WebDriver BiDi WPT tests

Validation:

• just wpt-webdriver-all - Run WebDriver BiDi WPT tests
• just test-playwright - Run Playwright E2E tests against Crater