Refactor the codebase

.agents/skills/render-musicxml/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: render-musicxml
+description: Render a MusicXML file in vexml by running `vex render -i <path/to/musicxml>`, inspect the generated screenshot when needed, and delete ephemeral render output when finished.
+---
+
+# Render MusicXML
+
+Use this skill when the user asks to render a MusicXML file, inspect how a MusicXML fixture looks, generate a quick screenshot from MusicXML, or verify rendering behavior visually without adding or updating an integration test.
+
+## Command
+
+Run the render command from the project root:
+
+```sh
+vex render -i <path/to/musicxml>
+```
+
+Replace `<path/to/musicxml>` with the project-relative or absolute path to the MusicXML file the user wants rendered.
+
+## Workflow
+
+1. Identify the MusicXML input path from the user's request or from the repository.
+2. Run `vex render -i <path/to/musicxml>` from `vexml`.
+3. Read the command output to find the generated screenshot path.
+4. If visual inspection is needed, open or inspect the generated screenshot with available tools.
+5. When finished, delete the generated screenshot if it was only meant to be ephemeral.
+
+## Ephemeral Output
+
+Treat the generated screenshot as ephemeral when it was created only for quick inspection, debugging, or answering a one-off question.
+
+Do **not** delete the screenshot when the user explicitly asks to keep it, save it, compare it later, attach it to a report, or use it as a baseline/test artifact.
+
+When deleting an ephemeral screenshot, remove only the screenshot generated by the `vex render` command you just ran. Do not remove existing fixtures, baselines, or unrelated image files.

