rust_browser/.claude/commands/investigate.md

Investigate rendering issues for the website at: $ARGUMENTS

Follow these steps:

Step 1: Determine site directory & render

Derive a site stem from the URL — use the last path segment (without extension) if present, otherwise the hostname (e.g., example for example.com, about for example.com/about.html). The stem should be filesystem-safe (lowercase, no special characters beyond hyphens/underscores).

Append an entry to investigations/sites.txt (create it if it doesn't exist) in the format:

<site-stem> -> <full URL>

Only add the entry if the site-stem is not already listed. If the URL for an existing stem has changed, update it.

Create the output directory and render:

mkdir -p investigations/<site-stem>/artifacts/
cargo run -p app_browser -- --render "$URL" --output-dir investigations/<site-stem>/artifacts/ --png

Then list the output directory to discover the file stem used for output files:

ls investigations/<site-stem>/artifacts/

Step 2: Gather all artifacts

Read all of these files (using the stem discovered above):

• investigations/<site-stem>/artifacts/{stem}.html — the raw HTML/CSS source
• investigations/<site-stem>/artifacts/{stem}.layout.txt — the layout tree dump
• investigations/<site-stem>/artifacts/{stem}.dl.txt — the display list dump
• investigations/<site-stem>/artifacts/{stem}.png — the rendered screenshot

Step 3: Check for existing report

If investigations/<site-stem>/report.md exists, read it to understand previously reported findings and their status. Note the existing finding IDs, their descriptions, and current statuses.

Step 4: Analyze for rendering bugs

Carefully analyze the HTML/CSS source, layout tree, display list, and screenshot together. Look for the following categories of issues:

Missing or unsupported CSS properties

• Identify CSS properties used in the page's stylesheets or inline styles that the engine may not support
• Check for modern CSS features (grid, custom properties, transforms, animations, transitions, etc.)
• Note any @-rules that may be ignored (e.g., @font-face, @keyframes, @supports)

Layout issues

• Elements with zero width or height that shouldn't be (collapsed boxes)
• Content overflowing its container when it shouldn't
• Incorrect stacking or overlapping elements
• Missing or incorrect margins, padding, or borders
• Inline elements not wrapping properly
• Flex/grid children not positioned correctly
• Floats not clearing or wrapping around properly
• Absolutely/fixed positioned elements in wrong locations

Display list issues

• Missing text that should be visible
• Missing backgrounds or borders
• Incorrect colors or font sizes
• Clipping regions that may be cutting off content
• Z-ordering issues (elements painted in wrong order)

HTML parsing issues

• Elements that may not be in the correct DOM position
• Missing implicit elements (html, head, body)
• Incorrectly nested elements

Image issues

• Images that failed to load or decode
• Images with incorrect dimensions

Focus on actionable findings that would improve rendering fidelity. Don't report issues with JavaScript-dependent content (we don't execute JS).

Comparing with previous findings (if a previous report exists)

If a previous report exists from Step 3:

• For each previously-reported finding, check if the issue is still present in the current render. If it is no longer observed, mark it Fixed with today's date.
• If a previously-reported finding is still present, keep its status as Open and preserve its original finding ID and Found date.
• Add any new findings not in the previous report, assigning them the next sequential ID.

Step 5: Write/update the findings report

Write investigations/<site-stem>/report.md with this format:

# Investigation: <site description>

**URL**: <url>
**Last investigated**: <YYYY-MM-DD>

## Summary

<Brief description of the page and overall rendering assessment>

## Findings

### F-001: <Short title>
- **Status**: Open
- **Found**: <YYYY-MM-DD when first found>
- **Category**: CSS Support | Layout | Display | Parsing | Image | Other
- **Severity**: High | Medium | Low
- **Description**: <what's wrong>
- **Evidence**: <specific lines from layout dump, display list, or CSS>

### F-002: <Short title>
- **Status**: Fixed (<YYYY-MM-DD when confirmed fixed>)
- **Found**: <YYYY-MM-DD when first found>
- **Category**: CSS Support | Layout | Display | Parsing | Image | Other
- **Severity**: High | Medium | Low
- **Description**: <what's wrong>
- **Evidence**: <original evidence>

## Stats

| Status | High | Medium | Low | Total |
|--------|------|--------|-----|-------|
| Open   |    0 |      0 |   0 |     0 |
| Fixed  |    0 |      0 |   0 |     0 |

Key conventions:

• Findings use sequential IDs (F-001, F-002, ...) that are stable across re-investigations
• New findings get the next available ID — never reuse IDs from fixed findings
• The Found date records when the finding was first observed
• Fixed status includes the date it was confirmed fixed
• The Stats table summarizes the current state by severity and status
• Preserve any Suggested fix notes from previous reports if present