rust_browser/docs/CSS2.1_Implementation_Checklist.md

# CSS 2.1 Compliance Checklist Plan

Checked items below are only for features that are implemented through the full relevant pipeline. For render-affecting features, that means parse/cascade/computed-style/layout/paint. Partial support is left unchecked and called out inline.

## Phase 0: Tracking & Infrastructure
- [ ] Create `css/` module boundaries: tokenize -> parse -> cascade -> compute -> layout -> paint
- [ ] Add feature flags / capability matrix for CSS2.1 (properties + selectors + at-rules)
- [ ] Add a CSS test harness (reftests + computed-style asserts)
- [ ] Import/organize CSS 2.1 test suites (or curated subset) into `tests/css21/`
- [ ] Add "known failures" mechanism (expected-fail list tied to issue IDs)
- [ ] Add debug tooling: dump tokens, AST, cascaded style, computed style, layout tree

## Phase 1: CSS Syntax, Tokenization, and Error Recovery
- [x] Implement comment handling (`/* ... */`) and whitespace rules
- [x] Implement identifiers, at-keywords, numbers, dimensions, percentages, strings, hashes
- [x] Implement escape sequences (including unicode escapes) and invalid escape handling
- [x] Implement `url(...)` tokenization (quoted + unquoted)
- [ ] Implement CDO/CDC handling (`<!--` / `-->`)
- [x] Parse stylesheets into rules (qualified rules + supported at-rules)
- [x] Parse declaration lists and declarations with `!important`
- [x] Implement robust error recovery (skip invalid decls/rules, continue parsing)
- [x] Support style attribute parsing (inline style declarations)

## Phase 2: At-rules (CSS 2.1)
- [ ] Implement `@import` (including ordering rules and media list parsing)
- [ ] Implement `@media` (CSS2.1 media types: `screen`, `print`, etc.)
  - Current state: `@media` rules are parsed and applied, but media type support is incomplete.
- [ ] Implement `@page` parsing (at least accept/ignore safely until print is implemented)
- [x] Implement unknown at-rule handling (ignore safely per spec)

## Phase 3: Selectors Level (CSS 2.1)
- [x] Type selectors (element names)
- [x] Universal selector `*`
- [x] Class selectors `.class`
- [x] ID selectors `#id`
- [x] Attribute selectors: `[attr]`, `[attr=value]`, `[attr~=value]`, `[attr|=value]`
- [x] Combinators: descendant `A B`, child `A > B`, adjacent sibling `A + B`
- [x] Grouping selectors: `A, B, C`
- [ ] Pseudo-classes: `:link`, `:visited`
  - Current state: `:link` matches; `:visited` is parsed but always false.
- [ ] Pseudo-classes: `:hover`, `:active`, `:focus`
  - Current state: parsed and included in specificity, but always false.
- [x] Pseudo-class: `:first-child`
- [x] Pseudo-class: `:lang(...)`
- [x] Pseudo-elements: `:first-line`, `:first-letter`
- [ ] Pseudo-elements: `:before`, `:after` (generated content hooks)
  - Current state: `::before`/`::after` styles and string `content` reach layout/paint, but generated content support is not complete.

## Phase 4: Selector Matching & Specificity
- [x] Implement selector matching against DOM (correct combinator semantics)
- [ ] Implement dynamic state updates (`:hover/:active/:focus`)
- [ ] Implement link state support (`:link/:visited`) with correct matching behavior
- [x] Implement specificity calculation for all supported selector types
- [x] Implement stable tie-breaking: later wins when specificity/origin/importance equal

## Phase 5: Cascade, Origins, and Inheritance
- [ ] Implement style origins: User Agent, User, Author
  - Current state: User Agent and Author origins exist; User origin is missing.
- [ ] Implement cascade order across origins including `!important` precedence
  - Current state: correct for User Agent vs Author only.
