c9bac01c41
Update the investigate command to record each site's stem and full URL in a central sites.txt file for easy reference. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
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:
|
|
|
|
```markdown
|
|
# 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
|