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

package/dist/assets/design/skills/music-to-video/references/frame-skeleton.md

@@ -0,0 +1,100 @@
+# Frame skeleton (Step 2) — read the music, lay out the frames
+
+At Step 2 **you (the orchestrator)** read `audiomap.json` and write the **skeleton** of
+`STORYBOARD.md` directly: cut the track into **frames** (one frame = one composition file =
+one scene), and for each frame set its **span**, its **pacing** (does this stretch want hard
+beat-cuts, or calm phrase/energy flow?), its **mood**, and a one-line **feel** note.
+
+You **classify and lay out the spine only.** You do **not** pick templates, write copy, choose
+colors/fonts, or decide a frame's groups — those are Step 3 (the plan fills each frame in
+place). Leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank.
+
+There is **no intermediate JSON** — the skeleton _is_ the start of `STORYBOARD.md`. Step 3
+edits the same file.
+
+## The trust boundary (read this first)
+
+`audiomap.json` is one analyzer's output. Some fields are robust on **any** music; some are
+reliable only when the music is **actually rhythmic**. This decides each frame's `pacing`:
+
+| Field                                                                                                                                                                                               | Trust                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `energy_phases[]` (level / energy / density / feel), `events[]` + `onset_rate`, `rolls[]` (and their **absence**), `silences[]`, `hard_stops[]`, `key_moments[]`, `phrases[]`, `audio.duration_sec` | **Always** — robust measurements                                                                                                                                                                                             |
+| `tempo.bpm`, `grid.beats_sec` / `downbeats_sec` **precision**                                                                                                                                       | **Only when the music is rhythmic.** On calm / sparse material the beat grid is a metronome the tracker _imposes_ (often octave-doubled) — usually **more grid beats than real onsets**. Do **not** anchor cuts to it there. |
+
+- **Grid is reliable** when: rolls present, and/or dense phases, and/or high `onset_rate` with a steady grid.
+- **Grid is fictional** when: `rolls`≈0, mostly `sparse` phases, low `onset_rate` → pace by `phrases[]` + `energy_phases[]`, not beats.
+
+## How to lay out frames (run in order)
+
+1. **Gestalt.** From `summary` / `tempo` / `audio.duration_sec` + the roll count, write the
+   frontmatter `compositionId`, `duration_s` (== `audio.duration_sec`), `canvas`, and a
+   one-line read of the track's density arc.
+2. **Cut into frames.** Walk `energy_phases[]` and split where the music genuinely changes
+   state — at `hard_stops[]`, `SURGE` / `DROP` `key_moments`, the start/end of a `rolls[]` run,
+   an **onset desert** (a long gap in `events[]`), or a big energy-level jump. Collapse adjacent
+   phases that are one gesture. Expect **~1–6 frames**; a short clip may be one.
+   **Snap every boundary to an audiomap anchor**, then re-snap to the nearest `beats_sec`
+   (tolerance ≤ ½ beat) **only when the grid is reliable**; on calm material snap to
+   `phrases[]` / `energy_phases[]` edges instead. Frames **tile the track** (first at 0, last
+   at `duration_s`, no gaps/overlaps).
+3. **Per frame, set `pacing`** — the trust-boundary call:
+   - **`beat_cut`** — genuinely rhythmic: a roll present, **or** dense, **or** (clearly high `onset_rate` **and** a steady grid). Hard cuts / per-onset reveals may anchor to beats.
+   - **`phrase_flow`** — calm / sparse: `rolls`≈0, mostly sparse, low `onset_rate`. Do **not** anchor hard cuts to the grid; pace by `phrases[]` + the energy envelope (slow crossfades, long holds).
+4. **Per frame, tag `mood`** (1–3 of: `warm` · `dark` · `hype` · `elegant` · `glitch` ·
+   `cinematic` · `playful` · `tense` · `dreamy` · `aggressive`) from `energy_phases[].feel` +
+   energy + any genre cue in the brief/title.
+5. **Per frame, write a one-line `feel`** — the plain-language music situation Step 3 matches a
+   template against (e.g. "accelerating onset stream into a held downbeat", "calm held pad, one
+   onset desert", "fast sustained-fill roll, no readable message"). This is what the planner
+   reads against the catalog's **Reach for it when** — keep it concrete, drawn from the robust
+   fields, never invented.
+
+## What the skeleton looks like
+
+A valid `STORYBOARD.md` with the spine set and every frame's treatment left for Step 3
+(full syntax in [`storyboard-format.md`](storyboard-format.md)):
+
+```markdown
+---
+compositionId: bgm
+duration_s: 30.0 # == audiomap.audio.duration_sec
+canvas: { w: 1920, h: 1080, fps: 30 }
+style: # blank — Step 3 fills it from the chosen frame.md preset
+build_notes: ["one paused timeline per frame", "no remote assets"]
+---
+
+## Frame 1 — f1
+
+- src: compositions/frames/01-f1.html
+- duration: 7.198s # = span length; assembler sums these for cumulative data-start
+- span_sec: [0.0, 7.198] # track seconds; frames tile the track
+- pacing: beat_cut
+- mood: [hype]
+- feel: accelerating onset stream building into a held downbeat
+
+### Groups
+
+- TBD (Step 3)
+
+## Frame 2 — f2
+
+- src: compositions/frames/02-f2.html
+- duration: 10.4s
+- span_sec: [7.198, 17.598]
+- pacing: phrase_flow
+- mood: [warm, cinematic]
+- feel: calm held pad, one long onset desert
+
+### Groups
+
+- TBD (Step 3)
+```
+
+## Self-check
+
+- `duration_s == audiomap.audio.duration_sec`; frames tile the track gap-free (first at 0, last at `duration_s`).
+- Every frame has `src` + `span_sec` + `duration` + `pacing` + `mood` + a one-line `feel`.
+- `pacing` was set from the **robust** fields (energy / density / rolls / onset_rate), never from `bpm` / `beats_sec` alone.
+- No frame boundary sits inside a `rolls[]` run or leaves a sub-1-bar fragment.
+- Every frame's `### Groups` is `TBD (Step 3)`; `style` is blank. **No template, copy, color, or font anywhere.**

package/dist/assets/design/skills/music-to-video/references/montage.md

@@ -0,0 +1,55 @@
+# Asset treatments — weaving user media onto the beat spine
+
+When the user supplies images/videos, a group can be an **asset treatment** instead of a
+typographic template/free-compose. Assets are an **additive ingredient on the same beat
+spine** — never a separate pipeline. Typography/templates stay the floor: if no asset fits a
+group, fall back to a template/free group (a complete video needs zero assets).
+
+The planner (Step 3) picks the treatment and the clips + anchors (WHAT); the frame-worker
+realizes it inside the frame file (HOW). **Obey the frame's `pacing`.**
+
+## The three treatments
+
+### `beat_cut` — one clip per anchor (only on a `beat_cut` frame)
+
+The asset-driven analogue of a per-onset typographic group: cut to a new clip on each anchor
+(the frame's beats/onsets from the audiomap). Each clip is a `class="clip"` element
+(`<img>` for a photo, **muted** `<video>` for a motion clip) placed at its anchor with
+`data-start`/`data-duration`/`data-track-index` per the core clip contract. Between clips,
+crossfade the outgoing content to `opacity:0` ending **at** the next anchor.
+Cut on the **strong** anchors; land a hero clip on a `key_moment`/downbeat.
+
+### `ken_burns` — slow push on one clip (fits a `phrase_flow` frame)
+
+For calm frames: one clip held over the span with a slow scale/translate push (e.g. scale
+1.0→1.08 + a small drift) eased across the whole `span_sec` — paced by the frame, not by
+beats. No hard cuts. Crossfade in/out at the frame edges. This is the right asset treatment
+when the beat grid is unreliable (calm music).
+
+### `bg_under_text` — clip dimmed behind a template/free group
+
+A full-bleed clip dimmed ~30–50% as the background of a group whose foreground is a template
+or free-compose typographic treatment. The text rides on the same anchors; the clip is the
+bed. Use when the user wants their footage present but the message must stay readable.
+
+## Rules
+
+- **`pacing` decides the treatment**: `beat_cut` only on a `beat_cut` frame; on a
+  `phrase_flow` frame use `ken_burns` or a slow crossfade — **never** per-onset hard cuts on
+  the (unreliable) calm grid.
+- **Clips are muted; the root owns audio.** Mount each `<video class="clip">` **muted**, as a
+  direct child of the frame root (never nested in another timed element, or the renderer
+  freezes it). The BGM is the only audio in v1.
+- **Crossfades animate `opacity`/`autoAlpha`**, never `visibility`/`display` on a `.clip`
+  (the framework owns clip visibility — that trips `gsap_animates_clip_element`).
+- **Backgrounds dim ~30–50%** so any foreground text stays legible.
+- Anchors are **track seconds from `audiomap.json`**; the worker subtracts the frame start
+  to get frame-local time.
+- Local staged assets only (`assets/` via `stage-assets.mjs`); never remote URLs.
+
+## Deferred hook (not v1)
+
+A clip that should play **its own sound** (interview cut, lyric clip) needs a sibling
+`<audio>` mounted at the **root** by the assembler, with the BGM ducked under it (a
+`data-automation` volume lane on the BGM, see `creator-editing-recipes.md` in `hyperframes-core`). The frame-worker mounts no audio. Keep clips muted in v1; wire clip-audio +
+ducking only when the user asks.

package/dist/assets/design/skills/music-to-video/references/motion-primitive-catalog.md

@@ -0,0 +1,75 @@
+# Motion-primitive catalog — the free-compose menu
+
+The atomic layer: one anchor → one micro-move. When no template fits a group, free-compose by
+naming primitives from here. Scan **anchor** + **best span** + **what it does**, then pick the
+smallest set that carries the group.
+
+## Timing & latency (applies to every primitive)
+
+- **Hard hits are 0ms.** Cuts, palette flips, content swaps, freezes are `tl.set(...)` with no duration — the percussion _is_ the motion. Easing a hit kills it.
+- **Lead the anchor.** A move that must _land_ on a beat (a wipe covering the frame, a count-up locking, two blocks colliding) starts **~40–190ms early** so it completes ON the anchor. Reactive entrances (something appearing _because_ of the hit) fire 0–45ms after.
+- **Eased entrances: 300–500ms** (scale punch, slides, camera pushes). **Macro builds: 800–2000ms** spanning a whole roll / silence.
+- **Per-bar caps:** one accumulating element per hit (not a burst); a camera move at most once per phrase, never per beat; a dense flip/strobe system runs ≤2–3s.
+- **Tension-builds lock.** A count-up / sequential build / morph must _resolve on_ a downbeat or hard_stop, never trail off mid-bar.
+- **Best span means active motion.** The catalog's span guidance is not a license to stretch one primitive over a whole frame. If a free-composed group runs longer than the listed span, add a hold / bed / next primitive, or split the frame into another group at the next musical anchor.
+
+## Catalog
+
+| id                    | anchor                           | best span         | what it does                                                              |
+| --------------------- | -------------------------------- | ----------------- | ------------------------------------------------------------------------- |
+| `hypercut-whip`       | beat / hard_stop                 | 0.18-0.45s        | fast whip-pan hard cut between frames                                     |
+| `kinetic-letter-in`   | downbeat / phrase                | 0.4-1.2s          | per-letter kinetic entrance                                               |
+| `braam-punch`         | drop / surge                     | 0.2-0.9s active   | big impact: scale + weight slam                                           |
+| `chromatic-split`     | snare / glitch / surge           | 0.1-0.6s          | RGB channel split / glitch on a word                                      |
+| `mask-reveal`         | section_start / downbeat         | 0.5-1.2s          | clip-path mask wipe reveal                                                |
+| `screen-shake`        | drop / crash / kick              | 0.1-0.5s          | camera / screen shake jitter                                              |
+| `binary-decrypt`      | roll / build                     | 0.8-2.5s          | scramble→decode text (binary → word)                                      |
+| `dolly-zoom`          | phrase / build                   | 1.2-2.5s          | vertigo dolly-zoom (scale vs perspective)                                 |
+| `iris-open`           | section_start / reveal           | 0.6-1.2s          | circular iris-open reveal                                                 |
+| `electric-arc`        | accent / glitch                  | 0.1-0.6s          | electric arc / lightning accent                                           |
+| `neon-flicker`        | hold / texture                   | 0.5-2.5s          | neon-sign flicker                                                         |
+| `chrome-sweep`        | downbeat / reveal                | 0.6-1.4s          | metallic specular sweep across text                                       |
+| `slot-machine-reveal` | roll → downbeat                  | 0.8-2.0s          | slot-machine spin-to-land character reveal                                |
+| `liquid-morph`        | phrase / transition              | 1.0-2.5s          | liquid / blob morph                                                       |
+| `gooey-metaball`      | build / drop                     | 1.5-3.0s          | gooey metaball merge field                                                |
+| `3d-card-flip`        | downbeat / swap                  | 0.8-1.6s          | 3D card flip (rotateY)                                                    |
+| `crash-zoom-in`       | drop / surge                     | 0.2-0.8s          | violent crash zoom-in                                                     |
+| `spotlight-sweep`     | reveal / hold                    | 0.8-2.0s          | spotlight / gradient sweep over text                                      |
+| `outline-to-fill`     | downbeat / reveal                | 0.8-1.8s          | stroke outline → solid fill                                               |
+| `counting-punch`      | roll → downbeat                  | 1.0-2.5s          | number count-up that punches & locks                                      |
+| `particle-burst`      | drop / crash                     | 0.2-1.2s          | particle explosion burst                                                  |
+| `radial-burst-lines`  | drop / surge                     | 0.2-0.8s          | radial speed-lines burst                                                  |
+| `pixel-dissolve`      | transition / hard_stop           | 0.5-1.5s          | pixelated dissolve                                                        |
+| `datamosh-smear`      | glitch / transition              | 0.4-1.2s          | datamosh / motion smear                                                   |
+| `text-wave-distort`   | hold / texture                   | 1.0-2.5s          | wavy text distortion                                                      |
+| `bg-flow-field`       | energy / whole span (bed)        | 4-12s bed         | generative curl-noise background bed; compose any foreground move over it |
+| `blur-resolve`        | stop / final hold                | 0.7-2.0s          | blur-in to crisp focus, then blur-out on the cut                          |
+| `chromatic-pressure`  | snare / glitch                   | 0.1-0.5s          | RGB split / digital tension on a transient                                |
+| `color-grid-shuffle`  | onset                            | 0ms hits; ≤2s run | grid of cells recolored by a deterministic index per onset                |
+| `content-swap`        | beat                             | 0ms hits; ≤3s run | 0ms swap of stacked nodes: the workhorse percussive move                  |
+| `directional-fill`    | beat / reveal                    | 0.3-1.0s each     | directional wipe-fill (scaleX) sweeping across bars                       |
+| `flash-cut`           | drop / crash                     | 0-0.6s            | full-frame flash masking a word / color state change                      |
+| `freeze-hold`         | hard_stop                        | 0ms in; 0.5-2s    | freeze the moving system and hold it                                      |
+| `hard-cut`            | beat / hard_stop                 | 0ms in; 0.3-2s    | sample-accurate color-block + word cut                                    |
+| `mosaic-pack`         | beat / build                     | 1.5-3.5s          | scattered tiles fly in and pack into a grid                               |
+| `negative-space-hold` | silence / hard_stop / final hold | 1-6s hold         | kill busy layers, hold one readable mark in empty space                   |
+| `overlay-pop`         | accent                           | 0.2-0.6s in       | badge / lower-third overlay pops in over a base                           |
+| `palette-flip`        | section change                   | 0ms flip; 0.5-4s  | same layout re-skins via 0ms palette-variable flips                       |
+| `staggered-exit`      | phrase / transition              | 0.4-1.2s          | ordered cascade-out clearing the frame                                    |
+| `staggered-reveal`    | build                            | 0.8-2.5s          | ordered cascade-in of a stack / list                                      |
+| `system-replace`      | drop / regime change             | 0ms cut           | hard-cut the entire visual system, then boot the new one                  |
+| `text-spectral-rays`  | phrase / sweep (hero text)       | 2.5-5s            | volumetric light-rays cast by a wordmark toward a sweeping light cursor   |
+| `tile-mosaic`         | build / reveal                   | 1.5-3.5s          | grid of tiles revealed in a diagonal sweep, assembling a poster           |
+| `typewriter-reveal`   | roll / build                     | 1.0-3.0s          | character / word type-on with caret                                       |
+| `value-counter`       | roll → downbeat                  | 1.0-2.5s          | count-up that locks on a downbeat / hard_stop                             |
+| `word-grid-burst`     | onsets → downbeat                | 1.8-3.2s          | grid of words revealed per onset, refocus one on a downbeat               |
+
+## How to combine
+
+- One dominant system per group; layer at most one texture primitive over one structural primitive.
+- Structure on strong beats (cuts, camera, `system-replace` → downbeat / phrase / section_start); texture on weak / syncopated hits (`content-swap`, typewriter letters, chromatic accents).
+- A roll is an accumulation container — build during it, hard-cut to a clean layout on the downbeat that ends it.
+- `drop` ≠ `downbeat`: a downbeat is a cut within the regime; a drop is a regime change (`system-replace`, total clear, element-count jump).
+- Let silence remove density (`negative-space-hold`).
+- Background beds are a layer, not a move: one bed at a time, under foreground primitives.
+- `text-spectral-rays` is the hero wordmark treatment; do not stack another visible copy of the same word on top.

package/dist/assets/design/skills/music-to-video/references/motion-primitives/3d-card-flip/index.html

@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>18 · 3d_card_flip</title>
+    <script src="../assets/gsap.min.js"></script>
+    <style>
+      :root {
+        --hg-violet: #7c3aed;
+        --hg-violet-2: #a855f7;
+        --hg-bg: #0a0a0f;
+        --hg-fg: #f5f5fa;
+        --hg-dim: #6b6b78;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: var(--hg-bg);
+        font-family: "Inter", system-ui, sans-serif;
+        color: var(--hg-fg);
+        -webkit-font-smoothing: antialiased;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="2"
+      data-width="1920"
+      data-height="1080"
+    >
+      <div
+        id="scene"
+        class="clip"
+        data-composition-id="3d-card-flip"
+        data-composition-src="scene.html"
+        data-start="0"
+        data-duration="2"
+        data-track-index="1"
+      ></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>

package/dist/assets/design/skills/music-to-video/references/motion-primitives/3d-card-flip/scene.html

@@ -0,0 +1,119 @@
+<template id="3d-card-flip-template">
+  <div data-composition-id="3d-card-flip" data-width="1920" data-height="1080" data-duration="2">
+    <style>
+      :root {
+        --hg-violet: #7c3aed;
+        --hg-violet-2: #a855f7;
+        --hg-bg: #0a0a0f;
+        --hg-fg: #f5f5fa;
+        --hg-dim: #6b6b78;
+      }
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      .card-stage {
+        position: absolute;
+        inset: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        perspective: 2400px;
+      }
+      .card {
+        position: relative;
+        width: 1000px;
+        height: 580px;
+        transform-style: preserve-3d;
+        will-change: transform;
+      }
+      .face {
+        position: absolute;
+        inset: 0;
+        backface-visibility: hidden;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-weight: 900;
+        font-size: 200px;
+        letter-spacing: -0.04em;
+        border-radius: 24px;
+        box-shadow:
+          0 40px 80px rgba(0, 0, 0, 0.5),
+          0 0 0 1px rgba(255, 255, 255, 0.08) inset;
+      }
+      .face.front {
+        background: linear-gradient(135deg, #1e1b3a 0%, #0a0a0f 100%);
+        color: var(--hg-fg);
+      }
+      .face.back {
+        background: linear-gradient(135deg, #7c3aed 0%, #a855f7 60%, #d946ef 100%);
+        color: var(--hg-fg);
+        transform: rotateY(180deg);
+      }
+      .face .meta {
+        position: absolute;
+        top: 36px;
+        left: 40px;
+        font-family: "JetBrains Mono", monospace;
+        font-weight: 600;
+        font-size: 18px;
+        letter-spacing: 0.16em;
+        opacity: 0.6;
+      }
+      .card-shadow {
+        position: absolute;
+        left: 50%;
+        bottom: 22%;
+        width: 1000px;
+        height: 80px;
+        background: radial-gradient(ellipse at center, rgba(0, 0, 0, 0.55) 0%, transparent 70%);
+        transform: translateX(-50%);
+        filter: blur(12px);
+        will-change: opacity, transform;
+      }
+    </style>
+    <div class="card-shadow"></div>
+    <div class="card-stage">
+      <div class="card" id="card">
+        <div class="face front">
+          <div class="meta">v4 · CURRENT</div>
+          PRODUCT
+        </div>
+        <div class="face back">
+          <div class="meta">v5 · LAUNCH</div>
+          v5.0
+        </div>
+      </div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+
+      tl.fromTo(
+        "#card",
+        { rotateY: 0, scale: 0.92, opacity: 0 },
+        { rotateY: 0, scale: 1, opacity: 1, duration: 0.45, ease: "power3.out" },
+        0.15,
+      );
+
+      // Hold then flip
+      tl.to("#card", { rotateY: 180, duration: 1.0, ease: "power3.inOut" }, 0.7);
+
+      // Shadow squishes mid-flip
+      tl.to(
+        ".card-shadow",
+        { scaleX: 0.6, opacity: 0.4, duration: 0.5, ease: "power2.inOut" },
+        0.7,
+      );
+      tl.to(".card-shadow", { scaleX: 1, opacity: 0.7, duration: 0.5, ease: "power2.inOut" }, 1.2);
+
+      // Tiny landing settle
+      tl.to("#card", { scale: 1.02, duration: 0.12, ease: "power2.out" }, 1.68);
+      tl.to("#card", { scale: 1, duration: 0.3, ease: "elastic.out(1, 0.5)" }, 1.8);
+
+      window.__timelines["3d-card-flip"] = tl;
+    </script>
+  </div>
+</template>

package/dist/assets/design/skills/music-to-video/references/motion-primitives/bg-flow-field/index.html

@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>bg_flow_field</title>
+    <script src="../assets/gsap.min.js"></script>
+    <style>
+      :root {
+        --hg-violet: #7c3aed;
+        --hg-violet-2: #a855f7;
+        --hg-bg: #050507;
+        --hg-fg: #f5f5fa;
+        --hg-dim: #6b6b78;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: var(--hg-bg);
+        font-family: "Inter", system-ui, sans-serif;
+        color: var(--hg-fg);
+        -webkit-font-smoothing: antialiased;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="4"
+      data-width="1920"
+      data-height="1080"
+    >
+      <div
+        id="scene"
+        class="clip"
+        data-composition-id="bg-flow-field"
+        data-composition-src="scene.html"
+        data-start="0"
+        data-duration="4"
+        data-track-index="1"
+      ></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>