- [ ] Implement `@import` cascade ordering effects
- [x] Implement inline style precedence correctly
- [ ] Implement inheritance for inherited properties
  - Current state: implemented for the subset of inherited properties present in `ComputedStyles`, not for the full CSS 2.1 inherited-property set.
- [ ] Implement `inherit` keyword for all properties
  - Current state: effective only for properties already copied by `inherit_from()`.
- [ ] Implement initial values for all properties (CSS2.1 table)

## Phase 6: Values, Units, and Computed Value Resolution
- [ ] Length units: `px`, `pt`, `pc`, `in`, `cm`, `mm`
  - Current state: these units parse, but this checklist item stays open until unit handling is complete across CSS 2.1 value resolution.
- [ ] Font-relative units: `em`, `ex`
  - Current state: `em` works; `ex` is missing.
- [ ] Percentages resolution rules per property
  - Current state: many common percentage cases work; several CSS 2.1 property-specific resolution rules are still incomplete.
- [ ] Numbers and integers parsing and clamping rules
- [x] Strings, identifiers, keywords handling (incl. case-sensitivity rules)
- [x] Colors: named colors (CSS2.1 set), `#rgb/#rrggbb`, `rgb()` integer/percent forms
- [ ] URLs and resource references resolution (`url(...)`)
  - Current state: `url(...)` parsing is implemented, but end-to-end resource wiring is partial depending on property.
- [x] Implement shorthands expansion:
  - [x] `margin`
  - [x] `padding`
  - [x] `border` (+ `border-top/right/bottom/left`)
  - [ ] `background`
    - Current state: shorthand expansion exists, but full CSS 2.1 background behavior is not complete end to end.
  - [ ] `font`
    - Current state: partially parsed; `font-variant` and full reset behavior are incomplete.
  - [ ] `list-style`
    - Current state: only `list-style-type` is effectively modeled.
  - [ ] `outline`
- [x] Implement computed-style output API for testing (per-node computed values)

## Phase 7: Box Tree Construction & Display Types
- [x] Implement `display: none` (no box generation)
- [x] Implement `display: block`
- [x] Implement `display: inline`
- [x] Implement `display: inline-block` (shrink-to-fit behavior where applicable)
- [ ] Implement `display: list-item` (marker + list item box model)
  - Current state: textual markers for `list-style-type` are generated and painted, but list-item support is not complete.
- [x] Implement anonymous box creation rules (block-in-inline, inline formatting)
- [x] Implement `visibility: visible/hidden`
- [ ] Implement `visibility: collapse` (tables; safe fallback behavior if partial)

## Phase 8: Block Formatting Context (Normal Flow)
- [x] Implement block layout algorithm (CSS2.1 normal flow)
- [x] Implement `width` resolution for blocks (auto vs specified)
- [x] Implement horizontal box model equation (margin/border/padding/content)
- [x] Implement vertical layout: `height` auto behavior for blocks
- [ ] Implement margin collapsing (adjacent vertical margins):
  - [ ] Parent/first-child collapsing cases
  - [x] Empty block collapsing cases
  - [x] Sibling collapsing cases
  - [ ] Interaction with borders/padding/clearance
- [ ] Implement `overflow: visible/hidden/scroll/auto` (BFC triggers where applicable)
  - Current state: `overflow:hidden` clips in paint; non-visible overflow forms a BFC; `scroll` and `auto` are not complete.
- [x] Implement `clear` (affects block positioning with floats)

## Phase 9: Inline Formatting Context (Text Layout)
- [x] Build inline formatting context with line boxes
- [x] Implement whitespace processing rules (`white-space`):
  - [x] `normal`
  - [x] `pre`
  - [x] `nowrap`
  - [x] `pre-wrap`
  - [x] `pre-line`
