mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
feat(skill): preview-beat.mjs + _beat-skeleton.html for faster beat iteration
Two friction-reducers from the real-AI-test feedback list:
1. scripts/preview-beat.mjs (~100 LOC)
- Snapshot ONLY the frames inside a single beat's window. Solves the
"I built beat-3, I want to see only beat-3's frames" iteration loop
without scanning past sibling beats in a full-timeline snapshot.
- Walks compositions/ in the same sort order as w2h-prep's
scanCompositionsDir (readdirSync.sort, skip captions.html), sums each
beat's data-duration to compute the target's cumulative start_s,
then invokes `hyperframes snapshot . --at <t1>,<t2>,...,<tN>` with
frames evenly spaced inside [start_s, start_s+duration_s).
- Beat arg accepts: a path under compositions/, a bare filename, OR
the composition-id slug (case-insensitive). Whichever the agent has
handy.
- Required project state: index.html must exist (assembler ran at
least once); otherwise dies with a clear "run assemble-index first"
message.
- Smoke-tested against synthetic 3-beat fixture: target by filename,
target by id slug, missing-beat error, missing-index error — all
four paths behave as expected.
2. templates/_beat-skeleton.html (~80 LOC)
- File copy of the starter template from beat-builder-guide.md Step 2,
so the agent can `cp` instead of paste-from-docs when starting a new
beat. Faster, less chance of drift between docs and on-disk content.
- Pre-wires the patterns each landmine defuses, with inline comments
pointing to the landmine number in step-5-build.md. Specifically
honors: #10 full-bleed bg child div (not root background:), the
frame-0 black trap (inline style="opacity:1"), GSAP transform-only
tween whitelist, the three-string match (root id / __timelines key /
dispatch slug), no inline <script src=...> for GSAP / HyperShader
(assembler emits both at root).
- Lives under templates/ not compositions/ so w2h-prep's scanner
doesn't pick it up as a beat in a real project.
beat-builder-guide.md:
- Step 2 now points at the on-disk skeleton (alongside the existing
paste-from-docs option).
- Step 4 adds the per-beat-window preview command next to the full
`snapshot` command, with the contract (assemble-index must have run)
spelled out.
This commit is contained in:
@@ -65,6 +65,8 @@ Four hidden pitfalls account for most rework in a single beat run — scan them
|
||||
|
||||
Save to the path the main agent specified (usually `compositions/beat-N-<slug>.html`). Copy-paste this starter and fill in the named placeholders. Every attribute, ID, and timeline key shown is load-bearing — the assembler (final action of Step 5) hard-fails if `data-duration` drifts from your dispatch packet's `estimatedDuration_s` by more than 0.01s.
|
||||
|
||||
There's also a file copy of this same starter at `skills/website-to-hyperframes/templates/_beat-skeleton.html` — `cp` it instead of paste-from-docs when starting a new beat to skip the copy/paste step and keep the landmine-defusing inline comments alongside your edits.
|
||||
|
||||
```html
|
||||
<template id="beat-N-<slug>-template">
|
||||
<style>
|
||||
@@ -133,6 +135,14 @@ Fix ALL errors. Zero errors required.
|
||||
npx tsx packages/cli/src/cli.ts snapshot . --frames 3
|
||||
```
|
||||
|
||||
This snapshots the FULL timeline. When you want frames from only YOUR beat's window (faster iteration, no scanning past sibling beats), once `index.html` exists run:
|
||||
|
||||
```bash
|
||||
node skills/website-to-hyperframes/scripts/preview-beat.mjs --hyperframes . --beat compositions/beat-N-<slug>.html --frames 5
|
||||
```
|
||||
|
||||
The script walks `compositions/` in the same sort order the assembler uses, computes your beat's cumulative start_s, and invokes `snapshot --at <t1>,<t2>,...` with frames evenly spaced inside `[start_s, start_s+duration_s)`. Same `snapshots/contact-sheet.jpg`, beat-local frames only. Re-run `scripts/assemble-index.mjs` first if you've changed durations since the last assemble.
|
||||
|
||||
**VIEW the contact sheet cell-by-cell** (`snapshots/contact-sheet.jpg`). Not a glance — look at EVERY frame your snapshot produced, in order. For each frame, write one short sentence naming what you see (subject, position, motion state, visible text). If you find yourself summarizing the contact sheet as a whole, stop and go back to frame-by-frame.
|
||||
|
||||
For each frame, the questions:
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
#!/usr/bin/env node
|
||||
// preview-beat.mjs — snapshot a SINGLE beat's window from an assembled w2h
|
||||
// project. Use during beat iteration: you've built `compositions/beat-3-X.html`,
|
||||
// you want to see what frames the renderer produces for THAT beat without
|
||||
// browsing the whole video's contact sheet.
|
||||
//
|
||||
// Mechanism: walks compositions/ in the same sort order w2h-prep uses
|
||||
// (readdirSync(...).sort()), sums each beat's data-duration to compute the
|
||||
// target beat's cumulative start_s, then invokes `hyperframes snapshot . --at
|
||||
// <t1>,<t2>,...,<tN>` with frames evenly spaced inside the beat's [start_s,
|
||||
// start_s+duration_s) window. The contact sheet that snapshot writes contains
|
||||
// only the beat-local frames.
|
||||
//
|
||||
// REQUIRES: project's index.html must exist (assembler has run at least once).
|
||||
// snapshot snapshots whatever index.html points to — if a beat's data-duration
|
||||
// has changed since the last assemble-index run, re-run that first.
|
||||
//
|
||||
// Usage:
|
||||
// node preview-beat.mjs --hyperframes <projectDir> --beat compositions/beat-3-X.html [--frames 5]
|
||||
//
|
||||
// Beat arg accepts: a path under compositions/, a bare filename, or the
|
||||
// composition-id slug (matched case-insensitive against scanned files).
|
||||
|
||||
import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
|
||||
import { join, resolve, basename, extname } from "node:path";
|
||||
import { spawnSync } from "node:child_process";
|
||||
|
||||
function parseArgs(argv) {
|
||||
const args = { hyperframes: ".", beat: "", frames: 5 };
|
||||
for (let i = 2; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (a === "--hyperframes") args.hyperframes = argv[++i];
|
||||
else if (a === "--beat") args.beat = argv[++i];
|
||||
else if (a === "--frames") args.frames = Number(argv[++i]);
|
||||
else if (a === "--help" || a === "-h") args.help = true;
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
function die(msg) {
|
||||
console.error(`✗ preview-beat: ${msg}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const args = parseArgs(process.argv);
|
||||
if (args.help || !args.beat) {
|
||||
console.log(
|
||||
"Usage: node preview-beat.mjs --hyperframes <dir> --beat <comp-file> [--frames 5]\n" +
|
||||
"Snapshots only the frames inside ONE beat's timeline window.",
|
||||
);
|
||||
process.exit(args.help ? 0 : 1);
|
||||
}
|
||||
|
||||
const projectDir = resolve(args.hyperframes);
|
||||
const compDir = join(projectDir, "compositions");
|
||||
if (!existsSync(compDir) || !statSync(compDir).isDirectory()) {
|
||||
die(`no compositions/ directory at ${compDir}`);
|
||||
}
|
||||
if (!existsSync(join(projectDir, "index.html"))) {
|
||||
die("project has no index.html — run scripts/assemble-index.mjs first");
|
||||
}
|
||||
|
||||
// Mirror w2h-prep's scanCompositionsDir ordering: readdirSync().sort(), HTML
|
||||
// only, exclude captions.html (caption track isn't a beat).
|
||||
const files = readdirSync(compDir)
|
||||
.filter((f) => extname(f) === ".html" && f !== "captions.html")
|
||||
.sort();
|
||||
|
||||
const DUR_RE = /data-duration\s*=\s*["']?([0-9]+(?:\.[0-9]+)?)/i;
|
||||
const ID_RE = /data-composition-id\s*=\s*["']([^"']+)["']/i;
|
||||
|
||||
let cumStart = 0;
|
||||
let target = null;
|
||||
for (const f of files) {
|
||||
const html = readFileSync(join(compDir, f), "utf-8");
|
||||
const dm = html.match(DUR_RE);
|
||||
const im = html.match(ID_RE);
|
||||
const dur = dm ? Number(dm[1]) : null;
|
||||
const id = im ? im[1] : null;
|
||||
if (dur == null || !isFinite(dur) || dur <= 0) continue;
|
||||
const isTarget =
|
||||
f === basename(args.beat) ||
|
||||
`compositions/${f}` === args.beat ||
|
||||
(id && id.toLowerCase() === args.beat.toLowerCase());
|
||||
if (isTarget) {
|
||||
target = { file: f, id, start: cumStart, duration: dur };
|
||||
break;
|
||||
}
|
||||
cumStart += dur;
|
||||
}
|
||||
|
||||
if (!target) die(`beat "${args.beat}" not found in compositions/ (scanned ${files.length} files)`);
|
||||
|
||||
const N = Math.max(1, Math.floor(args.frames));
|
||||
const stamps = [];
|
||||
for (let i = 0; i < N; i++) {
|
||||
const t = target.start + (target.duration * (i + 0.5)) / N;
|
||||
stamps.push(Number(t.toFixed(3)));
|
||||
}
|
||||
|
||||
const cliPath = resolve(projectDir, "packages/cli/src/cli.ts");
|
||||
const cliArgv = existsSync(cliPath)
|
||||
? ["tsx", cliPath, "snapshot", projectDir, "--at", stamps.join(",")]
|
||||
: ["hyperframes", "snapshot", projectDir, "--at", stamps.join(",")];
|
||||
|
||||
console.log(
|
||||
`▸ beat ${target.id || target.file} window [${target.start}s, ${(target.start + target.duration).toFixed(3)}s); snapshotting at ${stamps.join(", ")}s`,
|
||||
);
|
||||
const r = spawnSync("npx", cliArgv, { stdio: "inherit" });
|
||||
process.exit(r.status ?? 1);
|
||||
@@ -0,0 +1,89 @@
|
||||
<!--
|
||||
Beat skeleton — copy this verbatim into compositions/beat-N-<slug>.html and
|
||||
fill the named placeholders. Every attribute below is load-bearing; the
|
||||
inline comments name the landmine each pattern defuses. Cross-reference
|
||||
with references/beat-builder-guide.md (full guide) and
|
||||
references/step-5-build.md (landmines #1–12) for the rationale.
|
||||
|
||||
Do NOT keep this file inside a project's compositions/ dir — it would be
|
||||
scanned as a beat. Copy it OUT (rename to beat-N-<slug>.html) before
|
||||
editing.
|
||||
|
||||
Three strings MUST be identical across this file: the root
|
||||
<div data-composition-id="...">, the window.__timelines["..."] key, and the
|
||||
dispatch packet's BEAT_FILE slug. Drift = beat ships black.
|
||||
-->
|
||||
<template id="beat-N-SLUG-template">
|
||||
<style>
|
||||
/* Scope every selector with a beat-prefix class (e.g. .bN-title) so styles
|
||||
don't leak into sibling beat compositions. Landmine #6 in
|
||||
step-5-build.md: a generic `.cap` or `.scene` class can silently
|
||||
hide elements when a sibling composition uses the same name. */
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
.bN-root {
|
||||
width: 1920px; height: 1080px;
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
/* DO NOT set `background:` on the root — sub-comp root background CSS
|
||||
does NOT paint at render time (landmine #10). Use the full-bleed bg
|
||||
child div below instead. */
|
||||
}
|
||||
.bN-bg { position: absolute; inset: 0; background: #YOUR_BG_HEX; z-index: 0; }
|
||||
.bN-title {
|
||||
font-size: 96px; line-height: 1.05; font-weight: 700;
|
||||
color: #YOUR_FG_HEX;
|
||||
position: relative; z-index: 1;
|
||||
}
|
||||
</style>
|
||||
|
||||
<!-- Root sub-comp div. data-duration MUST equal estimatedDuration_s from
|
||||
your dispatch packet within 0.01s. The assembler hard-fails on drift. -->
|
||||
<div
|
||||
id="beat-N-SLUG"
|
||||
class="bN-root"
|
||||
data-composition-id="beat-N-SLUG"
|
||||
data-width="1920"
|
||||
data-height="1080"
|
||||
data-duration="5.5"
|
||||
>
|
||||
<!-- Full-bleed background div (NOT the root). Paints at render time. -->
|
||||
<div class="bN-bg"></div>
|
||||
|
||||
<!-- Visible elements carry inline style="opacity:1" so the frame-0 black
|
||||
trap doesn't bite (landmine: GSAP `from()` + CSS opacity:0 animates
|
||||
0→0 forever; any opacity tween starting at t=0 renders black under
|
||||
seek). Animate transforms only, never opacity at t=0. -->
|
||||
<h1 class="bN-title" style="opacity:1" data-layout-role="primary">YOUR HEADLINE</h1>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
(function () {
|
||||
var BEAT = 5.5; // MUST equal data-duration above to the centisecond.
|
||||
window.__timelines = window.__timelines || {};
|
||||
var tl = gsap.timeline({ paused: true });
|
||||
|
||||
// Entrance — transform-only. Use `x`/`y`/`scale`/`scaleX`/`scaleY`/
|
||||
// `rotation`/`opacity` ONLY. Never tween `width`/`height`/`top`/`left`
|
||||
// (the renderer's seek path cannot sub-pixel-position those).
|
||||
tl.fromTo(".bN-title", { scale: 0.92, y: 40 }, { scale: 1, y: 0, duration: 0.6, ease: "power4.out" }, 0);
|
||||
|
||||
// Hold motion — continuous-motion rule (Airbnb-style constant motion).
|
||||
// A scale-creep on the root keeps the frame alive across the beat.
|
||||
tl.fromTo(".bN-root", { scale: 1.0 }, { scale: 1.06, duration: BEAT, ease: "none" }, 0);
|
||||
|
||||
// Register synchronously — key MUST match data-composition-id above.
|
||||
// Async registration races the renderer's 45s timeout and the beat
|
||||
// ships black.
|
||||
window.__timelines["beat-N-SLUG"] = tl;
|
||||
})();
|
||||
</script>
|
||||
</template>
|
||||
<!--
|
||||
DO NOT include <script src="…gsap…"> or <script src="hyper-shader-local.js">
|
||||
inside this template. The assembler emits both at root; duplicating them
|
||||
double-loads GSAP and double-inits HyperShader.
|
||||
|
||||
DO NOT include `<link rel="stylesheet" href="...font...">` — bundle fonts
|
||||
via @font-face with local files in assets/fonts/ instead. Network font
|
||||
requests fail under headless render (no DNS, may stall the frame loop).
|
||||
-->
|
||||
Reference in New Issue
Block a user