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)
  • CSS 2.1 tests imported via WPT upstream into tests/external/wpt/ (2,900+ cases covering CSS2 normal flow, positioning, floats, margin/padding, tables, etc.)
• Add "known failures" mechanism (expected-fail list tied to issue IDs)
  • WPT harness supports known_fail status with reasons; promote/demote tooling via just wpt-status
• 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 (URL extraction, recursive fetch/merge, media list filtering via ImportDirective)
• Implement @media (CSS2.1 media types: screen, print, all; parsed, filtered in cascade and import resolution)
• 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
  • :link matches unvisited hyperlinks; :visited matches visited links from browsing history.
• 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 (imported rules prepended before importer's rules)
• Implement inline style precedence correctly
• Implement inheritance for inherited properties
  • All CSS 2.1 visual inherited properties present in ComputedStyles are covered by is_inherited() and inherit_from().
• Implement inherit keyword for all properties
  • copy_property_from_parent() covers all PropertyId variants in ComputedStyles.
• Implement initial keyword for all properties
  • reset_to_initial() covers all PropertyId variants; css_initial_values() provides spec-correct defaults.
• Implement unset keyword (CSS3 Cascading §3.6)
  • Acts as inherit for inherited properties, initial for non-inherited. Handled in cascade engine (context.rs).

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
    • All sub-properties expanded including font-variant; omitted sub-properties reset to initial values per §15.8.
  • 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 top margin collapsing (Level A + Level B)
    • Known limitation: 3+ level nested chains (e.g., grandparent→parent→child all collapsing) produce partially correct results. Each level only propagates one level deep, so a 3-level chain may under-collapse.
    • Known regression: clear-as-first-child interacts incorrectly with parent-child collapsing (3 WPT tests demoted to known_fail).
  • Parent/last-child bottom margin collapsing
  • Empty block collapsing cases
  • Sibling collapsing cases
  • Interaction with borders/padding/clearance
  • Table-internal margin suppression (margins don't apply to table-row-group, table-row, table-cell)
  • min-height interaction with self-collapsing detection
• Implement overflow: visible/hidden/scroll/auto (BFC triggers where applicable)
  • All four values parse, compute, clip, and trigger BFC. scroll/auto render non-interactive scroll indicators. §11.1.1 positioned-children clipping correctness implemented.
• 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
• Implement text-transform: none/uppercase/lowercase/capitalize
• Implement text-decoration: none/underline/overline/line-through/blink (blink can be ignored but must not crash)
• Implement direction + unicode-bidi (at minimum: correct propagation; full bidi if targeting strict compliance)
  • Implemented: direction (ltr/rtl) affects default text-align, unicode-bidi (normal/embed/bidi-override) parsed and stored. MVP: block-level RTL alignment.

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
  • All three work including font-variant: small-caps rendering.
• Implement font shorthand (including resets per spec)
  • Expands to all 6 sub-properties: font-style, font-variant, font-weight, font-size, line-height, font-family.
• Implement font-stretch is not CSS2.1 (ignore unless extra)
• Implement font metrics integration: ascent/descent/x-height for em/ex, baselines
  • ex unit resolves using actual x-height from ab_glyph glyph bounds; falls back to 0.5em per spec.

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)
  • Fixed elements use viewport as containing block, scroll offset exemption in display list builder verified and tested.
• Implement top/right/bottom/left resolution rules (auto combos)
  • CSS 2.1 §10.3.7 (horizontal) and §10.6.4 (vertical) auto resolution, over-constrained handling, and auto-margin centering for abs-pos elements.
• Implement z-index stacking contexts
• Implement painting order for positioned elements per CSS2.1
• Implement clipping (clip: rect(...)) for absolutely positioned elements
  • Full pipeline: CSS parsing, computed style, layout propagation, display list clip commands, rasterizer scissoring.

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)
  • caption-side: top (default) and caption-side: bottom fully implemented
• Implement table layout algorithms:
  • table-layout: auto
  • table-layout: fixed
• Implement border model:
  • border-collapse: separate (+ border-spacing)
  • border-collapse: collapse (+ conflict resolution rules per §17.6.2.1)
  • table-layout: fixed + border-collapse: collapse combination
  • All border styles supported in conflict resolution: hidden, double, solid, dashed, dotted, ridge, outset, groove, inset
• 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
  • empty-cells: show (default) and empty-cells: hide — suppresses borders/backgrounds for empty cells in separate border model
• 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: Full CSS 2.1 generated content support including strings, attr(), counter(), counters(), and quote keywords.
• Support content types:
  • strings
  • attr(...)
  • counter(...) / counters(...)
  • open-quote / close-quote / no-open-quote / no-close-quote
  • 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(...))
• 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 — all 10 values complete)
  • border-*-color
• Implement border shorthand(s)
• Implement outline, outline-style, outline-width, outline-color (CSS 2.1 §18.4)
• Implement outline-offset (CSS3, implemented 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
  • Complete: visible/hidden/scroll/auto all clip correctly. Visual scroll indicators for scroll/auto. §11.1.1 positioned-children clipping per spec.
• 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 (print rules skipped in cascade; import media filtering)
• 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)