diff --git a/skills/website-to-hyperframes/references/step-1-design.md b/skills/website-to-hyperframes/references/step-1-design.md index 64bb667d3e..c5bc3661bc 100644 --- a/skills/website-to-hyperframes/references/step-1-design.md +++ b/skills/website-to-hyperframes/references/step-1-design.md @@ -50,6 +50,8 @@ A flat lookup of the values sub-agents grab while composing beats. Two sub-secti List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't. +**Order matters: list the brand-primary HEX FIRST.** `w2h-prep` parses DESIGN.md and picks the first non-white / non-black hex it finds as the brand-primary for `tokens.css` emission. If you list a secondary color first, the wrong color becomes the brand-primary downstream. Order: Primary CTA color → secondaries → supporting → borders. + **Example:** ```markdown diff --git a/skills/website-to-hyperframes/references/step-5-build.md b/skills/website-to-hyperframes/references/step-5-build.md index ea3e881826..0ce1ed3f7b 100644 --- a/skills/website-to-hyperframes/references/step-5-build.md +++ b/skills/website-to-hyperframes/references/step-5-build.md @@ -153,6 +153,38 @@ Every CLI invocation in this skill uses `npx tsx packages/cli/src/cli.ts `. `lint` / `validate` take a DIRECTORY, not a file (`npx tsx packages/cli/src/cli.ts lint .` not `... lint index.html`). `--quality medium` is invalid — the valid set is `draft | standard | high`. +### 10. Sub-comp root `background:` CSS doesn't paint — use a full-bleed child div instead + +A composition's root `
` is the host element the assembler INSERTS into `index.html`. CSS like `.b6-root { background: #000; }` on the root will NOT paint in the rendered video — the renderer composites against transparency. Beat-6 of an early heygen test opened on a blank white frame because of exactly this. The fix is a full-bleed child div that paints the background INSIDE the root: + +```html + +
+

...

+
+ + +
+
+

...

+
+``` + +Same rule for gradients, images, or any `background-*` property. The lint won't catch this; it ships looking fine in Studio preview (where root CSS DOES paint) and breaks only at MP4 render. + +### 11. Captured assets disguised as the wrong format (AVIF-as-`.jpg`) + +The capture pipeline names downloaded images by URL extension (`hero.jpg` if the URL ends `.jpg`), but the SERVER's actual content type may be AVIF — modern image CDNs serve AVIF to browsers that accept it, regardless of URL extension. AVIF files saved with `.jpg` extension can break headless render (Chrome can render AVIF, but ffmpeg's image pipeline may not, depending on build). If a beat references a `.jpg` asset and the render fails to load that frame, check with `file capture/assets/.jpg` — if it reports `ISO Media, AVIF Image`, that's the cause. Workaround: use a different captured asset of the same subject, or convert with `ffmpeg -i broken.jpg good.png`. + +### 12. SFX CLI gotchas (cwd drift, zsh word-split, cache miss, dead clips) + +The `sfx` command flow has four real friction points lived agents have hit: + +- **CWD drift breaks `source .env`** — if you `cd` into a subdir between commands, `.env` relative paths fail. Either use `npx tsx packages/cli/src/cli.ts ... --env $PROJECT_DIR/.env`, or stay in the project root for SFX commands. The local CLI auto-loads `.env` from cwd, so cwd matters. +- **zsh doesn't word-split `$CLI sfx ...`** — if you store the CLI command in a variable (e.g. `CLI="npx tsx packages/cli/src/cli.ts"`), zsh treats `$CLI sfx search "..."` as one giant filename and fails with "no such file." Either invoke the CLI literally (don't store in a variable) or use `${=CLI}` to force word-splitting in zsh. Bash word-splits by default. +- **`sfx add ` requires a prior `sfx search`** — the catalog API has no fetch-by-id; `add` reads a per-project cache populated by `search`. If you `add ` without searching first, you get "Unknown SFX id." Always search → add. The cache persists per project. +- **Some catalog clips are silent / dead (-70 LUFS)** — occasional misindexed clips return audio that's effectively silent. `sfx add` prints the LUFS in the analysis. If you see something like `-70` LUFS where you expected `-12` to `-20`, the clip is dead — re-search with a different query and pick a different ID. + ## 2. Build each composition — USE SUB-AGENTS **Before dispatching, re-read DESIGN.md and STORYBOARD.md.** You wrote these files earlier in the session and you think you remember them. You don't — not the exact hex values, not the specific font families, not the button border-radius, not the Do's/Don'ts. Re-read them now so you can paste accurate brand rules and beat specs into each sub-agent prompt.