microsim-iframe-tester

What this skill does

# MicroSim Iframe Height Tester

## Purpose

MicroSims are embedded in MkDocs pages via `<iframe>` tags with fixed heights and `scrolling="no"`. If the iframe height is too short, controls at the bottom (sliders, buttons, dropdowns) get clipped and students can't interact with them. This skill automates checking that every MicroSim's controls are fully visible at the declared iframe height.

## How It Works

Always use the Python script (`scripts/test-iframe-heights.py`) — it only requires `pip install playwright` and avoids any Node.js/npm dependency. A legacy Node.js version (`scripts/test-iframe-heights.js`) exists but should not be used. The script uses Playwright to:

1. Find all MicroSim directories under `docs/sims/`
2. Read each `index.md` to extract the declared iframe height
3. Load `main.html` in a browser viewport constrained to that height
4. Wait for p5.js (or other libraries) to finish rendering controls
5. Find all interactive elements (buttons, sliders, selects, inputs, checkboxes)
6. Check whether each element's bounding box fits within the iframe height
7. Measure the actual content height needed
8. Report pass/fail with recommended height for failures

## Prerequisites

```bash
pip install playwright
playwright install chromium
```

## Running the Tests

```bash
# Test all MicroSims
python scripts/test-iframe-heights.py --sims-dir docs/sims

# Test a single MicroSim
python scripts/test-iframe-heights.py --sims-dir docs/sims --sim energy-pyramid

# Test with a custom height override (ignores index.md heights)
python scripts/test-iframe-heights.py --sims-dir docs/sims --height 530

# Generate a markdown report
python scripts/test-iframe-heights.py --sims-dir docs/sims --report report.md
```

## Reading the Output

The script outputs a table like:

```
MicroSim                    | Iframe Height | Content Height | Status | Suggested Height
----------------------------|---------------|----------------|--------|------------------
energy-pyramid              |           532 |            528 | PASS   |              532
predator-prey               |           697 |            720 | FAIL   |              730
greenhouse-effect           |           500 |            498 | PASS   |              500
```

- **PASS**: All controls fit within the iframe height (with 5px tolerance)
- **FAIL**: One or more controls extend below the iframe boundary
- **Suggested Height**: The actual content height rounded up to the nearest 10px, plus a 10px safety margin. If the sim's JS file contains a `// CANVAS_HEIGHT = N` comment, that declared height is used instead of the measured content height (responsive sims can measure taller at the test viewport width than they actually render in MkDocs).

## Responsive Sims and CANVAS_HEIGHT

Some p5.js sims dynamically resize their canvas based on viewport width. The test viewport (700px) may not exactly match the MkDocs content column, causing measured heights to differ from the actual embedded height. When a sim declares `// CANVAS_HEIGHT = N` in its JS file, the tester trusts that value as authoritative. **Always sanity-check suggestions for responsive sims** — if the suggested height is dramatically larger than the current iframe height, the sim likely has dynamic sizing and needs a `CANVAS_HEIGHT` declaration rather than a blind height increase.

## Fixing Failures

For each failing MicroSim, update the iframe height in `index.md`:

```html
<!-- Before -->
<iframe src="main.html" height="500" width="100%" scrolling="no"></iframe>

<!-- After — use the suggested height from the report -->
<iframe src="main.html" height="540" width="100%" scrolling="no"></iframe>
```

Also update the `// CANVAS_HEIGHT:` comment in the JavaScript file if present, and any chapter markdown files that embed the same sim.

## Step-by-Step for Claude

When the user asks to test iframe heights:

1. Confirm the project root contains `docs/sims/` with MicroSim directories
2. Check that `scripts/test-iframe-heights.py` exists in the skill directory at `~/.claude/skills/microsim-iframe-tester/scripts/`
3. Run `playwright install chromium` if not already installed
4. Run the Python test script from the project root
5. Present the results to the user
6. For failures, offer to update the iframe heights in the affected `index.md` files
7. If chapter markdown files also embed the failing sims, update those too