.agents/skills/test-musicxml/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: test-musicxml
+description: Add or update vexml MusicXML integration tests, validate screenshot output, implement rendering fixes, and selectively update baselines.
+---
+
+# Test MusicXML
+
+Use this skill when adding or updating a `vexml` MusicXML rendering test case, especially when the work involves integration fixtures, screenshots, or baseline updates.
+
+## Workflow
+
+**Important:** Use the `vex test` commands shown below, plus selective `vex test --update <name>` only after reviewing the screenshot output.
+
+1. First, check whether an existing test in `tests/integration/` already covers the use case.
+   - Inspect the relevant integration case definitions and existing files under `tests/integration/__data__/`.
+   - Reuse or extend an existing case when that is the least surprising option.
+
+2. If the use case is not already covered, add it to `tests/integration/__data__/` — preferably as a new measure inside the existing fixture for that category rather than as a brand-new file.
+
+   **Bundle by category; treat each measure as a pseudo unit test.** A category fixture (e.g. `key.musicxml`, `time.musicxml`, `note.musicxml`, `slur.musicxml`) is one MusicXML document whose measures each isolate one variant of that category's behavior — the way a unit-test file holds many small cases. The measure is the unit of isolation, not the file. For example, `key.musicxml` proves a sharp key, a flat key, a mid-system key change, and a no-redraw continuation across M1-M3; `slur.musicxml` walks nine slur scenarios across nine measures. When adding a new variant of an already-covered category, append a measure to that category's fixture (and a `M<n>:` bullet to its comment) instead of creating a near-duplicate file. When you find existing same-category fixtures that each test one variant (e.g. `key_sharps` + `key_flats` + `key_change`), consolidate them into one.
+
+   - **When bundling does NOT apply:** some things are fixed for a whole document and can't vary per measure — the `<part-list>` and each part's stave configuration (stave count, tab string count, braces). Those stay as separate `category_variant.musicxml` files. This is why `structure_*` (different part-lists) and `clef_*` (single stave vs grand staff vs 4-/6-line tab) are not bundled: each needs a different part/stave structure, not just a different measure. Rule of thumb: bundle what varies per measure (keys, meters, note/rest/accidental/articulation/beam/slur/tie/tuplet variants, voices); keep separate what needs a different part or stave layout.
+   - Name a fixture that covers a whole category `category.musicxml` (e.g. `key`, `time`, `note`, `slur`). Use `category_variant.musicxml` only when different part/stave structures force more than one file in that category (e.g. `clef_tab_4_string`, `structure_grand_staff`). Categories: `structure`, `clef`, `key`, `time`, `note`, `rest`, `accidental`, `measures`, …; match the existing files in `tests/integration/__data__/`.
+   - Register it in `tests/integration/render.test.ts` by adding `testCase('<filename>.musicxml', '<filename>.png')` to the `TEST_CASES` array. Pass any non-default `Config` as the third argument.
+   - Keep `TEST_CASES` ordered by increasing rendering complexity. A `render` implementer should be able to build a correct renderer progressively by going through the tests in array order: basic structure before clefs, clefs before key/time signatures, simple notes/rests before accidentals, measures, beams, chords, ties/slurs, tuplets, articulations, voices, system layout, and broad stress cases. Insert new cases where they fit this progression; the array order is the only ordering — there is no numeric prefix. A bundled category fixture sits in its category's slot; let its most complex measure set the position.
+   - Above each `testCase(...)` declaration, write a detailed comment describing what the screenshot should render: the clefs, staves, notes, and any distinctive notation or layout (positions, accidentals, beams, slurs, ledger lines, system breaks, …). Describe what is actually drawn so the comment alone tells a reader what to expect without opening the PNG. Match the descriptive style of the surrounding cases.
+   - For cases spanning more than one measure, split the comment by measure for readability. Start with a one-line lead describing the global setup (stave/clef/time signature and any wrap behavior), then add one bulleted line per measure using a stable `M<n>:` marker (`M2-3:` for a span). Wrap continuation lines so they align under the bullet text. For multi-voice cases, use inline `V<n>` markers (e.g. `V1`, `V2`) inside each measure bullet. This keeps the comment scannable for humans and greppable for tools, with each `M<n>` mapping directly to a `<measure number="n">` in the fixture. Example:
+
+     ```ts
+     // Treble stave, 4/4: dotted-note variations.
+     // - M1: dotted-quarter + eighth pairs (single dots).
+     // - M2: double-dotted-quarter + sixteenth pairs (double dots).
+     testCase('dotted_notes.musicxml', 'dotted_notes.png'),
+     ```
+   - Each measure should test only one thing. Vary one feature per measure and keep everything else stable (pitch, duration, clef); don't vary unrelated musical features within a measure unless the variation is part of what that measure is proving. The fixture as a whole deliberately spans many variants of its category — but each measure isolates exactly one.
+   - Wrong pattern: when testing articulations, do not vary duration or pitch needlessly; use stable, boring notes unless pitch or duration affects the articulation behavior being tested.
+   - Right pattern: when testing beams, varying pitch can be useful if the goal is to show how the beam renders under normal and extreme stem/ledger-line conditions. There should be a clear reason for every extra variation.
+   - Keep each measure as small as practical while still demonstrating its variant, and the fixture as a whole no larger than its variants require.
+   - Keep generated MusicXML fixtures as simple and barebones as possible; inspect nearby existing files and match their minimal structure and style.
+
+3. Run the integration test command:
+
+   ```sh
+   vex test
+   ```
+
+4. Interpret screenshot results carefully. Screenshot tests can fail or pass for two different reasons:
+   - **False positive:** a newly added test may pass only because its first generated screenshot was automatically accepted as the baseline. In this state the test accepts any current rendering as correct, even if the rendering is visibly wrong. Leave a `TODO` comment above the `testCase(...)` explicitly calling out this failure mode, for example: `// TODO: False positive: this baseline was probably created from the current render, so it may be accepting an incorrect screenshot. Review the render, then run vex test <name> --update only after the image is confirmed correct.` If the user provides a golden-standard image for the case, compare it against vexml's render before accepting. Eventually, the agent must run `vex test <name> --update` to intentionally accept the reviewed screenshot.
+   - **True negative:** an existing screenshot test failed because a previously accepted baseline is no longer reproducible. Inspect the diff artifact and leave a `TODO` comment above the `testCase(...)` that describes the visual difference in plain language and links to the diff. Do not prescribe a fix unless the root cause is already clear. Prefer wording like: `// TODO: True negative: the accepted baseline shows <expected visual>, but the new render shows <actual visual>. Diff: <path-or-link>.`
+   - In both cases, describe what a human should look for in the screenshot. Make the TODO specific enough that another agent can continue from it without opening unrelated files.
+   - If the correct rendering is ambiguous, ask the user for feedback and include file links to the relevant screenshot diff or artifact.
+
+5. Update the implementation in `src/` to fill the rendering gap.
+   - Prefer a minimal, root-cause fix.
+   - Keep changes consistent with the existing renderer and test patterns.
+
+6. Run the test command again:
+
+   ```sh
+   vex test
+   ```
+
+7. The target test may still fail. That is useful if it shows the implementation changed the rendered output.
+   - For the target test file, inspect the new render and confirm it matches the intended rendering described by the relevant test comment or TODO.
+   - Before updating any screenshot baseline, always perform the screenshot review checklist below.
+   - If a `TODO` describes a false positive, keep it until the screenshot has been manually reviewed and intentionally accepted with `vex test <name> --update`.
+   - If a `TODO` describes a true negative, keep it until the changed screenshot has been explained, fixed, or intentionally accepted.
+   - Do not update baselines until you have evaluated the screenshot output.
+
+## Screenshot Review Checklist
+
+Always run this checklist before accepting or updating a screenshot baseline. Answer these questions from the actual screenshot or diff artifact, not from assumptions about the code:
+
+- Is everything visible? Look for clefs, key signatures, time signatures, notes, rests, articulations, accidentals, ledger lines, beams, ties, slurs, lyrics, barlines, and other symbols that are cut off by the image bounds or page margins.
+- Are the results sized appropriately for the render options and the fixture? The image should not look accidentally zoomed in, zoomed out, cropped, or padded with excessive empty space.
+- Are musical glyphs clashing when they should not? Check collisions between noteheads, stems, beams, flags, accidentals, dots, rests, text, ties, slurs, clefs, key signatures, time signatures, and neighboring staves/measures.
+- Given the render options, does the music feel too cramped? Look for notation that is technically visible but hard to read because horizontal or vertical spacing is too tight.
+- Given the render options, does the music feel too spaced out? Look for measures, systems, or glyphs that are spread so far apart that the fixture no longer demonstrates the intended behavior clearly.
+- What does the test comment describe? Does the screenshot match that description, including the named clefs, staves, notes, rests, accidentals, beams, slurs, ledger lines, system breaks, and layout expectations?
+- Are all expected musical elements present exactly once, with no obvious duplicates, missing glyphs, wrong glyphs, or stale artifacts from a previous render?
+- Are stems, beams, flags, dots, accidentals, and rests positioned in musically plausible places relative to the staff and notes?
+- If this is a diff, can you explain the visual change in plain language from the diff artifact before updating the baseline?
+- If any answer is uncertain, do not update the baseline yet. Add or keep a `TODO` that names the uncertainty and links to the screenshot or diff artifact.
+
+8. If the target render passes the screenshot review checklist, update only that baseline:
+
+   ```sh
+   vex test --update <name>
+   ```
+
+   Where `<name>` is the test title — the screenshot filename passed as the second argument to `testCase()` in `tests/integration/render.test.ts` (helper in `tests/testing/test-case.ts`), e.g. `clef_treble.png`. The pattern matches by prefix, so `clef_treble` also matches.
+
+9. Validate that there are no regressions.
+   - Run `vex test` again after the selective baseline update.
+   - Per project rules, also run `vex fix` after code changes.
+   - If you deleted any integration test cases, run `vex test --clean` globally to remove orphaned screenshot baselines. Do not target a single test when cleaning deleted cases.
+   - If regressions appear, eagerly add or list `TODO` comments for each regression using the false-positive or true-negative language from step 4. Include the plain-language visual difference and the relevant diff path or artifact link.
+   - Do not update the whole suite by default. Create a plan for each regression and explain whether it is expected or unexpected.
+
+## Describing Screenshot Diffs
+
+Whenever you need to verbalize a screenshot difference — a regression diff artifact in `tests/integration/__diffs__`, or a comparison of vexml's current render against a golden-standard image the user provided (common for new test cases) — inspect the original image path(s) directly and describe the difference in plain language.
+
+Do **not** create transformed derivatives for diff work unless there is no other practical way to understand the artifact. Prefer the original screenshot or diff artifact. For a `__diffs__` artifact, remember that the image has old / diff / new vertical sections. For a golden-standard comparison, keep clear which image is the vexml render and which is the golden image.
+
+## Baseline Update Guidance
+
+Avoid running `vex test --update` for the whole suite unless the change is intentionally global and every affected render has passed the screenshot review checklist. Prefer one-by-one baseline updates after confirming why each render changed.

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

.github/workflows/deploy.yml

@@ -1,53 +1,37 @@
-# Simple workflow for deploying static content to GitHub Pages
-# See https://vitejs.dev/guide/static-deploy#github-pages
+# Builds the site/ playground and deploys it to GitHub Pages (vexml.dev).
+# Pages source must be set to "GitHub Actions" in repo settings.
 name: deploy
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches:
-      - 'master'
-
-  # Allows you to run this workflow manually from the Actions tab
+      - "master"
   workflow_dispatch:
 
-# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow one concurrent deployment
+# One deploy at a time; newer pushes cancel in-flight runs.
 concurrency:
-  group: 'pages'
+  group: "pages"
   cancel-in-progress: true
 
 jobs:
-  # Single deploy job since we're just deploying
   deploy:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - name: Install dependencies
-        # Includes @rollup/rollup-linux-x64-gnu, which is an optional dependency required for Vite.
-        run: npm install @rollup/rollup-linux-x64-gnu --save-dev
-      - name: Build
-        run: npx vex build site
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx vite build site
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
         with:
-          path: './site/dist'
-      - name: Deploy to GitHub Pages
-        id: deployment
+          path: "./site/dist"
+      - id: deployment
         uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -1,4 +1,8 @@
+# Premerge checks: format/lint/typecheck + unit and visual-regression tests.
+# `vex test` builds the Dockerfile and runs the suite inside it, so screenshot
+# baselines match local runs. Docker is preinstalled on ubuntu-latest.
 name: test