- [x] Implement line breaking algorithm (basic + break opportunities)
- [x] Implement `text-align: left/right/center/justify`
- [x] Implement `line-height` computation and baseline alignment
- [x] Implement inline vertical-align for inline-level and inline-table/inline-block
- [ ] Implement `text-indent`
- [x] Implement `letter-spacing`, `word-spacing`
  - Current state: `letter-spacing` is implemented; `word-spacing` is not.
- [x] Implement `text-transform: none/uppercase/lowercase/capitalize`
- [ ] Implement `text-decoration: none/underline/overline/line-through/blink` (blink can be ignored but must not crash)
  - Current state: underline/overline/line-through painting exists; CSS 2.1 text-decoration coverage is not complete.
- [ ] Implement `direction` + `unicode-bidi` (at minimum: correct propagation; full bidi if targeting strict compliance)

## Phase 10: Fonts and Font Properties
- [ ] Implement `font-family` selection (generic families + fallback)
- [ ] Implement `font-size` keyword mapping and absolute/relative sizing
- [ ] Implement `font-style`, `font-variant`, `font-weight`
  - Current state: `font-style` and `font-weight` work; `font-variant` is not implemented.
- [ ] Implement `font` shorthand (including resets per spec)
- [ ] Implement `font-stretch` is not CSS2.1 (ignore unless extra)
- [ ] Implement font metrics integration: ascent/descent/x-height for `em/ex`, baselines

## Phase 11: Positioning (Relative, Absolute, Fixed)
- [x] Implement `position: static`
- [x] Implement `position: relative` (offset without affecting normal flow)
- [x] Implement `position: absolute` (containing block rules, static position)
- [ ] Implement `position: fixed` (viewport containing block; scroll behavior)
  - Current state: basic fixed-position paint behavior exists, but this remains open pending broader CSS 2.1 coverage.
- [ ] Implement `top/right/bottom/left` resolution rules (auto combos)
- [ ] Implement `z-index` stacking contexts
- [ ] Implement painting order for positioned elements per CSS2.1
- [ ] Implement clipping (`clip: rect(...)`) for absolutely positioned elements

## Phase 12: Floats
- [x] Implement `float: left/right/none`
- [x] Implement float placement algorithm (line wrapping around floats)
- [x] Implement float interaction with block formatting context and clearance
- [x] Implement shrink-to-fit width for floats when `width:auto`
- [x] Implement `clear` behavior (left/right/both)

## Phase 13: Tables (CSS 2.1 Table Model)
- [ ] Parse and apply table display types (`table-*`)
  - Current state: core table display types work, but the full CSS 2.1 table display family is not complete.
- [ ] Implement table wrapper box and caption handling (`caption-side`)
  - Current state: captions exist, but `caption-side` is missing.
- [ ] Implement table layout algorithms:
  - [x] `table-layout: auto`
  - [x] `table-layout: fixed`
- [ ] Implement border model:
  - [x] `border-collapse: separate` (+ `border-spacing`)
  - [ ] `border-collapse: collapse` (+ conflict resolution rules)
- [ ] Implement cell/row/column sizing rules
  - Current state: `<col>`/`<colgroup>` width hints and `span` attributes are supported. Column backgrounds, `visibility: collapse` on columns, and column borders in the collapsed model are deferred.
- [ ] Implement `empty-cells`
- [x] Implement `vertical-align` in table cells

## Phase 14: Lists and Counters
- [x] Implement list item marker box generation for `display:list-item`
- [x] Implement `list-style-type`
- [ ] Implement `list-style-position`
- [ ] Implement `list-style-image`
- [ ] Implement CSS2.1 counters:
  - [ ] `counter-reset`
  - [ ] `counter-increment`
  - [ ] `content: counter(...)` integration

## Phase 15: Generated Content
- [ ] Implement `content` property for `:before` / `:after`
  - Current state: string `content` works for `::before`/`::after`; broader CSS 2.1 generated content support is incomplete.
