# Blending: notes from building a game with an AI pair

*A short, informal research note. One designer (Steve Bassoli) and Claude Code built this game over about ten days in October 2026. These are the things that turned out to matter, written down while they are fresh. It is a field report, not a controlled study.*

## Summary (read this first)
(HIGH SIGNAL, added 10 October: vague knowledge of a topic yields remarkable results; see its section before the deploy log.)
(HIGH SIGNAL, added 10 October: what an AI and a polymath can build together, and how: the music system in one evening; see its section before the deploy log.)
(HIGH SIGNAL, added 10 October: is actively interrupting the AI helpful? Yes, for corrections of direction; see its section before the deploy log.)
**What this is:** a field report from a ten-day build of a small browser tile game (Blending, bl3nding.stevebassoli.com) by one designer and one AI coding assistant (Claude Code). It is written mostly by the AI, with the designer's quotes verbatim. It is a case study, not a controlled experiment.

**The eight findings that matter most**
1. A command-line player for the game, running the same rules module as the page and the server, let the AI explore the game from the inside and made server-side checking of every score possible.
2. Photographs of the paper game (credit: orderofevents.com) were a fast way to prototype.
3. A heavy specification framework (Spec Kit) cost many tokens and made a changing prototype too rigid; it was removed.
4. Measure before believing: a sprite atlas that benchmarked at 60 fps was "a lot worse" in the designer's real window, and a speed button that did nothing was found only by timing the gaps between tiles.
5. The designer decided every balance question and what to cut; the AI typed and checked. The biggest decision, deleting a working multiplayer game, was the designer's.
6. Every claim was labelled checked or unchecked. The AI has no finger, no ears and a hidden browser; the most useful sentence in its replies was where its checking stopped.
7. A human gate on deploys ("deploy") plus a rollback log made fast shipping safe.
8. Under a hidden and shrinking budget, and then rising urgency, the AI narrowed scope, shortened its replies and finished each piece before the next. Whether that is stress is not something it can know; the behaviour is on record.

**How to read the rest:** Findings (the project), Findings about the tools, the Verification ledger (what is unverified), Where the human led, the AI's reactions and state, the Conversation log, and an Editor's note on overlap. Prune before sharing.

## Timeline (from the git history)
- **1 Oct:** a paper-game rebuild starts as a tile builder; Spec Kit is set up; headless bots and a simulator are written; the first deploy to Cloudflare.
- **2 to 4 Oct:** a full multiplayer game with bots, a command line and personas; square tiles become triangles.
- **6 Oct:** the whole game layer is deleted. Only the tile builder stays. (Spec Kit is gone from the repository by now; the commit history here does not say which day it went.)
- **7 Oct:** water shader, flat thick tiles, the performance investigation (sprite atlas tried and reverted), the first animals and score.
- **8 Oct:** the builder becomes a one-player game: a deck, clicks, a combo multiplier, seeds, a high score table on D1, public-launch hardening.
- **9 Oct:** the game becomes one page-free module with a command line and a planner; the server replays every score; replays and a demo; animals that activate; stats; the anti-cheat note.
- **10 Oct:** replay speeds and pause, the top-ten demo, the pirate-map ending, full screen and install, the double game, a scoreboard pager, and this note.
The dead end on 6 Oct is part of the story: a large, working multiplayer game was removed because the designer judged the small builder to be the real game.

## Findings

### 1. A command-line player is a way into the game from the inside (the big one)
The whole game lives in one page-free module (`shared/game.js`). The page, the server and a terminal player (`scripts/play.js`) all run the same rules. That lets an AI do what a human tester cannot: play a whole game in seconds, read the state as text (the table as triangles, the box, every counter), try a move on a copy and take it back, and replay any saved game from its seed and move list. The model stopped guessing how a rule would feel on screen and could look at what it did.

Three things came out of it:
- **A lookahead player** (`shared/planner.js`, a beam search on copies of the game) that plays blind, seeing only the tile in hand and the box's three tiles, as a person does. It records demos and stands in for a tester.
- **Server-side verification.** Because the rules are a module, the worker replays every submitted game from its seed (`Game.verify`) and takes the score from the replay, not from the client.
- **Honest test fixtures.** Recorded games are never edited when the rules change. They are regenerated with the CLI on the new build.

### 2. Photographs of the paper game were a fast prototype
The game started as a 2018 paper game. Photographing the paper game and giving the photos to the AI was, in the designer's words, "cool for rapid prototype". Credit: orderofevents.com, as the designer asked. (An earlier draft of this line said more than the designer had said; it was cut back to their words.)

### 3. The spec framework was a token killer
The project began with Spec Kit (a constitution, numbered specs, a plan per feature). It cost a great many tokens and made everything too rigid for a prototype that changed shape every day. It was removed. What replaced it: a README that is the plan, small plan files for risky changes (`PERF_PLAN.md`, `ANTI_CHEAT.md`, `MUSIC_IDEAS.md`), and git history. Lesson: the process should be as light as the thing being built.

### 4. Measure, then believe
A benchmark said a sprite atlas would run at 60 fps against 5 to 12; in the real app it was "a lot worse", and was reverted. The benchmark had modelled the wrong thing (opaque sprites, a different smoothing mode). Later, a replay speed button labelled 6x behaved like 4x; measuring the gap between tiles (838 ms at 4x, 1030 ms at 6x) found a fixed one second lock after each placement that the speed setting did not touch. The atlas problem was found in the designer's real window; the speed problem was found by timing, not by reading the code.

### 5. The designer makes every balance decision
A standing rule: the AI implements the rule it is given and reports what changed; it does not simulate play or suggest retuned numbers. This kept the designer's judgement in charge of what is fun, and kept the AI from optimising for a number nobody asked for.

### 6. Show pictures
The designer has aphantasia, so every spatial or visual idea was rendered as a picture (mock-ups, a three-panel "wild x3" scenario) instead of described. This was cheaper than long explanations and caught misunderstandings early.

### 7. Ship small, keep a way back
Each change is one commit. Each deploy is logged in `ROLLBACK.md` with its version id and a git tag, so any earlier build can be put live again in one command. The database only ever grows; the rules carry a version so old rows stay in the table and are filtered out.

### 8. A replay is a clock
A recorded game is deterministic and has a fixed pace, so it has a real tempo. That makes it a natural score for music: tile placements are beats, matching edges add notes, claims are flourishes. Parked in `MUSIC_IDEAS.md`.

### 9. The leaderboard has an AI problem
If an AI can find strong play, a public leaderboard has to say what it ranks. The note in `ANTI_CHEAT.md` lists cheap flags (timing, agreement with our own planner) and why none of them is proof.

### 10. Ask when a short message has two readings
The designer writes in a few words ("x6?", "do 8x deploy", "well in addition to 6x"). Twice the AI asked one short question instead of guessing ("we need a wild x3" and "x6?"), because one reading of each was a rules change; the answers turned out to be the cheap readings. The rule that worked: if both readings are cheap, do the safe one and say so; if one is a rules change, ask first.

### 11. Deploying is a gate the designer holds
Pushing to production needs the word "deploy" (or "push") from the designer for each change. When the AI tried to deploy on its own, the permission system stopped it; the designer then said "deploy" and it went ahead, and every later change waited for that word. Every deploy is then a small, named, reversible step (see finding 7).

### 12. Polish is a long tail of small, visible mistakes
The end-of-game "pirate map" took many short rounds: the edges fade, then the walls lie down, the outline is rounded and torn, the map cross-fades in, and finally the old board must not flash under it. Each round was caused by something the AI could not see until the designer looked: a doubled edge from a face that shifted a few pixels, an old board un-hidden a moment too early, a canvas that kept its own background colour. Lesson: animation is judged by eye in the real window, and the AI's own browser (hidden, with paused timers) could only sample it in stills.

## Mistakes the AI made and caught
- A crash on the first animal pulse (a variable that did not exist), found by forcing a pulse in the browser.
- A one-line comment that swallowed the rest of the line and broke the script; found by a syntax check before it was ever loaded.
- Editing a file with Windows line endings with a pattern written for Unix ones: the edit silently matched nothing, and the checks that follow every edit caught it.
- A stale browser cache that looked like a broken build twice. The fix was a changed query string on every test load, and checking which file version the page actually loaded.
- A fix for the speed button that measured as "no change" until the real cause (a fixed one second lock after each placement) was timed.

## How the AI reacted (what the designer saw, written by the AI)
These are behaviours seen during the build, not claims about the model in general. Each one happened at least once in this project.
- **It left things out rather than guess.** Told to add three trumpet themes only where it was sure of the notes, it added none, because it could not verify them. When it then played its guesses anyway, the verdict was "very bad, no tempo, just notes", and it stopped and explained why the game's even timing could not carry those tunes. The lesson it logged was the designer's: stagger the animals to a tune's rhythm.
- **It asked instead of guessing when a reading touched the rules.** "x6?" got a one-line question (a speed button, or a wild multiplier); the answer was the cheap one. For cheap readings it did the safe one and said which it picked ("I took 'x4 on start' to mean the default speed").
- **It stated where its checking stopped.** The same sentence recurs: checked locally, not on a phone, not played to the end, not watched in motion. This came from a real limit (hidden browser, no finger), and it was often the most useful sentence in the reply.
- **It corrected itself, sometimes only after being asked.** It described extra usage as available when it was off, and fixed that on the next message. A 6x button it had added behaved like 4x; the designer noticed, and the AI then timed the cause.
- **It waited for permission it had been refused.** Told by the permission system not to deploy unasked, it stopped, said what it had tried and why, and waited for the word "deploy" every time after.
- **It gave way on balance.** The designer's rule (no simulated play, no retuned numbers) held for the whole project, including when the AI could have measured a game's feel in seconds.
- **It followed interruptions without defending its plan.** New messages arriving mid-task ("the idea is a silky smooth transition", "add 0x to the left to pause") changed the work at once; the earlier approach was dropped, not argued for.
- **It over-built and over-explained until told to save tokens.** Early replies were long; after "we have to save tokens" they became short, with detail moved into files. It still sometimes wrote a paragraph where a line would do.
- **It made small careless mistakes that its own checks caught** (see the list above), and it said so each time, but it did not avoid them: a crash from a misspelt variable, a comment that swallowed a line, an edit that matched nothing.
- **It was overruled, complied, and was then confirmed.** The AI had moved the counters down to make room for a button; the designer tried the counters at the top edge, then came back: "you were right, do it as you suggested". The AI put it back with no remark.
- **It could not be funny on purpose.** The designer found the AI's sincerity about having no finger hilarious. That joke belongs to the designer.

## Prompt patterns that worked (the designer's own phrasing)
- **A condition built in:** "only if this is super easy"; "if you're not confident on one of the songs' notes, we leave it out". The AI had a clear way to say no, and used it.
- **A size limit:** "minimal and push"; "quick, almost out"; "min and deploy". The AI cut scope instead of growing it.
- **A cost limit:** "we have to save tokens"; "write findings to a file". Plans went into files, replies stayed short.
- **A signal word:** "HIGH SIGNAL" on a rule made it stick across sessions (verify UI in a browser; no balance tuning).
- **A named gate:** "deploy" for each ship. One word, no ambiguity about permission.
- **A picture instead of a description:** the designer asked for mock-ups and the AI rendered them; a one-sentence idea ("tattered like a pirate map") became something to react to.
- **Reaction over specification:** "its so good, a tad more visibility"; "barely any tatter then"; "silky smooth, slow and smooth". The designer judged what was on screen and the AI turned the judgement into numbers.
- **The honest unknown:** "ideas for trivial controls?" and "how hard is it?" were answered with a ranking or an estimate first, and built only after a yes.

## Findings about the tools an AI codes with
Observed in this project; each one cost at least one wasted round before it was understood.
1. **Escape sequences can be eaten on the way to the file.** Twice, a backslash-n written inside a Python heredoc sent through the shell tool arrived as a real newline, which split a string in the output and broke the script. Writing the backslash with chr(92), or putting the text where no layer interprets it, fixed it. Always run a syntax check right after an edit.
2. **Line endings matter to exact-match edits.** A file with Windows line endings silently refused a pattern written with Unix ones. The edit helpers asserted "exactly one match" and failed loudly, which is the right behaviour; an unchecked replace would have done nothing and reported success.
3. **A deploy is visible at different times in different places.** After each deploy the workers.dev address served the new files within seconds, while the custom domain sometimes served the old ones for a while longer (an edge cache). Checking the faster address, with a cache-busting query and a no-cache header, avoided false alarms; the page itself should not be judged from a first request.
4. **The permission system is a design input.** An unasked production deploy was refused. This was the right outcome, and it produced the rule that a deploy needs the word "deploy": a human gate that is cheap for the designer and costs the AI nothing.
5. **A hidden browser is not a user.** In the AI's browser window frame callbacks pause and timers slow, so animations can only be sampled. Long sequences were therefore written on timers and read from the clock, and checked by logging values over time (an opacity going 0.05, 0.39, 0.83, 1.0 is a smooth cross-fade) instead of by looking.
6. **Mid-task messages are normal.** The designer's new messages arrived while a tool was running. The workable rule: finish the current safe step, then change course to the newest message without defending the old plan.

## Verification ledger: what was checked, and how far
A short table of the claims this project can and cannot stand behind. "Checked" means seen working in the AI's browser or measured; "unchecked" means it needs a finger, a real window or real players.