+
 on:
   pull_request:
   push:
@@ -10,16 +14,21 @@ jobs:
     name: run premerge code checks
     runs-on: ubuntu-latest
     steps:
-      - name: checkout
-        uses: actions/checkout@v4
-      - name: setup node
-        uses: actions/setup-node@v4
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: echo "$PWD/bin" >> "$GITHUB_PATH"
+      - run: vex fix --check
+      # Build the test image once with gha layer caching and load it into the
+      # daemon. vex test then reuses it (VEX_TEST_SKIP_BUILD) instead of rebuilding.
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
         with:
-          node-version: 22.6.0
-          cache: npm
-      - name: install
-        run: npm ci
-      - name: fix
-        run: npx vex fix --check
-      - name: test
-        run: npx vex test --ci
+          context: .
+          load: true
+          tags: vexml-tests
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - run: vex test
+        env:
+          VEX_TEST_SKIP_BUILD: '1'

.gitignore

@@ -1,7 +1,6 @@
-dist
 node_modules
-.DS_STORE
-__diff_output__
-coverage
-__tmp_image_snapshots__
-.claude
+site/dist
+.zed
+tests/integration/__diffs__/
+.DS_Store
+.playwright-mcp

AGENTS.md

@@ -1,5 +1,4 @@
-Use the `vex` or command for development. If it's not available, use `npx vex` instead.
+After making code changes:
 
-After making changes, format, lint, typecheck, and run tests in the packages that were affected.
-`vex fix`
-`vex test --local`
+- Run `vex fix` to typecheck, format, and lint the project.
+- Run `vex test` to test the project.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md