- [ ] Support content types:
  - [x] strings
  - [ ] `attr(...)`
  - [ ] `counter(...)` / `counters(...)`
  - [ ] `url(...)` (as replaced content if supported; safe fallback otherwise)
- [x] Implement interaction with `display` on pseudo-elements

## Phase 16: Backgrounds and Borders
- [x] Implement `background-color`
- [ ] Implement `background-image` (including `none` and `url(...)`)
  - Current state: gradients and image paint support exist; ordinary element `url(...)` backgrounds are not fully wired through the core layout pipeline.
- [ ] Implement `background-repeat`
- [ ] Implement `background-attachment`
- [ ] Implement `background-position`
- [ ] Implement `background` shorthand
- [ ] Implement border properties:
  - [x] `border-*-width` (incl. thin/medium/thick)
  - [ ] `border-*-style` (none/hidden/dotted/dashed/solid/double/groove/ridge/inset/outset)
    - Current state: `none`, `solid`, `dashed`, and `dotted` are implemented; the full CSS 2.1 style set is not.
  - [x] `border-*-color`
- [ ] Implement `border` shorthand(s)
  - Current state: shorthand parsing/application works, but this remains open until full border-style coverage is complete.
- [ ] Implement `outline` and `outline-offset` behavior (outline-offset not CSS2.1; ignore or implement as extra)

## Phase 17: Visual Formatting Details
- [x] Implement `color` (foreground text color)
- [ ] Implement `opacity` is not CSS2.1 (ignore unless extra)
- [ ] Implement `cursor` (optional; not required for layout but part of UI behavior)
- [x] Implement `vertical-align` for inline formatting context
- [ ] Implement `overflow` painting + clipping behavior
  - Current state: `overflow:hidden` clips; broader CSS 2.1 overflow behavior is incomplete.
- [ ] Implement `box-shadow` not CSS2.1 (ignore)

## Phase 18: Stacking, Painting Order, and Visibility
- [ ] Implement stacking context creation rules (root, positioned with z-index, etc.)
- [ ] Implement painting order for:
  - [x] background/borders
  - [ ] negative z-index descendants
  - [x] in-flow blocks
  - [x] floats
  - [x] in-flow inlines
  - [ ] positioned descendants
- [x] Implement `visibility:hidden` (occupies space, not painted)
- [x] Implement `display:none` (no box, no paint, no hit-test)

## Phase 19: Media Types and Print (If targeting full CSS2.1 print compliance)
- [ ] Apply `@media print` vs `screen` rules correctly
  - Current state: basic `screen`/`print` media query matching exists, but CSS 2.1 media support is incomplete.
- [ ] Implement paged media basics:
  - [ ] page box generation
  - [ ] page breaks (`page-break-before/after/inside`)
  - [ ] widows/orphans
- [ ] Implement `@page` margin boxes (if included in your compliance target)

## Phase 20: Forms, Replaced Elements, and Intrinsics
- [x] Replaced elements sizing rules (images)
- [ ] `vertical-align` behavior for replaced elements in inline formatting
- [x] Intrinsic ratio handling (if available)
- [ ] Baseline rules for inline replaced elements

## Phase 21: Final CSS 2.1 Property Coverage Audit
- [ ] Create an authoritative list of all CSS 2.1 properties in `docs/css21-properties.md`
- [ ] For each property: parsing -> cascade/inherit -> computed value -> layout/paint effect -> tests
- [ ] Ensure every property has:
  - [ ] Parser support
  - [ ] Correct initial value
  - [ ] Correct inheritance behavior
  - [ ] Correct computed value behavior
  - [ ] At least 1 targeted test (more for complex ones)

## Phase 22: Compliance Exit Criteria
- [ ] Pass CSS 2.1 conformance test targets (define threshold: 100% except documented exclusions)
- [x] No "crashers": malformed CSS must not crash the engine
- [ ] All known failures have linked issues and documented spec rationale
- [ ] Publish CSS 2.1 compliance report (supported/unsupported + test results)