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

• Implement comment handling (/* ... */) and whitespace rules
• Implement identifiers, at-keywords, numbers, dimensions, percentages, strings, hashes
• Implement escape sequences (including unicode escapes) and invalid escape handling
• Implement url(...) tokenization (quoted + unquoted)
• Implement CDO/CDC handling (<!-- / -->)
• Parse stylesheets into rules (qualified rules + supported at-rules)
• Parse declaration lists and declarations with !important
• Implement robust error recovery (skip invalid decls/rules, continue parsing)
• 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)
• Implement unknown at-rule handling (ignore safely per spec)

Phase 3: Selectors Level (CSS 2.1)

• Type selectors (element names)
• Universal selector *
• Class selectors .class
• ID selectors #id
• Attribute selectors: [attr], [attr=value], [attr~=value], [attr|=value]
• Combinators: descendant A B, child A > B, adjacent sibling A + B
• 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.
• Pseudo-class: :first-child
• Pseudo-class: :lang(...)
• 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

• 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
• Implement specificity calculation for all supported selector types
• 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
• 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
• Strings, identifiers, keywords handling (incl. case-sensitivity rules)
• 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.
• Implement shorthands expansion:
  • margin
  • padding
  • 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
• Implement computed-style output API for testing (per-node computed values)

Phase 7: Box Tree Construction & Display Types

• Implement display: none (no box generation)
• Implement display: block
• Implement display: inline
• 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.
• Implement anonymous box creation rules (block-in-inline, inline formatting)
• Implement visibility: visible/hidden
• Implement visibility: collapse (tables; safe fallback behavior if partial)

Phase 8: Block Formatting Context (Normal Flow)

• Implement block layout algorithm (CSS2.1 normal flow)
• Implement width resolution for blocks (auto vs specified)
• Implement horizontal box model equation (margin/border/padding/content)
• Implement vertical layout: height auto behavior for blocks
• Implement margin collapsing (adjacent vertical margins):
  • Parent/first-child collapsing cases
  • Empty block collapsing cases
  • 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.
• Implement clear (affects block positioning with floats)

Phase 9: Inline Formatting Context (Text Layout)

• Build inline formatting context with line boxes
• Implement whitespace processing rules (white-space):
  • normal
  • pre
  • nowrap
  • pre-wrap
  • pre-line
• Implement line breaking algorithm (basic + break opportunities)
• Implement text-align: left/right/center/justify
• Implement line-height computation and baseline alignment
• Implement inline vertical-align for inline-level and inline-table/inline-block
• Implement text-indent
• Implement letter-spacing, word-spacing
  • Current state: letter-spacing is implemented; word-spacing is not.
• 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)

• Implement position: static
• Implement position: relative (offset without affecting normal flow)
• 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

• Implement float: left/right/none
• Implement float placement algorithm (line wrapping around floats)
• Implement float interaction with block formatting context and clearance
• Implement shrink-to-fit width for floats when width:auto
• 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:
  • table-layout: auto
  • table-layout: fixed
• Implement border model:
  • 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
• Implement vertical-align in table cells

Phase 14: Lists and Counters

• Implement list item marker box generation for display:list-item
• 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:
  • strings
  • attr(...)
  • counter(...) / counters(...)
  • url(...) (as replaced content if supported; safe fallback otherwise)
• Implement interaction with display on pseudo-elements

Phase 16: Backgrounds and Borders

• 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:
  • 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.
  • 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

• 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)
• 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:
  • background/borders
  • negative z-index descendants
  • in-flow blocks
  • floats
  • in-flow inlines
  • positioned descendants
• Implement visibility:hidden (occupies space, not painted)
• 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

• Replaced elements sizing rules (images)
• vertical-align behavior for replaced elements in inline formatting
• 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)
• 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)