feat(skills): frame-preset library + shared audio engine (foundation)

skills/general-video/SKILL.md

@@ -1,21 +1,17 @@
 ---
 name: general-video
 description: >
-  Use as the fallback for custom HyperFrames HTML video composition authoring
-  when no specialized workflow fits. Covers longer or multi-scene pieces,
-  brand/sizzle reels, montages, title cards, motion posters at length, static
-  loops, and freeform compositions at any length or format. Not for marketed
-  product promos (product-launch-video), general website-to-video capture
-  (website-to-video), topic explainers (faceless-explainer), GitHub PR
-  videos (pr-to-video), captioning existing footage (embedded-captions),
-  Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics
-  hits such as logo stings, kinetic type, stat/chart pops, lower-thirds,
-  animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it
-  (see /hyperframes); use this only as the input/length-agnostic fallback.
+  The fallback workflow for authoring custom HyperFrames video compositions at
+  any length or format — longer or multi-scene pieces, brand / sizzle reels,
+  montages, title cards, static loops, and freeform compositions. Input- and
+  length-agnostic. If a specialized workflow clearly fits the input — a
+  marketed product, a website, a topic explainer, a GitHub PR, existing
+  footage, a short motion graphic, or a Remotion port — prefer it (see
+  /hyperframes); use this only as the general fallback when none fit.
 metadata: { "tags": "orchestrator, general-video, fallback, freeform, composition-authoring" }
 ---
 
-# general-video — general composition authoring
+# general-video — general video workflow
 
 > **Confirm the route before you build.** This is the **fallback** for custom composition authoring. If the input clearly fits a specialized workflow, prefer it: marketed product → `/product-launch-video`; general site → `/website-to-video`; topic explainer → `/faceless-explainer`; GitHub PR → `/pr-to-video`; existing footage → `/embedded-captions` · `/graphic-overlays`; short unnarrated motion graphic → `/motion-graphics`; Remotion port → `/remotion-to-hyperframes`. **Out of scope**: live / at-render-time data, NLE-style editing of a finished video, or producing footage HyperFrames can't capture. Unsure? **Read `/hyperframes` first.**
 
@@ -100,18 +96,40 @@ Never use `position: absolute; top: Npx` on a content container — it overflows
 
 This maps the skill's full surface (see the `description`) to its references — non-exhaustive; when an intent isn't listed, route through `hyperframes-creative` (look/concept), `hyperframes-animation` (motion), `hyperframes-core` (contract), `hyperframes-media` (audio/captions). **The first row is ADDITIVE — read it AND your intent row, not one or the other.**
 
