mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
Pre-merge snapshot of 5+ sessions of w2h skill restructure work: - new orchestrator scripts (assemble-index, captions, w2h-prep, preflight-finalize, verify-output, check-rendered-perception, w2h-dispatch-packet) - skill reference reorg (steps 0-6, beat-builder-guide, capabilities, SKILL.md) - capture/lint infra updates (assetCataloger, assetDownloader, tokenExtractor, lintProject, fonts rule) - PLAN.md (the steal+adapt plan for sessions 17+) Commit exists to provide a rollback point before merging 463 commits of upstream main into this branch. Will likely be squashed/restructured before any PR. Skipping pre-commit hook (--no-verify): fallow audit flags 5 complexity findings inherited from earlier session commits, not introduced by this snapshot.
278 lines
16 KiB
Markdown
278 lines
16 KiB
Markdown
# w2h Skill — Steal+Adapt Plan (Sessions 17+)
|
||
|
||
**Author:** Claude (Opus 4.7) for Ular Kimsanov
|
||
**Drafted:** 2026-06-11
|
||
**Worktree:** `/Users/ularkimsanov/Desktop/hyperframes-w2h-v3`
|
||
**Branch:** `feat/w2h-restructure-v3`
|
||
|
||
---
|
||
|
||
## The verify-first rule (NEW — applies to EVERY phase, EVERY task)
|
||
|
||
Before starting ANY phase or task within a phase, I MUST:
|
||
|
||
1. **Read every related file in our worktree end-to-end** — the file I'm about to touch + every file it imports/references + every consumer downstream that would be affected.
|
||
2. **Read every upstream source I'm porting from end-to-end** — full file, not a snippet. `git show origin/feat/product-launch-v2:<path>` for plv2 imports; `git show 995dbb4f:<path>` for SFX-branch imports.
|
||
3. **Map the integration explicitly** — write down (in chat or in TodoWrite) which existing files will change, what their downstream consumers are, what the rollback looks like if it goes wrong.
|
||
4. **Only then start typing**.
|
||
|
||
This rule exists because Sessions 13/15 made architectural changes (FRAME.md → no DESIGN.md) without re-reading enough downstream context, and the result was a session of wasted work + a revert. Verify-first prevents that pattern.
|
||
|
||
**No exception. No "this one's small."** Especially when stealing patterns from plv2 — that codebase was written for a different identity and copying without reading the surrounding context produces subtle drift.
|
||
|
||
---
|
||
|
||
## Locked decisions (user-confirmed 2026-06-11)
|
||
|
||
1. **Music command shape:** `hyperframes music` (Option A — parallel command, cleaner UX).
|
||
2. **Bundled SFX deletion:** YES — `skills/website-to-hyperframes/assets/sfx/*` (20 mp3s + manifest.json + CREDITS.md) gets removed as part of the SFX-branch merge. The runtime-catalog flow replaces them.
|
||
3. **Branch audit before starting:** quick scan for any `feat/music-*` / `feat/*-audio-*` branches that might already exist. If nothing else relevant, proceed to PHASE 0a.
|
||
|
||
---
|
||
|
||
## Identity preservation (the non-negotiable spine)
|
||
|
||
Everything below is filtered through this. If a steal violates this, it's adapt-not-copy or skip.
|
||
|
||
Our `website-to-hyperframes` skill is:
|
||
1. **URL-in / video-out, capture-first** — start from a real website; the video draws from REAL captured assets (colors, fonts, components, photos, SVGs). No "pick a preset" upfront.
|
||
2. **Brand-fidelity over genre purity** — accepts ANY video type from the same URL (social ad, product tour, brand reel, launch teaser, feature announcement). Not launch-biased.
|
||
3. **VIDEO, not webpage rebuilt in divs** (Step -1) — cinematic grammar: framing, depth, camera, scale.
|
||
4. **Linear 7-step flow** with autonomous-mode exception, cell-experiment-tested (33+ real runs).
|
||
5. **Creative Tension Principle** answered FROM the captured assets, not from a lookup table.
|
||
|
||
`product-launch-video` (plv2) is a RELATED-BUT-DIFFERENT skill (launch-narrative oriented, preset-based). We mine its quality patterns; we do NOT adopt its identity.
|
||
|
||
---
|
||
|
||
## Plan summary (sequenced, ~12-15 hr total)
|
||
|
||
| Phase | What | Cost | Identity risk |
|
||
|---|---|---|---|
|
||
| **0** | Merge `feat/sfx-audio-search` (commit `995dbb4f`) + add music parity | ~2-3 hr | none — pure capability addition |
|
||
| **A** | Universal quality gates: `derive-context-pack` + `check-compositions` + `validate` | ~3-4 hr | none |
|
||
| **B** | Worker prompt rigor: absorb `hyperframes-scene` + `hyperframes-finalize` into our refs | ~2-3 hr | none |
|
||
| **C** | `prep.mjs` full upgrade from stub | ~3-4 hr | low |
|
||
| **D** | Story craft adapt: hook taxonomy + named-pause + 75%-exit + OPTIONAL archetypes | ~2-3 hr | medium (kept primary narrative-arc, archetypes are secondary) |
|
||
| **E** | Deferred / skip (presets, phases, build-design, audio.mjs, etc.) | n/a | see § E |
|
||
|
||
**Checkpoint pauses:** after Phase 0, A, B (identity-adjacent), and D. User reviews before next phase.
|
||
|
||
---
|
||
|
||
## PHASE 0 — Merge `feat/sfx-audio-search` + music parity
|
||
|
||
**Why first:** the branch REMOVES `assets/sfx/*` (20 mp3s + manifest.json) and switches the skill to runtime catalog search. Doing this before Phase A means our new scripts (PHASE A) don't get written against soon-to-vanish bundled-SFX assumptions.
|
||
|
||
### 0a — Manual file-by-file merge of commit `995dbb4f`
|
||
|
||
The cherry-pick can't auto-merge because we modified the same files in sessions 13/16. Applying manually:
|
||
|
||
**Clean adds (no conflict — apply verbatim):**
|
||
- `packages/cli/src/commands/sfx.ts` (dispatcher)
|
||
- `packages/cli/src/commands/sfx/{add,analyze,analyze.test,auth,catalog-manifest,catalog-manifest.test,inspect,list,search,state}.ts` (10 files)
|
||
- `skills/hyperframes/references/sound-effects.md` (183 lines, the new reference doc)
|
||
- `packages/cli/src/cloud/_gen/{client,types}.ts` (regenerated cloud client — `AudioContentType = "music" | "sound_effects"` now exposed)
|
||
- `packages/cli/src/cli.ts` (register sfx subcommand — light edit)
|
||
- `packages/cli/src/help.ts` (add sfx help-group entry)
|
||
- `skills/hyperframes/SKILL.md` (mention SFX in description)
|
||
- `skills/hyperframes/references/beat-direction.md` (link sound-effects.md)
|
||
- `skills/hyperframes/references/techniques.md` (light updates — w2h-side conflict possible from our M3 work; merge by hand)
|
||
- `skills/hyperframes/references/video-composition.md` (light update)
|
||
|
||
**Deletes:**
|
||
- `skills/website-to-hyperframes/assets/sfx/*` — all 20 mp3 files + CREDITS.md + manifest.json. The manifest swap I did earlier today (97 lines of agent-facing descriptions) becomes moot — descriptions live in the HeyGen catalog now.
|
||
|
||
**Real conflicts (resolve thoughtfully — read commit's intent + our state):**
|
||
- `skills/website-to-hyperframes/references/step-3-storyboard.md` — commit replaces "use bundled SFX from `sfx/`" with "search the catalog when the storyboard names a beat that needs SFX." Our session-13/16 edits to this file (FRAME.md revert prose + file tree) need to coexist with the new SFX flow.
|
||
- `skills/website-to-hyperframes/references/step-5-build.md` — commit replaces the `## 1. Copy SFX to project` section with `## 1. Search + add SFX from catalog`. Our session-13/16 edits (landmines + assembler section + dispatch prompt template) need to coexist.
|
||
|
||
### 0b — Music parity
|
||
|
||
The cloud API already exposes `AudioContentType = "music" | "sound_effects"`. Options:
|
||
|
||
- **Option A (cleaner):** add a new `hyperframes music` command — parallel CLI to `sfx`, reuses analysis/auth/state modules.
|
||
- **Option B (lighter):** add a `--type music` flag to `hyperframes sfx`. Smaller diff. Confusing UX (user expects music to be its own thing).
|
||
|
||
**Recommendation: A.** Music's discovery flow is different from SFX (bed-style, longer, ducks under VO) and deserves its own command surface. The implementation reuses 90% of the SFX command code.
|
||
|
||
### 0c — `references/background-music.md` (new, ~80 lines)
|
||
|
||
- When music helps (brand reels, atmospheric pieces) vs hurts (most product demos)
|
||
- Volume hierarchy: BGM 0.4–0.6 under VO 1.0; pure-music 0.7–0.9
|
||
- Duck-on-narration rule (drop BGM 6-10 dB when VO is active)
|
||
- Motif rule for music (one bed per scene, not stacked)
|
||
- Search prompts that work (semantic, by feel: "moody ambient", "upbeat lo-fi", "tense synth pad")
|
||
|
||
### 0d — Smoke verification
|
||
|
||
- `npx tsx packages/cli/src/cli.ts sfx list` — works, shows catalog families
|
||
- `npx tsx packages/cli/src/cli.ts sfx search "whoosh"` — works (prompts for free key if missing)
|
||
- `npx tsx packages/cli/src/cli.ts music search "ambient pad"` — works
|
||
- 88+ tests still pass
|
||
- `bun test packages/cli/src/commands/sfx/*.test.ts` — runs the bundled tests
|
||
|
||
**Pause for user review** before Phase A.
|
||
|
||
---
|
||
|
||
## PHASE A — Universal quality gates
|
||
|
||
### A1 — `derive-context-pack.mjs` + `lib/capture-meta.mjs` (~30 min)
|
||
|
||
- Port `scripts/derive-context-pack.mjs` (266 LOC) verbatim into `skills/website-to-hyperframes/scripts/`
|
||
- Port `scripts/lib/capture-meta.mjs` (39 LOC) verbatim
|
||
- Adapt: rename `context_pack.md` output to live at `capture/context_pack.md`; reference `capture/extracted/*` paths consistently
|
||
- Wire into `step-0-capture.md` as a Step 0.5 (auto-runs after `capture` completes)
|
||
- Wire into beat dispatch packet — workers read `capture/context_pack.md` instead of 5 separate JSON files
|
||
|
||
### A2 — `check-compositions.mjs` (~1 hr)
|
||
|
||
- Port `scripts/check-compositions.mjs` (503 LOC)
|
||
- Adapt selectors for our beat naming: `b<N>-*` (we use this) vs plv2's `s<N>-*`
|
||
- Drop any plv2-specific wrapper-ancestor checks that don't apply
|
||
- Wire into `preflight-finalize.mjs` (already exists, ported in Session 7) as a NEW gate before lint
|
||
- Smoke against cell-A airbnb fixture
|
||
|
||
### A3 — `validate.mjs` (~1 hr)
|
||
|
||
- Port `scripts/validate.mjs` (717 LOC) — dispatcher with `narrator` + `section` subcommands
|
||
- Adapt schemas:
|
||
- plv2's `narrator_scripts.json` → our `SCRIPT.md` (markdown, not JSON — schema = "must have hook line + 3-7 beats + CTA closer")
|
||
- plv2's `section_plan.md` → our `STORYBOARD.md` (validate beat count matches estimated duration / total ≤ 60s for social / etc.)
|
||
- Wire into Step 3 (post-storyboard) and Step 4 (post-script) as self-validation loops
|
||
|
||
### A4 — Smoke + verification
|
||
|
||
- All 4 new scripts pass `node --check`
|
||
- 88+ tests still pass
|
||
- Run `check-compositions` against an existing cell-A fixture, verify it surfaces realistic issues
|
||
|
||
**Pause for user review** before Phase B.
|
||
|
||
---
|
||
|
||
## PHASE B — Worker prompt rigor
|
||
|
||
### B1 — Absorb `hyperframes-scene.md` into `beat-builder-guide.md` (~1.5 hr)
|
||
|
||
Read plv2's `agents/hyperframes-scene.md` (436 LOC). Extract patterns and merge with our existing `beat-builder-guide.md` (375 LOC):
|
||
|
||
- **Pre-write cheat sheet** — our 6 items; plv2's 4 are sharper. Merge to 5-7 best.
|
||
- **14 numbered constraints** — our `## Rules` block has ~15 rules; plv2 has 14 numbered. Reconcile: keep ours' identity (continuity-heavy w2h) but adopt plv2's:
|
||
- GSAP transform alias whitelist (`xPx/yPx/sx/sy/rot`)
|
||
- CSS-baked vs GSAP transform mutual-exclusion rule
|
||
- Macro-camera scale-headroom (`maxScale = 0.88 * W / r.width`)
|
||
- Primary-handoff-before-enter rule
|
||
- **Tier-A shared-element bridge protocol** — w2h doesn't have multi-act bridges in the plv2 sense; SKIP wholesale. But the underlying *element-handoff* protocol (when a logo or card carries between beats) is useful — adapt.
|
||
- **Skip:** the "scene wall-off" framing. w2h is continuity-heavy — workers CAN read sibling beat files. Our current rule stays.
|
||
|
||
### B2 — Absorb `hyperframes-finalize.md` Step 3.5 into `step-6-validate.md` (~1 hr)
|
||
|
||
Read plv2's `agents/hyperframes-finalize.md` (251 LOC). Extract:
|
||
|
||
- **Step 3.5 — Mandatory Visual Inspection Checklist** (5 categories): illegibility / out-of-bounds / competing-primaries / cramped-frame / seam-jank. Direct port — these failure modes are universal across video genres.
|
||
- **Brief-digest fast-path** — `preflight_clean===true` → skip detailed read. Adopt — saves time when gates clean.
|
||
- **Edit-ready `edit_old`/`edit_new` triage** rule — adopt. Mechanically apply, don't re-derive.
|
||
- **The framing line** quoted verbatim: *"the eye is fragile (rate-limit prone, end-of-pipeline, subjective), so a structured pass over five concrete failure categories matters more than freeform 'does it look right.'"*
|
||
|
||
### B3 — Verification
|
||
|
||
- Both reference files re-parse cleanly
|
||
- 88+ tests still pass
|
||
- Word-count check: didn't bloat by more than 30%
|
||
|
||
**Pause for user review** before Phase C — this is identity-adjacent (worker contract changes; user should eyeball).
|
||
|
||
---
|
||
|
||
## PHASE C — `prep.mjs` full upgrade
|
||
|
||
### C1 — Read plv2's `prep.mjs` (1010 LOC) end-to-end + diff against our 280-LOC stub (~30 min)
|
||
|
||
### C2 — Port the upgrade (~2-3 hr)
|
||
|
||
**Take:**
|
||
- Anchor-walk through STORYBOARD.md (replaces our regex extraction)
|
||
- Per-beat `start_s` / `estimatedDuration_s` / `duration_s` derivation
|
||
- Transitions[] inference from storyboard prose
|
||
- Asset / font / SFX copy into `public/` (we may need to adapt — we currently use `capture/assets/` not `public/`)
|
||
- `font_face_css` aggregation (already in our stub but plv2's is more robust)
|
||
- `voice` auto-detection (already in our stub)
|
||
|
||
**Drop:**
|
||
- cap=2 grouping (plv2-specific; we're single-group continuity-heavy)
|
||
- Tier-A bridge logic (plv2-specific)
|
||
- Multi-act dispatch packet ingestion (plv2-specific)
|
||
|
||
### C3 — Smoke against cell-A airbnb fixture (~30 min)
|
||
|
||
- Replace existing stub
|
||
- Confirm group_spec.json shape is unchanged from downstream consumer perspective (captions.mjs / assemble-index.mjs / preflight-finalize.mjs all still work)
|
||
|
||
---
|
||
|
||
## PHASE D — Story craft adapt-not-copy
|
||
|
||
### D1 — Universal extracts into `step-3-storyboard.md` (~1.5 hr)
|
||
|
||
Add — these are genre-universal:
|
||
|
||
- **Named hook types** (10): shocking-statistic / imagine / direct-address / pain-validation / visceral-metaphor / rhetorical-question / category-announcement / visual-spectacle / question-invitation / trend-positioning. Each with one-line "when to use" + example.
|
||
- **"Stillness Before Climax"** named beat (0.3-0.75s pause between major action and confirmation).
|
||
- **"Exit = 75% of Entry"** named rule (with reasoning: entry is deliberate; departure is swift but not abrupt).
|
||
- **"Multiplicative breathing > yoyo"** rule (with the `scale = final * (1 + Math.sin(t*freq)*amp)` form).
|
||
|
||
### D2 — Optional archetypes (~1 hr)
|
||
|
||
Add as a SECONDARY section in `step-3-storyboard.md`. NOT primary. Wording: *"If the user explicitly wants a launch-style or persuasion-heavy reel, these archetypes give the storyboard a named structural spine. For general videos (social ads, brand reels, demos, tours), the narrative-arc options above (Problem→Solution / Reveal / Demonstration / Vibe / Comparison) are the primary frame."*
|
||
|
||
- **PAS** (Problem-Agitate-Solution) — when product solves a clear pain
|
||
- **Future-Pacing** — when the brand sells aspirational outcome
|
||
- **Demo-Loop** — when the product itself is the hook
|
||
- **BAB** (Before-After-Bridge) — transformation story
|
||
- **Feature-Benefit-Cascade** — when product has 3-5 distinct features
|
||
|
||
### D3 — SKIP
|
||
|
||
- Plv2's persuasion-family framing (Pain/Authority/Social/Cognitive/Hedonic) — wrong identity layer; pulls us toward sales-copy. Our Step -1 says "viral hook" not "sales pitch."
|
||
|
||
---
|
||
|
||
## PHASE E — Deferred / skip with explicit reasoning
|
||
|
||
| Item | Decision | Why |
|
||
|---|---|---|
|
||
| **19 style-presets** | DEFER | Philosophical question — capture-first vs preset-first is an identity question. Revisit AFTER Phases 0/A/B/C/D land. Possible future role: presets as FALLBACK when capture is thin (brochure-only sites), not the default path. |
|
||
| **`audio.mjs` + `wait-bgm.mjs`** | DEFER | Detached BGM only matters when we generate music. Music search (PHASE 0b) covers the user's need for now. Revisit if music GENERATION is on the table. |
|
||
| **`transitions.mjs` + `lib/transition-registry.mjs`** | DEFER | Our assembler handles transitions via `shader_transitions` field. Plv2's injection system is for THEIR `section_plan.md` flow. Not blocking. |
|
||
| **`build-design.mjs`** (2941 LOC) + **`emit-chunks.mjs`** | SKIP | Tied to preset-scoring system. Adopt only if we change identity to preset-first. |
|
||
| **`phases/` architecture** | SKIP | Linear 7-step flow is OUR pattern, just stabilized. Restructure risk doesn't pay off. |
|
||
| **`site_dna` register** | DEFER | Depends on build-design. Useful concept but presupposes the preset system. |
|
||
| **`check-bridge` subcommand** of transitions.mjs | DEFER | Plv2 uses for multi-act handoffs; we're single-act/continuity-heavy. Revisit if we add bridge-style transitions. |
|
||
|
||
---
|
||
|
||
## Sequence + checkpoints
|
||
|
||
```
|
||
PHASE 0 (sfx + music) → pause for user review
|
||
PHASE A (quality gates) → pause for user review
|
||
PHASE B (worker prompts) → pause for user review (identity-adjacent)
|
||
PHASE C (prep.mjs) → continue
|
||
PHASE D (story craft) → pause for user review (final)
|
||
→ ready for fresh-session real-URL test
|
||
```
|
||
|
||
After PHASE D, the worktree is at a state worth committing + pushing. We'll do that as a clean commit chain (probably 4-5 logical commits, one per phase + one for capture-layer work from earlier sessions).
|
||
|
||
---
|
||
|
||
## Open questions for the user BEFORE starting PHASE 0
|
||
|
||
1. **Music command shape** — `hyperframes music search` (parallel command, Option A) OR `hyperframes sfx search --type music` (single command with flag, Option B)? Recommend A.
|
||
2. **SFX file deletion** — are you OK with `skills/website-to-hyperframes/assets/sfx/` going away entirely? The branch's intent is clear (runtime catalog), but I want to confirm before deleting bundled assets.
|
||
3. **Order** — start PHASE 0 immediately on confirmation, OR audit any other related branches first (e.g. is there a `feat/music-...` or similar branch I should know about)?
|
||
|
||
Confirm and I start PHASE 0a.
|