Skip to content

Learn: the Learning Synthlet section - #62

Draft
danigb wants to merge 36 commits into
mainfrom
learning-synthlet
Draft

danigb wants to merge 36 commits into
mainfrom
learning-synthlet

Conversation

@danigb

@danigb danigb commented Sep 15, 2026

Copy link
Copy Markdown
Owner

The fifteen tickets of thoughts/tickets/learning-synthlet/, end to end: a second fumadocs collection at /learn holding 70 lessons across eleven chapters, each one ending in the patch that makes its sound, in the code that runs. Thirty-six commits, 322 files, and a headless browser that presses Play on every page so a silent lesson cannot ship.

What is in the branch

  • 01 The scaffold — a second collection in the same site (site/source.config.ts, site/app/learn/**), chapters as plain folders so the route-group 404 cannot reach them.
  • 02 Content model and the three layers — the semantic vocabulary, definePatch, learn- tokens, and site/learn/rules.test.ts: five rules that fail when content carries design.
  • 03 The kit — controls, views, the LessonWidget play gate and meter, and "View the code" served from the patch file's own text.
  • 04 Chrome and navigation — lesson page, chapter index, the map, previous/next, localStorage progress, "open in Playground".
  • 05 The tutorial voice — site/learn/voice/, a VoiceDefinition superset of monoVoice with the lesson presets and the parameter table.
  • 06 The Playground — Instrument(learnVoice) with every control, the preset gallery, an XY pad, and a patch you can send someone as a URL hash.
  • 07 Patch diagrams — the diagram view, declared in the patch now and reserved for graph() later; a test keeps node labels honest against exposes.
  • 08 Chapters 0–1 — Get started and Sound: the vertical slice that proved the pipeline.
  • 09 · 10 · 11 — Envelopes, Amplifiers, Filters and Modulation: the rest of the twenty-lesson core path.
  • 12 · 13 · 14 — Time, Notes and voices, the fourteen Recipes, Effects and Beyond the book: the deep half, ~60 patches under site/learn/patches/.
  • 15 Every lesson makes a sound — site/scripts/check-learn-sound.mjs: Chrome opens every page, presses Play, reads the level and the live-node count off window.__learn__, and asserts the export ships no test hooks. Wired into .github/workflows/test.yml beside check:links.
  • Eleven follow-ups raised as the section was built — 01b the home page links the tutorial; 02b one lockfile; 02c/03c a lesson loads its own patch and its own source rather than all sixty; 03b the code panel is lit by the docs' own shiki at build time; 04b the core path is twenty and a test says so; 06b rule 4 walks the Playground; 06c unmounting no longer throws; 07b a diagram box is reachable without a mouse; 08b ?raw returns the file instead of SWC's opinion of it; 08c one keyboard, whoever names it.
  • One library fix, with a changeset — @synthlet/level-meter: tap() undid its edge with a targeted disconnect, which throws once disposable() has already dropped every edge out of the source. In a React tree that is the ordinary unmount order, and a throw in an effect cleanup blanks the page. Both teardowns now tolerate an edge that has gone.

How it was verified

On the committed tip:

  • vitest run in site/ — 15 files, 180 tests, green.
  • tsc --noEmit -p site — clean.
  • Prettier — clean.
  • DEPLOY=true npm run build — clean.
  • npm run check:links — 658 links resolved against the export.
  • npm run check:sound — 85 pages, 68 widgets, every one of them sounding, none leaking a node.

Still open

Twelve follow-ups stay in thoughts/tickets/learning-synthlet/, each a small improvement to a part that already works: 05b tune the voice presets by ear; 09b the spectrum axis crowds low harmonics; 11b a spectrum cannot zoom; 10b · 10c · 11c · 13b a diagram can only draw one chain, one source, and cannot name a native node; 12b the vocoder has nothing to vocode; 13c "View the code" cannot open the library's own file; 14b a meter cannot show true peak; 14c the wavetable catalog is somebody else's GitHub Pages; 15b a patch that does not dispose is caught by nothing.

Note on CI

The build job gained two check:sound steps in c18cae6. They assume Chrome at /usr/bin/google-chrome on ubuntu-latest; the script falls back to the chrome channel and then to the ms-playwright cache if that path is wrong.

After the merge

The devlog for this branch is thoughts/devlog/2026-09-15_17-11-32_learning-synthlet-the-tutorial.md in assist-synthlet, already on main there together with the twenty-six retired tickets. The submodule pointer bump follows this merge, per that repo's workflow.

The tutorial gets its own collection, loader, routes and content root, so a
lesson is not a documentation page sorted between `ad-amp` and `adsr`.

`source.config.ts` gains a second `defineDocs`. `dir` has to be set on both its
halves - `defineDocs` defaults `docs` and `meta` to `content/docs`
independently, so setting it once would leave the chapter `meta.json` files
being scanned out of the documentation.

Chapters are plain folders. `fumadocs-core` strips any `(group)` segment from a
slug, which is the thirty-link 404 the documentation still has; the tutorial's
chapters are part of the URL and part of the pedagogy, so they can never be
route groups.

The front page is `content/learn/index.mdx` rendered by a route, not
`out/learn/<first lesson>.html` copied into place the way `deploy:fix` does it
for `/docs`. It is exported twice - `out/learn.html` and `out/learn/index.html`
- because `out/learn/` is a real directory and GitHub Pages' precedence between
a `.html` file and a same-named folder is observed behaviour rather than
anything GitHub documents. Two routes, no copy.

`scripts/check-learn-links.mjs` reads the export and fails on a `/learn` link
that points at a page nobody built, which is the only thing that would have
caught the documentation's 404s.

The documentation section is unchanged apart from the nav link: across all 39
exported pages the only difference in visible text is the word "Learn" and the
only new link is `/synthlet/learn`.
`learnVoice`, a site-only `VoiceDefinition` under `site/learn/voice/`: two
PolyblepOscillators, a Noise, an Svf, an AdsrAmp, a modulation AdsrEnv and
one Lfo, wired by hand with every connect() on its own line. Thirty-one
parameters, a lesson bank and a sixteen-sound gallery, and a vitest file that
checks the schema and renders the voice on an OfflineAudioContext through
node-web-audio-api.

Two parameters are not in the ticket's table, which lists twenty-nine where
the ticket's own criteria ask for thirty-one: `lfoRateEnv`, which is in the
verified reference engine, and `filterType`, which the recipes chapter needs.

The root jest config gains `testPathIgnorePatterns`, so the package suite and
the CI shards do not pick up site tests.
Content is `content/learn/**/*.mdx` and `learn/patches/**/*.ts` and knows
nothing about how it looks; the kit (`learn/kit`) renders it; the theme
(`learn/theme`) is a set of CSS custom properties bound into Tailwind as
`learn-`. `learn/rules.test.ts` is the part that survives a contributor: five
rules over the three directories, each failure naming the file and the rule.

- `learn/frontmatter.ts`: the lesson schema, used by `source.config.ts` and by
  rule 5 rather than restated in each.
- `learn/patches/define.ts`: `definePatch`, `Control`, `View`, `Diagram`,
  `resolveControls`. It imports nothing at all.
- `learn/patches/index.ts` spreads one file per chapter, so a chapter's patches
  are added without meeting anyone else in the same file. The registry key, the
  patch's `id` and its path are three statements of one name.
- `learn/kit/vocabulary.tsx`: the seven components. `<Patch>` resolves the
  registry and renders a placeholder naming the controls it would show; the kit
  fills it in.
- `theme/default.css` and `theme/ink.css`; `layout.tsx`'s `DEFAULT_THEME` is
  the one-word redesign, and `?theme=ink` is the same thing in development,
  compiled out of the export.
- `sound/harmonics` and the `what-is-in-a-sound` lesson, so every rule has a
  positive case; 01's second placeholder is gone.
- vitest in `site/`, a `test` script, and a CI step beside the packages' tests.
  Ticket 05's `learn-voice.test.ts` runs under it, `@ts-ignore` removed.
`<Patch>` renders a real widget: `LessonWidget` builds the patch on the shared
context, draws its controls from the manifest, attaches its views, gates its
sound behind a Play toggle, meters its output and shows the patch file's own
source through a `?raw` webpack rule.

Nothing is built until the reader touches the widget - no `AudioContext` on
page load, which is what "silent arrival" has to mean if it is to be testable.
Building is silent (the patch ends in a gain at 0); Play, a key or a gate opens
it and resumes the context in one gesture.

`Scope`, `Spectrum`, `Keyboard`, `MasterMeter`, `SynthSlot`, `PatternView` and
`useSynth` move to `site/components/audio/` and are shared by both sections;
only their import lines change in the docs examples, and where the kit needed
something of them the docs did not have - a trace colour, key colours, spectrum
marks - it is an optional prop whose default is what the docs rendered before.

`patches/voice.ts` derives all thirty-one of the tutorial voice's controls from
`learnVoice.params` by the contract in `learn/voice/README.md`, plus `keyboard`
and `glide` by hand.
Six lessons and the three patches they needed: Get started's "Play a synth"
on the tutorial voice, and Sound's harmonics, pitch/loudness/timbre, the four
waveforms, noise, and the map of the catalogue.

Also implements 04c: `MapFigure` moves from the chrome into the kit and
becomes `<Map />`, the eighth word of the vocabulary, so lesson 1.5 can draw
the three shelves without importing anything. Rule 1 needed no edit - its
allowed set is the vocabulary's own keys.
/learn/playground: the tutorial voice with nothing hidden. All thirty-one
parameters in the voice's own five groups, the voice count and the glide beside
them, sixteen gallery tiles, an XY pad whose bindings change per preset, and a
link that carries the lot.

- learn/voice/mappings.ts: what the pad moves, per gallery preset, plus the
  default (cutoff across, resonance up) and one taper both the patch and the
  page call, so the sound and the link cannot disagree.
- learn/patches/playground.ts: the thirty-one derived exactly as voice.ts
  derives them, plus the pad (setTargetAtTime, so a fast sweep does not
  zipper), the pool and the glide. The voice count swaps the Instrument
  in place - build, await ready, carry every value over, then dispose the old
  one - so the Playground keeps playing across a voice change.
- learn/playground/: the link format extended with clamps and a changed-only
  diff, a preset resolver checked against the library's for every sound in both
  banks, and the frame the kit's own renderers draw into.
- kit/controls/XY.tsx finished: pointer capture by id, writes coalesced to one
  per frame, a keyboard nudge that builds the graph, a focus ring.
- content/learn/no-big-red-button.mdx: the closing page, content only.
- The /learn/playground line is gone from the link checker's allowlist.
The patch files for chapters 2 to 5, put on disk ahead of the lessons that
will use them, and every one of them in the registry - so `rules.test.ts`
rule 2 is green now, and the three agents writing chapters 3, 4 and 5 each
touch their own chapter's `index.ts` and never the shared one.

- learn/patches/envelopes/ and amplifiers/: four patches each, with their
  chapter index files, plus the two chapter intros in content/learn/.
- learn/patches/filters/index.ts: `filtersPatches` / `filtersSources` with
  comb, slope, types and resonance. `sweep` and `shootout` are a line each.
- learn/patches/modulation/index.ts: `modulationPatches` /
  `modulationSources` with lfo-destinations, pwm, sample-hold, ring, fm and
  additive. `sync` is a line each.
- learn/patches/index.ts gains its four imports and four spreads in one go.
  One commit and not two because this file names all four chapters: split
  either way and the first half imports a directory that is not there yet.
- content/learn/amplifiers/index.mdx: the description says "synthesiser: a
  gain", and a colon-space in an unquoted YAML scalar is a mapping. Quoted,
  and the whole test run collects again.
Ten lessons and two `meta.json` files on the eight patches that landed in
85190af. The two chapters were live on the map with an intro and nothing
under it; this is what fills them.

- content/learn/envelopes/: attack, decay-and-sustain and release are the
  same widget revealing one more slider each, which is what `show` is for;
  then matching-envelopes (Part 3's four contours, with the target playable
  from the same keys), gates-and-triggers (the Minimoog and the Odyssey, as
  one toggle) and beyond-adsr (two transients summed into a contour no
  four-stage envelope can draw).
- content/learn/amplifiers/: the-vca, gain-in-the-control-path,
  initial-gain-and-drones and clipping-and-drive - Part 9's argument that
  an amplifier in an audio cable and an amplifier in a control cable are
  the same module, one page at a time.
- Every `show` list checked against the patch's own manifest rather than
  against the plan's table; all ten agree.
- No chapter index is named in `pages`: fumadocs reads it off the folder,
  and listing it would put the intro in the lesson list twice.

Lessons run 297 to 389 words. Rules 1, 3 and 5 green, `tsc` clean,
`check:links` resolves all 105, prettier clean at the worktree root.
Eight lessons on the seventh patch and the six from 85190af: one signal on
another signal's parameter, walked from a five-hertz wobble up to the audio
band where the same wiring stops being movement and becomes timbre.

- learn/patches/modulation/sync.ts: master square into `slave.sync`, `AdEnv`
  on `slave.frequency` so its `gain` is the sweep in hertz, and only the
  slave heard. The master is drawn as a *controller* - it makes no sound
  here, and an audio cable from it would collide with the slave in row 0
  (11c). Marks at the master and the slave: the lowest peak never leaves
  the first, which is Part 43's first rule, drawn.
- learn/patches/modulation/index.ts: `sync` registered in both records.
  learn/patches/index.ts already spreads the chapter and is untouched.
- content/learn/modulation/: lfos and shapes-rate-amount-delay are the same
  synth asked two questions, with two `show` lists; then pwm, random,
  amplitude-and-ring-modulation, frequency-modulation, additive, hard-sync.
  Four of the eight are on the core path, as the plan has it.
- The six existing patches checked against plan Phase 1 rather than
  rewritten - ids, control ids, diagrams, silent-on-arrival, analyser before
  the output gain all agree. One fix: five of them trimmed to 0.12 while
  claiming in a comment to be "the level the chapter-1 patches settled on",
  which is 0.125. Now 0.125. `additive` keeps 0.035 and says why - nine
  sines in phase peak together.
- Every `show` list checked against the patch's own manifest, including
  additive's nine drawbars, whose ids are built in a loop and do not appear
  in the file as literals.
- 5.5 and 5.6 stand an order of magnitude above Reid's own frequencies
  because the spectrum's axis is linear to Nyquist (43 Hz per pixel); an
  `<Aside kind="note">` in 5.5 says so. Tickets 11b and 11c record both
  limitations.

Lessons run 325 to 385 words. Rules 1 to 5 green, the diagrams test builds
all three declared diagrams on an `OfflineAudioContext`, `tsc` clean,
prettier clean for `modulation/`.
Six lessons and six patches, opening on phase rather than on a cutoff knob
because that is where Reid opens and because a comb filter is the cheapest
proof that a filter is a phase device first. The chapter ends on the page no
book could print: nine analogue circuits and one sawtooth, one select box.

- learn/patches/filters/sweep.ts: a Moog ladder with an `AdsrEnv` through a
  `Param` on its cutoff and an `Lfo` beside it, both summed with the 200 Hz
  the parameter already holds. The floor is the filter's own `frequency`
  value rather than a `Param.input` - only a node passed through a factory's
  options zeroes a parameter, so `amplifiers/env-amount`'s shape works here
  unchanged and the patch is one worklet lighter.
- learn/patches/filters/shootout.ts: `VirtualAnalogFilter`'s nine, in the
  factory's own order so the select's position is the type, plus `Svf` for
  contrast. One `Param` per quantity fans out to all ten, and `Param.lin`
  carries the one resonance knob into the `Svf`'s Q, which is the same
  quantity in another filter's units. Ten gains and a 10 ms crossfade, so a
  model change during a held note has no gap in it.
- learn/patches/filters/index.ts: the two added, six in each record.
- content/learn/filters/: `meta.json`, the chapter intro, and the six
  lessons. 318-387 words each.
- The four patches written ahead of the lessons check out against the plan;
  `comb`, `slope` and `types` are trimmed to 0.125, the section's level,
  from 0.25 and 0.18.

`filters/sweep` is the chapter's one diagram and it is missing its `Lfo`,
`filters/comb` has no diagram at all, and both files say why: the layout
centres every box in its column and draws every audio cable at the row's
middle, so a parallel path and a second modulator are both drawn on top of
the cable already there - invisible rather than wrong. Tickets 10b and 10c.
The landing page rendered a bare <main>, so it was the one page on the
site without the header - and so the one page without the "Learn" nav
entry. It now renders inside HomeLayout {...baseOptions} like every other
page, and says two things instead of one: Learning Synthlet for someone
who does not have the vocabulary yet, docs/ for someone who does.
CORE_PATH_SIZE said 22, the content tickets' tables said 20, and the
lessons on disk say 20: six in chapters 0-1, six in 2-3, four in 4, four
in 5. Tickets 12-14 each say "none are core" of the chapters they write,
so 20 is the whole path and not a waypoint; the constant, the frontmatter
comment, the two chrome comments and index.mdx now all say it.

learn/chrome/core-path.test.ts counts the `core: true` frontmatter under
content/learn and fails when it disagrees with CORE_PATH_SIZE, naming
every core lesson it found - so the next disagreement is a red run rather
than a reader finishing the path and seeing the bar stop at 91%.
Four chapter plans in a row ended with the same hand-rolled paragraph - start
`next dev` on a throwaway port, open each lesson in headless Chromium, read
`window.__learn__.level()`, press Play, navigate away, check the console - in
four slightly different forms, with four different floors. Nobody could run it
from a clean checkout without writing it again, and CI never ran it at all.
`npm --prefix site run check:sound` is that paragraph.

One script in `check-learn-links.mjs`'s voice, one browser, one page, every
page under `/learn` in reading order. Per page: it arrives silent (`level()`
is exactly `-Infinity`, because before the first interaction no probe is
registered at all), nothing is live from the page before it, every widget
rises above -60 dBFS inside three seconds, and the console carries nothing but
the favicon 404 the document asks for outside the base path.

**It walks by clicking, not by loading.** `page.goto` destroys the JavaScript
context, so `live()` on arrival would be 0 whatever the lesson before it did
and the leak assertion would mean nothing. Only a client-side navigation makes
"a synth not disposed on unmount fails on the *next* lesson" true, so the walk
takes the chrome's own `Next` link wherever one points where it is going, and
any other link to the same page where one does not. Where neither exists and
the page built something, it takes the reader's exit first and looks at what
that left behind before loading where it was going - which is not a nicety:
the one lesson whose widget shows a meter is the only lesson in its chapter,
and reading order alone walked straight past it.

**Play alone is not always sound**, so there is a ladder: Play, then the
widget's gate (a `pointerdown`, which is what `Gate` answers), then the `z`
key (`COMPUTER_KEYS`, and never an arrow, which `LessonKeys` turns into a
page), then a sweep of the sliders the lesson shows. The last rung is for a
lesson whose default is a null - `filters/comb` opens on a 5 ms delay
cancelling a 100 Hz sine and its own prose says "it is almost silent", and a
check that demanded sound from that state would be demanding the lesson stop
teaching its point.

`playwright-core` and not `playwright`, `@playwright/test` or `puppeteer`:
all three of the others download a browser in `postinstall`, which every
`npm ci` in `site/` would pay for. This one downloads nothing and resolves a
browser at run time - `CHROME_PATH`, then the system Chrome, then the
ms-playwright cache - and says all three fixes when it finds none, because a
missing browser must not read like a silent lesson.

`--export out` is the other half of the hooks' contract: it serves the export
and asserts `window.__learn__` is undefined. A grep would be wrong and the
comment says why - webpack folds the gate to a constant and the module's text
survives minification with the assignment unreachable.

Four data attributes so the script addresses what it needs instead of guessing
- `data-patch`, `data-kind`, `data-blocked-patch` - beside the `data-control`
and `data-view` the kit already carried for this reader. Two CI steps in the
`build` job, which already installs the site and builds the export.

40 pages, 30 widgets, 39 soft transitions, 68 seconds.
Unmounting a lesson widget *inside the app* threw `InvalidAccessError` out of
the meter's effect cleanup, once per meter - and React treats a throw in a
cleanup as an error in the commit, so it unmounted the rest of the tree and
re-rendered the document. The reader saw the page blink and lose what was on
it. Nine of them on one navigation away from `/learn/get-started/play-a-synth`.

`LevelMeter.tap` undid its edge with `source.disconnect(node, output)`, a
**targeted** disconnect, and a targeted disconnect of an edge that is already
gone throws. It regularly is gone: `disposable()` calls `source.disconnect()`
with no argument, which drops every edge out of the source, this one included.
React runs cleanups parent-first, so the compound is disposed and then the
meter watching it is - which makes this the ordinary order rather than an edge
case, and it is why the Playground worked around it by never unmounting.

Fixed at the library, which is where the bug is: both teardowns now tolerate an
edge that has already gone, the worklet's and the script-processor fallback's.
Nothing else changes - the rest of each cascade still runs, and a tap disposed
while its source is still connected still removes exactly the one edge it
added. A test builds a tap, disposes the source first, and disposes the tap.

Ticket 06c's last checklist item was "a step in 15's pass that unmounts a built
widget in-app and asserts a clean console". `check:sound` does exactly that, on
every soft transition it makes, so this cannot come back unnoticed.
`/learn/about` and `/learn/no-big-red-button` returned 500 in `next dev`:

    Page "/learn/[chapter]/page" is missing param "/learn/about" in
    "generateStaticParams()", which is required with "output: export" config.

They are one segment under `/learn`, and a single dynamic segment is narrower
than a catch-all, so Next resolves them to `[chapter]` and never offers them to
`[...slug]`. The export did not notice, because `generateStaticParams` is what
decides which files a static export writes and the catch-all wrote both of
them - `out/learn/about.html` has been there since chapter 0 landed. `next dev`
routes a request rather than a manifest, and answered 500 to every contributor
who clicked the link. Broken since 08, invisible to the build, to `check:links`
and to the suite; found within a minute of `check:sound` existing.

So `[chapter]` owns every single segment now, and hands the ones that are not
chapters to the page that knows how to render a page - which moves to
`app/learn/lesson-page.tsx` for the same reason `chapter-page.tsx` and
`index-page.tsx` are where they are: two routes render it. The catch-all keeps
everything two segments deep and its filter gets simpler for it, because the
three kinds of page it leaves out are now one kind - a narrower route owns
them.

The export gains `out/learn/about/index.html` and its neighbour, the same way
every chapter is already exported both ways, and for the same reason
`app/learn/index/page.tsx` gives: `trailingSlash` is off, so a static host
asked for a directory has nothing to serve. Every other file it writes is
byte-for-byte where it was; `check:links` reports the same 317 links.
`/learn/sound/sources-modifiers-controllers` cites Synth Secrets Part 3 in the
middle of a sentence, which `lesson-chrome.tsx` says a lesson may do - and
`<Book>` rendered a `<p>`, so the citation was a paragraph inside the
paragraph's paragraph. No browser accepts that: the parser closes the outer
`<p>` before the inner one, React finds a tree it did not send, reports a
hydration error and re-renders the whole document. One lesson, since chapter 1,
and nothing noticed until `check:sound` read the console.

`<span class="block">` instead. Phrasing content is legal in both places, and
`block` plus the same margins is the same box a `<p>` was, so the ten lessons
that write the citation on a line of its own render exactly as they did. Only
the eleventh changes, and it changes from broken.

`BookLine`'s arbitrary variant follows the element it is styling.
Rule 4 - "design is tokens, and only tokens" - walked learn/kit,
learn/chrome, learn/theme and app/learn. learn/playground is five client
components and two hundred lines of layout, and it was in none of those
lists: a #fff in the gallery tiles, the pad's frame or "Copy link" was a
colour the theme could not reach and nothing failed.

It did not go unchecked - ticket 06 wrote the same five patterns into
learn/playground/playground.test.ts, because ticket 08 owned rules.test.ts
in the same wave. That was correct and was a second copy of a rule that
should have one. The directory joins rule 4's walk (two lines in) and the
copy goes (forty-five out, with the walk and the patterns it needed).

Proved by putting a #fff in learn/playground/Gallery.tsx: rule 4 fails and
names the file.
A rule that fails a lesson for naming the module it is waiting on is a
rule that forbids writing the lesson first - and that is where the two
tools stood. check:sound asserts a `blocked:` lesson renders at least one
[data-blocked-patch] and no figure[data-patch]
(scripts/check-learn-sound.mjs), and the placeholder only exists if the
lesson writes a <Patch> tag, because app/learn/lesson-components.tsx
swaps Patch for BlockedPatch on a blocked page. Rule 3 reads every <Patch>
in every lesson, does not read frontmatter, and fails an id that is not in
the registry - which a blocked lesson's id is by definition.

patchReferences() now carries the frontmatter status through, and rule 3
skips the does-not-resolve violation for a blocked lesson. Nothing else is
relaxed: a <Patch> with no id still fails, because the placeholder prints
the id and it is the promise the lesson is making, and a ready lesson with
a mistyped id still fails - both checked by hand before committing.

Chapters 9, 10 and the two blocked lessons of chapter 6-7 are what needs
this; site/learn/README.md's "A blocked lesson" now writes the recipe down
so all three get it right the first time.
site/ carried both package-lock.json and pnpm-lock.yaml. Only the npm one
is used - CI runs `npm ci`, the deploy script runs `npm run deploy`, and
ticket 02 added vitest and gray-matter through `npm install` - so the pnpm
one had been describing a dependency set that no longer exists. Anyone who
took the invitation and ran `pnpm install` in site/ got a tree with no test
runner in it, and `npm --prefix site test` then failed with
`vitest: not found`.

pnpm-lock.yaml goes, its line in .prettierignore goes with it, and
site/README.md says once which lockfile is real so the next person does not
re-create it - which also means the README stops offering `pnpm dev` as an
alternative to `npm run dev`. pnpm for the whole repository is a larger
decision than site/ alone, the root being an npm workspace.
Chapters 6 to 10 are written by three agents at once, and the one file all
three would otherwise edit is learn/patches/index.ts. So the five chapter
directories - time, voices, recipes, effects, beyond - arrive now, each
with an index.ts exporting an empty <chapter>Patches and an empty
<chapter>Sources, and index.ts already imports and spreads all five in
chapter order. Each agent adds lines to its own chapter's index and to no
shared file.

Empty is legal: rule 2 checks that every patch on disk is registered and
that every registered key has a file, and five chapters with neither are
five chapters with nothing to disagree about. The suite agrees - 164 tests
green with them in.
`voice` declares its keys twice on purpose - a view, so a lesson that narrows
the knobs down to one is still playable, and a control, so a lesson can write
`show={["keyboard"]}` and mean "the keys are what this page is about". Both
resolved to the same component, so the lesson that took the invitation got two
identical keyboards and ticket 08 had to ship `show={[]}` instead.

The widget now drops a control whose kind is already on the patch's view list:
the view wins, because it is the copy no `show` can take away. One filter, in
the file that already owns the layout decision, and free for every patch whose
views and controls do not overlap. The diagram link reads the panel rather than
the lesson's list, so a box marks only knobs a reader can actually see.

No patch changes.
Half the link between the picture and the panel was keyboard-reachable and half
was not: tabbing onto the Cutoff slider outlined Svf, but a `<g data-node>` had
no tab stop, no role and no name, so nobody without a pointer could go the other
way and nobody on a phone had a hover to give.

The boxes carry a roving `tabindex` now - one stop for the whole diagram, not
one per box, on a page that is mostly knobs - and the arrow keys walk the chain
in either direction, wrapping at the ends. Focus sets the same link a hover
does, so the knobs light up identically and the box outlines itself in the
accent token, which is also its focus indicator; `Escape` puts the link down
without taking the focus off the picture; a pointerdown sets it, for the reader
who only taps, and a tap on the background clears it.

Each box is a `role="group"` named for the knobs printed on it - "AdsrAmp,
Attack", from a pure `describeNode` beside `describeDiagram` - which is why the
`<svg>` is a group rather than an image: `role="img"` takes everything inside it
out of the accessibility tree, and the boxes are in it now. Its own aria-label,
the chain as a sentence, is unchanged.

`LessonKeys` already stands down for anything with a tab stop, so walking a
diagram does not turn the lesson.
@danigb
danigb marked this pull request as draft October 9, 2026 09:24

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant