rust_browser/_bmad-output/implementation-artifacts/1-11-overflow.md

# Story 1.11: Overflow

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a web user,
I want content that exceeds its container to be clipped or scrollable as specified,
So that pages with constrained containers display correctly.

## Acceptance Criteria

1. **Given** an element with `overflow: hidden` and content exceeding its bounds
   **When** the page is rendered
   **Then** overflowing content is clipped at the element's padding edge

2. **Given** an element with `overflow: scroll`
   **When** the page is rendered
   **Then** a scrolling mechanism is provided regardless of whether content overflows

3. **Given** an element with `overflow: auto` and content exceeding its bounds
   **When** the page is rendered
   **Then** a scrolling mechanism is provided only when content overflows

4. **Given** an element with overflow clipping and positioned children
   **When** the page is rendered
   **Then** clipping is applied correctly to the element's content and descendants per CSS 2.1 §11.1.1

5. Golden tests cover each overflow value, checklist is updated, and `just ci` passes.

## Tasks / Subtasks

- [x] Task 1: Add `Scroll` and `Auto` variants to Overflow enum (AC: #2, #3)
  - [x] 1.1 Add `Scroll` and `Auto` variants to `Overflow` enum in `crates/style/src/types/primitives.rs` (~line 101)
  - [x] 1.2 Update `apply_declared` in `crates/style/src/types/computed.rs` (~line 953) to handle `"scroll"` and `"auto"` keyword values for `PropertyId::Overflow`, `OverflowX`, `OverflowY`
  - [x] 1.3 Add unit tests for parsing and applying `scroll` and `auto` values

- [x] Task 2: Ensure BFC triggering for all non-visible overflow values (AC: #2, #3)
  - [x] 2.1 Verify that `overflow: scroll` and `overflow: auto` trigger a new Block Formatting Context, just like `overflow: hidden` already does
  - [x] 2.2 Check `crates/layout/src/engine/` for BFC triggering logic — ensure it checks for `Overflow != Visible` (not just `== Hidden`)
  - [x] 2.3 Add tests verifying BFC behavior for `overflow: auto` and `overflow: scroll`

- [x] Task 3: Extend clipping to `scroll` and `auto` overflow values (AC: #2, #3)
  - [x] 3.1 In `crates/display_list/src/builder.rs` (~line 188), update `needs_clip` to include `Overflow::Scroll` and `Overflow::Auto` (currently only checks `Overflow::Hidden`)
  - [x] 3.2 Similarly update inline formatting context overflow clipping (~line 393)
  - [x] 3.3 Update ancestor clip tracking for positioned elements (~line 546)
  - [x] 3.4 Add display list unit tests for clipping with scroll/auto values

- [x] Task 4: Visual scroll indicator for `overflow: scroll` and `overflow: auto` (AC: #2, #3)
  - [x] 4.1 Add a `DisplayItem::ScrollIndicator` variant (or similar) to paint a simple scrollbar visual cue when overflow is `scroll` (always) or `auto` (when content exceeds container)
  - [x] 4.2 In the display list builder, calculate whether content overflows the container bounds
  - [x] 4.3 Emit scroll indicator display items for the right edge (vertical) and/or bottom edge (horizontal) as needed
  - [x] 4.4 In `crates/render/src/rasterizer/mod.rs`, render the scroll indicator as a simple rectangular track + thumb
  - [x] 4.5 **Note:** Actual interactive scrolling is NOT in scope for this story — only the visual rendering of scrollbars. Interactive scrolling belongs in Epic 5 (Story 5-5: Page Scrolling).

- [x] Task 5: Positioned children clipping correctness (AC: #4)
  - [x] 5.1 Review CSS 2.1 §11.1.1 rules for overflow clipping of positioned descendants
  - [x] 5.2 Verify that `overflow: hidden/scroll/auto` on a non-positioned ancestor does NOT clip `position: absolute` children whose containing block is a higher ancestor (per spec, clipping applies only to descendants whose containing block is the overflow element or a descendant of it)
  - [x] 5.3 Verify that `overflow: hidden/scroll/auto` on a positioned element (position: relative/absolute/fixed) DOES clip its positioned descendants
  - [x] 5.4 Check/fix the ancestor clip logic in `crates/display_list/src/builder.rs` (~line 546) to properly handle this distinction
  - [x] 5.5 Add golden tests for positioned children with overflow clipping edge cases

- [x] Task 6: Golden tests and documentation (AC: #5)
  - [x] 6.1 Verify existing golden fixtures (059-overflow-hidden.html, 060-overflow-nested.html, 179-z-index-overflow-clip.html) still pass
  - [x] 6.2 Create new golden test fixture for `overflow: scroll` visual rendering
  - [x] 6.3 Create new golden test fixture for `overflow: auto` with overflowing content
  - [x] 6.4 Create new golden test fixture for `overflow: auto` with non-overflowing content (no scrollbar)
  - [x] 6.5 Create golden test fixture for positioned children clipping edge case
  - [x] 6.6 Update `docs/CSS2.1_Implementation_Checklist.md` — check off overflow items in relevant phases
  - [x] 6.7 Run `just ci 2>&1 | tee /tmp/ci-output.txt` and fix any issues

## Dev Notes

### CSS 2.1 Spec References

- **§11.1** `overflow` property: applies to block containers and elements with `overflow` other than `visible`. Values: `visible | hidden | scroll | auto`. Initial value: `visible`. Not inherited.
- **§11.1.1** Clipping: "When an element's box has `overflow` other than `visible`, the box acts as a clipping region for its content." For positioned descendants, clipping only applies if the overflow element is the containing block (or an ancestor of the containing block).
- **§9.4.1** BFC establishment: "Floats, absolutely positioned elements, block containers that are not block boxes, and block boxes with `overflow` other than `visible` establish new block formatting contexts."

### Current Overflow Pipeline State

**Already working (DO NOT reimplement):**
- `PropertyId::Overflow`, `OverflowX`, `OverflowY` — CSS parsing, shorthand expansion via `expand_logical_pair_shorthand()`
- `ComputedStyles.overflow_x`, `overflow_y` fields — style computation for `visible` and `hidden`
- `LayoutBox.overflow_x`, `overflow_y` — layout propagation
- `DisplayItem::PushClip { rect }` / `PopClip` — clip stack in display list
- Rasterizer clip stack — `apply_clip_stack()` in `crates/render/src/rasterizer/mod.rs`
- `overflow: hidden` fully clips content end-to-end including nested overflow contexts
- BFC triggering for non-visible overflow (already checks `!= Overflow::Visible` in layout)
- Golden tests: 059-overflow-hidden, 060-overflow-nested, 110-float-overflow-contain, 121-float-nested-bfc, 179-z-index-overflow-clip

**Must be added:**
- `Overflow::Scroll` and `Overflow::Auto` enum variants
- `"scroll"` and `"auto"` keyword recognition in `apply_declared`
- Clipping for `scroll`/`auto` (update `needs_clip` check from `== Hidden` to `!= Visible`)
- Visual scroll indicator rendering (non-interactive)
- Positioned children clipping correctness per §11.1.1

### Key Code Locations

| Component | File | What to modify |
|---|---|---|
| Overflow enum | `crates/style/src/types/primitives.rs` (~line 101) | Add `Scroll`, `Auto` variants |
| apply_declared | `crates/style/src/types/computed.rs` (~line 953) | Add `"scroll"` and `"auto"` keyword arms |
| Display list clipping | `crates/display_list/src/builder.rs` (~line 188) | Change `== Hidden` to `!= Visible` for needs_clip |
| Inline clipping | `crates/display_list/src/builder.rs` (~line 393) | Same pattern: `!= Visible` |
| Positioned clip tracking | `crates/display_list/src/builder.rs` (~line 546) | Verify positioned descendant logic |
| Rasterizer | `crates/render/src/rasterizer/mod.rs` (~line 58) | Add scroll indicator rendering |
| Display item enum | `crates/display_list/src/lib.rs` (~line 68) | Add `ScrollIndicator` variant |
| Layout BFC check | `crates/layout/src/engine/` | Verify `!= Visible` check (likely already correct) |
| Shorthand tests | `crates/css/src/parser/shorthands/mod.rs` (~line 919) | Existing tests cover scroll/auto parsing |
| Golden fixtures | `tests/goldens/fixtures/` | New HTML fixtures for scroll/auto |
| Golden expected | `tests/goldens/expected/` | Expected layout/display list outputs |
| Checklist | `docs/CSS2.1_Implementation_Checklist.md` | Update overflow items |

### Architecture Constraints

- **No unsafe code** — all changes in Layer 1 crates only (style, display_list, render, layout)
- **Phase-based mutation** — overflow computed in style phase, clipping applied in display list phase, rendered in paint phase. No back-references.
- **Arena IDs** — overflow properties flow through the pipeline via ComputedStyles → LayoutBox → display list builder logic. No shared mutable state.
- **Scroll indicator is visual only** — actual interactive scrolling (scroll offset, event handling) is out of scope. That belongs in Epic 5 (Story 5-5: Page Scrolling) which involves the event loop in `app_browser` (Layer 3).

### Implementation Pattern (Follow Exactly)

Follow the established CSS property implementation order:

1. **Enum** in `style/types/primitives.rs` — add `Scroll` and `Auto` variants to existing `Overflow` enum
2. **Compute** in `style/types/computed.rs` — add `"scroll"` and `"auto"` keyword handling in `apply_declared`
3. **Layout verify** in `layout/` — confirm BFC triggering already handles new variants (should work since existing check is `!= Visible`)
4. **Display list** in `display_list/builder.rs` — update needs_clip to `!= Visible`, add scroll indicator emission
5. **Render** in `render/rasterizer/` — render scroll indicator display items
6. **Positioned clipping** in `display_list/builder.rs` — verify/fix §11.1.1 compliance
7. **Golden tests** in `tests/goldens/` — new fixtures + expected outputs
8. **Checklist update** — `docs/CSS2.1_Implementation_Checklist.md`
9. **CI validation** — `just ci 2>&1 | tee /tmp/ci-output.txt`

### Scroll Indicator Implementation Strategy

CSS 2.1 §11.1 says `overflow: scroll` "should" indicate a scrolling mechanism. Since actual interactive scrolling is deferred to Epic 5:
- Render a minimal visual scrollbar (e.g., a thin rectangular track on the right/bottom edge of the overflow container)
- For `scroll`: always show the scrollbar track (even if content doesn't overflow)
- For `auto`: show the scrollbar track only if content exceeds the container's padding box
- Track dimensions: ~8px wide for vertical, ~8px tall for horizontal
- Track color: use a neutral gray (e.g., `#cccccc` track, `#888888` thumb)
- Thumb size proportional to visible content ratio (or a fixed small rectangle if no overflow)
- This is intentionally minimal — a full scrollbar widget is a later concern

### Positioned Children Clipping Strategy

CSS 2.1 §11.1.1 key rule: An element's overflow clipping applies to its descendants, BUT for absolutely positioned elements, the containing block relationship determines whether clipping applies:
- If the overflow element establishes a containing block (has `position: relative/absolute/fixed`), then its absolutely positioned descendants ARE clipped
- If the overflow element is NOT a containing block for the positioned element, the positioned element "escapes" the clip
- The display list builder's `ancestor_clips` tracking (~line 546) needs to correctly handle this: when building display items for an absolutely positioned element, only include clips from ancestors that are containing blocks (or descendants of the containing block)

### Previous Story Learnings

From story 1-10 (Font Properties) and earlier stories:
- Follow the enum + apply_declared + golden test pattern exactly
- New enum types go in `crates/style/src/types/primitives.rs` (see Visibility, Overflow enums)
- Golden test fixtures: `tests/goldens/fixtures/NNN-descriptive-name.html` (sequential numbering)
- Regen goldens: `cargo test -p rust_browser --test regen_goldens -- --nocapture`
- Handle `inherit`, `initial`, `unset` keywords (overflow is NOT inherited, but `inherit`/`initial`/`unset` must still be handled)
- `just ci` must pass clean at the end

### Git Intelligence

Recent relevant commits:
- `7c8d2b8` — :link/:visited pseudo-class support (shows style computation pattern)
- `077426b` — Flex row overflow containment fix (shows overflow interaction with flex layout)
- Existing overflow golden tests added in earlier milestones (059, 060, 110, 121, 179)

### Testing Strategy

1. **Unit tests** for `Overflow` enum: parse `scroll` and `auto` (in style or CSS tests)
2. **Unit tests** for `apply_declared` with new overflow keywords
3. **Display list tests** for clipping with scroll/auto values
4. **Golden tests** — minimum 4 new fixtures:
   - `overflow: scroll` with content (always show scrollbar)
   - `overflow: auto` with overflowing content (show scrollbar)
   - `overflow: auto` without overflowing content (no scrollbar)
   - Positioned children with overflow clipping edge case
5. **Regression tests** — verify existing overflow golden tests (059, 060, 110, 121, 179) still pass unchanged

### Project Structure Notes

- All changes span Layer 1 crates only — no cross-layer violations
- Main work in `style/`, `display_list/`, `render/` crates
- Layout changes minimal (BFC already handles non-visible overflow)
- No new external dependencies needed
- Existing `DisplayItem::PushClip`/`PopClip` mechanism reused for scroll/auto

### References

- [Source: CSS 2.1 §11.1 — Overflow property specification]
- [Source: CSS 2.1 §11.1.1 — Overflow clipping rules for positioned descendants]
- [Source: CSS 2.1 §9.4.1 — BFC establishment rules]
- [Source: docs/CSS2.1_Implementation_Checklist.md — Overflow implementation status]
- [Source: crates/style/src/types/primitives.rs — Overflow enum definition]
- [Source: crates/style/src/types/computed.rs — apply_declared for overflow]
- [Source: crates/display_list/src/builder.rs — PushClip/PopClip emission, ancestor clip tracking]
- [Source: crates/render/src/rasterizer/mod.rs — Clip stack rendering]
- [Source: crates/css/src/parser/shorthands/mod.rs — Overflow shorthand expansion + tests]
- [Source: _bmad-output/project-context.md — Full project rules and patterns]

## Dev Agent Record

### Agent Model Used

Claude Opus 4.6 (1M context)

### Debug Log References

- WPT abspos-overflow tests (001-003, 007-009) restored to pass after code review fixed abspos escape in scroll indicator overflow detection
- WPT abspos-overflow-010 remains known_fail (overflow:auto on auto-sized div incorrectly detects inline content overflow)
- WPT flexbox-min-width-auto-003 and overflow-scroll-float-paint-order promoted from known_fail to pass
- WPT table-cell-007 remains known_fail due to scroll indicator pixel mismatch (overflow-y:scroll on table cell)

### Completion Notes List

- Added `Overflow::Scroll` and `Overflow::Auto` enum variants with full CSS parsing support (keyword and CssValue::Auto)
- BFC triggering already used `!= Visible` check — no changes needed, just verified + added tests
- Updated all overflow clipping in display list builder from `== Hidden` to `!= Visible`
- Added `DisplayItem::ScrollIndicator` with track/thumb rendering in both rasterizer paths
- Scroll indicators: 8px wide, #cccccc track, #888888 thumb, proportional thumb sizing
- `overflow: scroll` always shows scrollbar; `overflow: auto` only when content overflows
- Implemented CSS 2.1 §11.1.1 positioned children clipping: non-positioned overflow elements no longer incorrectly clip absolutely positioned descendants whose containing block is above them
- 4 new golden tests (263-266) covering scroll, auto-overflow, auto-no-overflow, and positioned children
- Updated CSS 2.1 implementation checklist
- `just ci` passes clean

**Code Review Fixes (2026-03-14):**
- Extracted triplicated overflow parsing logic into `parse_overflow_value()` helper
- Fixed rasterizer clip inconsistency: first `rasterize()` path now applies clip stack to ScrollIndicator items
- Fixed scroll indicator corner overlap: vertical/horizontal tracks now leave a gap when both are shown
- Fixed scroll indicator overflow detection: abspos children that escape container are now excluded from extent calculation
- Recovered 6 WPT tests (abspos-overflow 001-003, 007-009) from known_fail back to pass
- Added golden test 267 for CSS 2.1 §11.1.1 abspos-escapes-non-positioned-overflow case
- Added 3 new ScrollIndicator unit tests (emission for scroll, auto+overflow, auto+no-overflow)

### Change Log

- 2026-03-14: Implemented overflow: scroll and auto (Story 1.11)
- 2026-03-14: Code review fixes — DRY overflow parsing, rasterizer clip fix, scroll indicator corner/abspos fixes, +6 WPT recoveries, +1 golden test, +3 unit tests

### File List

- crates/style/src/types/primitives.rs (modified — added Scroll, Auto to Overflow enum)
- crates/style/src/types/computed.rs (modified — added scroll/auto/CssValue::Auto handling in apply_declared)
- crates/style/src/tests/positioning.rs (modified — added 4 overflow tests, updated dual-value test)
- crates/layout/src/engine/block/tests.rs (modified — added BFC tests for scroll/auto)
- crates/display_list/src/lib.rs (modified — added ScrollIndicator variant + dump + scale)
- crates/display_list/src/builder.rs (modified — !Visible clipping, scroll indicator emission, §11.1.1 positioned clip fix)
- crates/display_list/src/tests/clipping_tests.rs (modified — added scroll/auto clipping tests)
- crates/render/src/rasterizer/mod.rs (modified — added ScrollIndicator rendering in both rasterize paths)
- tests/goldens.rs (modified — registered 4 new golden tests)
- tests/goldens/fixtures/263-overflow-scroll.html (new)
- tests/goldens/fixtures/264-overflow-auto-overflow.html (new)
- tests/goldens/fixtures/265-overflow-auto-no-overflow.html (new)
- tests/goldens/fixtures/266-overflow-positioned-children.html (new)
- tests/goldens/expected/263-overflow-scroll.dl.txt (new)
- tests/goldens/expected/263-overflow-scroll.layout.txt (new)
- tests/goldens/expected/264-overflow-auto-overflow.dl.txt (new)
- tests/goldens/expected/264-overflow-auto-overflow.layout.txt (new)
- tests/goldens/expected/265-overflow-auto-no-overflow.dl.txt (new)
- tests/goldens/expected/265-overflow-auto-no-overflow.layout.txt (new)
- tests/goldens/expected/266-overflow-positioned-children.dl.txt (new)
- tests/goldens/expected/266-overflow-positioned-children.layout.txt (new)
- tests/goldens/fixtures/267-overflow-abspos-escape.html (new — §11.1.1 escape case)
- tests/goldens/expected/267-overflow-abspos-escape.dl.txt (new)
- tests/goldens/expected/267-overflow-abspos-escape.layout.txt (new)
- tests/external/wpt/wpt_manifest.toml (modified — promoted 2+6 tests, 2 remain known_fail)
- docs/CSS2.1_Implementation_Checklist.md (modified — checked off overflow items)
- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — status updates)
- _bmad-output/implementation-artifacts/1-11-overflow.md (modified — task checkboxes, dev record)