@homie-rocks/studio 0.48.4 → 0.50.0

package/guides/shop/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: shop
+description: Sell things in a Homie studio's games with the studio's OWN Stripe - a supporter pack, cosmetics, a season pass, a one-time unlock, a tip - in real money, with Stripe Checkout, Stripe Tax or Stripe Managed Payments, refunds from the office, and optional studio policies with an open default; set up with Stripe's own agent tools (Stripe's MCP server and skills) with one browser approval and Payment Links by default, no human-handled key and no API key in the Worker. Use when someone asks to sell something, add a shop or store, take payments or donations, make money from a game, set up or connect Stripe, make the products in Stripe, asks "how are sales?", about tax or Managed Payments, to add a supporter badge, refund a player, or about chargebacks, referral shares or affiliate links between studios.
+compatibility: The studio's own current toolkit with stripe_login or shop connect --renew, Wrangler, and the official Stripe CLI. Stripe's own agent plugin (MCP and skills) is optional for catalog work and analytics.
+metadata:
+  providers: stripe
+---
+
+Customer AIs can buy through the studio's own `/mcp`. Read the toolkit's `tools/TOOLS.md`
+and use the `tools` skill for `studio_catalogue`, cart quotes, standard agent payments,
+private purchase claims, and human Stripe checkout approval. Priced studio tools sell
+services through that same purchase engine; `shop connect` synchronizes their Payment Links.
+Keep orders, grants and refunds in the existing shop. For order/refund follow-up code, use
+Studio functions (`functions/FUNCTIONS.md`), with the event ID as the idempotency key.
+
+
+# The shop
+
+Check that the toolkit exposes `stripe_login`, or that `homie-studio --help` lists `shop connect` with `--renew` and `--manual`. An older toolkit's default is the paste page: upgrade before using this flow; do not send the owner to that old default.
+The guide is `node_modules/@homie-rocks/studio/shop/SHOP.md`; the owner's plain words are `SELLING.md`.
+
+**The model, said plainly to the person.** The studio sells with **its own Stripe account**. The studio is the
+seller: its prices, its refunds, its disputes, its tax. Money goes straight from players to the studio's Stripe;
+**homie.rocks never sees it, holds it or moves it, and Homie takes no cut.** The studio is responsible for the law where it sells and for Stripe's terms.
+
+In a rules game, keep shop UI in the view. Do not turn a client character save, an
+entity field or a command into proof of a purchase: grants still come from the shop's
+verified server records. Room state is replicated to players; keep payment and private
+customer data out of it. Read the game skill's RULES.md before changing game outcomes.
+
+## Connect with Stripe's own browser approval
+
+Use `stripe_login` (MCP) or `npx --no-install homie-studio shop connect`. Test mode and a
+sandbox first. If the CLI is missing, run the one installation command the result gives:
+`npm install -g @stripe/cli@latest`. The toolkit opens Stripe's page and completes its official
+non-interactive login. Give the person the pairing code; they select their own account and approve.
+Use `studio_job` for the background result. Do not call a raw CLI config command: it may print secrets.
+
+The default is **keyless**: the toolkit uses the CLI's approved account to sync Products, Prices
+(including custom amounts for tips), Payment Links and the webhook. It captures the signing secret
+privately and installs it with the link configuration; it never exports the CLI credentials.
+The Worker redirects buyers to Stripe and grants purchases from signed events. No desktop agent,
+Homie service or API key is needed when someone pays. Run connect again after editing shop.json;
+it updates changed objects and archives removed ones. Existing connections need no new approval.
+
+Only when the person asks for combined carts, spending reservations, custom checkout expiry,
+automatic recovery of lost webhooks or office refunds, explain one sentence:
+“The fuller connection adds combined carts, spending limits, automatic recovery and refunds here.”
+A pre-existing Worker key selects that path automatically. Never silently select `--manual` or ask
+for a key: explain its remaining Dashboard step only if the person explicitly chooses that route.
+Before relying on spending restrictions after switching, deactivate old Payment Links with the approved CLI and resolve in-flight checkouts; a credential change does not cancel them.
+`shop connect` selects keyless again and removes an existing Worker API key after saving the links.
+
+## Never
+
+- Never ask a person for a Stripe key, a webhook secret or a password in chat. Never display a CLI
+  config, credential response, environment value or raw login-completion output. The toolkit captures
+  these privately. Keys belong to the studio; no Homie account or service takes payments.
+- **Never make a webhook endpoint or an event destination through Stripe's MCP**: its signing secret
+  would enter the conversation. `shop connect` handles endpoint creation and secret storage privately.
+- Never silently select `--manual`. Only when the owner chooses the fallback, run
+  `shop connect --manual` (or `--manual --live`) and give the local page link. The page explains the
+  remaining Dashboard restricted-key step and creates the webhook automatically. This fallback
+  requires copying a key and does not meet the one-approval target; say so plainly.
+- Live mode only when the owner says go live. Account activation, tax, bank details and Stripe
+  approval links are the owner's. Never approve a Stripe confirmation link for them.
+- The studio chooses its settings. Omitted policies are open; choose a preset only when requested.
+
+## The owner's steps, for a creator with a fresh Stripe account
+
+With an existing Stripe account and deployed studio, there is **one Stripe approval** for the CLI;
+if that CLI profile is already connected, there are **zero new approvals**. An existing MCP-only
+consent is not a CLI login and is not exported or borrowed. Account creation/activation, an administrator
+enabling CLI access, and an initial Cloudflare sign-in are separate Stripe/hosting requirements.
+
+| The owner | You |
+|---|---|
+| Approves Stripe's browser page, selecting their studio account and sandbox. | Create/check shop.json; run stripe_login / shop connect; follow studio_job to completion. |
+| Nothing. | Sync all items and the webhook, install the signing secret and links privately, then verify a test purchase and grant. |
+| Requests a refund in Stripe or asks their connected AI. | Use the official Stripe connection, honor any confirmation link, verify the signed refund event removes the item. |
+| Says “go live” and completes Stripe activation if needed. | shop connect --live in the authorized account; verify only an authorized real purchase. |
+
+`shop connect --renew` restarts the approval flow when needed. CLI OAuth refresh is the CLI's job;
+there is no runtime API credential to expire. `shop catalog` remains the optional older catalog planner
+for keyed shops; keyless shops use connect for the complete catalog, links and webhook sync.
+
+## Optional Stripe agent tools
+
+For catalog work, analytics and advice, `stripe agent setup` installs Stripe's own agent plugin and
+skills; its OAuth MCP is `https://mcp.stripe.com`. This is optional and separate from Worker credentials.
+Check `get_stripe_account_info` before writes; confirm the account and mode match the studio.
+For CLI refunds or event resends, use the non-secret `profile` returned by connect with `stripe --project-name <profile>`; preserve its test/live context. Do not read credentials.
+The tools include `stripe_api_read`, `stripe_api_write`, API discovery and `stripe_analytics`.
+From **2026-10-31**, MCP rejects API keys without the Agent tag; OAuth remains supported. Agent keys
+can put refunds behind Stripe approval. A returned confirmation link belongs to the owner; wait
+for approval before retrying. Do not silently replace the payment runtime with MCP; a separate persistent MCP client would need its own production verification.
+
+## Do
+
+| The person says | Run | What happens |
+|---|---|---|
+| "Sell a supporter pack for $5" | `npx --no-install homie-studio shop init --supporter` (then `shop check`) | `shop.json` with a US$5 Supporter pack (a badge on their profile and beside their name in rooms, for a year; it changes nothing about play) and `SELLING.md`. Commit both. |
+| "Sell a skin / a season pass / the full game" | edit `shop.json` `items` (`kind`: `cosmetic`, `pass`, `unlock`; `price` in Stripe currency units; `gives`: the keys the game reads), `shop check`, then `shop connect` again | Kinds are studio labels, without a fixed list. `"advantage": true` follows the studio policy for beginner and kids servers. Homie sets no price ceiling. |
+| "Let people tip" | an item `{ "kind": "tip", "price": "choose", "min": 200, "max": 5000 }` | Pay what you want; amounts follow Stripe currency requirements, and max is optional and chosen by the studio. |
+| "Make the products in Stripe" | `shop connect` | Idempotent Product, Price, Payment Link and webhook sync from shop.json; no secret enters tool output. |
+| "Connect my Stripe" / "turn the shop on" | `stripe_login` or `shop connect` | Approve Stripe once if needed; the Worker receives links and the signing secret only. Follow the single next step returned. Live only when requested. |
+| "Is tax set up?" | `stripe_api_read` `GET /v1/tax/settings`, and `GET /v1/tax/registrations` | Seller "stripe": Stripe Tax needs `status: active` (the business address in Settings, Tax), or checkouts fail; with no registrations it collects no tax anywhere: say so, the accountant decides where to register. Seller "stripe-managed": Stripe files the tax; the connect page's test checkout said whether Managed Payments is on. Change nothing yourself. |
+| "Is the shop working?" | `npx --no-install homie-studio shop` | Open (test or live) or exactly what is missing, the last 30 days, the webhook address. |
+| "How are sales?" / "Show me the sales" | `shop` and `shop orders` first (the studio's own books); with Stripe's MCP, read-only: `stripe_analytics`, or `stripe_api_read` on `/v1/balance`, `/v1/payouts`, `/v1/checkout/sessions` | Counts, money and payouts in a few lines; never a buyer's name, email or card. Never a write to answer a question. The owner's `/_studio/office/shop` links every Stripe page and gives the accountant a CSV. |
+| "Refund that player" | The owner’s official Stripe connection, or link their Stripe Dashboard payment | Honor Stripe’s confirmation link; signed events update the books and revoke fully refunded items. The keyed way still offers office refunds. |
+| "Someone charged back" | nothing to undo: the owner answers it in Stripe (the office links it) | While open nothing changes; lost: that one item goes; won: it stays. **The account is never locked or deleted over a dispute.** |
+| "Show the item in the game" / "the supporter badge" | in the game: `createShop()` from `@homie-rocks/studio/shop`; `shop.has('skin:ember')`, `shop.on('change', …)`, `shop.open('ember-skin')` from a button the player pressed, `shop.used(key)` when equipped | The play shell answers for the signed-in player; a badge rides on their seat as `peer.badge` (the Worker sets it, never a hello). |
+| "Pay studios that send us players" / "affiliate links" | `shop.json` `referrals` (rate, window, hold), `shop statements [--send]` | A `?via=<host>` link from another site (homie.rocks is one more referrer, on the same terms) counts for a new player's purchases; statements are signed with the studio's key; the referrer invoices the studio; the owner pays and marks it paid (an ASK from you). Nothing moves through Homie. |
+
+## Your shop, your choices
+
+The default is open: guests buy repeatedly without an age question, with any wording or kind, from any page.
+`shop init` writes no policy. A released shop file without a preset now uses the open default.
+Write `"policy": { "preset": "protective" }` to retain earlier account and age behavior.
+`adults-only` is another optional bundle. Neither scans content. SHOP.md lists individual overrides.
+
+The studio can set items, quantities, prices, tip ranges, entitlements, sale dates, currency, optional
+`automaticTax`, `capPerPlayerMonth`, `refundDays`, referral terms and configurable flood protection.
+No toolkit amount or duration ceiling applies. Stripe currency constraints and safe integer arithmetic apply.
+A refund window includes used items unless `policy.refundUsedItems` is false. A player cannot refund a tip;
+the owner can refund through Stripe; keyed shops also offer office refunds. Guest purchases stay owned when the buyer signs in later.
+
+For keyed shops, carts: `shop.add(item, quantity, amount?)`, then `shop.checkout()`; `shop.buy(item)` buys directly.
+Free and paid lines share one order and one Stripe Session. The studio chooses where to open the shop.
+
+## The first sale (the acceptance)
+
+In test mode: buy the supporter pack on a phone with Stripe's test card `4242 4242 4242 4242`, see "It's yours",
+see the badge on the account page and beside the name in a room (from the next room the player joins), refund it
+in Stripe (or through the connected AI), and see the badge go. With the protective preset, a kids server's room shows no shop and `/<game>/tv` shows only a code.
+
+Keyless purchases buy one item type at a time, with quantity confirmed on Stripe. Tips choose the
+amount on Stripe and always have quantity one. Free orders grant locally without Stripe.
+Refund and dispute snapshots are stored by provider object ID and tolerate retries and reordering.
+A missing webhook stays pending: ask Stripe to resend the event (Dashboard or official CLI
+`stripe events resend <event> --webhook-endpoint <endpoint>`). Never grant based on the return URL.
+Payment Links are public and reusable; do not promise that local sale dates, repeat-purchase or
+eligibility checks revoke a previously opened link. Deactivation stops new sessions after re-sync;
+already opened sessions may still complete. Strict pre-payment enforcement needs the keyed way.
+Stripe always enables Adaptive Pricing on Payment Links; the buyer can use the original currency.
+Keyless has no per-session expiry or provider-read reconciliation. The keyed path retains both,
+carts, cap reservations, local refunds. Managed Payments is supported on Payment Links when Stripe enables it for the account. The studio chooses its needs.
+
+For a cause, use `shop init --giving --currency <organisation currency>`: one-time and monthly suggested gifts, no badge or game access. Read `giving.receiptText` from the organisation; leave it empty until provided. Local /shop/ previews before Stripe. Monthly gifts use the existing keyless Payment Links connection and Stripe handles renewals.
+
+## App payment references
+
+Create the booking/ticket/gift intention first. `shop.buy('full-tune', 1, undefined, { reference: booking.id })` or `shop.checkout({ reference: booking.id })` sends the app's own reference through checkout. Existing boolean returns are unchanged: checkout opened is not paid. The verified durable `order.paid` event carries `data.order`, `data.reference` (null if omitted) and `data.app`. Reopened Payment Links retain the reference. A reference is buyer-supplied correlation, not authorization: verify the record, app, amount and currency, deduplicate by event/order ID, then fulfil it. Keep personal data out of references. Before Stripe is connected, local prices and unpaid requests can be demonstrated; actual payment and recurring collection remain unverified. Test events must be labelled simulations.

package/guides/sound/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: sound
+description: Make a game's sound effects and synthesized music on the creator's own computer, free, with no provider or account — a set of effects (jump, coin, hit, explosion, win, lose, UI) rendered from presets, a short synthesized theme or score from chords and patterns with stems and seamless section loops, a mix of any audio files and expressions — measured for loudness, clipping, late starts and what a phone speaker loses, then wired into the game with a small player that starts on the first touch and switches music on bar lines. Use when someone asks for sound effects, SFX, game audio, a chiptune or synth theme, background music without a paid service, music that changes with the game, or says a game is silent.
+---
+
+# Sound for a studio's game
+
+Everything here runs on this computer with Node 22 and ffmpeg: nothing is sent anywhere and nothing
+costs money. Sung songs and produced music from a model are the `music` skill (ElevenLabs, paid);
+this skill is effects and synthesized music. They share the studio's `music/` folder and manifest, so
+a synthesized theme gets a song page just like a rendered one.
+
+One script: `scripts/sound.mjs` in this skill's folder (Claude Code:
+`node "${CLAUDE_PLUGIN_ROOT}/skills/sound/scripts/sound.mjs" <command>`), run from inside the studio
+(the folder with `studio.json`). Every command takes `--json`.
+
+```sh
+node <sound.mjs> check        # node, ffmpeg and its encoders, the studio and its games
+node <sound.mjs> presets      # every effect preset, instrument, groove and pattern, one line each
+```
+
+No ffmpeg: offer `brew install ffmpeg` (macOS) or the system package; the person approves.
+Finish in this turn: an effect set takes seconds, a one-minute score under a minute.
+
+## 1. Effects
+
+```sh
+node <sound.mjs> sfx <set> --kit arcade --for-game <id>          # a kit: arcade, platformer, shooter, party, ui
+node <sound.mjs> sfx <set> --only jump,coin,hit,win --style retro   # just these, crunchy 8-bit
+node <sound.mjs> sfx <set> --spec music/<set>/effects.json        # your own list (below)
+```
+
+It writes `music/<set>/sfx/<name>-<n>.wav` and an Ogg copy of each, `music/<set>/sfx.json` (the
+spec and every file's measured level), a reel to listen to (`<set>.mp3`) and its picture
+(`<set>-reel.png`, a spectrogram over the waveform). **Open the picture and look**: a sound you
+cannot hear is still a sound you can see. Then read the warnings; each one is something a person will
+hear wrong, with the fix.
+
+A spec is `{ "style": "clean", "variants": 3, "effects": [ { "name": "stomp", "preset": "land", "pitch": -3, "length": 1.2, "level": "big" } ] }`:
+`preset` is any name from `presets` (the effect's name is used when it is one), `pitch` in
+semitones, `length` a stretch, `seed` another take, `style` clean, retro or soft, `level` ui,
+small, normal, big or a number in dB. Name effects after what happens in the game (`stomp`,
+`gem`, `ko`), not after the preset.
+
+- **Variants** (three by default) are the same recipe a touch higher or lower, so a sound heard fifty
+  times a round does not machine-gun. Signals heard once a round (win, lose, go, countdown) get one take.
+- **Levels** are set by the loudest 50 ms of each effect into four classes (ui -20, small -16,
+  normal -12, big -9 dB), then held under -1 dBFS. The set sits together in a mix without balancing.
+- **Every effect must start at once** (a hit that starts 30 ms late feels laggy) and **must reach a
+  phone speaker**: under about 300 Hz a phone plays almost nothing, so a thud needs a knock on top.
+  The warnings measure both.
+
+## 2. A synthesized theme or score
+
+Write `music/<slug>/score.json` (the full language, with a worked example: `references/SCORE.md`):
+tempo, key, instruments (presets with a level, pan, echo in beats, reverb send, a duck under the
+kick), sections in whole bars with chords and one pattern per instrument, an arrangement, and the
+sections to loop. Then:
+
+```sh
+node <sound.mjs> score <slug> --spec music/<slug>/score.json --loops main,chase
+```
+
+- It renders the mix (-14 LUFS for a page; `--lufs -18` for a bed under a game's effects), the page
+  mp3, a 24-bit master kept off the site, one stem per instrument plus the room (they sum to the
+  mix), and **seamless loops** of the sections you name: each is rendered three times in a row and
+  the middle copy kept, so reverb and echoes that ring over the loop point are already in its head.
+  The report gives each loop's seam (1 or less is seamless) and its exact bar length. A loop over 1
+  is in `warnings` and the summary says NOT SEAMLESS (`loopsSeamless: false`): an empty warnings
+  list means the loops were checked and pass. The master's limiter is applied across the three
+  copies, so a loud loop keeps its seam; nothing is faded at the loop point and no bar is shortened.
+- `plan.json` holds the bar grid, so the `video` skill cuts a trailer on this music's bar lines.
+- Look at `<slug>.png` and read the numbers: loudness, true peak, and what it measures through a phone
+  speaker. Say them in your report, not adjectives.
+- Write music a person would hum: a hook in the first bars, a clear melody over simple chords, a
+  change every 4 or 8 bars. A score for a game is sections of the same tempo and key (calm, chase,
+  final seconds) so the game can move between them on a bar line.
+
+## 3. A mix of anything
+
+```sh
+node <sound.mjs> mix <slug> --spec music/<slug>/mix.json
+```
+
+Parts are audio files (a recording, a render, a loop), ffmpeg `aevalsrc` expressions (one, or two for
+left and right), or effect presets, each placed (`at` seconds), levelled (`db`), panned, faded, repeated
+and filtered with an ffmpeg `-af` chain. They are summed at exactly the levels written (no automatic
+normalisation), limited, and brought to `master.lufs` if you give one. Expressions have traps that
+fail silently: read `references/TRAPS.md` before writing one.
+
+## 4. Into the game
+
+```sh
+node <sound.mjs> wire <set> <score slug> --game <id>
+```
+
+It copies the files into the game (`public/sound/`, or `sound/` for a static game), writes
+`sound.json` (what exists) and `sound.js` (the player) and prints the two lines to add. Then, in the
+game's code:
+
+```js
+import { createSound } from './sound.js';
+const sound = createSound({ base: 'sound/' });
+sound.music('<score slug>');                    // once, at the top: it starts on the first touch
+sound.play('coin');                             // where the thing happens
+sound.play('coin', { pitch: combo });           // a climbing combo; pan -1..1 for where it is
+sound.section('chase');                         // the next loop, exactly on the next bar line
+sound.duck(0.4, 0.5);                           // music down for a big hit
+```
+
+- **Sound starts on the first touch or key, with no "tap for sound" screen**: the player resumes audio
+  inside the first gesture. A sound asked for before that is dropped, not queued.
+- **Every browser plays its own sounds** for what it sees: call `play` where the each browser
+  draw the event (a pickup that shows up in a snapshot, a hit that lands on screen), not only in the
+  rules handlers. In a rules game emit a declared effect and play it from room.on in the view; the server has no speaker.
+- Loops go out as Ogg with a WAV fallback (older Safari cannot decode Ogg): the player takes the first
+  one the browser decodes. `wire` prints the real download size; keep a game's sound under about 3 MB.
+- Each variant of an effect, and each loop, is a list of files tried in order (`["jump.ogg", "jump.wav"]`);
+  a list of one file is fine.
+- A trailer filmed frame by frame gets its sound from this player's own log of what it scheduled
+  (off unless a recorder asks; `references/GAME-SOUND.md`, "A log for a recorder"): sound that goes
+  through `sound.play` and `sound.music` is in the trailer, sound made any other way is not.
+- Rules for game sound (every action answers, what repeats, music under effects, intensity changes on
+  bar lines, the live-loop traps): `references/GAME-SOUND.md`.
+- For sound made live in the browser (a synth voice per player, pitch that follows speed, a beat
+  clock), the open engine package `@homie-rocks/audio` has the building blocks; install it exactly
+  pinned (`npm install --save-exact @homie-rocks/audio@0.1.0`).
+
+## 5. Prove it, and publish it
+
+Build, run the game, and let the `playtest` skill's sound row listen: it copies what the game really
+sends to the speaker while it is played, and says how loud it is, whether it clips, what a phone loses,
+whether actions answer with a sound, and whether the music ever started. Never say a game "has sound"
+from the code alone.
+
+```sh
+node <sound.mjs> add <slug> --title "<Title>" --blurb "<one line>" [--for-game <id>] --publish
+node <sound.mjs> publish <slug>        # rebuild and redeploy the site; the page answers 200
+```
+
+An effect set gets a page with its reel and every effect to download; a score gets its player, its
+loops and its stems. The credits line says they were synthesized from code (no samples, no model).
+Commit `music/<slug>/` specs and the manifest; the audio files stay out of git (the studio's
+`.gitignore`) and regenerate from the spec, byte for byte.
+
+## Tell the person
+
+The page or the game, what was made (how many effects, the theme's length and bars), the loudness
+numbers, the warnings you fixed and any you did not, and that it cost nothing.
+
+## Never
+
+- Never ship a sound you have not measured and looked at.
+- Never use a mp3 for an effect or a loop: encoders pad the start with silence (a late hit) and the
+  ends (a gap at the loop). WAV or Ogg.
+- Never imitate a real song, artist or brand jingle.

package/guides/sound/references/GAME-SOUND.md

@@ -0,0 +1,100 @@
+# Sound in a game
+
+What makes a web game sound finished, and the ways a correct-looking sound system goes quiet. Each
+rule below was learned by a game that broke it.
+
+## What the game owes a player
+
+- **Every action answers with a sound**, on the frame it happens: a press that does something makes
+  a sound; a press that is refused makes a different one (`deny`). Movement itself does not need a
+  sound per press, but landing, bumping and stopping do.
+- **Sound starts on the first touch**, with no "tap for sound" screen: browsers keep audio suspended
+  until a gesture, so resume inside the first `pointerdown`, `touchend` or `keydown` (the player's
+  `sound.js`, or the port toolkit, does it). On iOS a held stick is only a gesture when the finger
+  lifts, so the first tap or release is when sound begins; the silent switch mutes Web Audio unless
+  `navigator.audioSession.type = 'playback'`.
+- **Music carries the round**: calm at the start, a change when it gets tense, something for the last
+  ten seconds, a stinger for the result. A round that is all one intensity has no shape; silence
+  followed by a hit is worth more than a louder loop.
+- **It sounds good on a phone speaker and on a TV.** A phone plays almost nothing under 300 Hz: every
+  important sound needs energy between 500 Hz and 4 kHz (a knock on a thud, an upper harmonic on a
+  bass). Measure it: `sound.mjs analyze` gives the loss through a phone-speaker curve.
+- **Nothing clips** when many things happen at once: sounds share a bus that ends in a gentle limiter,
+  and each sound is capped at a few voices (`sound.js` keeps four of a name and 24 in all).
+
+## Levels that work
+
+| what | level |
+| --- | --- |
+| music bed under play | -18 to -20 LUFS (`score --lufs -18`) |
+| title or menu music | -14 LUFS |
+| effects | the four classes: ui -20, small -16, normal -12, big -9 dB (loudest 50 ms) |
+| a whole game while played | -16 to -12 LUFS measured off its output (the playtest's sound row) |
+
+Duck the music for the moments that matter (`sound.duck(0.4, 0.5)` for a knockout or a line of
+speech) instead of raising the effect.
+
+## Repetition
+
+- A sound heard many times a round needs **variants** (three takes a touch apart in pitch) and a
+  little random pitch on each play; the same sample fired twenty times in a row reads as a machine gun.
+- Signals the player must learn (start, win, lose, a warning) stay **the same every time**.
+- A long session should not loop one 8-bar clip for ten minutes: make two or three sections and move
+  between them with the game's state.
+
+## Changing music with the game
+
+- Every loop the same tempo and key; switch on the **next bar line**
+  (`next = start + ceil((now - start) / bar) * bar` on the audio clock), which `sound.section()` does.
+- Use the audio clock (`AudioContext.currentTime`), not timers, to schedule anything musical. A timer
+  or a `requestAnimationFrame` pump skips beats it sees late, and a loaded machine makes it late: a
+  bar counter that rides a pump lost three quarters of its sections under load while the audio
+  itself played on. Work the bar out from the audio clock each time you need it.
+- A live arrangement's position is `bar % total bars`: changing the total while it plays makes the
+  playhead jump. Change the content of a section, not the arrangement's length.
+- A section that plays once as an intro and a lap that repeats are different lengths: compute the lap
+  from the repeating part only.
+- A cue that names a sound that does not exist fails silently in most engines: check every name a
+  cue or a section uses against what was loaded, once, at start.
+- A gain, a bus or a send changed after a sound was wired may never reach the running graph (a loader
+  that skips "already wired" sounds). Set levels before the first play, or rebuild the node.
+- An `AudioContext` clock stalls while the machine is busy (a render, a capture), so a long set drifts
+  from wall time: correct its start offset, never its cues.
+- A module served from cache after a change runs the old code: version its URL (`?v=2`) when you
+  change it on a live page.
+
+## Events, not counts
+
+When sounds follow a game's event list (hits, pickups), give each event a rising sequence number and
+play every event newer than the last one played, in order. A list's length is not a signal: an
+expired event replaced at the same length, or two events in one frame, are lost otherwise.
+
+## Mixing effects into a running bed
+
+Send one-shots (hits, chimes, slams) straight to the final bus, not through the music's filters: a hit
+routed through a lowpass meant for the bed disappears into it. Bright noise belongs on the bright
+one-shots only. Never raise the master to make hits stand out; lower the bed or duck it.
+
+## Proving it
+
+Scheduling a node is not proof that anything is audible. Three instruments, cheapest first:
+
+1. `sound.mjs analyze <file>` on each asset: level, start, clipping, phone loss, and its picture.
+2. The `playtest` skill's sound row: the game's real output copied off its graph while it is played;
+   loudness, clipping, gaps, whether actions answer, whether music ever started.
+3. An offline render of the game's own audio graph (`OfflineAudioContext` in headless Chrome) with a
+   clock you can set: it finds NaN voices (a NaN anywhere silences the whole graph) and feedback loops
+   that double their gain, without playing anything out loud. `currentTime` stays 0 offline, so give
+   the game's audio a clock the render can drive.
+
+## A log for a recorder
+
+`sound.js` keeps a log of everything it schedules when a recorder asks for one, and only then: the
+recorder sets `window.__homieSoundCapture = { events: [] }` before the page's scripts run, and each
+`play`, each music loop, each stop, duck and fader move is pushed onto `events` with `performance.now()`
+and what is needed to mix it again (the file's address, gain, playback rate, pan, loop, delay). The
+head of `sound.js` lists the events. The `video` skill's `trailer` films the game frame by frame and
+rebuilds its sound from that log and the game's own files. A game with audio code of its own can push
+the same events, and only what is in the log is in the trailer's sound.
+
+A visual check can never hear a game. Report numbers, and look at the spectrogram.

package/guides/sound/references/SCORE.md

@@ -0,0 +1,131 @@
+# The score language
+
+A score is JSON: tempo and key, instruments, sections in whole bars, an arrangement. `sound.mjs
+score` renders it the same way every time (every random choice is seeded), so the score IS the
+music: commit it, and the audio regenerates byte for byte.
+
+## A worked example (48 s, three sections, two loops)
+
+```json
+{
+  "title": "Night Market Theme",
+  "bpm": 128, "key": "A minor", "beatsPerBar": 4, "stepsPerBeat": 4, "swing": 0,
+  "instruments": {
+    "lead":  { "preset": "pulse-lead", "db": -9,  "pan": 0.1, "stepsPerBeat": 2, "echo": { "beats": 0.75, "feedback": 0.3, "mix": 0.2 }, "reverb": 0.15 },
+    "arp":   { "preset": "pluck",      "db": -15, "pan": -0.35, "reverb": 0.2 },
+    "bass":  { "preset": "saw-bass",   "db": -10, "duck": 0.35, "reverb": 0 },
+    "pad":   { "preset": "pad",        "db": -17, "duck": 0.5, "reverb": 0.3 },
+    "drums": { "preset": "kit",        "db": -7,  "reverb": 0.05 }
+  },
+  "sections": [
+    { "name": "intro", "bars": 4, "chords": "Am F C G",
+      "play": { "pad": "chords", "arp": "arp:16", "drums": "hats" } },
+    { "name": "main", "bars": 8, "chords": "Am F C G",
+      "play": {
+        "lead": "A4 . C5 . E5 - D5 C5 | B4 . G4 . B4*2 C5 D5 | E5 - . C5 A4 . C5 D5 | E5*3 . G5*2 E5*2 | F5 . E5 D5 C5 - A4 . | C5 . B4 . A4*2 G4*2 | A4 . C5 . E5 . A5 - | G5*4 E5*4",
+        "bass": "root8", "pad": "chords", "arp": "arp:16", "drums": "four" } },
+    { "name": "chase", "bars": 4, "chords": "Dm E Am Am",
+      "play": {
+        "lead": { "notes": "D5 E5 F5 A5 | G#5*2 E5*2 | A5 E5 C5 A4 | E5*4", "stepsPerBeat": 1 },
+        "bass": "pulse", "arp": "arp-updown:16", "drums": "break+fill" } }
+  ],
+  "arrangement": ["intro", "main", "chase", "main"],
+  "loops": ["main", "chase"],
+  "master": { "lufs": -14 }
+}
+```
+
+## The top
+
+| field | meaning |
+| --- | --- |
+| `bpm` | 40 to 240 |
+| `beatsPerBar` | 4 by default (3 for a waltz) |
+| `stepsPerBeat` | the grid of a notes pattern: 4 = sixteenth notes (default), 2 = eighths, 1 = quarters. An instrument or a single pattern can set its own |
+| `swing` | 0 to 0.5: every second step comes that fraction of a step late (0.2 to 0.33 is a shuffle) |
+| `arrangement` | section names in playing order; a section can repeat. Default: the sections in order |
+| `loops` | sections to render as seamless loops for the game (`--loops` overrides; `all` for every one) |
+| `master.lufs` | -14 for a page or a trailer, -18 to -20 for a bed under game effects (`--lufs` overrides) |
+| `room` | the shared reverb's size, 0 to 1 (0.55 by default) |
+
+## Instruments
+
+`{ "preset", "db", "pan", "octave", "legato", "echo", "reverb", "duck", "stepsPerBeat", "tone" }`
+
+- `db` the level (-10 by default). Start the lead around -9, drums -7, bass -10, pads -17, and move
+  one at a time while listening to the numbers (`analyze` a stem).
+- `pan` -1 (left) to 1 (right). Keep the bass and kick in the middle.
+- `octave` shifts every note of the instrument by octaves.
+- `legato` how much of each step a note holds (0.92 by default; 0.5 is staccato).
+- `echo` `{ beats, feedback, mix, pingpong }`: a tempo-synced echo (0.75 beats is the dotted eighth).
+- `reverb` the send to the shared room, 0 to 1.
+- `duck` 0 to 0.95: the instrument dips on every kick and comes back within half a beat (the pump
+  that makes a pad breathe with the drums). Only when the section has a kick.
+- `tone` (drums) shifts the kit's pitch in semitones.
+
+Presets (`sound.mjs presets` lists them with what each is for): leads `pulse-lead`, `square-lead`,
+`saw-lead`, `soft-lead`, `bell`; keys `epiano`, `pluck`, `organ`; pads `pad`, `warm-pad`; basses
+`saw-bass`, `square-bass`, `triangle-bass`, `sub-bass`; drums `kit`, `chip-kit`.
+
+## Chords
+
+`"chords": "Am F C G"` is one chord a bar, repeated to fill the section. With bars marked,
+`"Am F | C G | Dm | E7"` puts two chords in a bar when you write two. Qualities: major (`C`),
+`m`, `7`, `maj7`, `m7`, `m9`, `9`, `add9`, `6`, `m6`, `5`, `dim`, `dim7`, `m7b5`, `aug`, `sus2`,
+`sus4`, `7sus4`; a slash puts another note in the bass (`C/E`). Sharps and flats: `F#m`, `Bb`.
+
+## Patterns
+
+A pattern is either generated from the chords, or written note by note.
+
+**From the chords**: `root` (the root held for the chord), `root8` (eighth-note roots; `root8:16`
+for sixteenths), `pulse` (sixteenth-note roots, a driving bass), `octaves` (root and its octave in
+turn), `chords` (the chord held: a pad), `stabs` (short chords on the off-beats), `arp`, `arp-down`,
+`arp-updown` (the chord's notes one at a time; `:16` sixteenths by default, `:8` eighths). The bass
+plays low, pads in the middle, arpeggios an octave up; `octave` moves any of them.
+
+**Notes**: one token per step of the pattern's grid.
+
+| token | meaning |
+| --- | --- |
+| `A4`, `C#5`, `Bb3` | a note (A4 = 440 Hz; octaves change at C) |
+| `.` | a rest |
+| `-` | hold the previous note one more step |
+| `A4*3`, `.*4` | a note or rest lasting 3 (or 4) steps |
+| `[A3 C4 E4]` | a chord |
+| `A4!` | an accent (louder); with a length: `A4!*2` |
+| a vertical bar | a bar line: optional, but when you write them every bar must be full, which catches a miscounted bar |
+
+A pattern shorter than its section repeats (a one-bar riff over eight bars). With the default grid a
+bar of 4/4 is 16 tokens; for a melody in eighth notes give the instrument `"stepsPerBeat": 2` (8
+tokens a bar), and a single section can differ with `{ "notes": "…", "stepsPerBeat": 1 }`.
+
+**Drums**: a groove by name, `four` (four on the floor), `backbeat`, `half` (half-time), `break`,
+`shuffle`, `hats`, `pulse` (kick only), `none`; `+fill` puts a snare and tom fill in the section's last
+bar (`"break+fill"`). Or write the bar yourself, one line per drum, `x` a hit, `X` an accent, `.`
+nothing, 16 cells a bar in 4/4 (the line repeats every bar):
+
+```json
+"drums": { "kick": "x.....x...x.....", "snare": "....x.......x...", "hat": "x.x.x.x.x.x.x.x.", "openhat": "..............x.", "fill": true }
+```
+
+Drums: `kick`, `snare`, `clap`, `hat`, `openhat`, `tom`, `rim`, `shaker`.
+
+## What makes it good
+
+- **A hook in the first bars.** The main melody should be singable: mostly steps, one leap, a note
+  held at the end of a phrase. Repeat it; change the last bar of the repeat.
+- **Contrast between sections**: the calm section drops the drums or the bass; the chase doubles
+  the bass rhythm and adds the break; the final seconds go up a key or add the open hat.
+- **Space for the game's effects.** A bed at -18 LUFS with the lead an octave away from the effects'
+  range; `duck` the pad and bass under the kick, and `sound.duck()` the music for big hits.
+- **Loops in 4 or 8 bars**, every loop the same tempo and key, so the game can switch on a bar line.
+- Listen with numbers: `analyze` each stem; a stem more than 12 dB under its neighbours is inaudible
+  in the mix, and a struck sound (a pluck, a bell) sits about 9 dB under a held one at the same peak,
+  so lengthen its decay instead of pushing its level.
+
+## Errors that name the fix
+
+A bar with the wrong number of steps, an unknown chord quality, a section that plays an instrument not
+in `instruments`, an arrangement naming a missing section: each stops the render with a sentence
+saying what and where. Fix that and render again; a render is free.

package/guides/sound/references/TRAPS.md

@@ -0,0 +1,93 @@
+# Traps: ffmpeg, expressions and synthesis
+
+Each of these produced silence, the wrong level or a click while every command exited 0.
+
+## ffmpeg
+
+- **Exit code 0 is not audio.** A graph that failed part-way still writes a file whose header promises
+  sound. Read it back: `ffprobe -v error -show_entries format=duration:stream=sample_rate,channels -of json <file>`,
+  and measure it (`sound.mjs analyze`). A duration of 0, or one far from what you asked for, is a
+  failed render with the right name.
+- **`c=2` on a source makes one channel.** `aevalsrc` and friends want a layout name (`c=stereo`,
+  `c=mono`) or `2c`; a bare number is read as a channel mask. Ask for the count on the output
+  (`-ac 2 -ar 48000`) and the source cannot be wrong about it.
+- **`amix` divides by the number of inputs** unless `normalize=0`: the levels you asked for never
+  arrive and nothing says so. (`sound.mjs mix` sums in JavaScript at the levels written.)
+- **`adelay` takes one value per channel** (`adelay=500|500`); a single value delays the left channel only.
+- **mp3 pads both ends with silence**: an effect starts late and a loop gaps at the wrap. Effects and
+  loops are WAV or Ogg; mp3 is for a page's player only.
+- **`<audio loop>` gaps at the wrap** in every browser: loop a decoded buffer in Web Audio
+  (`source.loop = true`).
+- There may be no `drawtext` in the user's ffmpeg build (it needs freetype): draw labels in a browser
+  or an image instead.
+- `loudnorm` needs 400 ms blocks: integrated LUFS of a 0.2 s effect is meaningless. Level short
+  effects by their loudest 50 ms (what `sound.mjs` does).
+- Encoders differ: many ffmpeg builds have no `libvorbis`; `libopus` in an `.ogg` is the fallback.
+  Older Safari cannot decode Ogg at all, so ship a WAV beside it.
+
+## aevalsrc expressions
+
+- **No comparison operators.** `t>=1` fails with a misleading "Missing ')'". Use `gte(t,1)`,
+  `lte()`, `gt()`, `lt()`, `between(t,a,b)`. There is no `sqr()`: `pow(x,2)`.
+- **`0*inf` is NaN and a NaN silences the whole sum.** An envelope like `exp(-(t-a)*k)*gte(t,a)`
+  overflows before the gate: write `exp(-max(0,t-a)*k)`.
+- **`random(x)` keeps its state in variable slot x** and overwrites it; put every `random` in one slot
+  (9) and keep `st()/ld()` state in 0..7. There is one random stream: to decorrelate a right channel,
+  advance it (`0*random(9)+…`). The first use of a slot must be its `st()`.
+- Quotes, backslashes, semicolons and brackets belong to ffmpeg's graph parser, not the expression;
+  keep expressions to arithmetic and functions. Very long expressions (a few thousand characters)
+  are fragile: split the terms across parts, they sum to the same thing.
+- `PI` may be missing: write `6.28318` for 2π.
+- One expression renders mono; two (left, right) render true stereo.
+
+## Pitch and phase
+
+- **In `synth.mjs` a number is hertz, always.** `freq: 110` is 110 Hz and `slide.to: 45` is 45 Hz.
+  A note is a name (`freq: "A2"`) or a MIDI number said out loud (`midi: 45`, `slide.toMidi: 45`,
+  or `hzOfMidi(45)`). There is no guessing by size: a number of 127 or less used to be read as a
+  MIDI note, and every bass note is a frequency under 127 Hz, so a 110 Hz bass came out at 4.7 kHz.
+- **A pitch bend is a change of frequency, integrated into phase.** `sin(2*PI*f(t)*t)` with a
+  changing `f` sweeps at twice the intended rate and runs backwards on the way down; the phase must be
+  the integral of the frequency (what `synth.mjs` does every sample). A scoop from below in closed
+  form is `+2π·df·τ·exp(-(t-a)/τ)` added to the phase.
+- Vibrato depth scales with pitch: ±0.4% of the frequency is about ±7 cents at any note.
+- A tremolo on one note is one voice whose envelope clock wraps (`mod(max(0,t-a)*rate,1)/rate`),
+  with the phase left running; restarting the phase each time clicks.
+- An uneven pulse wave (duty other than 50%) has a DC offset: subtract `2·duty - 1`, or high-pass the
+  result, or it clicks at every start and stop.
+
+## Loops and width
+
+- **A held sound loops without a click only if every frequency in it, beating pairs included, is a
+  whole multiple of 1/loop-length** (0.125 Hz for an 8 s loop) and no channel starts at a phase
+  offset. Notes whose envelope closes before the loop point are exempt. Or render the section three
+  times and keep the middle (what `sound.mjs score` does).
+- **Limit a loop before cutting it, not after.** A limiter run over the cut loop starts at full gain
+  and ends wherever the last bar left it: a step of gain at the wrap. `score` limits across the
+  three copies. A note, an echo or a reverb longer than the whole section still cannot repeat: the
+  seam goes over 1 and the report warns; make the section longer or the tail shorter.
+- **A 1-3 ms delay between channels widens a transient but cancels a held tone** in mono (a phone
+  speaker folds to mono): correlation fell to -0.2 and the note lost 4 dB. Widen held sounds by
+  detuning or by panning different notes, never by a channel offset; offset only the attacks.
+- Measure width with the stereo correlation and the mono loss (`analyze` gives both). Negative
+  correlation means parts cancel on a phone.
+
+## Levels
+
+- A struck sound (a pluck, a bell, a mallet) sits about 9 dB RMS under a held one at the same peak.
+  Lengthen its decay rather than raising its fader, then compare stems with their gains applied.
+- A generated room tone or ambience can carry a steady hum (a narrow line in the spectrum): `analyze`
+  lists narrow tones; notch them or regenerate. Each one comes with `prominenceDb` (over its
+  neighbours, which a filter does not change: the neighbours fall with it), `levelDb` (how loud it
+  is, dBFS), `energyShare` and `presentShare` (the share of the file it is there). Only a tone that
+  is prominent, above -60 dBFS and there 60% of the time or more is called steady; a melody's brief
+  high partial is listed and not warned about. Read its level and share to judge it.
+- Check every render at its head and tail as well as its peak: silence at the start of an effect is
+  latency; a tail cut mid-ring is a click.
+
+## Provider renders (when a model made the audio)
+
+- A paid render can land minutes after the command that asked for it timed out or failed. Before
+  asking again, list the output folder by time: the same request twice is twice the bill.
+- Before cutting a straight loop out of a swung track, find the onsets in the rendered file: a hit a
+  few ms early is a musical flam, not an error, and triplet grids suit a shuffle.