freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/skills/hyperframes-animation/transitions/overview.md

@@ -0,0 +1,153 @@
+# Scene Transitions
+
+A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+
+## Contents
+
+- Animation rules for multi-scene compositions
+- Energy and mood transition selection
+- Narrative position
+- Blur intensity
+- Presets
+- Implementation
+- CSS vs shader guidance
+- Shader-compatible CSS rules
+- Visual pattern warnings
+
+## Animation Rules for Multi-Scene Compositions
+
+These are non-negotiable for every multi-scene composition:
+
+1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
+2. **Every scene uses entrance animations.** Elements animate IN — opacity, position, scale, etc. No scene should pop fully-formed onto screen. Use `gsap.fromTo()` (not `gsap.from()`) so the start state is explicit: `from()` animates _to_ current CSS, so pairing it with CSS `opacity: 0` is a 0→0 noop and the element never appears (see `/hyperframes-core` → sub-compositions).
+3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
+4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
+
+```js
+// FAIL BANNED — fading the outgoing scene out, then the next scene just runs its entrance.
+//    This is a jump cut with a dip, not a transition.
+tl.to("#s1", { opacity: 0, duration: 0.4 }, 4.0);
+tl.from("#s2 .headline", { y: 40, opacity: 0 }, 4.4);
+
+// PASS CORRECT — outgoing and incoming animate AT THE SAME TIME T; the motion IS the handoff.
+const T = 4.0;
+tl.to("#s1", { yPercent: -100, filter: "blur(8px)", duration: 0.5, ease: "power3.in" }, T);
+tl.fromTo("#s2", { yPercent: 100 }, { yPercent: 0, duration: 0.5, ease: "power3.out" }, T);
+```
+
+> **You are NOT done after this file.** This overview gives you _which_ transition and _when_. Before writing any transition you MUST open **`catalog.md`** in this directory for the GSAP code and the hard rule every transition follows — _position new scene → animate outgoing → swap → animate incoming → clean up overlays_ — plus the per-category `css-*.md` files for specifics. Authoring transitions from this overview alone is how you end up shipping the FAIL pattern above.
+
+## Energy → Primary Transition
+
+| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
+| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
+| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
+| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
+| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
+
+Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
+
+## Mood → Transition Type
+
+Think about what the transition _communicates_, not just what it looks like.
+
+| Mood                     | Transitions                                                                                                                          | Why it works                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn · **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |
+| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens                                                   | Content transforms mechanically — compressed, shrunk, sliced, gridded.                      |
+| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |
+| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split                                  | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
+| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |
+| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |
+| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |
+| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black · **Shader:** cross-warp morph, thermal distortion                                    | Restraint. Cross-warp morph flows both scenes into each other organically.                  |
+| **Retro / analog**       | Film burn, light leak, VHS, clock wipe · **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |
+
+## Narrative Position
+
+| Position                   | Use                                                                        | Why                                                   |
+| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Opening**                | Your most distinctive transition. Match the mood. 0.4-0.6s                 | Sets the visual language for the entire piece.        |
+| **Between related points** | Your primary transition. Consistent. 0.3s                                  | Don't distract — the content is continuing.           |
+| **Topic change**           | Something different from your primary. Staggered blocks, shutter, squeeze. | Signals "new section" — the viewer's brain resets.    |
+| **Climax / hero reveal**   | Your boldest accent. Fastest or most dramatic.                             | This is the payoff — spend your best transition here. |
+| **Wind-down**              | Return to gentle. Blur crossfade, crossfade. 0.5-0.7s                      | Let the viewer exhale after the climax.               |
+| **Outro**                  | Slowest, simplest. Crossfade, color dip to black. 0.6-1.0s                 | Closure. Don't introduce new energy at the end.       |
+
+## Blur Intensity by Energy
+
+| Energy     | Blur    | Duration | Hold at peak |
+| ---------- | ------- | -------- | ------------ |
+| **Calm**   | 20-30px | 0.8-1.2s | 0.3-0.5s     |
+| **Medium** | 8-15px  | 0.4-0.6s | 0.1-0.2s     |
+| **High**   | 3-6px   | 0.2-0.3s | 0s           |
+
+## Presets
+
+| Preset     | Duration | Easing            |
+| ---------- | -------- | ----------------- |
+| `snappy`   | 0.2s     | `power4.inOut`    |
+| `smooth`   | 0.4s     | `power2.inOut`    |
+| `gentle`   | 0.6s     | `sine.inOut`      |
+| `dramatic` | 0.5s     | `power3.in` → out |
+| `instant`  | 0.15s    | `expo.inOut`      |
+| `luxe`     | 0.7s     | `power1.inOut`    |
+
+## Implementation
+
+Read `catalog.md` in this directory for GSAP code and hard rules for every transition type, and the `css-*.md` files for per-category implementation details.
+
+| Category    | CSS                                                            | Shader (WebGL)                                                            |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |
+| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |
+| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |
+| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |
+| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | —                                                                         |
+| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |
+| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
+| Pattern     | Grid dissolve, morph circle                                    | —                                                                         |
+
+## Transitions That Don't Work in CSS
+
+Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
+
+## CSS vs Shader
+
+CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
+
+**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
+
+**Mixing is supported.** You can have some transitions use WebGL shaders and others use a CSS crossfade in the same composition. Omit the `shader` field on any `TransitionConfig` entry to get a smooth opacity crossfade instead of a WebGL effect:
+
+```js
+var tl = HyperShader.init({
+  bgColor: "#000",
+  accentColor: "#6366f1",
+  scenes: ["s1", "s2", "s3", "s4"],
+  transitions: [
+    { time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader
+    { time: 8.5, duration: 0.8 }, // no shader → CSS crossfade
+    { time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader
+  ],
+});
+```
+
+HyperShader manages all scene visibility regardless of transition type. Let it create the timeline (don't pass `timeline:` into `init()`) and add your beat animations to the returned `tl` after the call.
+
+## Shader-Compatible CSS Rules
+
+Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
+
+1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
+2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
+3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
+4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
+5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
+6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.
+
+These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
+
+## Visual Pattern Warning
+
+Avoid transitions that create visible repeating geometric patterns — grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.

package/dist/assets/design/skills/hyperframes-audio/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: hyperframes-audio
+description: >
+  Use when audio already placed in a HyperFrames composition needs to be mixed:
+  fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking,
+  a music bed that fights a voiceover (voiceover carve), effects on a track
+  (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser,
+  bitcrush), automation envelopes drawn on a track's volume or any effect
+  parameter, or one submix bus carrying a chain, a fader and an automation clock
+  for several tracks at once (`<hf-audio-group>`).
+  Don't use for sourcing or generating audio — finding BGM, SFX, or making a
+  voiceover is `/media-use`. Don't use for clip timing or track layout, which is
+  `/hyperframes-core`.
+---
+
+# HyperFrames Audio
+
+A mix is a set of relationships, not a stack of processors. Two tracks that each
+sound right alone can be unlistenable together, and the fix is almost never "turn
+one down" — it is finding what they are fighting over and giving it to whichever
+one needs it. Every tool here exists to express one of those relationships.
+
+Effects live on the element as `data-fx-chain`, and preview and render run the
+same Web Audio graph — the studio in a live context, the engine in an offline one
+inside the browser it already drives. There is one implementation of each effect,
+so what you hear while scrubbing is what gets written. You never tune twice.
+
+Clip timing remains `/hyperframes-core`: audio/video trims and source ranges use
+`data-start`, `data-duration`, and `data-media-start`, and crossfades overlap
+clips on different tracks. This skill owns placed-track fade-in/fade-out,
+crossfade envelopes, track gain/track volume, volume and effect automation,
+ducking/voiceover carve, and the effect chain. `/media-use` owns sourcing,
+generation, and preprocessing.
+
+Constant `data-playback-rate` (`0.1..10`) is render-safe for picture and
+pitch-preserved sound when matching audio/video elements use the same timing,
+source offset, and rate. A speed ramp is a `rate` lane in `data-automation`
+(see `docs/reference/speed-ramps`); it wins over the constant and keeps pitch
+in preview and render. HyperFrames does not
+provide automatic waveform sync or drift correction.
+For copyable cut/crossfade/retime recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.
+
+Three attributes carry everything, on the audio/video element itself — or, for
+the first two, on an `<hf-audio-group>` bus (see "One bus for many tracks"):
+
+| Attribute         | Holds                                                     |
+| ----------------- | --------------------------------------------------------- |
+| `data-fx-chain`   | the effects, in signal order                              |
+| `data-automation` | envelopes on this track's volume or its effect parameters |
+| `data-fx-carve`   | the carve's own settings, so it can be re-derived         |
+
+The shipped effect families are gain, EQ (highpass, lowpass, peaking, shelves),
+compressor, limiter, gate, saturate, delay, reverb, chorus, phaser, and bitcrush.
+
+Exact JSON for each, and the rules a lane must satisfy: `references/attributes.md`.
+Every effect with its parameters, ranges and units: `references/fx-registry.md`.
+How to work out what is wrong with a file you cannot hear:
+`references/diagnosis.md`.
+**Presets, named jobs and one-knob profiles, plus a symptom-to-fix table:
+`references/presets.md`** — read that before hand-building a chain, because one
+of the presets or named jobs usually already names the problem.
+
+## How it fits together
+
+Two authoring surfaces write those attributes; two runtimes read them through the
+same builders. That shared middle is why preview predicts the render.
+
+```mermaid
+flowchart TB
+  voice["voice track<br/>media file"]
+  bed["music bed<br/>media file"]
+
+  subgraph AUTHOR["Authoring — the only things that write attributes"]
+    panel["Studio<br/>Voiceover carve control"]
+    script["scripts/carve.mjs<br/>detects the pair, dynamic by default"]
+    analysis["core/audioCarve.ts<br/>carveProfile · analyseCarveBands<br/>analyseCarveDuck · analyseCarveDynamics"]
+    panel --> analysis
+    script --> analysis
+  end
+
+  voice --> analysis
+  bed --> analysis
+
+  subgraph ATTRS["Written onto the bed element"]
+    carveAttr["data-fx-carve<br/>source · strength · dynamic"]
+    chainAttr["data-fx-chain<br/>peaking xN + gain, tagged fromCarve"]
+    autoAttr["data-automation<br/>a lane per carved parameter"]
+  end
+
+  analysis --> carveAttr
+  analysis --> chainAttr
+  analysis --> autoAttr
+
+  subgraph SHARED["One implementation, read by both"]
+    build["audioFxGraph.ts · buildFxChain"]
+    sched["audioFxAutomation.ts · scheduleChainAutomation"]
+  end
+
+  chainAttr --> build
+  autoAttr --> sched
+
+  build --> preview["Preview<br/>live AudioContext<br/>attachElementFxChain"]
+  sched --> preview
+  build --> render["Render<br/>OfflineAudioContext in the headless browser<br/>applyAudioFxChain"]
+  sched --> render
+
+  preview --> heard["what you hear while scrubbing"]
+  render --> wav["processed WAV<br/>+ chainTailSeconds so the mix lets the tail through"]
+  wav --> mix["engine · audioMixer<br/>volume lane baked into the PCM here, not in the graph"]
+  mix --> out["the rendered mix"]
+
+  edit["editing the attribute mid-playback"] -.->|MutationObserver| preview
+```
+
+The carve's own settings are never read at playback — the chain and lanes it
+produced are what play. `data-fx-carve` exists so strength can be changed on an
+existing carve instead of guessed back out of the filters.
+
+Inside a carved bed the signal runs through the dips first, then the level match,
+then anything you built yourself — which is why a limiter you add still acts as
+the last ceiling:
+
+```mermaid
+flowchart LR
+  src["decoded bed"] --> p1["peaking<br/>400 Hz"]
+  p1 --> p2["peaking<br/>1 kHz"]
+  p2 --> p3["peaking<br/>1.6 kHz"]
+  p3 --> g["gain<br/>level match"]
+  g --> hand["your own effects<br/>e.g. limiter"]
+  hand --> dest["track gain, then out"]
+
+  l1["lane fx.n1.gain"] -.->|"envelope of the voice's<br/>level in that band"| p1
+  l4["lane fx.n4.gain"] -.->|"how far the bed<br/>ducks overall"| g
+```
+
+A static carve is the same graph with fixed values and no lanes at all.
+
+## First, work out what is wrong
+
+The table below starts from "it sounds boomy" — which presumes somebody already
+listened and said so. Handed a file and "fix this", you have no such sentence
+and you cannot listen, so you have to measure. One rule governs all of it:
+
+> **The absolute spectrum of a single unknown voice cannot be diagnosed.**
+> Formants are ±10 dB, fundamentals run 85–255 Hz, and sentences decline 5–6 dB
+> as they end. Every one of those reads as a defect on its own, and every one of
+> them is the speaker.
+
+So compare, and compare against something **inside the same file**: the clean
+original if it exists, otherwise the pauses — whatever is audible in a gap is
+additive, and the gap's spectrum is the channel rather than the voice. Comparing
+against a published average spectrum or a synthesised control voice does not
+work: two speakers differ by more than most defects, and both wrong answers in
+the evaluation behind this guidance came from exactly that.
+
+When there is no original and no usable silence, a static tonal defect is
+genuinely under-determined. Say so and offer the readings that fit, rather than
+picking one and building a chain on it.
+
+Commands, traps and worked recipes: **`references/diagnosis.md`**. Read it
+before diagnosing a file nobody has described.
+
+## Start from the symptom
+
+Once you know the band and the kind, name what is wrong with the audio. Most bad audio is
+one or two of these, and each has a shipped answer:
+
+| It sounds like                     | Reach for                                          |
+| ---------------------------------- | -------------------------------------------------- |
+| Hum or thump underneath            | `rumble-cut`, or a `highpass` at 80 Hz             |
+| Boomy, chesty                      | **Tame Boominess** job (200 Hz)                    |
+| Muffled, behind cardboard          | **Reduce Mud** job (250 Hz)                        |
+| Words hard to make out             | **Add Clarity** job (3 kHz), or carve the bed      |
+| Harsh and tiring                   | **Soften Harshness** job (3.2 kHz)                 |
+| Some words much louder than others | **Evenness** on a compressor, or Even Out Levels   |
+| Room tone between sentences        | `room-gate`                                        |
+| Voice and music fighting           | **Voiceover carve** — not an EQ on either          |
+| Dry, recorded nowhere              | `room-tight` or `room-natural`                     |
+| Just "amateur"                     | `voice-clean`, which is four of the above in order |
+
+Full catalogue, what each preset contains, the band vocabulary, and what is
+deliberately NOT covered (de-essing, noise removal, tone match):
+`references/presets.md`.
+
+Subtract before you add, level after you filter, relationships after level,
+character and ceiling last. Each step changes what the next one hears — a
+compressor set before a high-pass spends its time chasing rumble.
+
+## Reach for a family by the problem, not the name
+
+**Filters** (`highpass`, `lowpass`, `peaking`, `lowshelf`, `highshelf`) decide
+which frequencies a track is allowed to occupy. This is the first tool for two
+sources colliding, because collisions happen in bands: a bed and a voice both
+want 1–3 kHz, and taking that from the bed costs the bed far less than turning
+the whole thing down costs the mix. A high-pass on a voice is the standard fix
+for rumble; a low-pass darkens or muffles deliberately.
+
+**Dynamics** (`gain`, `compressor`, `limiter`, `gate`) decide how a track's level
+behaves over time. Compression narrows the distance between loud and quiet so the
+quiet parts can come up. A limiter is a ceiling — it does not shape anything, it
+guarantees nothing gets past. A gate removes what is below a threshold, which is
+how you silence room tone between phrases. `gain` is a plain level stage, and it
+is what an automation lane rides when a track has to move out of the way.
+
+**Nonlinear** (`saturate`, `bitcrush`) changes the waveform's shape, which adds
+harmonics that were not there. Reach for it when a track needs character or
+grit rather than correction — and remember it is generative: it makes a thin
+source denser, not cleaner.
+
+**Time** (`delay`, `reverb`, `chorus`, `phaser`) puts a track in a space or gives
+it width. These are the ones that most easily wreck a mix, because a tail or a
+detuned copy occupies the same room a voice needs. Use them on the thing that
+should sit _behind_ something else, and keep the wet amount lower than sounds
+right in isolation.
+
+The chain is serial: each effect processes what the one before it produced. So
+corrective filtering goes early, character in the middle, and a limiter last
+where it can actually act as a ceiling.
+
+## Voiceover carve
+
+**The problem it solves.** A music bed under a voice makes the voice hard to
+follow. The reflex is to duck the whole bed, which works and costs the bed all of
+its presence — the music goes limp for the entire voiceover. But the voice does
+not need the whole spectrum. It needs the few bands it actually occupies. Carve
+takes only those, and the bed keeps its low end and its top, so it is still music
+while the voice is still intelligible.
+
+**It is a relationship, not an effect.** The settings live on the _bed_ — the
+track that gets processed — and they name the voices to listen to, exactly as a
+sidechain compressor does: you select the track that gets quieter and pick what
+makes it quieter. **Never put a carve on a voice track.** A voice carved against
+itself is a bug, not a subtle mix choice.
+
+**Every voice, not one of them.** `sources` is a list, because a bed usually runs
+under a whole sequence — a narrator, an interview answer, a second presenter. They
+are summed onto the bed's own clock before anything is measured (`mixCarveSources`),
+so one analysis covers all of them: the bands come from all the speech there is, and
+the envelopes rise wherever any of it is happening. Voices that never play while the
+bed does are left out; they cannot mask it.
+
+**A carve against more than one clip id is wrong. Group the clips and carve
+against the group.** This is an invariant, not a tip. Naming clips one by one has
+to be exhaustively right and stays right only until the next edit — a fourth
+narration clip added later plays outside the carve's awareness, and the bed
+fails to duck under it silently. Naming the group instead resolves membership at
+analysis time, so a clip added to the group later is covered without touching
+`sources` at all:
+
+```html
+<!-- group the narration, then carve the bed against the group -->
+<audio id="vo-intro" data-audio-group="voiceover" …></audio>
+<audio id="vo-middle" data-audio-group="voiceover" …></audio>
+<audio id="vo-outro" data-audio-group="voiceover" …></audio>
+
+<audio id="music" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.8}' …></audio>
+```
+
+A `sources` list naming two or more plain clip ids instead of a group is caught
+by the `audio_carve_ungrouped_sources` lint rule — it still works, but it is the
+version that silently rots when a clip is added.
+
+**Keep the carve group a voice group: no bed, no SFX, no music.** A group id in
+`sources` resolves to every _current_ member on _every_ analysis, so the group
+you name is the group you get later — not the tracks that were measured when it
+was written. Two ways that bites:
+
+- **The bed in its own source group.** It is handed to itself as a voice and
+  carved against its own content — the "never carve a track against itself" rule
+  arriving one re-analysis later.
+- **An SFX or music clip in the voice group.** It enters the sidechain on the
+  next analysis and the bed starts ducking under a whoosh, even though the run
+  that wrote the attribute never measured it.
+
+Both are invisible at the moment the carve is written: the analysis sums the
+voices it detected and never round-trips through group resolution, so the first
+pass is genuinely correct and only the next one is wrong. So give each role its
+own group — `music` for the bed, `voiceover` for the narration, `sfx` for the
+hits — and keep the group named in `sources` holding nothing but voices.
+
+`carve.mjs` refuses to write the group form when it sees either case, records
+clip ids, and says on stderr which member blocked it. The
+`audio_carve_ungrouped_sources` rule then points at the arrangement instead of
+the CLI quietly persisting a wider carve than it measured.
+
+A voice that this run left out is **not** one of these cases and does not block
+the group form: `carve.mjs` only analyses voices that overlap the bed, and
+picking up a clip that plays later without an edit to `sources` is the whole
+reason to name the group.
+
+### One bus for many tracks
+
+Membership alone is enough to carve against, as above — but add an
+`<hf-audio-group>` element with that id and the group becomes a real submix bus:
+one chain, one fader, one automation clock for every member.
+
+```html
+<hf-audio-group
+  id="voiceover"
+  data-label="Voiceover"
+  data-volume="0.9"
+  data-fx-chain='{"version":1,"nodes":[
+    {"type":"compressor","id":"g1","params":{"threshold":-18,"ratio":3}},
+    {"type":"peaking","id":"g2","params":{"frequency":3000,"gain":2,"q":1}}]}'
+></hf-audio-group>
+
+<audio id="vo-intro" data-audio-group="voiceover" …></audio>
+<audio id="vo-middle" data-audio-group="voiceover" …></audio>
+```
+
+**Reach for the bus when the same treatment belongs on several tracks.** Four
+narration clips that each want the same compressor is four chains to keep in
+step, and they drift the moment one is edited; on the bus it is one chain, and
+the compressor sees the whole voice rather than each clip in isolation — which is
+the point, since a compressor cannot ride a sequence it only hears a third of.
+Per-clip chains remain right for what is genuinely per-clip: one noisy take that
+needs its own de-esser.
+
+| On the bus        | Does                                      |
+| ----------------- | ----------------------------------------- |
+| `data-fx-chain`   | one chain over the summed members         |
+| `data-automation` | envelopes on the bus, in COMPOSITION time |
+| `data-volume`     | one fader for every member (default 1)    |
+| `data-label`      | the display name; falls back to the id    |
+| `data-hidden`     | drops every member from the mix           |
+
+**Group automation is composition time, not clip time.** A bus has no
+`data-start` — members are already at their composition positions when they
+reach it — so `t: 0` in a group lane is the start of the composition, not of any
+clip. A lane on a clip is clip-local; the same numbers mean different instants on
+the two, which is the one thing to get right when moving an envelope from a clip
+up onto its bus.
+
+**A carve stays on the clip.** `data-fx-carve` is not a group attribute. The bed
+being carved is a single track, and it is that track which carries
+`data-fx-carve` — pointed AT a group, per the rule above. Group and carve meet in
+`sources`, not on one element. A carve written onto a bus is half an effect
+applied twice: the level half measures the bed's own audio, which a bus has none
+of, so only the filters survive — and a bus and its members are one signal path,
+so the bed then runs through the bus's filters AND its own. The
+`audio_group_carve_attr` lint rule catches it.
+
+**One clip is not a bus.** A group exists to give several tracks one chain, one
+fader and one clock. Wrapping a single clip in a bus buys nothing the clip's own
+`data-fx-chain` does not already do, and it doubles the places a later edit has
+to land. The one reason to do it anyway: a bus's automation clock is composition
+time, so a single-member bus is how a lane on that clip gets composition-time
+timing.
+
+**One knob.** `strength` is 0..1 and derives everything: how deep to cut, how
+many bands, how wide, how far to favour intelligibility over raw voice energy,
+how far the level may drop, how far under the voice to aim. Those six move
+together in any real mix — a gentle carve is a shallow cut in few bands with
+little ducking, a hard one is deeper in more bands with more — so they are one
+relationship written once, in `carveProfile`. `carve.mjs` defaults to `0.8` —
+six bands from 250 Hz to 2.5 kHz cut about 7 dB each and 15 dB at 1.6 kHz, with
+19 dB of level room — because a bed under narration has to get out of the way
+first and be music second; `0.25` (a 6 dB dip in three bands, 6 dB of room) kept
+the bed present but still let it fight the voice, and was judged too weak in
+practice. At `0.5` the dip reaches 10 dB, which is where a carve starts being
+heard as an effect rather than as room for the voice. Drop the strength when the
+bed is the point and the voice is sparse. `0` is spectral only — one band, no
+level match at all.
+
+**Carve by default — required whenever music plays under a voice.** A bed
+under any voice track (narration, avatar speech, interview, voiceover) gets a
+carve as part of finishing the mix, not as a polish step to get to if there is
+time. Place both tracks, run the command below (default strength `0.8`; add
+`--bed` / `--voice` when detection picks wrong), confirm the written
+`data-fx-carve`, `data-fx-chain` and `data-automation` with `freecodego_design_lint`,
+and only then render. A volume duck on its own is not a finished mix: it leaves
+the voice and the bed fighting in the 1–3 kHz band and costs the bed all of its
+presence for the whole voiceover. Skip the carve only when there is no voice for
+the music to sit under — a music video, a title card, a montage cut to the track.
+
+**It always follows the voice.** There is no static mode: a fixed depth thins the
+bed through every pause, and once you have heard both there is no reason to want it.
+Every value becomes an envelope of the speech's own level — silence leaves the bed
+alone, a loud passage pushes the carve to full depth — written as ordinary automation,
+which is why the lanes show up in the timeline and can be edited afterwards.
+
+**Level matching is part of it.** Spectral carving cannot fix a bed that is
+simply louder than the voice. So the carve also measures how far over the voice
+the bed sits and writes a `gain` stage: held at one value for a static carve,
+driven by an envelope for a dynamic one. That envelope releases slowly on
+purpose — music that snaps back to full the instant a word ends sounds like a
+machine doing it.
+
+**Running it.** In Studio the carve is one module at the top of a track's effect
+rack — voice, strength, dynamic, and the analysis it produced, in one card. It is
+there whenever another track could be the voice, and a bed with exactly **one**
+candidate above it is carved by default, dynamically, at the default strength:
+that is what a bed under narration wants, and the module is where you change or
+switch it off. Several candidates leaves the picker waiting rather than guessing.
+Headless —
+which is the path when you are authoring a composition rather than editing one:
+
+```bash
+node <SKILL_DIR>/scripts/carve.mjs --comp index.html
+```
+
+That is the whole command. It finds the voice and the bed itself, carves
+dynamically at the default strength, and prints what it decided:
+
+```
+bed    music-bed (name looks like music)
+voice  narration (only track left)
+carve  strength 0.8 dynamic
+bands  250Hz -7.4dB q2.06, 400Hz -7.4dB q2.06, 630Hz -7.4dB q2.06, 1000Hz -7.4dB q2.06, 1600Hz -14.8dB q2.06, 2500Hz -7.4dB q2.06
+level  273-point envelope, floor -19.2 dB
+```
+
+Name the tracks with `--bed` / `--voice` (repeatable) when the automatic choice is
+wrong, `--strength` to push it, `--dry-run` to see that report and write nothing.
+
+**How it picks the tracks.** Names first, because that is what you already told it
+and the answer is explainable — `classifyAudioName` in core, the same classifier
+Studio's own picker uses, so the two cannot disagree. A track whose id or filename
+looks like music (`music`, `bgm`, `bed`, `score`…) is the bed; everything else that
+plays over it and is not SFX-shaped is a voice. Audio elements are preferred: video
+counts only when no audio track is left to be the voice, or every B-roll clip in the
+composition would read as somebody talking. **It refuses when it cannot tell which
+track is the bed** rather than carving the wrong one — typing one id is cheap.
+
+Same analysis functions as the panel, so the result is identical. Needs `ffmpeg`
+on PATH and `@hyperframes/core` installed in the project (`npm i -D
+@hyperframes/core`) — the CLI inlines core rather than shipping it, so it cannot
+be borrowed from there.
+
+**What it writes** is an ordinary chain of peaking filters plus a gain stage,
+tagged `fromCarve`. That tagging is the whole trick: a re-run replaces the
+previous carve and leaves every effect you built by hand — and every lane you
+drew by hand — exactly where it was. So re-carving at a new strength is safe and
+repeatable, and `data-fx-carve` exists so the settings can be read back rather
+than guessed from the filters.
+
+## Automation
+
+A lane is a set of breakpoints on one parameter: `{t, v}` in clip-local seconds
+and the parameter's own units. Targets are `volume` for the track's level, or
+`fx.<nodeId>.<param>` for an effect's knob.
+
+**Only some parameters can be automated, and a lane on the others is silently
+inert.** A knob is automatable when a Web Audio `AudioParam` backs it. The four
+worklet-based effects — `compressor`, `limiter`, `gate`, `bitcrush` — expose
+none at all, so no lane on any of their parameters will ever move: to make a
+compressor's behaviour change over time, automate a `gain` stage before it
+instead. `references/fx-registry.md` marks every parameter.
+
+## Verify
+
+Almost no static gate covers the mix. The linter reads `data-automation` for
+exactly one conflict — `audio_volume_double_automation`, a volume lane on a track
+that also has a GSAP tween on `volume`, where the lane wins and the tween is
+ignored — plus `audio_volume_tween_overrides_gain`, an authored `data-volume`
+on a track whose `volume` is tweened, where the tween's values are absolute and
+replace that gain instead of scaling it. Nothing validates the
+chain or the effect lanes at all. What
+enforces those is the render: a chain it cannot parse fails the whole mix rather
+than quietly writing the dry signal, because a mix that sounds plausible and is
+wrong is worse than a refusal. Preview is the opposite by design: an unreadable
+chain plays dry so the composition stays workable.
+
+A lane pointing at a node the chain does not have is pruned on read, not an
+error — so a typo'd `nodeId` costs you the envelope silently. Read the ids back
+out of the chain rather than assuming what was minted.
+
+Effects with a tail (`reverb`, `delay`) make the rendered track **longer** than
+its source, and the mix is told how much by the chain. So a bed with reverb no
+longer ends exactly at its `data-duration`; that is expected, not a bug.
+
+Beyond that, a mix is verified by rendering and listening. For a carve: the voice
+should be legible without the bed sounding hollowed, and with `dynamic` the bed
+should come back up between phrases rather than staying flat. If the bed sounds
+notched rather than simply quieter under the voice, the strength is too high —
+that is the one failure mode with an obvious sound.