-| Building…                                                             | Read first (in order)                                                                                                                                                       |
-| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **ALWAYS — every non-trivial piece, on top of your intent row below** | `hyperframes-creative/references/house-style.md` + `references/video-composition.md` (also gated in Step 1 / HARD-GATE; the "produced, not generated" foreground detailing) |
-| **Kinetic typography / text-forward**                                 | `hyperframes-animation/techniques.md` (kinetic type) + `adapters/gsap-easing-and-stagger.md` + `rules/kinetic-beat-slam.md`                                                 |
-| **Title card / lower-third / overlay / PiP / text-behind-subject**    | `hyperframes-creative/references/composition-patterns.md` + (for the centered/sized frame) `hyperframes-core` → "Root must be sized"                                        |
-| **Logo / brand-mark reveal**                                          | `hyperframes-animation/rules/svg-path-draw.md` (draw-on) + `rules/3d-text-depth-layers.md` + `rules/scale-swap-transition.md`                                               |
-| **Data / stats / numbers**                                            | `hyperframes-animation/rules/counting-dynamic-scale.md` + `rules/stat-bars-and-fills.md` + `hyperframes-creative/references/data-in-motion.md`                              |
-| **Product / app / UI demo**                                           | `hyperframes-animation/rules/3d-page-scroll.md` + `rules/cursor-click-ripple.md` + `rules/press-release-spring.md`                                                          |
-| **Audio-reactive / music-driven**                                     | `hyperframes-creative/references/audio-reactive.md` (pre-extract bands; map to motion)                                                                                      |
-| **Narrated / voiceover / captions / subtitles**                       | `hyperframes-media` (`tts`, `transcribe`, caption authoring) → place assets via `hyperframes-core`                                                                          |
-| **Multi-scene / transitions**                                         | `hyperframes-animation/transitions/overview.md` **then** `transitions/catalog.md` (you are not done after the overview — the GSAP recipe is in the catalog)                 |
-| **Modular / sub-compositions**                                        | `hyperframes-core/references/composition-patterns.md` + `references/sub-compositions.md`                                                                                    |
+| Building…                                                             | Read first (in order)                                                                                                                                                                                |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ALWAYS — every non-trivial piece, on top of your intent row below** | `hyperframes-creative/references/house-style.md` + `references/video-composition.md` (also gated in Step 1 / HARD-GATE; the "produced, not generated" foreground detailing)                          |
+| **Kinetic typography / text-forward**                                 | `hyperframes-animation/techniques.md` (kinetic type) + `adapters/gsap-easing-and-stagger.md` + `rules/kinetic-beat-slam.md`                                                                          |
+| **Title card / lower-third / overlay / PiP / text-behind-subject**    | `hyperframes-creative/references/composition-patterns.md` + (for the centered/sized frame) `hyperframes-core` → "Root must be sized"                                                                 |
+| **Logo / brand-mark reveal**                                          | `hyperframes-animation/rules/svg-path-draw.md` (draw-on) + `rules/3d-text-depth-layers.md` + `rules/scale-swap-transition.md`                                                                        |
+| **Data / stats / numbers**                                            | `hyperframes-animation/rules/counting-dynamic-scale.md` + `rules/stat-bars-and-fills.md` + `hyperframes-creative/references/data-in-motion.md`                                                       |
+| **Product / app / UI demo**                                           | `hyperframes-animation/rules/3d-page-scroll.md` + `rules/cursor-click-ripple.md` + `rules/press-release-spring.md`                                                                                   |
+| **Audio-reactive / music-driven**                                     | `hyperframes-creative/references/audio-reactive.md` (pre-extract bands; map to motion)                                                                                                               |
+| **Narrated / voiceover / music / SFX / captions**                     | `hyperframes-media` → the shared audio engine `scripts/audio.mjs` (one call = TTS + BGM + SFX → `audio_meta.json`); caption authoring + asset placement via `hyperframes-core`. See **Audio** below. |
+| **Multi-scene / transitions**                                         | `hyperframes-animation/transitions/overview.md` **then** `transitions/catalog.md` (you are not done after the overview — the GSAP recipe is in the catalog)                                          |
+| **Modular / sub-compositions**                                        | `hyperframes-core/references/composition-patterns.md` + `references/sub-compositions.md`                                                                                                             |
+
+### Audio: one engine (TTS · BGM · SFX)
+
+Only when the piece calls for it (per "build exactly what was asked" — no ambient music on a title card). Don't hand-roll TTS or vendor a copy: write a neutral `audio_request.json` and call the shared engine in `hyperframes-media`. It auto-degrades on one switch — HeyGen credential present → HeyGen TTS + music/SFX **retrieval**; absent → ElevenLabs/Kokoro TTS, Lyria/MusicGen BGM **generation**, and the bundled SFX library. Full flag list + request/meta schema: the header comment of `hyperframes-media/scripts/audio.mjs`.
+
+```jsonc
+// audio_request.json — one line per narrated segment; `id` is yours (joins audio_meta back)
+{
+  "lines": [
+    { "id": "s1", "text": "Your opening line.", "sfx": ["whoosh"] },
+    { "id": "s2", "text": "The next beat." },
+  ],
+  "bgm": { "query": "calm cinematic underscore" }, // omit "mode" → auto (retrieve if HeyGen, else generate); "none" to disable
+}
+```
+
+```bash
+# <MEDIA_DIR> = the installed hyperframes-media skill dir (sibling of this skill)
+node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json
+```
+
+Then read `audio_meta.json`: mount each `voices[].path` + (`bgm.path`, `sfx[]`) as `<audio>` tracks and use `voices[].words` for captions, all per `hyperframes-core` (audio tracks + caption authoring). If BGM took the generate path (`bgm_pending: true`), run `hyperframes-media/scripts/wait-bgm.mjs` before final render.
 
 ## Output checklist → `hyperframes-cli`
 
@@ -121,12 +139,3 @@ This maps the skill's full surface (see the `description`) to its references —
 - [ ] contrast warnings addressed; for multi-scene work, review the animation map (`hyperframes-animation/scripts/animation-map.mjs`)
 - [ ] deliver the preview; render to MP4 only on explicit request
 - [ ] surface the preview **only at handoff** (it is the stable, final preview); don't pop one mid-build — build-phase snapshots are headless
-
-## Not this workflow
-
-- A specific **product / company / SaaS / website** being marketed, launched, or promoted → `/product-launch-video`
-- A **concept / topic / article / how-X-works** being explained, no product → `/faceless-explainer`
-- A **GitHub PR / code change** → `/pr-to-video`
-- An **existing talking-head video** to add captions to → `/embedded-captions`
-- Porting an existing **Remotion** composition → `/remotion-to-hyperframes`
-- Cutting / editing a **finished video file** like an NLE → out of scope (HyperFrames composites HTML and media into a deterministic timeline; it does not edit footage)

skills/hyperframes-cli/SKILL.md

@@ -14,7 +14,7 @@ Everything runs through `npx hyperframes` unless project instructions specify a
 3. **Lint** — `npx hyperframes lint`
 4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
 5. **Visual inspect** — `npx hyperframes inspect`
-6. **Preview** — `npx hyperframes preview`
+6. **Preview** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
 7. **Render** — pick the variant:
    - Iterate: `npx hyperframes render --quality draft`
    - Deliver: `npx hyperframes render --quality high --output out.mp4`
@@ -34,6 +34,7 @@ Cross-cutting rules that hold for every command:
 - **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
 - **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
 - **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
+- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
 - **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇  <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.
 
 ## Routing

skills/hyperframes-cli/references/preview-render.md

@@ -9,7 +9,7 @@ npx hyperframes preview                   # serve current directory
 npx hyperframes preview --port 4567       # custom port (default 3002)
 ```
 
-Hot-reloads on file changes. Opens the studio in your browser automatically.
+Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.
 
 When handing a project back to the user, use the Studio project URL, not the source `index.html` path:
 
@@ -53,6 +53,8 @@ Validation runs before any server boots, so an invalid value exits cleanly witho
 
 ## render
 
+> Render only after the user has reviewed in `preview` and approved. Don't auto-render when the checks pass.
+
 ```bash
 npx hyperframes render                                # standard MP4 from cwd
 npx hyperframes render ./my-video --output ./out.mp4  # render from outside the project dir