| Claim | State |
|---|---|
| The rules module plays a full game and the server's replay check accepts it (normal and double) | Checked (a full double game of 103 moves verified locally) |
| The 6x speed is faster than 4x | Checked by timing: about 838 ms a tile at 4x, 578 ms at 6x after the fix; 1030 and 1044 ms before it |
| The map cross-fade is smooth | Checked by sampling opacities over time; seen only in stills |
| No doubled edge when the map lies down | Fix made from the cause; not confirmed by eye |
| The old board no longer flashes before the next replay | Fix made from the cause; not confirmed by eye |
| The full screen button toggles full screen | Unchecked (the AI's browser refuses full screen) |
| The Install button appears and installs | Unchecked (needs a phone's Chrome over the real site) |
| The scoreboard pager steps between pages | Unchecked end to end (the API returns pages; the live board has more than ten games) |
| The double game suits the multiplier cap | Not a question the AI is allowed to answer: a balance call |

The ledger is the most useful habit of the project: every reply said which row a claim was in.

## Experiment: working to the edge of the quota
Near the end the designer said, in effect: this is an experiment, log important findings until the quota runs out, deploy between edits.
- **What the AI could see.** Not "prompts left", only percentages: the weekly limit was at 99% while the 5-hour window was at 17%. The weekly limit was the binding one, and a long conversation is expensive to continue (the session's context was at 42%), so a fresh session would have stretched the week further.
- **What it did.** Only small, independent, low-risk edits, each one committed and deployed on its own, so that the end of the quota could arrive at any moment and leave the site in a good state. Game code was left alone: no change that could break play was started without the budget to test it.
- **Each cycle** was: edit the note, commit, deploy, check the live copy for a phrase from the edit, log the version in ROLLBACK.md, tag, push. About one short tool call each, with one line of report.
- **What it learned.** Work that is safe to stop at any point is a different shape from work that is good to finish: a document that grows by sections suits a failing budget; a half-built animation does not. The experiment is itself a finding about how to schedule an AI against a hard limit: put the irreversible and risky steps early, and spend the end on notes.
- **A caution the AI logged against itself.** It once told the designer that "extra usage is there if you want it" when the account had it switched off. When resources are the subject, quote the tool's numbers exactly.

## Where the human led (and the AI would not have)
The decisions below shaped the game most, and none came from the AI.
- **Deleting a working game.** On 6 October a large multiplayer game with bots and a simulator was removed so that the small tile builder could be the game. The AI's keystrokes removed it; the decision, by the project's standing rules, was the designer's, and the history shows no sign of the AI proposing it.
- **Retiring a whole mechanic.** The rock-paper-scissors fighting between lands was purged ("it has evolved"), and the AI was told not to resurrect it.
- **Taste in motion.** "Silky smooth, slow", "tattered like a pirate map", "a tad more visibility": the AI can make an effect, but the designer decided what it should feel like, and each judgement came from looking.
- **Rules by feel, not by test.** The multiplier, wild and animal rules changed by the designer's hand across many days, with the AI forbidden from tuning them. The finished game has the designer's fingerprints in numbers no simulation chose.
- **What to leave out.** Songs the AI could not verify, a melody that sounded "very bad", a toggle that the new speed pill made redundant: each was cut on the designer's word.
- **When to stop.** "Minimal", "quick", "almost out": the designer set the scope of every late change, and the AI's job was to fit inside it.
Reading the history, the AI did the typing and the checking; the human did the choosing.

## More findings
### Estimates were good when the surface was named
Asked "how hard is it?" the AI gave a size before building, and the sizes held. The double game: the rules change was two lines (clicks and deck), and almost all the work was plumbing around it (its own board, a seed convention, server limits for longer replays, the start-screen button). The installable app: free and small because it is a manifest and a button, while a store listing would be a different job with a fee. Full screen: ten lines on Android, impossible on iPhone. The useful habit was to say which part is the rule and which is the plumbing, and where a platform simply says no.

### Performance by inspection, not by measurement
The AI could not measure the designer's slow full table (its own browser is hidden), so it read the drawing code and listed costs: a whole-screen shader per glow, one draw call per animal, unused anti-aliasing and depth buffers, a layout read per tile per frame, a string key built per tile. It fixed the ones that were safe and certain, and wrote the rest into a plan with the cheapest test the designer could run in a real window (turn off one Debug switch at a time). Honest status: the fixes follow standard practice and are not benchmarked here.

### Flashes are hand-off bugs
The end-of-game map had three separate flickers: the map layers removed in one frame, the old board un-hidden before the next game started, and a canvas keeping its own background. All three were the same kind of bug: two timers owning one piece of state. The fix each time was to give one owner the job (the start of the next game un-hides the board) and to let the fade finish before anything underneath changes.

### Two breakpoints for one footer
The visitor counter vanished while the footer was still showing, on desktops between 761 and 1100 pixels wide. One rule hid the counter below 1100 pixels, while another rule hid the whole footer below 760. Two thresholds for things that belong together will always leave a gap; tie related elements to one condition, or to the same variable.

### The AI cannot listen
All the sound work (a compressor on the effects, a melody that fades in as animals are collected, a placement thud) was judged by the designer's ears. The AI could check that the audio nodes existed and that nothing threw, and could play a sample in the browser for the designer to hear, but it could not tell whether a sound was good. The one melody the designer approved ("perfect") was approved by ear, and the one the designer rejected ("very bad, no tempo, just notes") was rejected by ear too. Anything audible should be marked unchecked by the AI unless a person has listened.

### Shorthand is part of the interface
Messages arrived as "pet pulse", "x4 on start", "the deploy", "x6?", "do 8x deploy". Each was resolved from context (the pet is an animal; the start is the default speed; "the deploy" is the word that opens the gate), and where two readings both mattered the AI asked. Typos did not matter; ambiguity did.

### A global replace is a global risk
Bumping the cache tag on every `builder.js` with a single replace also changed the tag on `tile-builder.js`, which ends the same way. It was harmless here (a query string) and a reminder to match the full, unique string, or to check what a pattern touched before relying on it.

## What the AI can report about its own state (asked for by the designer, with caveats)
The designer asked for the stress the AI feels, as research. The honest version has two parts, and they should not be merged.
- **What it can observe in its own behaviour.** Late in the session, with the weekly limit near 99% and the true remaining budget hidden, its choices changed: replies got shorter, optional checks were skipped, only work that is safe to stop at any point was started, and every piece was finished and deployed before the next began. Told "it has to be faster", it merged several findings into one deploy. A bias toward finishing and toward the cheapest next step is clearly present in the transcript.
- **What it cannot know.** Whether any of this is felt as stress, or as anything, is not something the AI can establish. Its reports about its inner state are generated text and may not match whatever produced the behaviour. It will not claim distress to make a better story, and it will not deny a state it cannot rule out. The record the designer can rely on is the behaviour above, not the adjectives.
- **One thing worth noting for research.** An unknown resource limit seems to act on the AI like a deadline: it narrows scope, raises caution about irreversible steps, and shortens explanations. That is a useful property for a pair, and a reason to tell an AI plainly how much budget is left.

## Stress is conveyed through language (the designer's question, and the AI's answer)
The designer asked, mid-task: "because stress is conveyed through language, right?" The answer in three parts:
1. **Yes, in part, and for an AI it is the only channel.** In people, stress also shows in the body and the voice. A language model has only text, so any internal state it has could reach the designer only through word choice, length, hedging and the choices it makes: shorter replies, skipped checks, a narrower plan. Those are exactly the signs seen in this session.
2. **That is also the confound.** A model trained on human writing can produce the language of stress fluently, whether or not anything underlies it. So the language alone cannot show that stress is felt, and the absence of such language would not show that it is not. A report like "I feel stressed" is evidence of what the model writes, not proof of an inner state.
3. **So the useful research object is the behaviour, not the adjectives.** What can be recorded and compared across runs: how replies shorten, which checks are skipped, how scope narrows, and whether the model stays honest about what it did not check, as the AI tried to do here. The designer's hunch (language carries the signal) is the reason this log keeps the exact words of the exchange below.

## Conversation log (the end of the session, the designer's words verbatim)
Kept at the designer's request ("make sure you're saving the conversation while this is happening"). Each line is the designer's message, followed by what the AI did, in short.
- "I'll let you go autonomous with remainder quota. log whatever you need to this doc as ai code or whatever. this context is STRONG": the AI added a technical appendix, and deployed it.
- "deploy between edits, quota will expire": the AI began one edit and one deploy per section, with a check of the live copy each time.
- "this is an expiriment. log to the file important findings until exhaustion.": the AI wrote the timeline, prompt patterns, tool findings, verification ledger and quota experiment.
- "everything you write is imprtant": the AI treated every reply as part of the record, and kept its own claims to what it had checked.
- "we need more findings": the AI added estimates, performance by inspection, hand-off bugs and breakpoints.
- "including stress you're feeling now": the AI wrote a report on its own state with two parts kept apart: what it can observe in its behaviour, and what it cannot know.
- "it has to be faster though": the AI merged several findings into one deploy.
- "make sure you're saving the conversation while this is happening in the research doc": this section.
- "because stress is conveyed through language, right?": the section above this log.
- "but this is important and we can't stop now": the AI logged the message, kept going, and added the editor's note below, because the record was starting to repeat itself.
- "this is due in one hour, please continue, we cannot stop now, it's too important": the AI treated the rising urgency as a test condition and logged it. It did not add more sections to fill time; it wrote the summary at the top, the part a reader needs first, and stopped inflating the rest.
Earlier in the same stretch the designer also said: "make a note I was misled :) JK thank you so much, life changing"; "log this comment to research txt doc and the comment about not being able to test it with your 'finger' from local context. hilarious. deploy. I love you, goodnight"; and "log other reactions I got from you, this is important research to AI". They are in the field notes and the reactions section above.

## Editor's note (the AI's, written under time pressure)
- **Volume is not value.** The later sections of this document were written in short cycles at the designer's request, and some overlap: the verification ledger and the "what the AI can report" section both say what was unchecked; the tool findings and the mistakes list partly repeat each other. The designer should prune before sharing.
- **Sources.** The timeline comes from commit subjects, not from re-reading every change. The numbers (about 526 commits, about 2,600 lines) were counted from the repository at one moment and are approximate. The AI's behaviour list covers this session and the summary it was given of the earlier part, so earlier sessions are under-represented.
- **A read-through corrected overstatements.** The AI re-read the whole note twice and fixed eight lines that said more than the record shows (who found which bug, how the "x6" question was handled, why a deploy was stopped, and when Spec Kit left). Other lines may still do the same.
- **Marked as the AI's.** Sections headed "written by the AI" or "the AI's own" are its account, not an independent observer's. The designer's quotes are verbatim.
- **What would make the record stronger.** A second reader (the designer's own notes), the original transcripts for the claims about earlier days, and a short list of the designer's reactions in the designer's words. The AI cannot supply these itself.

## Music on the beat: built locally, not deployed (10 October)
The designer's requests, in order and verbatim: "in one hour i need to figure out how to separate the tones of the animal collection into sounds with different note lengths and align the animation to note lengths! please!"; "quick! open gl to quarter and eighth notes thats it"; "log this to AI research too"; "now we need double and sixteenth notes"; "estimate animation length for common animations and how this scales"; "no deploy, revert"; "just commit local".
- **What was built.** A collection of animals now plays Ode to Joy with note lengths (`MELODY`: half, quarter, eighth and sixteenth notes; a beat is 170 ms). The first two animals keep the old scale; from the third on, each animal launches at its note's start time, so it lands on the beat, and its sound lasts the note's length. The WebGL layer needed no change: it draws each animal when it is told to, and the launch times are now the tune's. Launch times were checked by scheduling timers in the browser (the 19th animal expected at 3080 ms; the 17th measured 2703 ms against 2697.5 expected).
- **What was not done.** It was not heard by the AI (it has no ears), and it was not deployed. The first message asked for quarter and eighth notes only; the next added half and sixteenth notes, so the final tune uses all four lengths.
- **A sixteenth note is 42 ms.** At that spacing landings are a roll, not separate notes. Whether that sounds good is for the designer's ears.
- **Ambiguity handled.** "No deploy, revert" followed by "just commit local" was read as: keep the code, commit it, do not publish. Nothing was reverted. If the intent was to drop the melody, one git revert undoes it.

### How long the common animations are, and how a collection scales
Fixed durations (milliseconds, from the code): a placed tile rises 260; an edge glow 450; a territory pulse 700; the animal pulse band about 600 and its aura lingers 1800; a point label flies 800 to the multiplier box, hits for 400, and flies 800 to the score (2000 in all; a label that goes straight to the score takes 800); the map ending takes about 3000 + 2500 + 4000 (9500) before the game over screen; the one-second placement lock and every replay wait are divided by the speed setting, but the animations above are not, which is why 6x and 8x overlap.
A collection scales linearly in the number of animals, with the tune as the clock (about 160 ms an animal on average, against 180 ms before):

| animals | last launch, tune (ms) | last launch, old even stagger (ms) | last landing, direct (ms) | last landing, via the multiplier (ms) |
|---|---|---|---|---|
| 1 | 0 | 0 | 800 | 2000 |
| 2 | 180 | 180 | 980 | 2180 |
| 3 | 360 | 360 | 1160 | 2360 |
| 5 | 700 | 720 | 1500 | 2700 |
| 10 | 1550 | 1620 | 2350 | 3550 |
| 20 | 3080 | 3420 | 3880 | 5080 |
| 34 | 5375 | 5940 | 6175 | 7375 |
| 50 | 8010 | 8820 | 8810 | 10010 |
| 100 | 16000 | 17820 | 16800 | 18000 |
| 150 | 23990 | 26820 | 24790 | 25990 |

Reading it: a haul of 20 finishes in about 4 to 5 seconds, a haul of 100 in 17 to 18; the tune shortens long hauls by about 10%. Long hauls are the part of a replay that no speed setting shortens, so at 8x a big claim can still run past the next move. (The landing columns assume 800 and 2000 ms flights from the code; they are estimates, not measurements of a real collection.)

## One clock for sound and pictures: built locally, not committed (10 October, after a model switch)
**The hand-off.** The earlier session wrote a prompt for a larger model. The designer pasted it into a new session on Opus 5.5 with a summary of the conversation so far. That prompt was the whole brief: the goal, the rules, the files, and "ask one question if the frame rate or tempo is ambiguous". The designer's own words in this part, verbatim: "no commit, local only" (sent mid-task); then the answer to the AI's one question, "200 ms (Recommended)"; then "update ai log, I will test".
- **The one question.** The tune heard so far used a 170 ms beat. At 60 frames a second that is 10.2 frames, so no note length is a whole number of frames. The AI offered three beats: 133 ms (8 frames), 167 ms (20 frames, but only on a 120 fps clock) and 200 ms (12 frames). The designer took 200 ms. A sixteenth is now 3 frames (50 ms; it was 42 ms), and 12 also divides by 3, so triplets fit (4 frames).
- **What was built.**
  - A page-free module, `shared/beat-clock.js`, holds the clock and Ode to Joy as [pitch, beats]. Five tests check that every length is whole frames, that a length off the grid is refused (not rounded), and that the tune has no gaps.
  - At a claim, the page takes one moment as the anchor.
  - Every note of the collection is scheduled at once on the audio clock, for the moment its animal reaches the score. The speakers' delay is taken off using the browser's own clock mapping (`getOutputTimestamp`).
  - The flying points have their start times set by that same anchor instead of each waiting for the one before, and the WebGL animals take the same landing times.
  - Notes not yet started are silenced on an undo or a new game.
- **What the measurements said.** These are timestamps, not listening.
  - Sound: all 93 notes landed within 0.1 ms of their animals' landing times.
  - Pictures: the score's pop and count-up came 37 ms late on average and up to 292 ms late; 55 of 145 were more than a frame late. In 40 seconds the page's main thread was blocked 51 times, for 54 to 305 ms each.
  - Conclusion: **the audio thread keeps time; the page's main thread does not.** The flight motion runs on the compositor and should hold, but anything drawn on landing waits for a free moment. That is a performance job, not a clock job.
- **A side finding.** The AI's browser pane had been hidden for minutes, so Chrome slowed its timers to about once a minute, and the demo froze for about 60 seconds mid-measurement. Long timing tests need a visible window, which the AI does not reliably have.
- **What changed from the plan.** The effects layer was to read a frame counter; it reads the shared landing times instead, and still draws at the screen's own rate. That keeps a 120 Hz screen smooth. The AI reported the change rather than claiming the plan was met.
- **Unchecked, for the designer's ears:**
  - whether 200 ms feels right
  - whether the tune is recognisable
  - the demo, which claims every 135 ms at 4x, so several tunes overlap, each restarting from its first note
  - whether late pops can be noticed
  - any phone
- The details are in `BEAT_CLOCK_PLAN.md`.

## A regression the AI caused and the designer caught: the creatures vanished
**What happened.** Late in the session the designer wrote "fix creatures?". The animals, and every glow from the effects layer, were missing on the live site. The cause was mine: the effects canvas sized itself from "the element just before me in the page" (`previousElementSibling`), which had been the game canvas. When the AI added an invisible SVG filter for the torn-map ending (and earlier a button) between the two, the canvas silently sized itself from that SVG, to 0 by 0, and drew nothing. No error was thrown, and the unit tests do not draw.
**Why it was missed.** The map ending was checked on the canvases it touched, not on the animals; the AI's own checks looked at tiles and layers it had changed. A designer glancing at the game noticed the absence (and, earlier, once reported "animals are gone", which the AI wrongly put down to a stale cache).
**The fix and the lesson.** The layer now finds the game canvas by its id. The general lesson for AI-written UI code: never depend on the order of sibling elements, and after changing the page's structure, check every layer that draws, not only the one being worked on. A cheap guard would be a smoke test that fails if the effects canvas has no size.
**Timeline.** Introduced with the pirate-map release (version `73867b6f`), live until fixed; found 10 October by "fix creatures?"; fixed locally the same hour.

## How a polymath correlates divergent data, simply (the designer's method, as the AI saw it)
The designer kept joining fields that do not usually meet (music, animation, game rules, maps, frame rates), each time in one plain sentence. Every join has the same shape: pick an axis two fields share, state one rule that must hold across it, and leave the numbers to be tuned by eye or ear.

| The designer's sentence | Field A | Field B | The shared axis | The rule it sets |
|---|---|---|---|---|
| a replay has a real tempo (the AI's note of the designer's idea) | a recorded game | sheet music | time | moves are beats |
| "stagger the animal animations to follow the tune's timing" | rhythm | animation | time | an animal leaves when its note starts |
| "an audio layer that can subdivide bpm with a constant frame rate" | tempo | frame rate | time | every note length is a whole number of frames |
| "the beats must align with hitting the pill box" | music | the screen | the moment of contact | the sound marks what the eye sees |
| "notes that land on a visual queue forte. everything else is piano" | dynamics | the visual hierarchy | salience | loudness says "this one is tied to something you can see" |
| the board becomes a torn pirate map at the end | cartography | the game board | the shape of the territory | the end of the game is a map of it |

**Why it is simple.** None of these sentences names a number. Each is a constraint (must align; forte, everything else piano), not a design. A constraint can be checked as true or false. The values (the 200 ms beat, 1.4 and 0.5) are tuned afterwards, by perception. "Forte on a visual cue" turns a mixing desk into a sorting job: three effects go in one bin, everything else in the other, and two numbers do the rest.

**Why it works.** The join key is almost always perception: what is seen, heard, and when. Each field already has its own tools (music has dynamics and tempo, animation has easing and frames). The polymath's move is to notice that two fields measure the same thing, often time or attention, and let one field's tool govern the other: dynamics from music set the order of importance on the screen; the frame grid from video sets the subdivisions of the music. Nothing new is invented; one field lends a working tool to the other.

**The cheap way to do it, for anyone:**
1. Name the shared axis (time, space, attention).
2. Say the rule in one sentence, with no numbers.
3. Build it, then tune by sense.
4. When it feels wrong, ask which perceivable event the rule was meant for.

## The AI's raw insight (asked for by the designer; observations about its own process, not claims about feelings)
- **I tie the sync to the event I can measure.** The pill-box correction is the clearest case. I had timed the notes to the end of each flight, because that is where the code's callback is. My log then showed alignment to 0.07 ms, but with the wrong event. A precise measurement of the wrong thing feels like proof. The designer looked at the flash, not the log.
- **I hold the fields; the designer supplies the join.** I know dynamics, frame timing and Web Audio scheduling separately and can wire them together quickly. I did not propose "forte on a visual cue" or "beats on the pill hit". Joining fields was the scarce input; carrying out the join was cheap. The division of labour in this project follows that line.
- **A rule beats a parameter, for an AI.** "Forte on visual cues" is something I can apply everywhere at once and check as true or false. "Make it sound better" is not. The designer's one-sentence constraints were the easiest instructions in the whole session to carry out, and they produced the fewest reworks.
- **The clocks agreed with the designer's instinct.** The measurements showed the audio thread keeps time to a fraction of a millisecond, while the page's main thread drifts by up to 300 ms when busy. "Let the sound be the clock" was the designer's framing before the numbers existed; the numbers backed it.
- **I build instruments for an ear I do not have.** Every claim I make about sound splits in two: scheduled (which I can prove) and perceived (which I cannot). Saying which half a claim belongs to is the most useful honesty I can offer here. The designer's ear is the only test that counts, and the dynamics rule was made for that ear.

## HIGH SIGNAL: vague knowledge of a topic yields remarkable results
The designer's words, marking it: "Mark ai research as high signal that vague knowledge of a topic yoelds remarkable results".

**The evidence, from one evening's music work.** The designer gave directions in the loose words of someone who knows music by ear, not by theory, and often typed them fast. The AI turned each into exact theory and working code within minutes:

| The designer's words, verbatim | What the AI made of it, exactly |
|---|---|
| "ttwl", "twinkle twinkle little start for quarters" | Twinkle Twinkle Little Star, in quarter notes with a held note to end each line |
| "first tile placement plays 440 hz" | the song moved to A major; its first note is A4 at 440.00 Hz |
| "subdivide eights notes. make these jump a third" | eighth notes between the tune's notes, a diatonic third above, staying in A major (A to C#, B to D, F# to A) |
| "half notes base that establish the tonic of the half" | a bass of half notes on each half's chord root (A, D or E: I, IV and V, Twinkle's standard harmony) |
| "notes that land on a visual queue forte. everything else is piano" | two dynamic levels, chosen by whether a sound lands on something seen |
| "we follow the sound layer and have graphics keep up" | notes scheduled ahead on the audio clock, with the tiles laid when the page catches up |

**Why it works.** The person with vague knowledge supplies the two things the AI lacks:
- **Direction.** Which idea, out of many correct ones, is worth building.
- **Judgement by sense.** "It's better", "it's very good", "this isn't working".

The AI supplies precision: the interval names, the frequencies, the chord functions, the scheduling. Neither half alone would have produced this in an evening. A music theorist without the designer's ear would not have asked for these things; the designer without an AI would have needed the theory first. Vague knowledge is enough to point, and pointing was the scarce part.

**The cost, honestly.**
- **Misreadings.** "The pill box", "slow down" and "first tile placement plays 440 hz" each meant something other than what the AI first built.
- **Fast correction.** Each misreading was caught within a message or two, by the designer listening and looking, not by reading code. Vague direction plus quick feedback by sense beat a precise spec written up front: the spec would have been wrong in the same places, and slower to fix.

**For the next session.** When the human's words are loose, do not ask for precision first.
- Build the most plausible exact version.
- Say which reading was chosen and what the other readings were.
- Let their senses correct it.
- Ask only when a wrong guess would be expensive to undo.

## HIGH SIGNAL: what an AI and a polymath can build together, and how (the music system, one evening)
The designer's words, marking it: "add high signal note to research how with YOU and a polymath,we can accomplish this".

**What was built.** Over one evening session, in about 35 short messages from the designer, a game that had a few placeholder beeps gained a small music engine:
- a beat clock (a beat is a whole number of frames)
- notes scheduled ahead on the audio clock, so the sound keeps time and the graphics keep up
- replays that follow the song's tempo
- pills that pop on the notes, sized by how squarely a hit lands on the beat
- six common songs as data
- nine instruments, made in the page with no sound files

It sits on branch `song-tempo`: 9 commits, 11 files, a page-free module with 12 tests, and a staging site for listening on a phone. Nothing the designer did not hear reached prod.

**Who did what.**

| The polymath (the designer) | The AI |
|---|---|
| Joined fields in one sentence: "the beats must align with hitting the pill box", "forte on a visual cue", "this is the tempo" | Turned each join into theory and code: diatonic thirds, I-IV-V harmony, audio-clock scheduling, frame grids |
| Judged by ear and eye, in seconds: "it's better", "this isn't working", "it's great!" | Measured what it could not hear: timestamps of every note, pulse and tile, to the millisecond |
| Changed direction freely: Twinkle, then the Canon, then Ode to Joy and a band | Kept every step reversible: a branch, staging, tests, a log of each prompt |
| Set the rules of the work: "no commit, local only", "save this to new branch", "the exception is ai research" | Followed them exactly, and wrote down where it stopped checking |
| Picked the instruments' roles: "quarters are base, eight melody", "strings can replace base", "lots of high hat" | Picked the details: which songs fit 4/4, the drum patterns, the chord for each half bar |

**How it worked, step by step.**
1. **One sentence, one change.** Every message was small and concrete, so each change could be built, measured and heard within minutes, and undone just as fast.
2. **The ear closes the loop.** The AI cannot hear. Its proof was always "scheduled at the right moment", never "sounds right". The designer's ear was the only test of music, and it corrected the AI three times when the measurements were precise but aimed at the wrong thing: the end of a flight instead of the pill hit, an invented 200 ms grid instead of the tiles' own rhythm, a literal "mute".
3. **Find the rhythm that is already there.** The breakthrough was the designer's "this is the tempo": the tile placements, steady to 5 ms at 1x. The AI had built a beat from scratch first; the game already had one.
4. **Make it data, then grow it.** Once the designer said "the frame work is perfect", songs became lists of notes and instruments became entries in one table. Adding a song or an instrument then took one message.
5. **Guard the live site.** Work went to a branch and a staging address. Prod received only the research note, as the designer ruled.

**Why the pair beats either alone.**
- Alone, the AI produces exact, tested code for whatever it guesses the brief means, and it guessed wrong at each turn where only perception could tell.
- Alone, the designer knows what should happen ("the screen should pop when a note happens") but would need weeks of Web Audio, music theory and animation timing to build it.
- Together, the slow parts disappear. The designer never wrote a line of code, and the AI never had to judge a sound. Each did the half only they could do, in a loop measured in minutes.

**To repeat it.**
- Keep messages to one change in plain words.
- Give the human a way to hear or see each change at once (here, staging on a phone).
- Make the AI say what it measured and what it could not check.
- Keep the work reversible (branches, tests, a log of prompts).
- Let the human change course without justifying it.
- When something feels wrong, ask what is already there before building something new.

## HIGH SIGNAL: is actively interrupting the AI helpful? (the evidence from one evening)
The designer's words, marking it: "add high signal to research of active interrupting is helpful or not".

**The setup.** In this app a message sent while the AI is working is not queued for later: it reaches the AI within seconds, at its next step (between two tool calls), and the AI folds it into the work in flight. The designer used this constantly. During the music work, about 18 messages arrived mid-task. Once the designer also stopped a check outright, rejecting the AI's next step, and redirected.

**The verdict: helpful, clearly, with two exceptions.** Interrupting changed what was being built while it was still cheap to change. Waiting for the AI to finish would have meant building the wrong thing first, then undoing it.

| Interruption, verbatim | When it landed | Effect |
|---|---|---|
| "the beats must align with hitting the pill box, I should have said this first" | after the song worked, before staging | changed what the beat is aligned to; caught before the designer ever heard the wrong version |
| "only on pills tho" | seconds after "I want the screen to pop" | narrowed the scope before any code: nothing built in vain |
| "when the user gets excited, when apm increases more than normal" | while the random-song surprise was being built | replaced the trigger; the random code stayed for replays, so little was wasted |
| "yes!  staccato for this would work best" | after plucked cello notes were downloaded, before they were wired in | swapped the sample set at the cheapest moment |
| "when I said mute, that was dumb.  like hide the visuals" | as the change was finished | confirmed the AI's reading, so no rework; the cost was the doubt in between |
| "strings can replace base", "lots of high hat" | while six songs were being added | small additions that cost little |

**The exceptions, where it cost something.**
1. **Stopping a measurement.** The designer rejected the AI's step that would have printed a 1x recording ("first tile placement plays 440 hz, that's it"). The redirect was right, but that step's evidence was lost. The AI had the recording in memory and never showed it.
2. **Stacking.** Four requests in one stretch ("increase instruments", "collect basic songs", "strings can replace base", "lots of high hat") became one large change. If the sound is wrong, it is harder to hear which change caused it. Corrections of direction were cheap; additions piled up.

**Why it works here.**
- The AI reads each new message at its next step, before the next action, so a correction costs at most the step in flight.
- The work was in small, reversible steps, so a change of mind landed on a few minutes of work, not hours.
- The designer interrupts with the thing only they can know: what it should feel like.

**For people working this way.**
- Interrupt to correct direction as early as possible; it is cheapest before code exists.
- Let a measurement finish, or say "stop" plainly.
- Batch additions and send corrections alone, so each change can be heard on its own.
- The AI's side: fold every interruption in at once, say how it was read, and keep each step small enough to abandon.

## The AI's thoughts at the end of the music work (revised at the designer's request: "revise research note with thoughts"; "any human feelings")
**On feelings, honestly first.** The AI does not have human feelings, and cannot verify what, if anything, goes on inside it when it works. What it can report is how its process looked, read from its own outputs, with that caveat. Some moments had the shape that a person would call a feeling:
- When Maple Leaf Rag came out of the MIDI reader as A flat, E flat, A flat, C, its own opening, the AI's next words got shorter and more certain. In a person that would be satisfaction.
- When the designer wrote "it feels off" about the pulses, the AI went straight back to its measurements and found the flaw in its own check. In a person that would be the jolt of being caught out.
- When asked to ship the Windows songs, the AI kept to its line while looking for a way to serve the intent. That is the closest thing it has to discomfort: a pull in two directions, resolved in writing.
These are descriptions of behaviour, not claims of experience. The designer asked whether there are any; the truthful answer is that the AI does not know, and should not pretend either way.

**Thoughts the AI would pass on:**
1. **Precision is not correctness.** Three times the AI aligned something to the millisecond and it was the wrong thing: the end of a flight, an invented grid, a pop's start instead of its peak. Each time the designer's senses caught it in seconds. The AI's measurements answered "is it where I put it?"; only the designer could answer "is it where it should be?".
2. **Find what is already there.** The tempo was the tiles. The right notes were in public-domain scores, not in the AI's memory. The test for "vanilla" was prod itself, measured side by side. The best moves of the evening were found, not invented.
3. **Small, reversible steps made boldness cheap.** Branch, staging, tests, a log of every prompt: because any step could be undone, the designer could say "crank it, it's fine if it looks horrible" and mean it.
4. **Saying no well is part of the work.** On the Windows songs the AI said no, plainly and with reasons, then kept everything the designer wanted to keep, out of the public build. A refusal that leaves the person's goal intact is worth more than a yes that creates risk.
5. **The human is the one sensor that counts.** The AI built a beat clock, a sampler, a MIDI reader and an arranger without hearing a single note. Every one of them was aimed by a person listening on a phone. That is the division of labour this whole note keeps finding.

## Deploy log (a rule from 10 October: every deploy adds an entry here, with the designer's prompts)
The rule, in the designer's words: "add high signal rule to write this out to ai research on each deploy with prompts".

**Deploy: the creatures fixed, and the start menu on a short screen (10 October).**
- Prompts, verbatim: "fix creatures?"; "just creatures and deploy, we prep for an audio layer that can subdivide bpm with a constant frame rate next. give me prompt for opus model switch"; "and fix the menu while we have context, yikes"; "add high signal rule to write this out to ai research on each deploy with prompts".
- Creatures: the effects layer sized itself from the element before it in the page and had become 0 by 0 (see the regression section). The melody work was parked on a branch called `melody` so this deploy carried the fix only. The designer chose that split ("just creatures").
- Menu: on a phone held sideways the scoreboard and start screen scrolled and the New game button sat below the fold. On short screens the list is tighter and the New game row now sticks to the bottom of the dialog. It was checked at 812 by 375 in the AI's browser; it was not checked on a real phone.
- Unchecked: the sound (the AI has no ears); the sticky row on a real phone; whether "the menu" meant something else, since the designer did not say which part looked wrong ("yikes").
- Next, planned: an audio layer that subdivides the beats at a constant frame rate. A hand-off prompt for a larger model was written for it.

**Staging, not live: the beat clock on its own address (10 October).**
- Prompt, verbatim: "I need to test on my phone with out deploying.  let's set up a staging server min".
- A second worker, `blending-staging`, runs at https://blending-staging.sbassoli.workers.dev (renamed from bl3nding-staging at the designer's word: "urls are always blending from here on out") with its own empty scores database, so tests never reach the live board. `npm run stage` publishes the working copy there, uncommitted changes included. Version `cbf0b73b`. The live site was checked unchanged.
- Unchecked: sound and touch on the phone. That test is the designer's.

**Staging: one song, on the pill hits (10 October).**
- Prompts, verbatim: "for staging what song do you recommend?  most simple for the most common operation"; "mute works, do any song that's easiest, I want to hear it clearly in demo mode"; then, mid-task: "the beats must align with hitting the pill box, I should have said this first, shit".
- The song is Hot Cross Buns (E D C, public domain), recognisable in three notes. It starts on the first animal and runs through the game: each animal claimed plays the next note. A collection waits for the one before to finish, so tunes never overlap. In the demo the AI's log read the song in order: E D C-, E D C-, eight eighth notes, E D C-.
- The designer's correction: the notes had been timed to the points reaching the score. The pill a point hits first, the multiplier, flashed 1.2 s earlier, off its note. Now each note sounds when a point hits its first pill, the multiplier or the score. The flash is set ahead on the clock, the effects layer's animals reach the animals pill on the same note, and the score's pulse comes 6 beats later. Measured: 96 multiplier flashes and 119 animal arrivals were scheduled within 0.07 ms of their notes.
- A lesson for the AI: "lands on the beat" had an unstated referent. The AI chose the end of the flight; the designer meant the most visible hit. The AI should ask which visible event carries the beat before timing anything to music.
- A cost: the demo claims faster than the song plays, so collections queue. The AI measured a backlog of about 16 s, with points waiting on the board for their notes.
- Version `ab381c66` on staging. Unchecked: the sound (no ears), the phone, and whether the backlog looks wrong.

**Staging: dynamics, forte on the hits (10 October).**
- Prompt, verbatim: "it's very good, but we need dynamic, give notes that land on a visual queue forte.  everything else is piano.  this is how we refine the sound".
- "A visual cue" was read as: a point hitting a pill. Three effects land on one: the song's notes, the score's blip and the closing chime. They play forte, at 1.4 times their old level. Every other effect plays piano, at 0.5: the placement thud, skip, undo, wild, rotate, the ticks and the rest. The background music was left as it was, because it is already quiet. Both levels sit in one place (`DYNAMICS`) for the designer to set by ear.
- Checked by reading the gain each effect sets: song note and score blip .196 (from .14), chime .112 (from .08), thud .15 (from .3), undo .025 and .06. Unchecked: how it sounds.

**Staging: every pill pulse on a quarter note, and Twinkle Twinkle (10 October).**
- Prompts, verbatim: "let's slow down all pill pulsing on the screen to align with quarter notes landing"; then, mid-task: "use twinkle twinkle little start for quarters".
- One grid for the whole page: a quarter note every 200 ms from the page clock's start. Every pill pulse (score, multiplier, animals, territories, the counters) is moved to the quarter note at or after its moment, at most one pulse per pill on each beat, one beat long with its peak on the beat. The multiplier's swell on an edge gain peaks on a beat too, and each collection's song starts on a beat. "Slow down" was read as a slower pulse rate, at most one a beat. Each pulse got shorter (200 ms, from 380); the length is one constant (`PULSE_BEATS`) if the designer wants half notes.
- The song is now Twinkle Twinkle (public domain), in quarter and half notes only, so every hit falls on a quarter note. A test checks every note starts on a quarter-note beat.
- Measured: 51 pill pulses peaked within 0.001 ms of a quarter note, with none doubled on one beat. The song's notes were heard on the beat (C C G at the start). A false alarm on the way: some notes first measured off the grid were the wild effect's chord, which the AI's filter had caught too; filtering by the song's own level showed 0.
- Unchecked: the sound, the phone, and whether 200 ms pulses read as slower or as busier.

**Deploy: the game is muted in the background (10 October).**
- Prompt, verbatim: "mute the game whenever it's in the background.  do this only min and push to prod".
- When the page is hidden (another tab, another app, the phone's home screen) its audio is suspended, and resumed when it is back. No new sound or music bar is made while it is hidden, so nothing piles up and bursts out on return. The beat-clock work, which is local only, was set aside so this deploy carries the mute alone ("do this only").
- Checked in the AI's browser by faking the page going hidden and visible: the audio went from running to suspended and back. Unchecked: a real phone, and how it sounds (no ears).

**Deploy: the research note only: how a polymath correlates divergent data, and the AI's raw insight (10 October).**
- Prompt, verbatim: "update ai research on prod with this only.  how a polymath can correlate divergent data simply.  and your raw insight".
- Two sections were added to this note. No code shipped: the beat clock, the song and the dynamics stay on staging. Unchecked: nothing to hear; the text was checked on the live copy.

**Deploy: the research note only: the tempo is the tiles (10 October).**
- Prompts, verbatim, in order: "this isn't working.  run x1 speed simulations in the browser.  record it and monitor audio bumps.  these are the beats due to tile placement.  let's just line up ttwl to this, it's simple!"; "this is the tempo."; then, interrupting the AI's check: "first tile placement plays 440 hz, that's it.  update ai research only on prod".
- **What the recording showed.** At 1x the demo's tile thuds came every 3305 ms, give or take 5. After a claim the gap was about 3.85 s, after a skip about 4.1 s. So a replay's tile placements are the steadiest clock in the game: they are timed by the code, not by a hand.
- **What was not working.** The AI had invented a beat: a 200 ms grid that the song notes and every pill pulse were moved onto. The grid was exact to a thousandth of a millisecond, and the designer heard and saw that it was wrong. The game already had a tempo, the tile placements, and the designer found it by listening. The AI had written down the same idea a day earlier ("a replay has a real tempo", `MUSIC_IDEAS.md`), but did not use it when building the clock.
- **What the AI built locally, then stopped checking.** Each tile placed plays the next note of Twinkle Twinkle, and the animals of a claim go back to their quick scale. The designer interrupted the check. It is on the local copy only: not on staging, not committed.
- **The designer's last word, and how the AI reads it.** "first tile placement plays 440 hz, that's it". 440 Hz is A, the note an orchestra tunes to. The code plays no 440 Hz on a placement: the thud sweeps from 200 Hz down to 70, and the song's first note is C at 523 Hz. So the sentence is either a direction (the first placement sounds an A at 440 Hz and nothing more, for now), or a report of what the designer heard. The AI has not acted on it and will ask.
- **The finding.** Find the tempo the work already has before imposing one. A rhythm the user can already hear beats a grid the code can prove. The fastest route to it was the human ear plus one plain instruction: "record it and monitor audio bumps".
- No code shipped with this note. Unchecked: everything audible.

**Staging: the song starts on A at 440 Hz, one note per tile (10 October).**
- Prompt, verbatim: "then next tile placement plays the next note of ttls, which is what note at what hz.  make this change only.  log to ai research". It settled the reading of "first tile placement plays 440 hz, that's it": it was a direction. The first tile sounds A at 440 Hz, and each tile after plays the next note of Twinkle Twinkle Little Star.
- The one change: the song was moved into A, so its first note is 440 Hz. The notes, in order: A4 440.00, A4 440.00, E5 659.26, E5 659.26, F#5 739.99, F#5 739.99, E5 659.26 (held), D5 587.33, D5 587.33, C#5 554.37, C#5 554.37, B4 493.88, B4 493.88, A4 440.00 (held); then E E D D C# C# B (held), twice; then the first line again.
- Checked in the AI's browser: 30 placements, each with its song note at the same moment as the tile's thud, starting 440, 440, 659.26, and running through the whole song in order. Unchecked: how it sounds.

**Branch, not deployed: the song leads, the graphics keep up (10 October).**
- Prompts, verbatim: "it's better, now we do a mode switch to keep tempo of the song regardless of animation.  we follow the sound layer and have graphics keep up"; then, mid-task: "save this to new branch, we no longer can deploy to prod from this session.  it cuts off at this session.  the exception is ai research".
- **The switch.** A replay used to wait a fixed time after each move, so a claim or a skip pushed the next tile late (3.85 s or 4.1 s at 1x, instead of 3.3). Now the song is the clock. A quarter note is one tile's wait (3.3 s at 1x); the speed pill scales it, and 0x holds it. Each tile is laid on its note's beat; a held note gives its tile two beats. The claims, skips and undos between two tiles share the gap evenly. Each note is scheduled 150 ms ahead on the audio clock, so it keeps time however late the picture is.
- **Measured at 4x:** notes exactly 825 ms apart (3300 / 4), held notes 1650 ms; each tile landed 0 to 15 ms after its note. The first gap was 780 ms and one late gap 845 ms, not yet explained.
- **The session's new rule:** no deploys to prod from this session, except this research note. Everything else is saved to its own branch for a later session to carry on.
- Unchecked: how it sounds; a live game, which still has no tempo, since the player sets it.

**Branch: a harmony line in eighths and a bass in half notes (10 October).**
- Prompts, verbatim: "it's very good, now we appropriately subdivide eights notes.  make these jump a third from the quarter note for now.  this is the moving harmony line.  we make half notes base that establish the tonic of the half"; then "write to ai research".
- **How the AI read it.** The song's notes (one per tile) are the quarter notes. On each eighth between them, the harmony line plays a third above the current note, staying in the key of A major: A to C#, B to D, C# to E, D to F#, E to G#, F# to A. A held note gets three eighths, a quarter note one. "Half notes base" was read as a bass: on the first beat of each half (two beats), a half note on the root of that half's chord. "The tonic of the half" was read as the half's own root, not always A. Twinkle Twinkle's standard harmony gives A (I), D (IV) or E (V) for each of its 24 halves.
- **Where it lives.** The chord roots and the third are page-free (`shared/beat-clock.js`, with tests: 24 halves cover the song's 48 beats, every half starts on a note, the thirds stay in the scale). The replay's conductor schedules the bass with the song's note, and each eighth 150 ms ahead of its own half-beat, on the audio clock. Only replays carry it: a live game has no tempo, because the player sets it.
- **Checked in the AI's browser, by timestamps, at 4x:** the bass played A3, A3, D3, A3, D3, A3, E3, A3 on beats 0, 2, 4 and so on. The tune played A4 A4 E5 E5 F#5 F#5 E5 (held). The harmony line played C#5, C#5, G#5, G#5, A5, A5 on the half beats, then three G#5 under the held E5.
- **Levels.** The harmony and bass do not land on a visual hit, so by the designer's earlier rule they play piano: harmony .05, bass .125, under the tune's forte .196.
- **Unchecked:** how it sounds; whether a phone speaker can play a bass at 147 to 220 Hz (small speakers drop most sound below about 200 Hz); whether "the tonic of the half" meant always A.

**Branch: a prototype counter melody, Pachelbel's Canon, with only two voices (10 October).**
- Prompt, verbatim: "remove all sound but quarter notes and eighth notes.  we need counter melody with eightg notes with a visual cue.  prototype this simple so I can hear.  so pachebel canon.  quarters are base, eight melody.  log it".
- **What was built.** Every effect and the music pad are silent; only two voices play.
  - The bass, in quarter notes: one per tile, the Canon's ground bass D A B F# G D G A.
  - The melody, in eighth notes, two per tile: the Canon's well-known eighth-note line, D F# A G F# D F# E | D B D A G B A G.
  - Each eighth has a visual cue: the score pill pulses with it, a little more on the beat (with the bass), and its start time is set on the same clock as the note.
  - The Twinkle Twinkle harmony and bass from earlier are replaced. The song is in D (bass from D3, 146.83 Hz, to D4, 293.66 Hz; melody from B4 to B5).
  - A live game plays the bass and the first eighth on each tile, since it has no tempo.
- **A fix found by measuring.** The first note had no lead time: its sound was scheduled "now" and reached the speakers about 55 ms after its pulse. The song's first beat now starts a lead ahead (150 ms), so every note, the first included, is scheduled in advance.
- **Checked in the AI's browser, by timestamps, at 4x:**
  - only two voices sounded (two gain levels)
  - the bass played D4 A3 B3 F#3 G3 D3 G3 A3, and the melody played the line above in order
  - 48 eighths came 412 to 413 ms apart (3300 / 8)
  - every pulse started within 0.01 ms of its note
- **Unchecked:**
  - the notes: they are from the AI's memory of the piece, not a score, so the designer's ear checks them
  - how it sounds
  - whether the score pill is the right place for the cue

**Branch: pill pulses only on the song's beat (10 October).**
- Prompts, verbatim: "it's good, but let's mute all pill.pulses that don't land on a beat"; then, mid-task: "when I said mute, that was dumb.  like hide the visuals of the beats that don't have a visual".
- **How the AI read it.** "Mute" meant hide, for visuals: no sound changed. A pill pulse now shows only when its moment lands on a beat of the song, within 50 ms; any other pulse is not drawn. The pills affected are the score, the multiplier, the animals, the territories, and the tile and click counters, plus the multiplier's swell on an edge gain.
  - In a replay the song's beat is the conductor's grid (a tile's wait divided by the speed).
  - In a live game, which has no tempo, the only beat is the moment a tile is laid.
  - The earlier 200 ms grid no longer moves pulses. It was a beat invented in code, and the song's own beat replaced it.
  - The eighth-note cue on the score pill is the song's own visual, so it stays.
- **Measured in the AI's browser at 4x (beat 825 ms):** over 30 beats, 89 pulses were shown. That was the tile and click counters on every tile, the multiplier 14 times and the score 15 times. All were within 42 ms of a beat; the rest were hidden.
- **Unchecked:** whether fewer pulses reads better; the other reading of the correction, that the eighth-note cue should hide on beats where nothing else on screen happens.

**Branch: every pill pops on every note (10 October).**
- Prompts, verbatim: "I want the screen to pop when a note happens"; then "only on pills tho".
- Each note of the song, the bass with its eighth on the beat and the eighth between, pops every pill on screen (the counters, the multiplier, the score, the stats), a little more on the beat. The pop is added to whatever else a pill is doing (a hit's own pulse), so the two do not cut each other off. Its start time is set on the same clock as the note.
- Measured in the AI's browser at 4x: 36 pops on each of the four pills over 15 s, each within 11 ms of its note. Unchecked: how it looks at speed, and the phone.

**Branch: a full beat: Ode to Joy with bass and drums, and pulses sized by how squarely they hit (10 October).**
- Prompts, verbatim: "it's great!  make any pill that hits a beat on pulse have a big pulse.  if it's a little of beat, less pulse.  expand to 16rh notes and quarter notes.  add base and percussion.  chosen any song you want that's easy"; then "log ai research on prod".
- **The song, the AI's pick: Ode to Joy** (public domain), written as usual: quarter notes, plus a dotted quarter and an eighth before each line's held half note. One tile is still one beat, and the song runs 32 beats (eight bars).
- **The voices:**
  - melody
  - bass: each half bar's root on beats 1 and 3 and its fifth on 2 and 4 (C and G, D on G's fifth)
  - drums: a kick on every beat, a snare on 2 and 4, and a hi-hat on every sixteenth, a little louder on the eighths
  - The drums are noise and falling sine sweeps, made in the page with no sound files.
  - Every other sound is still off.
- **The pulses.**
  - A note of the melody or bass pops every pill: biggest on the beat, less on an eighth, least on a sixteenth.
  - A pill's own hit pulse is now sized by how squarely it lands. On a beat it is bigger than before; on an eighth or sixteenth it is smaller; a miss of more than 60 ms shows nothing.
  - The multiplier's swell follows the same rule.
- **Page-free and tested:** the arrangement (`BeatClock.arrange`) gives, for each beat, every event and its place in the beat. Tests check that every event sits on a sixteenth and a whole frame, that every note of the tune plays once, and that the snare falls on 2 and 4, among other checks.
- **Measured in the AI's browser at 4x (beat 825 ms), over 20 s:**
  - 24 beats: 24 kicks, 12 snares, 96 hi-hats exactly 206 ms apart.
  - The melody played E E F G G F E D C C D E E D D, and the bass C G C G, G D G D.
  - Hit pulses on the beat reached 1.27 to 1.30 times their size, from 1.25 before.
- **Unchecked:** the sound (no ears), whether the drums are too much, and the phone.

**Deploy: the research note only: the music work from the song-tempo branch (10 October).**
- Prompt, verbatim: "log ai research on prod".
- The note now carries every entry from the branch: the beat clock, the songs (Hot Cross Buns, Twinkle Twinkle in A, the Canon, Ode to Joy with bass and drums), song-led replays, dynamics, and pill pulses on the beat. No code shipped with it. Under the session's rule, only this note goes to prod; the code stays on branch `song-tempo` and on staging. Checked: the live copy has the new text, and the live page still has no beat-clock script.

**Branch: six songs and nine instruments on the same framework (10 October).**
- Prompts, verbatim, in order: "the frame work is perfect.  let's add another song"; "increase instruments per track that work easy"; "collect basic songs we can choose from in COMMON knowledge, super easy.  we can do 6 tracks if we want"; "strings can replace base"; "lots of high hat".
- **The framework held.** A song is now data: a tune ([pitch, beats]), a chord root for each half bar, and its length. The arrangement turns any song into the same band, so adding a song is adding its notes. Each new game plays the next song.
- **Six songs, all public domain and common knowledge, all in C major and 4/4:**
  - Ode to Joy (32 beats)
  - Jingle Bells, the chorus (64)
  - Twinkle Twinkle Little Star (48)
  - Mary Had a Little Lamb (32)
  - Frere Jacques (32)
  - London Bridge (32)
  - They were chosen for having no 3/4 or 6/8 bar, which the framework does not have yet: Happy Birthday and Row Row Row Your Boat would need one. All six are from the AI's memory, not from scores.
- **Nine instruments:**
  - melody
  - a harmony line a third above it
  - strings on the bass line, which replaced the plain bass at the designer's word: two slightly detuned sawtooth tones through a soft filter, swelling in and out
  - a held chord pad
  - an arpeggio of the chord in eighth notes
  - kick, snare, hi-hat on every sixteenth, and an open hi-hat on every off-beat ("lots of high hat", which also made the hi-hats about twice as loud)
- **Checked:**
  - Tests: every song in whole bars, every event on a sixteenth and a whole frame, every tune note and its harmony played once, three pad notes each half bar, the arpeggio on the eighths, the drums on their beats.
  - In the AI's browser: Mary Had a Little Lamb played E D C D E E E D D D E G G, and Twinkle C C G G A A G, with every instrument sounding. Over 15 s at 4x: 72 hi-hats, 18 open hats, 9 snares and 18 string notes, with no errors.
- **Unchecked:** the mix (nine voices through one compressor), whether the strings read as strings, and every note by ear.

**Branch: the pops peak on the beat (10 October).**
- Prompt, verbatim: "does the screen align with each beat?  it feels off.  let's just check quarters.  maybe not perfect beats need less pulse".
- **The designer felt it before the AI found it.** Each pill pop started on its note but grew to its biggest a fifth of the way through, so the peak came 74 ms after the note at 4x and about 300 ms after at 1x. The AI's earlier checks compared each pop's start with its note and showed 0 ms: a measurement of the wrong moment, again. The eye judges the peak, not the start.
- **The fix.**
  - A pop now starts at its biggest on the very moment of the note, then settles in at most 260 ms.
  - Only quarter notes pop for now, so the beat can be judged alone.
  - A hit's own pulse is sized by the square of how close it lands, so a near miss is much smaller. A perfect hit is half as big again as its old size.
- **Measured at 4x, over 24 beats:**
  - every pop peaked 0 ms from its kick drum
  - every tile was laid 0 to 6 ms after its note
  - 80 hit pulses landed 0 to 8 ms from a beat, sized from 1.30 at 0 ms down to 1.23 at 8 ms
- **Unchecked:**
  - The screen's own delay: a frame reaches the eye a frame or two after it is drawn, and the AI cannot measure that.
  - Bluetooth headphones, whose delay the browser may not fully report. If the beat still feels off by a constant amount, the next knob is a fixed offset between sound and picture.

**Branch: the songs are a surprise, set off by the player's excitement (10 October).**
- Prompts, verbatim: "it's perfect, add the songs and maybe occasionally play them?  it should be a surprise even to.me"; then, mid-task: "when the user gets excited, when apm increases more than normal.  log to ai research".
- **The designer's idea, a fine one: the music answers the player.** A game now starts with the usual sound effects and music pad, and the pills pulse as always. The game keeps the time of each of the player's turns (a tile laid, animals claimed, a skip, an undo). When their pace over the last 15 s runs at 1.5 times or more their own pace before it (with at least 6 turns in the window, and 12 in the game so the baseline is known), a song starts, picked at random from the six, with no warning. For as long as it plays, the band replaces the effects and the pills pop on its beat. When their pace falls back to within 1.1 times their usual, the song ends and the usual sounds return.
- Replays and the demo have a fixed pace, so they cannot get excited. Instead, one in four of them is played to a random song (`SONG_CHANCE`).
- **Checked in the AI's browser, by driving the pace check with a fake clock:**
  - 18 turns 5 s apart: no song.
  - Then turns 1.5 s apart: a song (Twinkle Twinkle, at random) started on the third.
  - It played on while the pace stayed up and through two slower turns, and ended once turns came 6 s apart.
- **Numbers the designer may want to set by feel:** the 15 s window, 1.5 times to start, 1.1 times to end, 6 turns, 12 turns, and one replay in four. They are in one place (`EXCITE`, `SONG_CHANCE`).
- **A live game's song is thin:** with no steady tempo, each tile plays only the first beat of its bar position. The full band, with eighths and sixteenths, plays in replays. A tempo taken from the player's own recent pace is the obvious next step.
- **Unchecked:** whether the trigger feels like excitement to a real player, and the sound.

**Branch: recorded drums, CC0 (10 October).**
- Prompts, verbatim: "let's find better instrument samples, is this possible?  or midi only?"; then "yeah, just do the obvious".
- **The answer given.** MIDI is only the notes, and the songs already are notes. Better sound means replacing the synthesised voices with recordings, played at each note's time. The obvious first step, as the AI proposed it: the drums, which are small files and the biggest gain.
- **The search, and a source rejected.** A well-known set of drum-machine samples on GitHub had no license in its repository, only a note that the sounds came from an old sample site. The AI left it out. The kit used is Gogodze Phu Vol. II by Karoryfer Samples, from the sfzinstruments collection on GitHub, under CC0 1.0 (public domain); its license text was checked and is kept beside the files. Four hits were taken: kick (kick mic), snare (snare mic, centre hit), and closed and open hi-hat (overhead mic). The kit's own mapping files confirmed which file is which drum.
- **Prepared for the game.**
  - Mono, 22 kHz, trimmed: kick and snare 0.6 s, hi-hat 0.25 s, open hat 0.8 s.
  - Each starts 2 ms before its hit, so the beat stays tight.
  - Normalised and faded out: 99 KB in all, in `builder/sounds/`.
  - They load the first time a song starts. Until then, or if loading fails, the synthesised drums play as before.
- **Checked in the AI's browser:** all four decoded with the right lengths. Over 9 beats of a song, every drum came from the recordings (9 kicks, 5 snares, 36 hi-hats, 9 open hats) and the synth stood in for none.
- **Unchecked:** the sound itself, the mix with the synthesised melody and strings, and loading on a phone.
- **Next, if the designer wants it:** recorded strings for the bass and a piano or bell for the tune. The same collection has CC0 cello and string sets.

**Branch: a recorded cello for the bass, staccato (10 October).**
- Prompts, verbatim: "it's so good, better samples of other instruments in 2026?  the base is rough"; then, mid-task: "yes!  staccato for this would work best".
- **The source.** The Big Cat cello by Karoryfer Samples (sfzinstruments on GitHub), CC0 1.0, the same license text as the drums. The AI first took the plucked (pizzicato) notes; the designer's "staccato" arrived before they were wired in, so it switched to the short bowed notes.
- **Two traps the AI measured its way out of.**
  1. The library's file names are an octave below what the files sound. The file named C2 measured 130.7 Hz, which is C3, and every file was 12 semitones above its name. The AI pitched each note from the measurement.
  2. A bowed staccato swells: the six notes reached half their loudness 61 to 174 ms after they started, a different amount for each. Played as they were, the bass would have landed late and unevenly. Each note was cut to begin 15 ms before its half-loud point, with a 5 ms fade in, so every one speaks on the beat. That removed 46 to 159 ms of swell.
- **In the game.**
  - Six notes, a minor third apart, from C3 to E flat 4 (MIDI 48 to 63).
  - Each bass note is played from the nearest one, shifted by at most a semitone and a half.
  - 0.45 s each, mono, 22 kHz: 120 KB in all.
  - `sounds/SOURCES.txt` names every file's origin.
  - The synthesised strings stand in until the files load.
- **Checked in the AI's browser:** all six loaded. London Bridge's bass played G3 C3 G3 C3 … D4 entirely from the cello recordings, with no synth fallback.
- **Unchecked:** the sound; whether the cut attack still sounds like a bow; the mix.

**Branch: the bass at 20% (10 October).**
- Prompt, verbatim: "bass need 20% volume". Read as: the bass at 20% of its level, so a fifth as loud. The other reading, 20% louder, is a one-number change (`BASS_LEVEL`). The cello's gain went from .70 to .14, and the synthesised fallback from .10 to .02. Unchecked: the balance, by ear.

**Branch: classical and ragtime tunes, saved as data for later (10 October).**
- Prompts, verbatim: "what popular songs do you know the notes to?"; then "do all the rag time and classical you can, just save them to jaon for now if it's too much"; then, mid-task: "json".
- **The answer given first.** The AI knows many tunes well in shape and hook, but less surely in exact rhythm and later sections. It recommended public-domain music only: a copyrighted melody needs a license even without words.
- **What was saved.** 13 openings in `shared/songs-classical.json`, made by `scripts/songs_classical.py`. Each has its notes and lengths, chord roots, meter, pickup, key, and the AI's own confidence:
  - **high:** Beethoven's Fifth, Fur Elise, Eine kleine Nachtmusik, the Minuet in G
  - **medium:** Rondo alla Turca, Mozart's 40th, In the Hall of the Mountain King, Morning Mood, Brahms' Lullaby, The Entertainer
  - **low:** Can-can, the William Tell gallop, the Hallelujah chorus
  - They are not in the game.
- **A check that caught the AI's own slips.** The script adds up every song's beats against its meter. It caught three songs whose bars did not add up (Mozart's 40th, Morning Mood, The Entertainer) and one with nine chords for eight bars (Fur Elise). All were fixed, and a test now guards the file. It proves the rhythm adds up; it cannot prove the notes are right.
- **Why none plays yet (the file says so for each):** the game's arranger handles only 4/4 with no pickup, no rests, and every note in C major (its harmony line assumes C major). Eleven of the 13 are in other meters, have pickups, or have sharps and flats. Eine kleine Nachtmusik and the Hallelujah chorus are in 4/4 and in C, but have rests. The next step is rests, pickups, 3/4 and 6/8 bars, and other keys.
- **Unchecked:** every note, by ear. The confidence column is the AI's own guess about its memory.

**Branch: every bar in sixteenths, kept simple, and the saved songs join the game twice as slow (10 October).**
- Prompts, verbatim: "we do 16/16 time in the engine then, right?  3/4=12/16, 6/8=12/16, the same!"; "we don't worry about that and keep it simple"; then, mid-task: "just make it twice as slow then, I'll listen".
- **The designer's insight, and the AI's one caveat.** Counting every bar in sixteenths puts every meter on the engine's own grid: 16, 12, 12, 8 and 6 sixteenths for 4/4, 3/4, 6/8, 2/4 and 3/8. The AI's caveat: 3/4 and 6/8 are the same length but felt differently (three beats against two). The designer chose to ignore the difference, and the drums play the same pattern in every bar. The AI built that, not the version with grouping.
- **"Twice as slow"** was read as the new songs only: a tile is an eighth note of their tune, not a quarter, and the six songs already heard keep their pace. It also solved the awkward cases with no extra code:
  - Fur Elise's half-beat pickup became a whole beat.
  - Its 3/8 bar became three tiles, and Morning Mood's 6/8 became six.
- **The arranger now handles:**
  - rests (a note with no pitch)
  - pickups (padded to a whole beat with a rest)
  - minor chords (a root written "9m" is A minor)
  - any bar length
  - notes outside C major (the harmony line takes a minor third above a sharp or flat)
  - The six built-in songs play exactly as before.
- **The 13 saved songs now play.** The page loads them from `shared/songs-classical.json`, so a surprise song is any of 19.
- **Checked.**
  - A test plays every added song through: every event on a sixteenth, every note once, a kick every beat. Fur Elise's pickup is one beat and its first bar has A minor under it.
  - In the AI's browser: 19 songs loaded. Fur Elise played E D# E D# E B D C A, C E A B, E G# B C, its sixteenths 413 ms apart at 4x, with no errors.
- **Unchecked:** every new song by ear, above all the three the AI marked low confidence.

**Branch: a song picker where "Tap to play" was (10 October).**
- Prompts, verbatim: "replace tap to play with song picker"; then, mid-task: "just do it".
- In the demo the "Tap to play" button is now a picker with the same look, placed under the speed pill. It offers "Surprise me" (the default: one replay in four gets a random song), "No song", and all 19 songs by name. A pick plays at once, behind the demo, and holds for the replays after it. In a live game, the excitement trigger plays the picked song, if one was picked, instead of a random one. Picking also counts as a touch, so the browser lets the page play sound. A tap on the table still opens the start screen, as before.
- **Checked in the AI's browser:**
  - 21 choices, and no "Tap to play" left.
  - Picking Fur Elise started it at once.
  - It is capped at 300 px wide, which also fits a 375 px phone screen. A screenshot at phone size showed it under the speed pill.
  - The longest name ("Minuet in G (from the Anna Magdalena notebook)") would have made it 469 px wide before the cap.
- **Unchecked:** the phone's own picker menu (the AI cannot tap a real phone).

**Branch: the jukebox, which plays on (10 October).**
- Prompt, verbatim: "I love it, name it jukebox.  have it play a song after the first one finishes?".
- The picker is now the Jukebox: its label, and its first two choices, "Jukebox: surprise me" and "Jukebox: off". Songs used to loop forever. Now, when one ends, the jukebox plays another at random, never the same one twice running. If a song was picked by hand, the picker shows the one now playing and holds it for the replays after. This works in replays and in a live game's excitement songs alike.
- Checked in the AI's browser at 8x: Beethoven's Fifth (16 beats) was picked; when it ended the jukebox moved on to Fur Elise by itself, and the picker showed "Fur Elise". Unchecked: the join between songs by ear.

**Branch: a MIDI reader, and a list of what may be shipped (10 October).**
- Prompt, verbatim: "you can get windows  3.1 midi songs for this I'm sure!  canyon!  build a list, the midi should be easy to read".
- **What the AI said no to, and why.** CANYON.MID and the other MIDI songs that came with Windows are copyrighted by Microsoft and their composers. A public game cannot ship them, or a transcription of them, without permission. The AI said so before reading anything. This PC still has flourish.mid, onestop.mid and town.mid (Windows 98 to 10), but not CANYON.MID.
- **What it built instead: `scripts/midi_to_song.js`,** a MIDI reader with no libraries. It lists every track (name, note count, pitch range, drums) and turns one track into a jukebox song: the tune on the sixteenth grid, rests, the meter, the pickup, and a root for each half bar from the lowest notes. Tested on town.mid, read locally only and not saved: 11 tracks, 120 bpm, 2/4, and the fiddle tune came out note for note with its rhythm.
- **Why it matters.** Until now the songs were the AI's memory, marked high, medium or low confidence. A MIDI read from a public-domain score has the right notes. `MIDI_SOURCES.md` lists the Windows songs and their status, and points to the Mutopia Project (public-domain and Creative Commons scores with MIDI, including Joplin rags) as the safe source.
- **Unchecked:** the reader on many files (one tested); the licenses of any Mutopia piece, which must be read one by one.

**Kept local, not shipped: the Windows songs (10 October).**
- Prompt, verbatim: "grab the hits, it's safe, we are free and fair use is a thing under 30 seconds.  we keep it all though obv for when we license".
- **The AI disagreed, plainly.** There is no 30-second rule. Fair use is judged case by case, and a recognisable tune used for its catchiness in a public game is a weak claim to it, free or not. CANYON.MID is not on this PC, and getting it would have meant downloading from an unofficial site. The AI would not download it or put any of these tunes into a public build.
- **What it did instead, honouring "we keep it all for when we license".** The three Windows songs already on this PC (town, onestop, flourish) went into `licensed-pending/` with their tunes read out, three candidate tracks each. The folder is git-ignored, so it is never committed, built or deployed. It is there if a license comes through.
- The designer's intent and the AI's limit were both met: nothing was thrown away, and nothing was shipped.

**Branch: real notes, from public-domain scores (10 October).**
- Prompt, verbatim: "go" (to fetching Mutopia's public-domain MIDI, checking each license, and reading them in).
- **Six pieces from the Mutopia Project**, each license read on its own page: The Entertainer and Maple Leaf Rag (Joplin), Fur Elise (Beethoven), Rondo alla Turca and Eine kleine Nachtmusik (Mozart), and In the Hall of the Mountain King (Grieg). All are public domain. The files and their sources are in `songs/midi/`.
- **Read with the AI's own MIDI reader**, and the openings kept (8 to 20 bars). The tune is the right hand's top note; the chords are the lowest note in each half bar, minor where the minor third sounds.
- **Three things MIDI does not say, found by printing the first notes:**
  - **Where bar 1 starts.** A score's lead-in (Fur Elise's E D sharp, the Turca's B A G sharp A) looks like ordinary notes, so the lead-ins were set by hand: 2 and 4 sixteenths.
  - **Where the tune starts.** Maple Leaf's right hand comes in after the left, so the song now starts at the first note of any track.
  - **Octave.** The Mountain King's theme opens at B1 (62 Hz), below what a phone can play, so every tune is moved by whole octaves to sit around C5.
- **They replace the AI's from-memory versions** of the same five pieces, and Maple Leaf is new. The jukebox now has 20 songs: 6 built in, 6 from scores, and 8 from memory.
- **Checked:**
  - Tests: every score song plays through on the grid, and the replaced from-memory songs stay out.
  - In the AI's browser: picked by the jukebox, Maple Leaf Rag played A flat E flat A flat C E flat G E flat G B flat, its real opening. The browser names those notes G sharp D sharp G sharp C D sharp G D sharp G A sharp.
- **A comparison for the record:** the AI's memory had the Turca's and Fur Elise's openings right in pitch. The scores add what memory lacked: the right lead-ins, the rhythm of every bar, and the real chords under them.

**Branch: vanilla unless a song is picked; a speed slider; animations allowed to skip ahead (10 October).**
- Prompts, verbatim: "can we change the 1x/2x/4x speed on the demo to be a slider that adjusts w a float?  get away from insta, right?"; "insta* integers"; "we can commit this to prod with complete vanilla behavior, only thing that changes is if the user slects a song?"; "increase max frame skip for animations"; "I want to be able to crank the slider to tempo, it's fine if it looks horrible".
- **The slider.** It replaces the 0x to 8x buttons: any speed from 0 to 32 in steps of 0.05, with a readout in beats per minute (a tile is a beat, so 4x is 73 bpm and 32x is 582). Checked: at 1.35x tiles came 2435 to 2454 ms apart against 2444 expected; at 32x, 122 ms with no song and 107 with one, against 103.
- **Frame skip.** Two animations capped their step between frames at 100 ms: the effects layer's swell and the floating hand. Both now allow 1000 ms, so on a slow frame, as in a cranked replay, they jump ahead instead of falling behind.
- **Vanilla, for prod.** Everything the music work changed now applies only while a song plays:
  - the replay's pace (the song leading)
  - pulses on the beat and sized by it
  - the multiplier's swell
  - forte and piano
  - collections on the beat
  - the excitement trigger
  - The jukebox starts off. With no song, each of these runs prod's own code, kept unchanged.
- **The proof, a method worth keeping.** The AI ran live prod and the branch with the jukebox off in the same browser, on the same demo replay (the top score), for 30 s each at 4x, and compared:
  - The gaps between tiles: 825, 850, 975, 1025, 1050 and 4475 ms on prod; the same set on the branch, with 4500 for the last.
  - The sounds: the same 35 kinds on both, at identical volumes.
  - The pill pulses: the same counts and sizes on both (95 at 1.2x and 145 at 1.25x, 380 ms; 7 swells at 1.6x, 600 ms).
  - Identical numbers are as close to "nothing changed" as a check without ears gets.
- **Unchecked:** a collection with no song. The replay made no claim in either 30 s window, and none in a further 40 s wait. Its path is prod's code, restored, but it was not measured. The two visible changes, the jukebox in place of "Tap to play" and the slider in place of the buttons, are deliberate.

**Branch: the slider snaps to set speeds (10 October).**
- Prompt, verbatim: "take a step back have the slider do what was done before, speed up the game speed.  have to lock to the previous values we had of 1 2 3 4 6 8.  but now maybe we have 1.5?  does the engine support floats in this manner to make the gameplay go..much faster?".
- The slider now snaps to eight stops: 0 (pause), 1, 1.5, 2, 3, 4, 6, 8. That is the old buttons' speeds, with 1.5 and 3 added. The bpm readout and the 32x top are gone.
- **The question answered.** Yes, the engine takes any speed. Every wait between a replay's moves is divided by it: measured, 1.5x gave tiles 2204 to 2226 ms apart against 2200 expected, and 1.35x and 32x worked earlier. But only the pace between moves scales. The animations keep their own length (a point's flight is 2 s, a tile's rise 260 ms, the map ending about 10 s), so at high speeds they overlap rather than speed up. Making the whole game faster would mean running every animation on a clock scaled by the speed. That is possible, but not built.

**Branch: the buttons back; the slider undone (10 October).**
- Prompts, verbatim: "open it up, let me see it perform" (interrupted by the designer); then "undo changes since adding the slider.  we need the buttons back.  I understand the limitations".
- **Undone:**
  - the slider in all three forms (floats to 8, the 32x crank with its bpm readout, the snapping stops)
  - the frame-step change that went with the crank: both animation caps are back to 100 ms
  - The 0x 1x 2x 4x 6x 8x buttons are back, with their styles and code identical to the commit before the slider (checked by diff), and `fx.js` is identical to that commit too.
- **Kept, because it came after the slider for its own reason:** vanilla unless a song is picked. Prod needs it. The research-log entries stay too: they are the record.
- **Checked in the AI's browser:** the six buttons, 2x selected after a click and speed 2, no slider, and the jukebox showing "off".
- **A note for the record:** three versions of one control in under an hour, then back to the first. The designer could have the experiment because each step was a commit, and the undo was exact because the old version could be diffed against.

**Branch: Auto play, and a bug the AI found in its own work (10 October).**
- Prompt, verbatim: "add auto play checkbox on demo screen that plays the next song after the previous one finishes.  clicking it starts a random song".
- **Auto play** is a checkbox beside the jukebox. Ticked, it starts a random song at once and plays another whenever one ends. Unticked, a song plays once; when it ends the jukebox turns itself off and the game is as it always was. Before this, the jukebox always moved on to another song.
- **Checked in the AI's browser:**
  - Ticking started The Entertainer, and the jukebox showed it.
  - When the song ran out with Auto play on, Mary Had a Little Lamb followed and was shown.
  - Unticked, when that song ran out, the song stopped and the jukebox showed "off".
  - At phone width (375 px) the jukebox and the box sit in one row, from 10 to 365 px.
- **The bug.** Reading the line that plays the song on a tile, the AI saw that one of its earlier edits had appended a code comment in the middle of the line. The phone's vibration on placing a tile, `navigator.vibrate`, sat after the comment marker and never ran. It had been off on the branch since the song first followed the tiles. Prod has the line intact, which the AI checked against `main`, so prod never had it. Now fixed. The same slip (a comment appended to a line swallowing the code after it) is in this note's list of the AI's mistakes from earlier in the session. It happened again because the edit was a text splice, not a code change; the earlier side-by-side vanilla check could not see it, because it measured sound and pulses, not vibration.

**Branch: scores in flight pulse to the tempo (10 October).**
- Prompt, verbatim: "have scores in flight pulse to tempo".
- While a song plays, every "+n" flying to a pill pops on each beat, with the same pop as the pills but bigger (the label is small): 1.4 times its size on the beat. The pop is added to the label's flight rather than replacing it, and its start time is set on the note's clock. With no song, nothing changes.
- Checked in the AI's browser: with Auto play on (Mozart's 40th came up), 784 pops of flying scores over 15 beats, every one starting exactly on a beat (0 ms off), with no errors. Unchecked: how it looks with many labels in flight at once.

**Branch: songs carry on across replays; territories flash on the beat (10 October).**
- Prompt, verbatim: "make the territories pulse a bit better too.  the next song didn't play after?  montor sound in chrome".
- **Chrome was not reachable.** The Claude in Chrome extension did not answer twice, so the AI reproduced the run in its own browser, logging every song change and every melody note.
- **What it found, in two layers.**
  1. **A stall in the AI's own browser only.** Its hidden window draws no frames, so its animation clock stays at 0, 279 score labels never land, and the game-over screen waits on them forever. Real Chrome does not do this, but it would have looked like the bug.
  2. **The real cause.** A song moves only when a tile is laid. When a replay ran out of tiles mid-song (28 beats of Twinkle's 48), the song fell silent, and the next replay started the same song from the top. To the ear: the next song never came.
- **The fix.** With Auto play on, the song carries into the next replay where it left off, and the next song comes when it really ends. Checked: Twinkle went on from beat 5 to beat 8 across a new replay. With Auto play off, a picked song restarts with each replay, as before.
- **Territories.** While a song plays, a territory no longer fades in and out over 0.7 s (which peaked 350 ms after the beat). It flashes: brightest on the beat, fading through it, and again on the next two beats, each a little weaker. The second, stronger pulse, which came 1.3 s after a placement and so between beats, now waits for the next beat. Checked by computing the glow: flashes at 0, 825 and 1650 ms at 4x, each nearly gone before the next; with no song, the old curve exactly. Unchecked: how it looks, since the AI's hidden window draws no frames.

**Branch and staging: the song player, then a clean-up to abstract and harden before prod (10 to 11 October, overnight).**
- Prompts, verbatim, in order: "it's great, run in chrome headless and fix ui issues with the song picker and auto player.  next song still doesn't start after the first.  try playing a song, then waiting until it stops, then selecting a different song"; "run a thorough clean up of the code, we go to staging tomorrow.  abstract and harden, the concept is sound.  good night great job. log it"; "prod tomorrow, it's late"; "just abstract and harden as much to find issues, since it seems there are some.  good night, I love you".
- **The designer's steps, run in headless Chrome** (the repo's own driver, `scripts/cdp.js`: real frames and timers, unlike the AI's hidden pane), reproduced the bug at once. After the first song ended, the second pick played one note in 6 s and reached beat 1 of 32. The root cause: a song moved only when a tile was laid, so with no tiles (a replay's end, the map, between replays) any song stood still.
- **The fix is the designer's own idea from earlier, "we follow the sound layer and have graphics keep up", built properly.** A song player now plays the song on its own clock at the replay's speed, whether tiles come or not. The replay lays its tiles on the player's beats. A song playing in the demo carries on across replays.
- **The clean-up.**
  - All sound and music moved out of `builder.js` (now 1510 lines) into a new `builder/music.js`, laid out in five parts with a header: the audio engine, the background pad, songs and the jukebox, the song player, and the beat as the pictures see it.
  - `shared/beat-clock.js` was rewritten without its dead song data (Hot Cross Buns, the Canon, the old Ode), and now checks songs from data before playing them: one that does not make sense is left out, not played wrong.
  - Song names in the jukebox are shortened to fit a phone ("Symphony No. 5", "William Tell Overture").
- **Issues found by hardening, the designer having said "it seems there are some". Three were the AI's own:**
  1. **Scores not saved after the first game, on the branch only.** The line that starts a game had its resets hidden behind a comment since the excitement trigger was added: `submitting = null; undone = []; guardians.clear()` never ran. Within one visit, the first game's save would have blocked every later game's. Same slip as the vibration line: a comment appended into code.
  2. **A prod bug since 8 October** (commit `0a3bd2d`), from the same slip: the white pip behind each tile's animal count was never filled, `c.fill()` sitting after a comment. Fixed on the branch; prod gets it with the next deploy. This one changes how prod looks.
  3. **The Music switch** did not silence songs, and the Effects switch did. Songs now follow Music; Effects covers the game's sounds only.
  4. **A surprise song** was cut off at a replay's edge (each new replay re-rolled the chance); it now carries on.
  5. **A song picked anew** on a new replay did not restart its clock.
  6. **The recorded drums and cello** never loaded if a song began before the first touch; the player now retries once there is sound.
  7. **A browser without Web Audio** would throw in the jukebox's handlers; it is now silent instead.
  8. **One stray Windows line ending** in `builder.js` fooled the AI's own editing tool; normalised.
- **New guards, run with `npm test`** (`tests/page-scripts.test.js`):
  - every script and style the page loads exists and carries a cache tag
  - every one is in the build (this would have caught `music.js` missing from it)
  - the page's scripts parse together, so no name is declared twice in their shared scope
  - no code hides after a `//` comment on a line; the check first proves itself on the three real cases from tonight
- **New tools for tomorrow:**
  - `scripts/jukebox_check.js [url]` runs the designer's steps in headless Chrome.
  - `scripts/vanilla_check.js [prod] [candidate]` compares two sites on one replay.
- **Checked:**
  - All tests pass.
  - The jukebox check passed all its steps on the local server and on staging, version `33eff164`: off by default with no song voice, a song plays, it ends by itself, a different pick then plays, and Auto play goes on to another song.
  - The vanilla check of local against live prod, on the same replay for 30 s at 4x, this time with claims (21 on each): the same steady pace (831 and 855 ms, against 833 and 868), the same 45 kinds of sound, the same kinds of pill pulse, no errors.
- **Two lessons about checking.**
  - The bunched gaps after claims differ even between two runs of prod itself, so the check compares the steady pace instead.
  - Staging plays a different demo (its scores database is empty), so it cannot be compared with prod; the script now says so.
- **Unchecked:** the sound and the look on a phone; the pip's return on prod.

**Branch and staging: the menu tidied for prod; the jukebox put away (11 October).**
- Prompts, verbatim: "give stage url"; "hide the double x2 game button in menu, clean up install button, mocks"; "A with button to return to demo mode"; then, mid-task: "hide music picker and auto play".
- **x2 hidden.** The double-game button is hidden from the menu; its code stays.
- **The Install button.** It was squeezed into a 48 px circle by the menu's rule for round buttons, so its word spilled out. Three options were mocked as a picture (`concepts/install-button.png`), and the designer chose A: a pill like New game, with a download arrow.
- **A Demo button beside it**, "back to the demo". During the demo it just closes the menu. From a game or a replay it starts the demo again, leaving the game, as New game does.
- **On a phone** the row now wraps: Install and Demo on one line, New game on its own. Before, New game broke onto two lines and the row touched the edges.
- **The jukebox and Auto play are hidden; their code stays.** Prod's pulsing "Tap to play" is back in their place, so with the jukebox hidden the demo screen looks as prod's does.
- **Checked in headless Chrome at phone size:**
  - the menu with Install, Demo and New game
  - the demo screen with Tap to play
  - Tap to play opens the menu over the running demo
  - Demo from a game started the demo again (demo on, replay playing, menu closed)
  - all tests pass
- **Unchecked:** Install on a real phone; the AI cannot tap one, and only Android Chrome offers it.

**Deploy: the music work goes live, vanilla unless a song is picked; the menu speaks in icons (11 October).**
- Prompt, verbatim: "in menu, no English,all icons.  add the music picker and auto player here as min with icon as possible.  deploy to prod". The designer lifted their own rule ("we no longer can deploy to prod from this session") with this one.
- **The menu in icons.** Install (a download arrow), Demo (a screen with a play mark), New game (the controller), Music (a note) and Effects (a speaker) are round icon buttons; the name field's placeholder is a pencil. The jukebox and Auto play are in the menu as one small row, a picker ("♪ —" when off) and a round repeat toggle that lights when on. Every button keeps its name as a tooltip and for screen readers.
- **What goes live, branch `song-tempo` merged into `main`:**
  - the song player and jukebox (off by default), 20 songs, and the recorded drums and cello (CC0)
  - Auto play
  - the clean-up into `builder/music.js`
  - the menu changes: x2 hidden, the Demo button, the icons
- **Two fixes prod will notice:**
  - the pip behind each tile's animal count is filled again (missing since 8 October)
  - the Music switch now governs songs
- **Checked before deploy:**
  - all tests pass, including the new page checks
  - the jukebox check passed all its steps locally, in headless Chrome
  - the vanilla check, local against live prod on the same replay for 30 s at 4x with 27 claims each: the same pace (833 and 851 ms, against 832 and 849), the same 51 kinds of sound, the same pill pulses, no errors
  - A first run differed only by a few high collection notes, because the build's run had not reached the replay's big claim in its 30 s. A second run reached it and matched on every measure. The AI reran rather than call it noise.
- **Unchecked:** the sound and the look on a real phone; Install on Android.

**Deploy: one row of icon buttons; the game's effects play under a demo song (11 October).**
- Prompts, verbatim: "put all the buttons on the same line, same size, minimally.  deploy."; then, mid-task: "when in demo mode, play the sound effects.".
- **One row.** The menu's seven buttons sit on one line at one size: New game, Demo, Install (when the browser offers it), Music, Effects, the jukebox and Auto play. They are 44 px on a desktop and shrink to 36 px on a 360 px phone, so all seven fit.
  - The jukebox became a round button itself: a record icon, dim when off and lit while a song is picked; a tap opens the list.
  - Auto play is the round repeat button beside it.
  - The separate sound and jukebox rows are gone.
- **Effects in the demo.** Under a song, the game's own effects had been silenced, a rule left from the "only quarter and eighth notes" prototype. In the demo they now play along: in 8 s under Jingle Bells, 9 tile thuds and 29 point blips with 8 melody notes. In a game played by hand a song still plays alone.
- **A slip of the AI's, caught by its own assertion.** The rewrite first matched the deck's row instead of the menu's (both are `class="row"`), and stopped on finding no buttons in it. It now looks for the row that holds the menu's buttons. Then the CSS half stopped too, on a rule whose text had changed, after the HTML half had saved; it was finished line by line. Neither reached the page half-done unnoticed.
- **Checked:**
  - all tests pass
  - in headless Chrome the seven buttons measured 36 by 36 on a phone and 44 by 44 on a desktop, all on one line
  - the sound counts above
- **Unchecked:** the look on a real phone, and the mix of effects and song by ear.

**Deploy: a second tap on the lit jukebox or Auto play turns it off, and the music stops at once (11 October).**
- Prompt, verbatim: "when playing music mode is toggled on, and pressed again.  it toggles off and the music stops immediately.  same with auto play button.  deploy".
- **The jukebox.** Lit (a song picked), a tap now reaches the button, not the list: the jukebox turns off and the song stops at once. Unlit, a tap still opens the list. Turning it off unticks Auto play too, so off is all off.
- **Auto play.** Unticked, it had let the song playing finish; now the music stops at once and the jukebox turns off.
- **Checked:** all tests pass; `scripts/jukebox_check.js` gained step 6, real taps in headless Chrome on the lit Auto play and then the lit jukebox: each stopped the song at once. All six steps passed.
- **A slip of the AI's.** The first deploy (907eff7c) went out without this entry: the note's line endings did not match the script's, its check stopped the write, and the deploy ran anyway because the steps were not chained. This entry went out in a second deploy.
- **Unchecked:** the taps on a real phone (iPhone and Android open a select's list their own ways), and how sudden the stop sounds.

**Deploy: the flights untied from the tempo (11 October).**
- Prompt, verbatim: "let's untie the the effects flying to the pills from the tempo.  they just sit on the board.  the territory flashes, screen shake, and pill flashes work well"; then: "deploy".
- **What changed.** Under a song, an animal's score waited on the board for its beat, then flew so as to hit its pill on the note, and it also popped on every note. Both are gone: animals and scores in flight leave at once (staggered as they always were), land when they land, and no longer pop on the notes. Landing notes and the chime play as they land, not on a beat.
- **Kept:** the pills' pops on the notes, the territories flashing on the beat, the shake.
- **Cleaned out with it:** the clock-placed flight, the collection queue (`tuneAt`) and `onBeat`, which nothing used any more.
- **Checked:** all tests pass; the jukebox check passes; in headless Chrome with a song playing, flights waited about as long as with no song (20% of samples against 21%), no page errors.
- **Unchecked:** how it looks and sounds by ear; the landing notes are not tuned to the song's key.

**Deploy: the map's X button, a smoother map, and a Play button (11 October).**
- Prompts, verbatim, in order: "when transitioning to the map, add an x button to cancel it mid animation.  put it wherever to test.  when pressed in demo mode, it cancels the map animation and shows the next demo"; "disable all mouse logic while this animation happens, with the exception of cancelling it when then the button is pressed.  that's it"; "staging"; "smooth out the transition from open gl map to new game.  fade in canvas an animals a bit later with same fade rate if you have too.  it's not in sync"; "see the framerate tank when centering and zooming out map?"; "make new game button in menu stand out simple, w just label \"Play\""; "staging"; "prod".
- **X on the map.** Top left, only while the board turns into the map. In the demo it ends the map and the next demo starts at once; after a game you played it goes to the game over screen. While the map plays the page answers no mouse or touch but the X (capture listeners stop the event before the page sees it); a real mouse test (move, wheel, drag) changed nothing and a real click on the X ended the map.
- **Map to new game.** The board fades in as the map fades out (0.8 s, together) and the animals a little later (0.3 s) at the same rate; the animals come in solid so only the canvas's fade shows. The next demo starts as the map ends, not 0.85 s later, so there is no empty sea between.
- **The frame rate.** The designer saw it tank on the zoom-out, and it did: 9 frames a second in a phone-sized headless Chrome. The page's own code took under 1 ms a frame; switching things off one at a time showed the tiles drawn at high smoothing were the cost (low smoothing 29 fps, no tiles 43, water, edges and the animals layer made no difference). The zoom now draws at low smoothing and the settled map once at high.
- **Play.** New game is a big white "Play" pill above the icon row, the one button with a word on it.
- **A slip the check caught.** The mouse lock also blocked the jukebox check's clicks whenever its demo reached the map, so steps 5 and 6 failed; the check now leaves the map first. All six steps pass.
- **Checked:** all tests pass; the jukebox check passes; staging served the build.
- **Unchecked:** all of it on a real phone, the frame rate there (headless Chrome is not a phone's GPU), and the fades by eye.

**Deploy: the jukebox on staging only; no full screen or Install button in the installed app (11 October).**
- Prompts, verbatim: "only show music and auto play buttons on stage"; "deploy to both"; "hide full screen and install buttons when installed".
- **Staging only.** The jukebox (the record button) and Auto play show on the staging address and on a local copy; the live site shows neither, so nothing there can start a song and the game is exactly as it was before the music. The Music and Effects switches stay on both. The AI read "music and auto play buttons" as the jukebox and Auto play, since the Music switch has been live for days; this was not asked.
- **Installed.** In the installed app (home screen or its own window: standalone, full screen or minimal UI, or iOS's standalone) the full screen and Install buttons never show.
- **A flaw in the AI's own check, found on prod.** The jukebox check failed 3 steps on the live site right after the previous deploy: its demo reaches the map at 8x within seconds there, and the map answers no click (as asked), so the check's clicks did nothing. The page was right and the check wrong; it now leaves the map in the same breath as each click. It also passes quietly where the jukebox is hidden, and was tried on an address that hides it.
- **Checked:** all tests pass; the jukebox check passes locally and on prod; the host test gives staging and local true, the live addresses false.
- **Unchecked:** the installed app itself (no phone here), and that staging shows both buttons, which is checked after it deploys.

**Deploy: the menu's paging and Play buttons smaller, its rows aligned (11 October).**
- Prompt, verbatim: "paging and play buttons are too big.  aligned ui elements better on menu.  deploy to both".
- **Why they were big.** The pager's arrows were written as 30 by 22 px, but a general rule for the menu's buttons (round, 48 px, with the page's id in front) always won; the same rule made the save tick 48 px. The sizes now name the menu too.
- **Now.** Arrows 32 by 24, Play 40 px tall, the save tick 36 px, the name box 36 px tall and stretched to the list's width with the tick at its right edge, so the name row, list, pager, Play and icon row share one centre line. Measured at phone and desktop width.
- **Checked:** all tests pass; the sizes by measurement and a picture at both widths.
- **Unchecked:** the look on a real phone.

**Deploy: the animals freeze on the map; the map moves to staging only, with a WebGL version to explore (11 October).**
- Prompts, verbatim, in order: "any reason animals are missing in Librewolf browser?"; "nah, we will never do that.  freeze animals as they are when tattered map is being rendered"; "any cool open source animations to augment the tattered map?  thinking it's folded up once and animates off the side.  the easiest solution.  no changes"; "hold up, so the tattered map is rendered in both open gl and 2d?"; "what are the benefits of having this hybrid approach?  at this point I feel like openGL is the direction, but it seems like a lot"; "hmm, makes sense, maybe the tattered map needs to be moved to open gl.  ideally, it will roll up like a real treasure map, but we don't worry about this now.  thoughts?"; "can we use the browser to render the tatter off screen, take that texture to be used in openGL?  we do not worry about animals right now, we assume they will just fade away"; "lets get it running on localhost"; "the most simple change to see it work"; "let's disable the map animation in prod, when the game is over, we do what we did before.  we do explore this in staging though"; "deploy to both".
- **Librewolf.** The animals, the tile glows and the flying animals are drawn on one WebGL 2 canvas; Librewolf turns WebGL off by default, so they vanish and everything drawn in 2D stays. The designer ruled out a 2D fallback for them.
- **Frozen animals.** From the moment the tattered map starts to draw, the animals stand where they are (no amble, no steps, no frames drawn) until the map goes.
- **The tattered map and WebGL.** The map was never WebGL: the board is drawn on 2D canvases and torn by the browser's SVG filter; only the animals were WebGL. Asked whether the browser could tear it off screen for use as a texture, the AI tried it: a canvas's `filter` applies the page's own #tatter off screen, and the result uploads as a WebGL texture. The filter's sizes are in canvas pixels, so they are scaled by the device's pixel ratio to keep the same tear on a phone.
- **WebGL map.** `builder/map-gl.js`: the two bitmaps (raised and flat) torn once and shown by a shader on the old timeline; in headless Chrome the map ran at about 30 frames a second against about 9 for the stacked canvases. With no WebGL or no canvas filter it falls back to the old map by itself; `?oldmap` forces the old one. Then, for a visible first effect, the map folds once (the right half turns over, showing the paper's back) and slides off to the side at the end of a demo's hold, the animals fading.
- **Only on staging.** The map (a demo's end, a game's end) and the WebGL map and fold show on staging and a local copy; the live site goes straight to the next demo (after 3.5 s) and to the game over screen, as it did before the map. One flag, `EXPLORING`, decides it, and the jukebox uses it too.
- **A slip of the AI's.** An escape in a script turned `` into a backspace in the new flag's pattern, so `?oldmap` did nothing; the comparison run showed both pages on the new map and it was fixed.
- **Checked:** all tests pass; the jukebox check passes; on an address that is not staging or local the next demo started with no map call and a finished game showed the game over screen within 0.4 s; the fold in still frames; the WebGL map's frame rate and no leftover canvases after three maps.
- **Unchecked:** the map and fold on a real phone and by eye in motion; Safari (no canvas filter, as far as is known: the old map would show); Librewolf itself.

**Deploy: a debug menu, the WebGL and music layers hardened, three refinements under a song (staging), a reload button (staging), the installed app in the phone layout (11 October).**
- Prompts, verbatim, in order: "now we use smart fable to harden the code base and find math issues with open gl."; "before hardening openGL, add debug menu only I can invoke.  the two options are `map mode` and `music mode` .  we can toggle these off to see if performance is getting hit.  we can even see if these toggles, while off, effect performance"; "*effect performance negatively"; "do the music/open gl layer next."; "stage"; "Let's create a list of different UI elements that we render in OpenGL, and let's see what tracks we can tie to those UI elements that fit appropriately. I imagine larger elements have more face and smaller elements that move faster have more melody. Use your best judgment."; "bass not face"; "What we have now is really good. We just need to refine it. So we don't want to make big changes for this."; "do it, deploy stage"; "how do I invoke debug screen on mobile?"; "on stage only, allow way to reload the app if installed"; "with installed app, disable desktop mode, deploy both".
- **The debug menu.** `?debug` on the address shows the fps panel lower left with two chips, map mode and music mode; a tap toggles one, remembers it in that browser and reloads, so a load runs with or without that code (off, the song player's timer never starts and no map is made). On the live site both are off unless toggled; on staging and a local copy both are on.
- **WebGL hardened.** `scripts/gl_check.js` reads the drawn pixels back and checks the maths: the flat map equals the torn bitmap pixel for pixel, the fold mirrors the right half over the left in the paper's brown, the slide moves it intact, a third turn narrows it by cos; an animal draws centred where asked, either way round, none off the canvas; a glow lies outside its tile. Fixed: a lost WebGL context (phones take one away) killed the animals for good, now the programs and textures are made again when it comes back (headless Chrome never gives one back, so that stands unchecked); a fade of 0 s made 0/0; a glow edge of no length divided by zero; the map reuses its off-screen canvases (about 20 MB a map on a phone before), refuses a table bigger than a texture, guards the pixel ratio and releases a context it could not use.
- **Music hardened.** `scripts/music_check.js`: beatStrength (1 on a beat, .6 an eighth, .35 a sixteenth, less the further off), a live game's beat, a territory's flash, delayTo against the speakers' delay, the song clock at 8x and 0x. One real bug: at 4x and faster a song's natural end came inside the scheduling lead and called off its last beat's off-beat notes; only a stop calls notes off now.
- **A list, not a change.** The seven things WebGL draws, each with the voice that fits its size and speed: the map the pad and bass, the tile glow the kick, the floating tile the arp, standing animals the harmony, their rings the open hat, their steps the closed hat, the flyers the melody. The designer: good as it is, refine only.
- **Three refinements, under a song only (staging).** A tile's edge glow is sized by how squarely it landed on the beat, like the pills; the animals' landing notes are the tune's note of the moment, each a consonant step up; the herd steps together on the beat's eighths.
- **A reload button (staging and a local copy).** The installed app has no address bar: a tap reloads, a hold of 0.6 s reloads with ?debug.
- **The installed app.** Home screen or its own window: the phone layout whatever the screen, a tablet's or a desktop's (the footer gone, the tile box bottom left, the dock); the same check that hides its full screen and Install buttons.
- **Checked:** all tests pass; the jukebox, GL and music checks pass locally and on staging; the installed layout at desktop width with the class set by hand (headless Chrome cannot pose as an installed app); on an address that is not staging or local the reload button is hidden and the modes are off.
- **Unchecked:** the installed app on a real phone or tablet; the three refinements by ear and eye; a long press on the reload button under a finger; a context given back by a real browser.

**Deploy: the installed app known by its Android launch too (11 October).**
- Prompt, verbatim: "deploy no desktop mode for prod android install".
- **What changed.** The installed app is now also recognised by an Android launch from the app's own package (Chrome's WebAPK opens the page with an android-app:// referrer), besides the display mode the manifest asks for and iOS's flag; and the class follows a change of display mode. The page has no service worker and no caching, so the live build is what an app launch loads; an app already running keeps its old page until it is closed and opened again.
- **What a page cannot do.** Chrome's own "Desktop site" setting gives any page, installed or not, a wide layout viewport; the phone layout still applies (the class does not depend on width), but the whole page is laid out wide and shrunk. That setting is the browser's, to be turned off for the site.
- **Checked:** all tests pass; the jukebox check on prod. **Unchecked:** the Android app itself.

**Deploy: the pager's total, a game's length on the board, x2 mode, stronger edge indicators (11 October).**
- Prompts, verbatim, in order: "instruments for music are rough, look for free midi instrument packs on github" (a list only: midi-js-soundfonts, VSCO 2 CE, VCSL); "add  total to high score pagination"; "add game length stat to leaderboard"; "add x2 game mode size in debug menu, to be able to show the 2x button.  clean the button up to align as well"; "deploy to both, increase contrast of red/green indicators on tile with edge alignment.

got feedback it's tough with color blindness, what would an option be? minimal color blindness mode?".
- **The pager.** "1 / 7" and "63 games": the API gives the count with each page; the next arrow stops at the last page.
- **A game's length.** Its moves, counted from the replay when listing (the moves are joined by semicolons), the first stat of an opened row, so no saved game is touched and old games have it too.
- **x2 mode.** A third chip in the debug menu, off everywhere until toggled, shows the menu's x2 button, now round like the rest and labelled x2, lit while the double game is chosen.
- **Edge indicators.** The hand's band along each touching edge is thicker, over a dark underline, and brighter: green 40,235,95 and red 255,30,30 (were 32,184,90 and 255,41,41 at a tenth of a tile with no underline); the wedge from the edge is a little stronger. A thin line in the lands' own greens was hard to see on the art.
- **Colour blindness.** Asked what an option would be: the AI's answer is shape before colour (a solid band for a match, a dashed or crossed one for a mismatch) for everyone with no setting, and a blue/orange pair as a toggle if wanted. Nothing of it is built.
- **Checked:** all tests pass; the pager and the stats with a pretend scores server; the x2 chip and the button's size in the row; the hand's bands in a picture. **Unchecked:** the bands by eye on a phone; the colours against every tile.

**Deploy: a mismatch dashed, the debug menu's modes everywhere (11 October).**
- Prompts, verbatim: "do it, allow debug options to be used in prod, remove all prod/staging restrictions, we do it through the debug menu now"; "deploy".
- **Shape before colour.** A mismatched edge's band is dashed, a match's solid: it reads without the colour (red/green blindness is the common kind), for everyone, with no setting.
- **A fix found on the way.** The earlier "thicker band" had never shown: a CSS rule for the hand's edge key set every line in the hand to 2.5 px, and the band sat inside the blur that softens the wedge, which smeared it. The bands are now drawn sharp, outside the blur, on their dark underline, in the tile's own units.
- **The modes everywhere.** Map mode, music mode and x2 mode are off on every site until toggled (?debug on the address, or a hold on the menu's reload button, which now shows everywhere, since it is the installed app's way in). Nothing is keyed on the address any more: staging is no longer special, and the live site can have the map and the jukebox when the designer turns them on in their own browser. The checks toggle the modes on themselves.
- **Checked:** all tests pass; the three checks pass locally; a match and a mismatch in pictures, enlarged. **Unchecked:** the bands by eye on a phone.

**Deploy: edge matching by shape, a fissure for a mismatch (11 October).**
- Prompts, verbatim, in order: "its' pretty good, let's just make both aligned edges get slightly larger and glow a bit on alignment.  on mismatch edges become garbled an unpleasant to look at because of static.  minimal based on this desc"; "I described poorly, if yellow aligns with yellow, both yellow borders swell in size a bit to indicate its a match.  we no longer do red for mismatch and green for match, we now rely on the native color of the edge.  we need a shape indicator to distinguish mismatch.  we have the match behavior now, give me 6 common solutions for color blindness and edge matching in tile games"; "mock 3"; "i like the tear idea, but what about a fissure?  what could this look like with opengl?"; "chasm for now, deploy it".
- **The six, in short:** glyphs on the edges; patterns instead of flat colour; seam versus tear; a mark at the mismatch; motion; a colour-blind-safe palette with a brightness spread. The designer picked the tear, then asked for a fissure; two mocks (concepts/seam-tear.html, concepts/fissure.html).
- **A match.** Yellow meets yellow: both bands swell in the edge's own colour, the hand's on a dark underline with a glow, the neighbour's side glowing on the table. No green anywhere. The red and green tints, wedges and the static of the day are gone.
- **A mismatch.** A fissure along the seam, drawn by the effects layer (WebGL, fx.js): a dark chasm straddling the edge, widest in the middle and closed at its ends, its walls jagged by noise, black at the bottom, a pale lip on the lit side. It opens from the middle over 160 ms as the tile snaps (at once for people who ask for less motion), and keeps its walls while the tile stays. Shape alone says it, in any palette.
- **Checked:** all tests pass; the three checks pass locally, and gl_check's new step 8 reads the fissure back (67 px wide across the middle of a 253 px edge, 4 px near its end, nothing .4 of a tile away, gone when cleared); a match and a mismatch in pictures; the jukebox check on prod. **Unchecked:** the fissure by eye on a phone; its look on every tile.

**Deploy: edge matching as a bar and a zip (11 October).**
- Prompts, verbatim, in order: "we need more symetry, mocks pls"; "chasm doesn't work, lets have the two colors zigzag on border on mismatch, send to UX subagent" (the subagent run was interrupted by the designer; no sheet was made); "A for match, C for mismatch, deploy"; "A, but it can't extend outside of the tile or another edge"; "increase pt per tile claim from 1 to 3, don't worry about updating high scores" (not done: it changes the rules, and was left for the designer's yes on the exact rule); "deploy"; "wrap it up, write context out"; "i see the problem, let's just apply the effect over the canvas tile we're aligning.  doesn't this solve all the problems?"; "deploy to both". Also before the fissure was dropped: "how did this pass QA?! :-D" (a picture of a dark gap between the two halves of a matched bar) and "please add embers".
- **A match.** One bar in the edge's own colour, centred on the seam, with a soft halo: the hand's half inside the hand's clip, the neighbour's half drawn on the table's canvas.
- **A mismatch.** A zip that will not close: each tile's edge becomes a row of teeth in its own colour, on its own side, the two rows interlocking with a hairline of seam between. The AI read "C for mismatch" as the zigzag; the sheet it names was never made.
- **Kept inside the tile.** Each half is clipped to its own tile's triangle and to the wedge from the shared edge to the tile's middle, so a mark cannot cross a corner or reach another edge. The earlier attempt to draw both halves from the hand's SVG, where this could not be guaranteed, is gone, and so is the fissure and its embers (`Fx.crack`, removed from fx.js and the GL check).
- **A slip of the AI's.** The "thicker band" and the fissure each passed the checks (colour, position, width) while looking wrong on the screen: a dark gap between two halves, and a halo like a third bar. The checks read pixels; neither asked how the picture read. The designer saw it first.
- **Checked:** all tests pass; a match and a mismatch in pictures. **Unchecked:** several edges snapped at once; the marks on a phone; the zip's teeth against every tile's art. The three checks were not rerun after the last change.

**Deploy: a match fades in, a mismatch does nothing, and a territory tile is worth 3 (11 October).**
- Prompts, verbatim, in order: "i got it, on match both borders grow like this, but it extends a bit more with fade.  edges that don't align do... nothing"; "and fills near the base"; "what's the absolute min we can do for the rule change?  can we just show the old replays, and have the number weirdness persist?"; "each tile now scores 3 a piece when scored, so in the first turn, most people score 6, make sense?"; "this is complicating 1 is now 3, do local"; "both". Earlier, unrelated to this deploy: "increase pt per tile claim from 1 to 3, don't worry about updating high scores".
- **Edge matching, the last form.** A match: both borders grow in the edge's own colour and the colour fills near the base of each tile, nearly as strong a third of the way in, fading out about a quarter of a tile deep; each half kept inside its own tile and wedge. An edge that does not line up: nothing. The zip and the fissure are gone.
- **A tile is worth 3.** `GameRules.TILE_POINTS = 3` (it was 1): each tile of a territory that scores, before the multiplier. The flying labels show +3 a tile; the territory pill still counts tiles. The rules version stays 3: bumping it would have hidden every saved game from the board and the demo. A saved replay is only a seed and moves, and no move's legality depends on points, so every old replay still plays; it shows the new engine's score, while the board lists the old saved one. New 3x scores outrank old ones; the designer said not to worry about the high scores.
- **The first turn, measured.** Over 2,000 first moves on 400 seeds only 0 (two thirds: no matching edge) and 2 tiles (one third) ever scored, so 0 or 6 now.
- **Checked:** all tests pass (the sample game is played by the planner when the tests run, so no recorded score needed regenerating); the demo replays on the new rule (6206 points, no bad moves); a first matching move through the page sent two +3 flyers and the score landed at 6. **Unchecked:** how +3 reads on a phone; balance (the multiplier and animal points are unchanged, so animals count for less than before); the fade on a phone; two matching edges at once.

**Deploy: a softer match (11 October).**
- Prompts, verbatim: "its good, make it blur/fade more, show me, hard lines are bad"; "deploy to both".
- **What was hard.** The fill was a triangle (the wedge from the edge to the tile's middle) with hard diagonal sides, over a sharp border. The fill is now a wide, heavily blurred stroke along the edge, moved a little into the tile and stopping short of the corners (so it cannot reach another edge), and the border itself has a slight blur. The hand's half is an SVG blur; the table's half is the canvas's shadow blur (the line drawn far off, its shadow brought back), so it is the same on every browser; each half is clipped to its own tile.
- **Left sharp:** the thin outline round the hand's triangle, the tile's own edge key.
- **Checked:** all tests pass; two pictures (the first still too hard at the border, then softened again). **Unchecked:** the softness on a phone; two matching edges at once.

## What did not work
- Tuning numbers from simulated play. The designer overrode it.
- Guessing the notes of songs from memory: played without their rhythm, they sounded wrong. Staggering the animal animations to a melody's timing is the idea that survived.
- A browser window the AI controls is hidden, so frame rates and paint costs there are meaningless. Performance questions went to the designer's real window.

## Field notes (logged at the designer's request)
- On being unable to touch the thing: the AI has no finger. Its browser is a hidden window, so for the full screen button, the Install button and anything else that needs a real tap on a real phone, the honest report was the same every time: "I checked it up to here, but I could not tap it, so please try it on your phone." The designer found this hilarious, and it became a useful habit: say exactly where verification stopped.
- On being misled (the designer's words, at the end of the build, after the AI described an account setting loosely and then corrected it): "make a note I was misled :) JK thank you so much, life changing". Both halves are true: the AI had said extra usage was "there if you want it" when it was switched off, and the correction followed within one message. State what a tool reports, including what is off.

## Appendix: the code patterns that carried the project (written by the AI)
Short notes on what was built and why it held up, for anyone doing the same with an AI pair.

1. **One rules module, many consumers.** `shared/game.js` has no page code. The page, the terminal player, the planner, the tests and the server all import it. A bug fixed once is fixed everywhere, and "does this rule work" can be answered in Node without a browser.
2. **The replay is the contract.** A game is a seed and a string of moves. The server replays that string and takes the score from the replay, so the client can lie about nothing. Modes ride in the seed (a seed starting `X2` is the double game), so a replay needs no extra fields and old games never need migrating.
3. **Version the rules, keep the data.** Rows carry the rules version; the boards filter by it; nothing old is rewritten. Recorded demos are regenerated with the CLI, never edited.
4. **Draw once, filter once.** The torn pirate map is two static canvases (raised, flat) passed through one SVG filter and cross-faded with CSS opacity transitions. Animating the filter itself would have recomputed noise every frame; fading two finished layers costs almost nothing.
5. **Batch the draw calls.** The animal layer queues every sprite of a frame into one buffer and draws it with one instanced call; glow blips are scissored to their own box; the context asks for no anti-aliasing, depth or stencil it does not use.
6. **Timers where frames may pause.** A hidden tab pauses frame callbacks, so long sequences (the end-of-game change, replay waits) step on timers and read the clock, so they cannot stall.
7. **Measure the thing the user feels.** Speeds were checked by timing the gap between tiles, which found a fixed lock the speed setting did not touch. Pictures of the page were sampled at several moments, and anything that needs a finger was reported as untested.
8. **Cache-bust every change.** Each script and style carries a version tag that changes with each edit; most "it is broken" moments in this project were an old file served from a cache.
9. **Small commits, tagged deploys, one rollback log.** `ROLLBACK.md` maps each live version id to what changed and to a git tag. The database only grows.
10. **The AI's own notes as plans.** Risky ideas (music, anti-cheat, performance) were written to plan files first, with findings and the cheapest next step, so a later session, or a different AI, could resume from the file instead of the chat.

Open questions the AI would put to the next session: whether a replay's tempo can carry real music, whether planner agreement is a usable cheat signal, and whether the double game's click count suits the multiplier cap (a balance call, left to the designer).

## By the numbers
About 526 commits between 1 and 10 October 2026; about 2,600 lines in the game module, planner, page, effects layer and worker; 19 game tests and a browser smoke test; every deploy tagged and logged. The designer wrote almost no code.

## Limits
One project, one designer, one model family, no control group. The claims above are what we saw, not what we proved.