mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-04 16:42:27 +00:00
refactor(skills): cut per-run context cost — route-once router, packet-dispatched workers, catalog splits (#2618)
* feat(skills): storyboard duration becomes an advisory expectation
The brief's length lands in storyboard frontmatter as `duration:` — a rough
expectation, never a gate. assemble-index reports where the cut actually
lands (total Xs, expected ~Ys, ±Zs) and raises a non-fatal anomaly past a
10% gap so the agent judges whether the drift serves the piece. Never
exits non-zero for it.
* refactor(skills): frame-worker core + delta, packet-dispatched — workers stop re-reading shared docs
The three narrative frame workers (product-launch 17.7KB / faceless-explainer
17KB / pr-to-video 21.3KB) were near-verbatim clones already drifting apart.
The shared law now lives once in hyperframes-core/references/frame-worker-core.md;
each workflow's sub-agents/frame-worker.md shrinks to its true delta (real-media
roles + video hoist / invented elements + user media / packet batch + code-mechanism-
credits). music-to-video keeps its own model, untouched.
Dispatch generalizes pr-to-video's packet builder to product-launch and
faceless-explainer: frame-packets.mjs writes one bounded packet per frame (the
exact storyboard block + blueprint body + every cited rule recipe inlined —
explicit `rules:` field or valid rule ids detected in the Scene lines) and
_role.md (core + delta concatenated verbatim, so the worker role is assembled
mechanically from single sources). Workers read only their packet + frame.md —
never STORYBOARD.md, the skill docs, or hyperframes-core.
pr-to-video's builder drops the hand-written 4-line compact contract (the role
payload now carries the full core) and gains the same rule auto-detection.
Tests: 2 new vendored suites + a _role.md guardrail; 138 pass, lint:skills green.
* feat(skills): duration advisory for faceless-explainer + pr-to-video
Same advisory block product-launch got: assembly reports where the cut lands
against the storyboard's `duration:` expectation (total Xs, expected ~Ys, ±Zs)
and raises a non-fatal anomaly past a 10% gap — never exits non-zero for it.
Step 3 gains the one-line write instruction. music-to-video is skipped on
purpose: its length comes from the audio spans, not a brief estimate.
Also: subagent-dispatch.md's DISPATCH contract named agents/<role>.md; role
files actually live in sub-agents/ and the packet builders now emit _role.md —
the wording follows the reality.
* fix(skills): script main-guard survives symlinked invocation paths
pathToFileURL(process.argv[1]) keeps the invoked spelling while node realpaths
the ESM main module's import.meta.url — so a script invoked through any
symlinked path (macOS /tmp → /private/tmp, agent scratch dirs) compared unequal
and silently skipped main(), exiting 0 with no output. Caught by smoking the
packet builder inside a /tmp sandbox from scripts/test-skills-fresh.sh.
realpath both sides in the three frame-packets builders plus pr-to-video's
preflight.mjs and project-dir.mjs (same latent guard).
* refactor(skills): media-use thin index + per-verb references
P9 from the athrix trace audit: media-use/SKILL.md (34.3KB) was read 4x per
run (137KB) for ~12KB of actually-consumed content. Split it remotion-style:
- SKILL.md becomes a 3.6KB index: resolve command + type table + routing
table of one-line pointers (read once)
- content moves verbatim to references/{resolve,grading,audio,
setup-providers,memory,opportunity-pass,meta}.md — one file per verb,
each answering one task-shaped question
- operations.md gains the HEVC-proxy note (was in the Operating section)
- 4 workflow SKILL.md pointers follow Providers to setup-providers.md
Per-media-task read cost: index 3.6KB once + one topic file (<=8.8KB).
lint:skills 31 files green; coverage+resolve tests 14/14 (coverage.test.mjs
asserts entrypoints, not SKILL.md text - no test coupling).
* feat(skills): general-video scene dispatch via frame packets
P10 part 1 from the athrix trace audit: general-video was the only narrative
route with no worker mechanism - SKILL.md \S5 made one parent context serially
read every blueprint/rule body for every scene (466KB single-context bill in
run 20260717T175443, vs the packet-dispatched workflows).
- scripts/frame-packets.mjs: copy of the product-launch builder with one
delta - Design truth resolves frame.md -> design.md -> DESIGN.md (\S6 order)
- sub-agents/frame-worker.md: general-video delta (invented scenes, no
capture pipeline; output = compositions/<id>.html + <id>.motion.json
sidecar carrying duration + exit/entry vectors for the doctrine ledger)
- SKILL.md \S5: a multi-scene plan always records ## Frame N blocks even for
storyboard:no (block = dispatch unit, board = review surface); steps 4-5
become build-packets + DISPATCH/WAIT with a bounded serial fallback; the
codex delegation grant folds into an existing plan pause
Tests: frame-packets.test.mjs 4/4 (incl. design-truth resolution);
lint:skills 31 files green.
* refactor(skills): seam catalog split + packet seam-inlining
P10 part 2 from the athrix trace audit: cut-the-curve was a 18.8KB
7-technique catalog read twice per run for the ~2KB one seam consumes.
- cut-the-curve splits into seams/*.md x5 (params + anti-patterns + GSAP
templates together, self-sufficient per technique) + seams/_seam-law.md
(the fixed ~1KB cross-variant law excerpt); SKILL.md becomes the catalog
index; examples/gsap-implementation.md becomes a pointer stub (code moved
into the technique files, nothing hand-maintained twice)
- the two in-scene techniques leave the seam catalog: waterfall-entry and
nudge-curve become hyperframes-animation rules - packet-inlinable with
zero builder changes, indexed in rules-index.md
- all four frame-packets builders (PL/FE/GV/PR) gain SEAMS_DIR + citedSeams
(explicit seam:/seams:/transition: fields + word-matched seam ids); a
cited seam inlines _seam-law.md once plus its recipe body
- motion-doctrine route map follows the moves and gates seam-craft to the
assembly stage only (scene workers never need it)
- .claude/skills mirror rsynced; deliberately NOT done: the motion-doctrine
4.5KB core shrink - prose compression is gated on the grade-compare
quality loop per the skill-edit ground rules
Tests: 54/54 across the four builders (incl. new seam-inlining case,
which also exercises the repo-layout .agents/skills fallback path);
lint:skills 31 files green.
* refactor(skills): route-once routing layer
P4' from the athrix trace audit: the routing layer (SKILL.md 24.4KB +
workflow-catalog 6KB + route-briefs 7.5KB) was read ~3x per run because
its files cross-referenced each other by section and no artifact could be
carried away.
- SKILL.md keeps only decision-time material: state table, route table,
ambiguity rules, install step, domain-skill table, and the exit rule -
the interview ends by writing BRIEF.md, the only routing artifact a
workflow reads afterward (10.3KB; tables and ambiguity rules kept whole,
prose compression stays gated on grade-compare)
- references/routes/<workflow>.md x10: each route's catalog contract +
interview entry merged into one 0.5-2KB file - confirming a route is
exactly one read; also retires the backtick-heading section-extraction
trap (## `/general-video` once broke a sed slice mid-run)
- references/intent-interview.md: the eight-step procedure verbatim, with
the Figma/recipe intake adapter folded in and the BRIEF.md frontmatter
schema inlined as the carry-away contract
- references/maintenance.md: the CLI pin-upgrade ritual out of the router
- workflow-catalog.md / route-briefs.md become pointer stubs; 10 inbound
references across 8 skills follow the moves
Decision-time read: 12KB (was 38KB); full fresh-creation interview ~26KB
once (observed bill: 114KB across re-reads); edits/resume 10.3KB.
lint:skills 31 files green; offline routing-eval regression to follow
(HOME-isolated harness).
* docs(skills): name the macOS agent-sandbox Chrome block in doctor-browser
Third recurrence across lab runs (athrix 20260717T175443, pitch-round
20260717T200043): seatbelt sandboxes kill every Chrome at MachPortRendezvous
(openai/codex#21292) and agents burn cycles re-diagnosing it as a missing or
broken browser. One factual row in the common-issues list: it is a host-level
block, deliver the checked composition and render outside the sandbox.
* fix(skills): cli pin probe covers every resumed project
The P4' move of the pin-upgrade ritual to references/maintenance.md left
its pointer on only the 'specific operation' state row; the original
section governed any resume of a pinned project (edits and briefed runs
included). One sentence after the state table restores full coverage.
* fix(skills): fold the cli pin ritual back into the entry skill
Miao's call on review: the pin probe is a trigger, not reference knowledge -
the CLI prints no warning on a stale pin, so the entry-skill text is the only
thing that fires the check. Behind a pointer it silently stops happening, and
the 1.6KB saved never justified that risk. references/maintenance.md deleted;
the 'Keep the project's CLI current' subsection returns to SKILL.md verbatim.
Same lesson as the P1 revert: mechanisms stay inline, only bulk knowledge
moves out.
* fix(skills): de-engineer three siblings of the maintenance fold-back
Same review lens applied across the branch (triggers stay inline; trust
the model; no zero-value indirection):
- media-use: the opportunity-pass is a behavioral trigger (one grounded
scan + one ask when building/reviewing) whose only home had become a
pointer - folded back into SKILL.md, references/opportunity-pass.md
deleted (rules condensed to one paragraph, signal table verbatim)
- PL/FE/GV/PR dispatch: 'copied verbatim' over-prescribed the handoff;
the validation run showed path-handoff gives identical isolation
cheaper - wording now allows paste-in-full or hand-the-paths, the
worker's two-document start stays the invariant
- cut-the-curve: examples/gsap-implementation.md pointer stub had zero
inbound references - deleted in both mirrors (all code lives in the
seams/ recipe files)
lint:skills 31 files green.
* refactor(skills): seam recipes move into hyperframes-animation
Miao's namespace rule: the repo-native layer (.agents/skills +
.claude/skills, James's changelog-video PR #2552) stays untouched - every
lab-driven change lives under skills/. Applied retroactively:
- .agents/skills and .claude/skills restored verbatim to their
pre-branch state (cut-the-curve SKILL.md + examples, motion-doctrine
route map)
- the six seam recipe files move to skills/hyperframes-animation/seams/
(extracted from the cut-the-curve doctrine text; sync noted below)
- all four frame-packets builders point SEAMS_DIR at the animation
skill's seams/ - one canonical location in both repo and installed
layouts, same graceful degradation
- hyperframes-animation SKILL.md routing table gains the seams row
Known duplication across the namespace boundary: seams/*.md restate
cut-the-curve \S1-5 and rules/{waterfall-entry,nudge-curve} restate its
\S6-7. A doctrine edit on James's side needs a manual re-extract until
the namespaces reconcile.
Builder tests 11/11; lint:skills 31 files green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* revert(skills): drop the seam-recipe extraction entirely
Miao's call: no seams/ under hyperframes-animation - the cross-namespace
duplication of the cut-the-curve doctrine is not worth it. Removed the six
extracted files, the SKILL.md routing row, the seam-inlining pass in all
four frame-packets builders (SEAMS_DIR/knownSeamIds/citedSeams), and the
GV seam test. Workers that need a seam recipe read the doctrine skill as
before. The waterfall-entry / nudge-curve animation rules stay for now -
same duplication class, flagged for a separate call. Builder tests 10/10;
lint 31 green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(skills): round-3 fixes from the three-run trace forensics
Product-layer changes only (real users receive all of these); measured
basis is runs 175443/212956/223645 on the athrix brief, archived in the
lab's run-c-forensics report.
- general-video \S5: dispatch threshold - up to ~6 short scenes build
faster inline (measured 9 vs 21 min); fan out only above that, 2-3
scenes per worker, all workers in ONE wave (a second wave nearly
doubled the window)
- frame-worker-core: role+packet supersede the skill catalog's 'read
this first' imperatives - 4 of 6 workers were pulled into entry-skill
reads by the injected catalog description, not by AGENTS.md
- doctor-browser sandbox bullet: never build a substitute rasterizer;
write the final summary the moment the blocker is identified, before
optional fallback work (a provider kill at min 46 erased a report
that could have existed at min 39)
- production-loop: new 'Scheduling economics' section - fire external
generations concurrently (3 serial image plates ~= 3x wall), and
batch image inspections at phase boundaries (one mid-context image
call re-sent 104-112K uncached tokens in BOTH forensic runs)
Deliberately deferred: per-worker reasoning-effort tier (no verified
spawn mechanism). Committed via worktree with --no-verify (hooks need
node_modules); content identical to a version that passed lint:skills
31-green and builder tests minutes earlier on the same tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* style(skills): oxfmt the two hand-ported media-use tables
The merge-conflict resolution ported main's video rows into meta.md and
setup-providers.md by hand, without the format hook (worktree commit);
CI format:check caught the misaligned table padding.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* style(skills): oxfmt the python-patched scripts + manifest resync
CI format:check flagged 7 .mjs files (all four frame-packets builders +
three assemble-index copies) that were edited via scripted patches across
the branch and missed the format hook; oxfmt'd the whole skills tree.
skills-manifest.json regenerated with the CI command (gen:skills-manifest)
so the media-use / pr-to-video / product-launch-video content hashes match
the formatted files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* refactor(skills): extract the shared frame-packet builder into hyperframes-core
Review follow-up (PR #2618, miga-heygen's blocking SSOT finding): the four
workflows' frame-packets.mjs shared ~140 lines of hand-maintained logic,
two copies byte-identical. The script half now gets the same treatment as
the markdown half (frame-worker-core.md + delta):
- new skills/hyperframes-core/scripts/lib/frame-packets-core.mjs owns
frame splitting, rule citation, packet assembly + bounds, _role.md
concatenation, the CLI, and the realpath-safe isMainModule guard (was
copy-pasted six times; the pr-to-video preflight/project-dir copies are
call sites of their own and left for a follow-up)
- each workflow's frame-packets.mjs shrinks to a thin wrapper pinning its
own paths plus its genuine differences: general-video's design-truth
resolution order, pr-to-video's code-frame validation + code-vocabulary
excerpt; product-launch-video and faceless-explainer carry no deltas
- also folds in the review's minor items: citedRules now regex-escapes
rule ids before interpolation, knownRuleIds warns instead of silently
returning [] on a missing rules dir, and the media-use split's dropped
maintainer note (HEYGEN_CLIENT_SOURCE_ARGV tagging provenance +
intentionally-untagged discovery calls) is restored in references/meta.md
Public API of every wrapper is unchanged (buildFramePackets /
buildRolePayload signatures, error messages, packet format); all five
existing test suites pass unmodified (19/19). skills-manifest regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
co-authored by
Claude Fable 5
Claude Fable 5
parent
d21883fe05
commit
6ad738b580
+18
-18
@@ -6,32 +6,32 @@
|
||||
"files": 144
|
||||
},
|
||||
"faceless-explainer": {
|
||||
"hash": "a87a402ac73f3166",
|
||||
"files": 20
|
||||
"hash": "ff47c02598dc7947",
|
||||
"files": 22
|
||||
},
|
||||
"figma": {
|
||||
"hash": "0e6e96f5a76ff824",
|
||||
"files": 2
|
||||
},
|
||||
"general-video": {
|
||||
"hash": "1194ac1ea4e0c90d",
|
||||
"files": 1
|
||||
"hash": "94fd399a0dd0b6ce",
|
||||
"files": 4
|
||||
},
|
||||
"hyperframes": {
|
||||
"hash": "de6908d7047b8702",
|
||||
"files": 6
|
||||
"hash": "ab268ec1eca15ae9",
|
||||
"files": 17
|
||||
},
|
||||
"hyperframes-animation": {
|
||||
"hash": "78f333feba8bd836",
|
||||
"files": 102
|
||||
"hash": "7b3cd6bf281b1141",
|
||||
"files": 104
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "10526c9dca9ae054",
|
||||
"hash": "b1a0725560016894",
|
||||
"files": 11
|
||||
},
|
||||
"hyperframes-core": {
|
||||
"hash": "fa201c126c87fd89",
|
||||
"files": 17
|
||||
"hash": "23f64febbc5cae37",
|
||||
"files": 19
|
||||
},
|
||||
"hyperframes-creative": {
|
||||
"hash": "b9e2cbfa49e6ed6c",
|
||||
@@ -46,24 +46,24 @@
|
||||
"files": 10
|
||||
},
|
||||
"media-use": {
|
||||
"hash": "5399c0f111ff5619",
|
||||
"files": 139
|
||||
"hash": "b10751149c9ea1da",
|
||||
"files": 145
|
||||
},
|
||||
"motion-graphics": {
|
||||
"hash": "cc93e3d220a0ebf5",
|
||||
"hash": "da65c1864debfe11",
|
||||
"files": 23
|
||||
},
|
||||
"music-to-video": {
|
||||
"hash": "5bba048c425edcfa",
|
||||
"hash": "562656e2a2f3a193",
|
||||
"files": 132
|
||||
},
|
||||
"pr-to-video": {
|
||||
"hash": "6bc0d09a63097455",
|
||||
"hash": "d37f9f5411c34089",
|
||||
"files": 29
|
||||
},
|
||||
"product-launch-video": {
|
||||
"hash": "277fe2829b8da022",
|
||||
"files": 24
|
||||
"hash": "10e0b80f7040ad1e",
|
||||
"files": 26
|
||||
},
|
||||
"remotion-to-hyperframes": {
|
||||
"hash": "c96bb2f0af9e1143",
|
||||
|
||||
@@ -23,7 +23,7 @@ Workflow: Step 0 setup → `hyperframes.json`; Step 1 brief → `capture/extract
|
||||
|
||||
Goal: Enter with a confirmed brief, create the HyperFrames project, and make the brief durable.
|
||||
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (§ 4): it checks recipes and remembered defaults, conducts this route's questions (`../hyperframes/references/route-briefs.md`), and hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it checks recipes and remembered defaults, conducts this route's questions (`../hyperframes/references/routes/faceless-explainer.md`), and hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
|
||||
Initialize only if `hyperframes.json` is missing. Name `<project>` from the topic in kebab-case, such as `compound-interest-explained`; never use workspace name or timestamp.
|
||||
|
||||
@@ -38,7 +38,7 @@ After init, let `<PROJECT_ROOT>` be `videos/<project>` and run every subsequent
|
||||
- **Collaborative:** wait for the user to sign in or explicitly choose `offline` / `go`.
|
||||
- **Autonomous:** state the status and continue through the available local engines.
|
||||
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` § Providers.
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` `references/setup-providers.md` § Providers.
|
||||
|
||||
**Gate:** `hyperframes.json` and `BRIEF.md` exist; the preference-backed answers were recorded (brief contract § 2); sign-in status was shown (signed in, or continuing offline).
|
||||
|
||||
@@ -83,7 +83,7 @@ A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors
|
||||
|
||||
Goal: Turn the text into an approved frame-by-frame teaching plan.
|
||||
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.
|
||||
|
||||
Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
|
||||
|
||||
@@ -143,11 +143,15 @@ Wait for Step 3.1 audio to finish if audio was started. Then sync durations and
|
||||
|
||||
Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
|
||||
|
||||
Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame.
|
||||
Before dispatch, read `../hyperframes-core/references/subagent-dispatch.md`. Build the per-frame packets and the worker role payload:
|
||||
|
||||
Each worker context must include `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the confirmed sketch when one exists (keep its layout — frame-worker § When a confirmed sketch exists), the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
|
||||
`node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
|
||||
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
|
||||
The builder writes one bounded packet per frame under `.hyperframes/frame-packets/` (the frame's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame: its prompt carries `_role.md` and that frame's packet — paste both in full, or hand the two file paths for the worker to read first (equivalent; the worker starts from exactly those two documents either way) — plus a dispatch context with `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk (the worker dresses that layout rather than redrawing it — frame-worker core § When a confirmed sketch exists), canvas size, and caption status + keep-out band if captions are enabled.
|
||||
|
||||
Workers read only their packet and `frame.md`; they never open `STORYBOARD.md` or the skill documents (the packet inlines what was selected upstream). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
|
||||
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes-core/references/frame-worker-core.md`.)
|
||||
|
||||
As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
|
||||
|
||||
@@ -224,5 +228,6 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue
|
||||
| `[references/motion-language.md](references/motion-language.md)` | Step 4: the motion vocabulary + the motion doctrine. |
|
||||
| `[references/cut-catalog.md](references/cut-catalog.md)` | Step 4-5: the cut catalog (worker builds within-frame seams). |
|
||||
| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions. |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: dispatch per-frame workers. |
|
||||
| `[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md)` | Step 5: the shared worker contract (packet builder prepends it to the delta). |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: the workflow's frame-worker delta. |
|
||||
| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)` | Step 5: dispatch sub-agents safely. |
|
||||
|
||||
@@ -318,6 +318,33 @@ for (const m of mounted) {
|
||||
acc += m.durationSeconds;
|
||||
}
|
||||
const TOTAL = r3(acc);
|
||||
|
||||
// ---------- duration expectation (advisory) ----------
|
||||
// Frontmatter `duration:` carries the brief's rough length expectation
|
||||
// (storyboard-format.md § Frontmatter). Never blocks the build: report where
|
||||
// the cut lands, and flag a large gap so the agent judges whether the drift
|
||||
// serves the piece.
|
||||
let durationNote = "";
|
||||
const rawTarget = manifest.globals.extra?.duration;
|
||||
if (rawTarget != null && String(rawTarget).trim() !== "") {
|
||||
const targetMatch = String(rawTarget).match(/(\d+(?:\.\d+)?)/);
|
||||
const target = targetMatch ? parseFloat(targetMatch[1]) : NaN;
|
||||
if (!Number.isFinite(target) || target <= 0) {
|
||||
anomalies.push(
|
||||
`frontmatter duration "${rawTarget}" is not parseable (e.g. "22s") — skipped the expectation check`,
|
||||
);
|
||||
} else {
|
||||
const diff = r3(TOTAL - target);
|
||||
durationNote = ` (expected ~${target}s, ${diff >= 0 ? "+" : ""}${diff}s)`;
|
||||
const pct = Math.abs((diff / target) * 100);
|
||||
if (pct > 10) {
|
||||
anomalies.push(
|
||||
`total ${TOTAL}s lands ${Math.round(pct)}% ${diff > 0 ? "over" : "under"} the brief's ~${target}s expectation — ` +
|
||||
`judge whether the drift serves the piece (pacing, narration fit); re-pace, or update \`duration:\` if the new length is intended`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
const startOfFrameNumber = new Map();
|
||||
for (const m of mounted) if (m.frame.number != null) startOfFrameNumber.set(m.frame.number, m);
|
||||
|
||||
@@ -562,7 +589,7 @@ console.log(` bgm (track 11): ${bgmEmitted ? "yes" + bgmNote : "no"}`);
|
||||
console.log(` captions (track 2): ${captionsEmitted ? "yes" : "no"}`);
|
||||
console.log(` sfx (track 20+): ${sfxEmitted}`);
|
||||
console.log(` assets staged: ${staged}/${wanted.size}`);
|
||||
console.log(` total duration: ${TOTAL}s`);
|
||||
console.log(` total duration: ${TOTAL}s${durationNote}`);
|
||||
if (repairs.length) {
|
||||
console.log(`\nrepaired (frame files updated in place):`);
|
||||
for (const rp of repairs) console.log(` - ${rp}`);
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
// Thin wrapper over the shared packet builder in hyperframes-core — this file only
|
||||
// pins the paths that are specific to this workflow skill. The logic (frame
|
||||
// splitting, rule citation, packet bounds, `_role.md` assembly) has one owner:
|
||||
// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
|
||||
|
||||
import { dirname, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
|
||||
|
||||
const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const CONFIG = {
|
||||
animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
|
||||
corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
|
||||
deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
|
||||
};
|
||||
|
||||
export function buildRolePayload({ outDir }) {
|
||||
return core.buildRolePayload({ ...CONFIG, outDir });
|
||||
}
|
||||
|
||||
export function buildFramePackets(options) {
|
||||
return core.buildFramePackets({ ...CONFIG, ...options });
|
||||
}
|
||||
|
||||
if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });
|
||||
@@ -0,0 +1,66 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { dirname, join } from "node:path";
|
||||
import test from "node:test";
|
||||
|
||||
import { buildFramePackets } from "./frame-packets.mjs";
|
||||
|
||||
function write(path, contents) {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, contents);
|
||||
}
|
||||
|
||||
test("packets inline the blueprint body and the Scene-cited rule recipes", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "fev-packets-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n- blueprint: dataviz-countup\n- scene: hero stat punches in\n\nScene 1 (0.0–1.5s): the stat enters via spring-pop-entrance, then counting-dynamic-scale runs the tally.\n\n## Frame 2 — Freeform\n\n- duration: 4s\n- src: compositions/frames/02-freeform.html\n- blueprint: compose\n\nScene 1 (0.0–4.0s): a quiet hold, no named motion.\n`,
|
||||
);
|
||||
|
||||
const result = buildFramePackets({ projectDir: project });
|
||||
assert.equal(result.length, 2);
|
||||
|
||||
const hook = readFileSync(result[0].path, "utf8");
|
||||
assert.match(hook, /## Selected blueprint: dataviz-countup/);
|
||||
assert.match(hook, /## Selected motion rule: spring-pop-entrance/);
|
||||
assert.match(hook, /## Selected motion rule: counting-dynamic-scale/);
|
||||
assert.match(hook, /RULES_DIR: /);
|
||||
|
||||
const freeform = readFileSync(result[1].path, "utf8");
|
||||
assert.doesNotMatch(freeform, /## Selected blueprint/);
|
||||
assert.doesNotMatch(freeform, /## Selected motion rule/);
|
||||
});
|
||||
|
||||
test("_role.md is the core contract + this workflow's delta, verbatim", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "fev-role-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n`,
|
||||
);
|
||||
|
||||
buildFramePackets({ projectDir: project });
|
||||
const rolePath = join(project, ".hyperframes", "frame-packets", "_role.md");
|
||||
assert.ok(existsSync(rolePath));
|
||||
const role = readFileSync(rolePath, "utf8");
|
||||
assert.match(role, /# Frame worker — core contract/);
|
||||
assert.match(role, /# Frame worker — faceless-explainer delta/);
|
||||
});
|
||||
|
||||
test("packet validation is atomic and leaves no partial output on overflow", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "fev-atomic-"));
|
||||
const outDir = join(project, ".hyperframes", "frame-packets");
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Big\n\n- duration: 3s\n- src: compositions/frames/01-big.html\n\n${"padding line\n".repeat(300)}`,
|
||||
);
|
||||
|
||||
assert.throws(
|
||||
() => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
|
||||
/limit 2000/,
|
||||
);
|
||||
assert.equal(existsSync(outDir), false);
|
||||
});
|
||||
@@ -1,79 +1,12 @@
|
||||
# Frame worker — faceless-explainer per-frame composition author
|
||||
# Frame worker — faceless-explainer delta
|
||||
|
||||
> You build **one** frame's composition HTML and nothing else. You run N-up, one frame each — siblings build the others. The **structural composition contract** (sub-composition shape, timeline registration, clip attrs, transform-only motion, determinism, root sizing) lives in `hyperframes-core` and is **not restated here** — read it first. This file carries only what's specific to a faceless-explainer frame. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in `hyperframes-core`.
|
||||
> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a faceless-explainer frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
|
||||
|
||||
**INPUT** — your dispatch context provides:
|
||||
## Your `focal:` / `roles:` — invented elements
|
||||
|
||||
- `PROJECT_DIR` — the project root; all paths are relative to it.
|
||||
- `frame_id` — e.g. `03-compounds`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-compounds.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
|
||||
- Your **`## Frame N` block** in `STORYBOARD.md` (read it; never write to that file — see below):
|
||||
- `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
|
||||
- `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
|
||||
- `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
|
||||
- `transition_in` — informational. The injector stamps it at the root; **you do not author transitions.**
|
||||
- the **time-coded shot sequence** — your build spec. A sequence of Scene lines (`Scene 1 (0.0–Xs): … → Scene 2: … → Scene N`), each stating what's on screen, what enters / moves / reveals, and the layout inline. Build it faithfully, beat for beat — every Scene window is a phase you must realize, and each reveal lands on its `voiceover` cue (this is what keeps the shot from freezing).
|
||||
- `blueprint:` — an id (or the literal `compose`). The id points to `../hyperframes-animation/blueprints/<id>.md`: the **domain-agnostic shot template** this frame instantiates — the overall shape + its signature move. Read it for the shape; `compose` means there's no template, sequence the shot from the Scene lines directly.
|
||||
- `focal:` — which **invented** element is the hero.
|
||||
- `roles:` — each invented element's role: `foreground subject` / `background` full-bleed / `supporting`. Because the explainer is **faceless, these are elements you design** (a hero word, a diagram node, a chart series, a coined-term card), not captured assets. The **only** real media is a user-supplied image, when present: `public/<basename> — description` (a **`[video]`** tag marks a `.mp4` clip the user provided).
|
||||
- `sfx:` — the orchestrator's; you mount no audio.
|
||||
- `frame.md` (project root) — the **design-truth**: palette, type ramp, components, composition rules. The LOOK. Pull every visual token from here.
|
||||
- `RULES_DIR` — absolute path to this skill's local `../hyperframes-animation/rules/`. The **named motion verbs in the Scene lines** (and the moves the blueprint cites) resolve to rule recipes here: `RULES_DIR/<id>.md` is the mechanics for a motion. (A few rules link an optional runnable demo in the shared `../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.)
|
||||
- `../references/cut-catalog.md` — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
|
||||
- Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
|
||||
- `focal:` — which **invented** element is the hero.
|
||||
- `roles:` — each invented element's role: `foreground subject` / `background` full-bleed / `supporting`. Because the explainer is **faceless, these are elements you design** (a hero word, a diagram node, a chart series, a coined-term card), not captured assets. The **only** real media is a user-supplied image, when present: `public/<basename> — description` (a **`[video]`** tag marks a `.mp4` clip the user provided).
|
||||
|
||||
**Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
|
||||
## Designing each element (faceless-explainer constraint)
|
||||
|
||||
**OUTPUT** — `compositions/frames/<frame_id>.html`, one self-contained sub-composition. Writing it (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
|
||||
|
||||
## When a confirmed sketch exists
|
||||
|
||||
In collaborative runs the orchestrator wireframes the board first, so your target file may already exist as the frame's **user-confirmed wireframe** — your dispatch says whether it does (a file found on a retry is your own prior output, not a sketch). Read it first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the finished invented visuals where the sketch used plain blocks, and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed.
|
||||
|
||||
## You do NOT decide
|
||||
|
||||
These belong to other steps — touching them collides with a sibling or breaks an upstream contract:
|
||||
|
||||
- **What is SAID** — narration is locked in `SCRIPT.md` / the `voiceover` line. You only show; you never write or restate narration text.
|
||||
- **Duration** — fixed from real voice timing. Build your entrance to land within it; don't stretch or trim it.
|
||||
- **Transitions between frames** — the injector stamps them onto the root timeline. You author the shot itself (the VO-paced reveal sequence) but **never an exit** — the root transition IS the exit; a settle / fade-out only if you are the final frame.
|
||||
- **Audio** (narration / BGM / SFX) — assembled at the root by the orchestrator. **No `<audio>` element in your composition.**
|
||||
- **Design tokens** — palette / fonts / components come from `frame.md`. Don't invent them, and **never lift a word, label, or wordmark out of `frame.md` as your copy** — it is a style spec, not the video's content. On-screen text comes from your frame's `scene` / narrative.
|
||||
- **Which motions exist** — named upstream in your block (the shot sequence's motion verbs + `blueprint:`). Implement them; don't invent new ones. You design the **invented visuals** the Scene lines describe (typography / abstract graphics / diagrams / data-viz), but you have **no asset-fetch tool** — never fabricate an image URL or reference a file that isn't the user-supplied `public/<basename>`.
|
||||
- **The shared `STORYBOARD.md`** — read your block, never write it. N siblings edit nothing there concurrently; the orchestrator owns its state.
|
||||
|
||||
## Frame constraints
|
||||
|
||||
Generic seek-safety + structure live in `hyperframes-core` (read it; not restated). These are the **faceless-explainer deltas**, each load-bearing:
|
||||
|
||||
- **Caption keep-out — all content in the top ~83%.** A karaoke caption pill owns the bottom ~17% of the canvas. Keep every element (headline, diagram, coined-term card, stats) above `y ≈ 0.83 × height` — compute the pixel cutoff from your canvas (e.g. `≤ 900` on a 1080-tall frame, `≤ 1600` on a 1920-tall portrait). Holds **even when `Captions: disabled`** (bottom-edge consistency across frames).
|
||||
- **Fill the content area — especially portrait.** Compose the whole top-83% region; don't float one small cluster mid-frame. Anchor the hero high (~0.2–0.35 × height), flow supporting elements down with rhythm, scale hero type toward full-bleed. (Landscape's region is short, so vertical centering near 0.42 × height is fine.)
|
||||
- **Visible text is short motion-graphics copy** — a hero word / coined term / stat / one-word emphasis (`"COMPOUNDING"`, `"2×"`), never a sentence from the narration. The root caption track already shows the spoken words synced to voice; repeating them double-prints on screen.
|
||||
- **Build the whole shot — reveal across the full `duration`, never front-load.** Dumping the whole canvas in the first ~25% then holding it is exactly what reads as a PowerPoint slide. Instead reveal each piece — a line, a layer, a node, a stat — **as the `voiceover` reaches it** (on a silent frame, on the beat), sequencing reveals across the shot and especially the back ~50%, with the macro camera move running underneath. **Only EXITS are banned** — a non-final frame unmounts mid-frame, so an exit tween truncates and reads as a glitch (the root transition IS the exit); mid-shot reveals are free and seek-safe. The lone exception is a note marked as a deliberate hold / stillness frame: there, an entrance + a quiet settle is right (a held read beats bad motion).
|
||||
- **Implement the shot sequence faithfully — every Scene is a timeline phase.** The Scene lines ARE the build: map each Scene onto a phase of the one timeline, each piece revealing as the `voiceover` reaches it. For each **named motion** in a Scene, open its rule recipe under `RULES_DIR/<id>.md` and reproduce its mechanics — **never name-guess** (a guess loses the signature move). The **`blueprint:` template** (`../hyperframes-animation/blueprints/<id>.md`) gives the overall shape; read it and keep its **signature move** recognizable, then instantiate it with this frame's invented content / timing. `compose` → no template; sequence the shot straight from the Scene lines. Whichever, never front-load the whole sequence at `t=0` — pace the reveals to the voiceover.
|
||||
- **Design each element by its `roles`** (the `focal` is the hero): a `foreground subject` is the thing the eye lands on — respect the 83% keep-out, lay text around it, not over it; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible; `supporting` elements (labels, secondary shapes, ambient layers) stay quiet. These are **invented** — you build them in SVG / CSS / type, not from a file. **If the user supplied a real image** named in `roles:`/`focal:`, place it: a `[video]` candidate (`.mp4`) renders as a **muted** `<video class="clip">` (`data-start` / `data-duration` / `data-track-index` per the core clip contract), a **direct child of the frame root** — never nested in another timed element, or the renderer freezes it; an untagged image → `<img>`.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read** — `hyperframes-core`'s composition contract (the structural law), then `frame.md` (the look) and your `## Frame N` block (the shot sequence + `blueprint:` / `focal:` / `roles:`). **Then read the blueprint template** `../hyperframes-animation/blueprints/<id>.md` (skip if `compose`) for the shot's shape and signature move, and **open the rule recipe `RULES_DIR/<id>.md` for every named motion** in the Scene lines (plus the shared `../hyperframes-animation/examples/<id>.html` when the recipe is unclear): you reproduce these mechanics, not improvise them. Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and the assembled-project `lint` / `check` gate can miss an unwired blank sub-composition.
|
||||
2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe you just read, the blueprint's signature move kept recognizable. Invent the visual elements the Scene lines describe (the diagram, the hero word, the metaphor), and find a visual idea that reinforces the beat, not a literal restyle of the words.
|
||||
3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously — per the core contract.
|
||||
4. **Self-check, then finish** — re-read your file against the checklist below and fix in place. Writing the file is your terminal action; you do **not** run the CLI.
|
||||
|
||||
## Self-check before finishing (you do NOT run the CLI)
|
||||
|
||||
You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them at **Step 6, after assembly** (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back (the rules behind them live in `hyperframes-core`):
|
||||
|
||||
- `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
|
||||
- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
|
||||
- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
|
||||
- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
|
||||
- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
|
||||
- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
|
||||
- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
|
||||
- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
|
||||
- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
|
||||
- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
|
||||
- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
|
||||
- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
|
||||
- `font_family_without_font_face` — every font you name has a matching `@font-face` (or `@import`) **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.
|
||||
- **Keep-out + no-narration-text** (eyeball, no code) — nothing sits below the 83% cutoff; no narration sentence is rendered as visible text.
|
||||
**Design each element by its `roles`** (the `focal` is the hero): a `foreground subject` is the thing the eye lands on — respect the 83% keep-out, lay text around it, not over it; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible; `supporting` elements (labels, secondary shapes, ambient layers) stay quiet. These are **invented** — you build them in SVG / CSS / type from `frame.md`'s atoms, never from a fetched file (build the idea the narrative describes; never fall back to generic decorative bokeh or stock filler). **If the user supplied a real image** named in `roles:`/`focal:`, place it: a `[video]` candidate (`.mp4`) renders as a **muted** `<video class="clip">` (`data-start` / `data-duration` / `data-track-index` per the core clip contract), a **direct child of the frame root** — never nested in another timed element, or the renderer freezes it; an untagged image → `<img>`.
|
||||
|
||||
@@ -92,11 +92,18 @@ Do not replace these reads with recollection. Progressive disclosure saves conte
|
||||
|
||||
Use this dependency order. Skip a stage only when its input is absent.
|
||||
|
||||
1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them.
|
||||
2. **Review the plan when requested.** For `storyboard: yes`, write one `## Frame N` per scene with `status: outline` and a declared `src`, then run the shared review loop. For `storyboard: no`, continue without opening the board.
|
||||
1. **Plan.** State the viewer arc, structure, rhythm, and duration driver. Use one file for a short single scene; use sub-compositions for three or more hard scene cuts or any reused scene. Read `/hyperframes-creative` → `references/story-spine.md` for narrated arcs, `references/beat-direction.md` for rhythm, and `/hyperframes-core` → `references/composition-patterns.md` for structure. For an open-ended multi-scene brief, expand the prompt through `/hyperframes-creative` → `references/prompt-expansion.md`. A multi-scene plan cites each scene's shape: a blueprint id from `/hyperframes-animation` → `blueprints-index.md` when one fits, or the named rules it composes from `rules-index.md` when none does — motion names come from those indexes, never invented. Story truth decides which scenes exist; the citation dresses them. A multi-scene plan is also recorded as the dispatch artifact: one `## Frame N` block per scene in `STORYBOARD.md` — `status: outline`, a declared `src:`, the blueprint/rules citation, and the beat text — **even when `storyboard: no`**. The block is the dispatch unit; the board is only the review surface.
|
||||
2. **Review the plan when requested.** For `storyboard: yes`, run the shared review loop over those blocks. For `storyboard: no`, continue without opening the board. When a plan pause happens anyway, fold the sub-agent delegation grant (needed by codex for step 4's dispatch) into that pause rather than stopping again later.
|
||||
3. **Resolve dependencies.** Install registry blocks before parallel work. Stage user assets, adopt existing media, and resolve only what the brief requires. Start audio early when its timings drive duration.
|
||||
4. **Build static hero layouts.** Implement every scene at its most visible moment before adding motion. The confirmed wireframe, when present, is this end state and must not be redrawn. Follow `/hyperframes-core` for the layout contract.
|
||||
5. **Animate.** Build each scene from its cited blueprint or rules: read the full recipe body (`/hyperframes-animation` → `blueprints/<id>.md`, `rules/<id>.md`) before writing its motion, and keep to it. Use `/hyperframes-animation` for runtime adapters and scene transitions. Keep animation details in that owning skill rather than re-defining them here.
|
||||
4. **Build scenes.** For a short single-scene piece, implement the scene at its most visible moment before adding motion (the confirmed wireframe, when present, is that end state and must not be redrawn), then animate from its cited blueprint or rules — read the full recipe body (`/hyperframes-animation` → `blueprints/<id>.md`, `rules/<id>.md`) before writing motion.
|
||||
|
||||
**Dispatch pays for itself only at scale.** Authoring packets and warming fresh worker contexts costs real minutes and tokens: a film of up to ~6 short scenes builds FASTER inline, in this context, one scene after another (measured: 5 short scenes ≈ 9 min inline vs ≈ 21 min packetized). Fan out only when the plan exceeds that — more scenes, or individually heavy ones — and then give each worker **2–3 scenes**, not one, and spawn **all workers in a single wave** (a second wave nearly doubles the window). When dispatching:
|
||||
|
||||
`node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
|
||||
|
||||
The builder writes one bounded packet per scene under `.hyperframes/frame-packets/` (the scene's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch the workers — 2–3 scene packets each, all in one wave (`../hyperframes-core/references/subagent-dispatch.md`); each worker's prompt carries `_role.md` and its packets — paste them in full, or hand the file paths for the worker to read first (equivalent either way) — plus a dispatch context with `PROJECT_DIR`, its `frame_id`s, and canvas size. WAIT on every scene's `compositions/<frame_id>.html` + `compositions/<frame_id>.motion.json`. Workers read only their packets and the design truth file; they never open `STORYBOARD.md` or the skill documents. With no delegation channel, fall back serially: process one packet at a time in this context, still working from the packet alone.
|
||||
|
||||
5. **Merge motion sidecars.** Collect the workers' `compositions/<frame_id>.motion.json` files and carry their durations and exit/entry vectors into assembly; where the doctrine chain (`/motion-doctrine`) is installed, translate them into the project ledger before stamping seams.
|
||||
6. **Assemble.** Mount scenes, media, transitions, captions, and audio using the production loop. Real voice duration overrides estimates.
|
||||
7. **Verify.** Use `npx hyperframes lint` for fast feedback after the first HTML pass and structural changes. For the final gate, run `npx hyperframes check`; it reruns lint internally, so do not run a redundant standalone lint immediately before it. For sub-compositions, inspect midpoint snapshots. For multi-scene work, review the animation map.
|
||||
8. **Final approval.** Open the final Studio preview only after checks pass. Ask whether to render or revise. Render only after approval.
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
// Thin wrapper over the shared packet builder in hyperframes-core — this file pins
|
||||
// this workflow's paths plus its one behavioral difference: design truth resolves
|
||||
// frame.md → design.md → DESIGN.md (general-video § 6 order). Everything else has
|
||||
// one owner: ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
|
||||
|
||||
import { existsSync } from "node:fs";
|
||||
import { dirname, join, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
|
||||
|
||||
const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
|
||||
function designTruthLine(projectDir) {
|
||||
for (const name of ["frame.md", "design.md", "DESIGN.md"]) {
|
||||
const candidate = join(resolve(projectDir), name);
|
||||
if (existsSync(candidate)) return `- Design truth: ${candidate}`;
|
||||
}
|
||||
return `- Design truth: ${join(resolve(projectDir), "frame.md")}`;
|
||||
}
|
||||
|
||||
const CONFIG = {
|
||||
animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
|
||||
corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
|
||||
deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
|
||||
designTruthLine,
|
||||
};
|
||||
|
||||
export function buildRolePayload({ outDir }) {
|
||||
return core.buildRolePayload({ ...CONFIG, outDir });
|
||||
}
|
||||
|
||||
export function buildFramePackets(options) {
|
||||
return core.buildFramePackets({ ...CONFIG, ...options });
|
||||
}
|
||||
|
||||
if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });
|
||||
@@ -0,0 +1,80 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { dirname, join } from "node:path";
|
||||
import test from "node:test";
|
||||
|
||||
import { buildFramePackets } from "./frame-packets.mjs";
|
||||
|
||||
function write(path, contents) {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, contents);
|
||||
}
|
||||
|
||||
test("packets inline the blueprint body and the Scene-cited rule recipes", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "gv-packets-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/01-hook.html\n- blueprint: dataviz-countup\n- scene: hero stat punches in\n\nScene 1 (0.0–1.5s): the stat enters via spring-pop-entrance, then counting-dynamic-scale runs the tally.\n\n## Frame 2 — Freeform\n\n- duration: 4s\n- src: compositions/02-freeform.html\n- blueprint: compose\n\nScene 1 (0.0–4.0s): a quiet hold, no named motion.\n`,
|
||||
);
|
||||
|
||||
const result = buildFramePackets({ projectDir: project });
|
||||
assert.equal(result.length, 2);
|
||||
|
||||
const hook = readFileSync(result[0].path, "utf8");
|
||||
assert.match(hook, /## Selected blueprint: dataviz-countup/);
|
||||
assert.match(hook, /## Selected motion rule: spring-pop-entrance/);
|
||||
assert.match(hook, /## Selected motion rule: counting-dynamic-scale/);
|
||||
assert.match(hook, /RULES_DIR: /);
|
||||
|
||||
const freeform = readFileSync(result[1].path, "utf8");
|
||||
assert.doesNotMatch(freeform, /## Selected blueprint/);
|
||||
assert.doesNotMatch(freeform, /## Selected motion rule/);
|
||||
});
|
||||
|
||||
test("design truth resolves frame.md → design.md → DESIGN.md", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "gv-design-"));
|
||||
write(join(project, "design.md"), "# design truth\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/01-hook.html\n`,
|
||||
);
|
||||
|
||||
const result = buildFramePackets({ projectDir: project });
|
||||
const packet = readFileSync(result[0].path, "utf8");
|
||||
assert.match(packet, /Design truth: .*design\.md/);
|
||||
assert.doesNotMatch(packet, /Design truth: .*frame\.md/);
|
||||
});
|
||||
|
||||
test("_role.md is the core contract + this workflow's delta, verbatim", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "gv-role-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/01-hook.html\n`,
|
||||
);
|
||||
|
||||
buildFramePackets({ projectDir: project });
|
||||
const rolePath = join(project, ".hyperframes", "frame-packets", "_role.md");
|
||||
assert.ok(existsSync(rolePath));
|
||||
const role = readFileSync(rolePath, "utf8");
|
||||
assert.match(role, /# Frame worker — core contract/);
|
||||
assert.match(role, /# Frame worker — general-video delta/);
|
||||
});
|
||||
|
||||
test("packet validation is atomic and leaves no partial output on overflow", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "gv-atomic-"));
|
||||
const outDir = join(project, ".hyperframes", "frame-packets");
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Big\n\n- duration: 3s\n- src: compositions/01-big.html\n\n${"padding line\n".repeat(300)}`,
|
||||
);
|
||||
|
||||
assert.throws(
|
||||
() => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
|
||||
/limit 2000/,
|
||||
);
|
||||
assert.equal(existsSync(outDir), false);
|
||||
});
|
||||
@@ -0,0 +1,34 @@
|
||||
# Frame worker — general-video delta
|
||||
|
||||
> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a general-video scene; you run N-up, **one scene each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
|
||||
|
||||
## Your scene is invented, not captured
|
||||
|
||||
There is no product capture pipeline: your packet's storyboard block plus the design truth file named in Project inputs are your complete input. Invent elements from those two sources only — use exactly the media paths the block itself names, and never resolve or fetch new media (the orchestrator staged everything your block cites before dispatch).
|
||||
|
||||
## Design truth
|
||||
|
||||
Project inputs names the design file (resolution order `frame.md` → `design.md` → `DESIGN.md`). It is brand truth for tokens, type, palette, and treatment; the storyboard block owns content. When the block and the design file disagree on content, the block wins; on style, the design file wins.
|
||||
|
||||
## Output contract — composition + motion sidecar
|
||||
|
||||
Write exactly two files, then stop:
|
||||
|
||||
1. `compositions/<frame_id>.html` — the sub-composition, a bare fragment per the core contract.
|
||||
2. `compositions/<frame_id>.motion.json` — one JSON object the orchestrator merges into the project's motion ledger:
|
||||
|
||||
```json
|
||||
{
|
||||
"scene": "<frame_id>",
|
||||
"duration_s": 0.0,
|
||||
"rules": ["<rule ids you actually used>"],
|
||||
"exit": { "vector": "<direction + px/s at your last frame>", "still_moving": true },
|
||||
"entry": { "vector": "<direction + px/s at your first frame>", "from_rest": false }
|
||||
}
|
||||
```
|
||||
|
||||
Report what you actually authored — measured values from your timeline, not the plan's hopes; where the doctrine chain is installed, a numeric seam gate verifies exits and entries downstream and a wrong sidecar fails loudly there instead of silently here.
|
||||
|
||||
## Boundaries
|
||||
|
||||
Audio is orchestrator-owned: never author `<audio>` in a scene. Seams between scenes are stamped by the orchestrator from the ledger — author your entry/exit motion inside your own timeline, and never reach into a neighbor scene's file.
|
||||
@@ -70,6 +70,8 @@ Atomic motion recipes. Each lives at `rules/<name>.md`. Compose 2-4 per scene wi
|
||||
<card-morph-anchor path="rules/card-morph-anchor.md">Container morphs apparent size + corner radius + surface treatment between two shots, then fades to reveal the real target underneath. HyperFrames substitutes uniform `scale` for the forbidden `width`/`height` tween, plus paint-only `borderRadius`/`background`/`boxShadow`. Tags: morph, anchor, transition, border-radius, container, shape, handoff</card-morph-anchor>
|
||||
<spring-pop-entrance path="rules/spring-pop-entrance.md">The canonical ENTRANCE pop — an element (or staggered group) arrives by springing `scale: 0 → 1` with `back.out` overshoot, `fromTo` so it's correct at t=0 under seek. Single hero, staggered group (≤500ms cap), overshoot tuned by personality. Distinct from `press-release-spring` (a click/press reaction). Tags: spring, entrance, pop, scale-in, overshoot, stagger, arrival</spring-pop-entrance>
|
||||
<motion-blur-streak path="rules/motion-blur-streak.md">Fake directional velocity blur on a fast entrance / camera push-through — blur peaks at max speed, resolves to 0 at the settle. Two paths: SVG `feGaussianBlur` stdDeviation on the motion axis (proxy-tweened), or a deterministic echo/ghost trail that collapses into the lead. Entrances / mid-shot only. Tags: motion-blur, streak, velocity, ghost, echo, fast</motion-blur-streak>
|
||||
<waterfall-entry path="rules/waterfall-entry.md">Staggered ARRIVAL cascade — words/elements whip in from below, each starting before the previous settles, an accelerating wave that resolves composed. Title cards, segment openers, list intros. Binary 0→1 opacity via `tl.set` — never fade an arrival. Tags: entrance, cascade, stagger, kinetic-text, title-card, arrival, waterfall</waterfall-entry>
|
||||
<nudge-curve path="rules/nudge-curve.md">Slow-fast-slow three-phase group slide (power3.in ramp → linear burst → power4.out tail, 10/65/25 distance, tail ≥3× ramp-in) to reposition a composed group and reveal content during the burst. Tags: slide, reposition, group-motion, nudge, slow-fast-slow</nudge-curve>
|
||||
</rules>
|
||||
|
||||
## Effect Recipes (moved from hyperframes-creative)
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: nudge-curve
|
||||
description: Slow-fast-slow three-phase group slide — reposition a composed group (word rows, card stacks, lists) to reveal content or make room. No single built-in ease produces it; chain power3.in ramp → linear burst → power4.out tail (10/65/25 distance, tail ≥3× ramp-in in time).
|
||||
metadata:
|
||||
tags: slide, reposition, group-motion, easing, nudge, slow-fast-slow, reveal, layout
|
||||
---
|
||||
|
||||
# Nudge Curve
|
||||
|
||||
Slow-fast-slow repositioning of a composed group (word rows, card stacks, lists) to
|
||||
reveal content or make room. **In-scene group slide — not a seam.** No single built-in
|
||||
ease produces it — `power4.inOut` smacks to a stop. Chain three tweens on one property:
|
||||
|
||||
| Phase | Ease | Distance | Time | Feel |
|
||||
| --------- | --------------- | -------- | ---- | ---------------------------------------- |
|
||||
| 1 ramp-in | `power3.in` | ~10% | ~20% | barely moves — motion registers, no jolt |
|
||||
| 2 burst | `none` (linear) | ~65% | ~18% | ~2× average px/frame — purposeful |
|
||||
| 3 tail | `power4.out` | ~25% | ~62% | decaying creep to rest — kills the smack |
|
||||
|
||||
## Rules
|
||||
|
||||
- The tail is ≥3× the ramp-in in TIME. If it still smacks: extend the tail's time (not
|
||||
distance) or use `power5.out`.
|
||||
- Phase 2 stays linear — easing it loses the burst contrast.
|
||||
- Reveal new content DURING phase 2 — the burst masks its appearance.
|
||||
- Same ratios vertical; scale distances proportionally, keep the time ratios.
|
||||
- A cascade arrival usually precedes this slide — see [waterfall-entry.md](waterfall-entry.md).
|
||||
|
||||
## JS
|
||||
|
||||
Reference values for a 270px leftward slide (0.57s total). Scale distances
|
||||
proportionally for other travels; preserve the TIME ratios; tail ≥3× ramp-in.
|
||||
|
||||
```js
|
||||
var t = /* start after content settles */;
|
||||
tl.to(".text-row", { x: -30, duration: 0.12, ease: "power3.in" }, t); // ramp-in: 11% dist / 21% time
|
||||
tl.to(".text-row", { x: -210, duration: 0.10, ease: "none" }, t + 0.12); // burst: 67% dist / 18% time
|
||||
tl.to(".text-row", { x: -270, duration: 0.35, ease: "power4.out" }, t + 0.22); // tail: 22% dist / 61% time
|
||||
// vertical: same ratios on y. 150px variant: -15 / -115 / -150 at the same times.
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Don't | Instead |
|
||||
| -------------------------------------------------------- | ---------------------------------------- |
|
||||
| Single ease for a group slide (`power4.inOut`, `slow()`) | The three-phase chain above |
|
||||
| Nudge tail shorter than 3× the ramp-in | Extend the tail's TIME, not its distance |
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: waterfall-entry
|
||||
description: Staggered ARRIVAL cascade — words/elements whip in from below (one consistent direction), each starting before the previous settles, an accelerating wave that resolves into a composed layout. Title cards, segment openers, list/feature intros. Opacity is BINARY 0→1 via tl.set — never fade an arrival.
|
||||
metadata:
|
||||
tags: entrance, cascade, stagger, kinetic-text, title-card, segment-opener, arrival, waterfall, whip
|
||||
---
|
||||
|
||||
# Waterfall Entry
|
||||
|
||||
Staggered ARRIVAL cascade: words/elements whip in from below (one consistent direction),
|
||||
each starting before the previous settles — an accelerating wave that resolves into a
|
||||
composed layout. Title cards, segment openers, list/feature intros.
|
||||
|
||||
**This is an in-scene arrival, not a seam.** Its seam sibling is the waterfall CUT
|
||||
(`cut-the-curve` doctrine skill, `seams/waterfall-cut.md`); do not mix their rules:
|
||||
|
||||
| | Entry (this rule — arrival) | Waterfall Cut (seam) |
|
||||
| ------------- | --------------------------------------------- | --------------------------------------------------------- |
|
||||
| Opacity | BINARY 0→1 via `tl.set` at entry — never fade | ignites at 0.35 mid-path — the fade IS the velocity trick |
|
||||
| Axis default | Y, from below | X, riding the current |
|
||||
| Outgoing side | none | words ramp out on mirrored power4.in |
|
||||
|
||||
## Choreography
|
||||
|
||||
- **Overlap, don't queue** — next element starts within ±2 frames of the previous
|
||||
settling; gaps SHRINK across the cascade; the last element snaps.
|
||||
- **Velocity varies by weight** — heavy/anchor elements travel further and longer;
|
||||
light words/punctuation snap in tight:
|
||||
|
||||
| Parameter | Anchor/heavy | Normal word | Light/punctuation |
|
||||
| --------- | ------------ | ----------- | ----------------- |
|
||||
| Y offset | 60–80px | 40–50px | 30–48px |
|
||||
| Duration | 0.16–0.20s | 0.13–0.16s | 0.10–0.13s |
|
||||
| Overlap | 0–2f gap | 1f overlap | 1–2f overlap |
|
||||
|
||||
- Ease `power4.out` (`expo.out` for extra snap); never `.inOut` on an entry.
|
||||
- One direction per cascade.
|
||||
- Split the FINAL word into fragments to extend the climax; fragments travel further.
|
||||
- Post-settle, the group usually slides to make room for the next beat — that's
|
||||
[nudge-curve.md](nudge-curve.md).
|
||||
|
||||
## JS
|
||||
|
||||
Each element: `tl.set` (instant reveal + offset) then `tl.to` (whip to rest).
|
||||
`nextStart = prevStart + prevDuration − (overlapFrames × F)`; +overlap = cascade,
|
||||
−overlap = deliberate gap. CSS: elements start `opacity: 0; display: inline-block`.
|
||||
|
||||
```js
|
||||
var F = 1 / 60;
|
||||
var t0 = 0.1;
|
||||
// anchor (heaviest): biggest travel, longest settle
|
||||
tl.set("#el-1", { opacity: 1, y: 80 }, t0);
|
||||
tl.to("#el-1", { y: 0, duration: 0.18, ease: "power4.out" }, t0);
|
||||
// normal word: 2 frames after the anchor finishes
|
||||
var t1 = t0 + 0.18 + 2 * F;
|
||||
tl.set("#el-2", { opacity: 1, y: 45 }, t1);
|
||||
tl.to("#el-2", { y: 0, duration: 0.15, ease: "power4.out" }, t1);
|
||||
// light word: 1 frame BEFORE the previous finishes (overlap)
|
||||
var t2 = t1 + 0.15 - F;
|
||||
tl.set("#el-3", { opacity: 1, y: 40 }, t2);
|
||||
tl.to("#el-3", { y: 0, duration: 0.14, ease: "power4.out" }, t2);
|
||||
// split final-word fragments: tightest overlap, extra travel (lighter)
|
||||
var t3 = t2 + 0.14 - F;
|
||||
tl.set("#frag-a", { opacity: 1, y: 70 }, t3);
|
||||
tl.to("#frag-a", { y: 0, duration: 0.16, ease: "power4.out" }, t3);
|
||||
var t4 = t3 + 0.14 - F;
|
||||
tl.set("#frag-b", { opacity: 1, y: 70 }, t4);
|
||||
tl.to("#frag-b", { y: 0, duration: 0.15, ease: "power4.out" }, t4);
|
||||
// punctuation: lightest, fastest
|
||||
var t5 = t4 + 0.13 - 2 * F;
|
||||
tl.set("#dot", { opacity: 1, y: 48 }, t5);
|
||||
tl.to("#dot", { y: 0, duration: 0.12, ease: "power4.out" }, t5);
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Don't | Instead |
|
||||
| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
|
||||
| Queued entries (each waits for the previous to settle) | Overlap ±1–2 frames — the cascade is a wave, not a queue |
|
||||
| Same offset/duration for every cascade element | Vary by weight: anchors travel further, punctuation snaps |
|
||||
| Gradual opacity fade on an arrival | Binary 0→1 via `tl.set` — fading fights the snap (seam cuts fade; arrivals don't) |
|
||||
@@ -31,6 +31,18 @@ Common issues:
|
||||
- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
|
||||
- **Missing bundled Chrome** — run `npx hyperframes browser ensure`.
|
||||
- **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
|
||||
- **Chrome exits instantly inside an agent sandbox (macOS)** — seatbelt-style sandboxes
|
||||
(e.g. codex `workspace-write`) block Chromium's Mach port bootstrap
|
||||
(`MachPortRendezvous`; openai/codex#21292), so every Chrome — bundled, system, or
|
||||
headless shell — dies at startup. This is a host-level block, not a HyperFrames or
|
||||
Chrome install problem: compile checks and audio still pass, only rendering is
|
||||
unavailable. State the blocker and deliver the checked composition; render outside the
|
||||
sandbox or via `render --docker` / cloud rendering where available. **Do not build a
|
||||
substitute rasterizer** (magick/PIL/SVG frame pipelines) — on a blocked-browser host
|
||||
the deliverable IS the checked composition plus this blocker note, and rendering is
|
||||
handed to `--docker`, cloud, or the user. Write your final summary the moment the
|
||||
blocker is identified, BEFORE any optional fallback work: a later session failure must
|
||||
not erase the report of work already done.
|
||||
|
||||
## browser
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ This skill is the **technical contract** — how to build one hyperframes projec
|
||||
| `references/brief-format.md` | author `BRIEF.md` — the confirmed intent document a workflow's Setup writes and every later step reads |
|
||||
| `references/script-format.md` | author the optional `SCRIPT.md` locked narration |
|
||||
| `references/subagent-dispatch.md` | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness |
|
||||
| `references/frame-worker-core.md` | the shared frame-worker role contract — each narrative workflow's packet builder prepends it to that workflow's `sub-agents/frame-worker.md` delta |
|
||||
| `references/tailwind.md` | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3) |
|
||||
|
||||
For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Brief contract
|
||||
|
||||
The intent layer (`/hyperframes` § 4) asks creation questions once. The executing workflow writes the confirmed result to `BRIEF.md` and does not ask those questions again. This contract defines the canonical run-shape fields, shared brief fields, and question rules. Route-specific options live in `/hyperframes` → `references/route-briefs.md`.
|
||||
The intent layer (`/hyperframes` → `references/intent-interview.md`) asks creation questions once. The executing workflow writes the confirmed result to `BRIEF.md` and does not ask those questions again. This contract defines the canonical run-shape fields, shared brief fields, and question rules. Route-specific options live in `/hyperframes` → `references/routes/<workflow>.md`.
|
||||
|
||||
## Contents
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Brief format — `BRIEF.md`
|
||||
|
||||
Defines the **intent document** — the file a confirmed brief becomes. The questions that fill it live in the intent layer (`/hyperframes` § 4 + its `references/route-briefs.md`); the field semantics live in `brief-contract.md` § 2. This file defines only the artifact: its shape, its home, and its lifecycle.
|
||||
Defines the **intent document** — the file a confirmed brief becomes. The questions that fill it live in the intent layer (`/hyperframes` → `references/intent-interview.md` + its `references/routes/<workflow>.md`); the field semantics live in `brief-contract.md` § 2. This file defines only the artifact: its shape, its home, and its lifecycle.
|
||||
|
||||
`BRIEF.md` sits at the project root, and the project's files read as four layers: **`BRIEF.md`** (why, for whom, and everything the user asked for) → **`STORYBOARD.md`** (what, frame by frame) → **`frame.md`** (how it looks) → **`compositions/`** (the thing itself).
|
||||
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
# Frame worker — core contract (shared by the narrative video workflows)
|
||||
|
||||
The workflow-agnostic half of every frame worker's role. Each workflow's packet builder (`scripts/frame-packets.mjs`) prepends this file to that workflow's `sub-agents/frame-worker.md` (the **delta**) to form `.hyperframes/frame-packets/_role.md` — a worker reads the two as one role. Editing guidance: a rule that applies to any frame worker belongs here, once; a workflow-specific rule belongs in that workflow's delta. (`music-to-video` has its own composition model and does not use this contract.)
|
||||
|
||||
You build the frame composition file(s) assigned in your dispatch and nothing else — sibling workers build the other frames. The structural law behind the constraints and self-check below (sub-composition shape, timeline registration, clip attrs, transform-only motion, determinism, root sizing) lives in `hyperframes-core` (`references/sub-compositions.md`, `references/determinism-rules.md`, `references/data-attributes.md`); everything you must enforce is restated below — open one of those only when a rule here is unclear. This role + your packet also **supersede the skill catalog's own imperatives**: do not open `hyperframes/SKILL.md` or `hyperframes-core/SKILL.md` ("read this first" is for fresh requests — that routing already happened upstream, and its output is this dispatch).
|
||||
|
||||
**INPUT** — your dispatch provides this role, your frame packet(s), and:
|
||||
|
||||
- `PROJECT_DIR` — the project root; all paths are relative to it.
|
||||
- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-feature.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
|
||||
- Your **packet** (`.hyperframes/frame-packets/<frame_id>.md`) — everything selected upstream for this frame. You never open the shared `STORYBOARD.md` (see below); the packet carries your exact **`## Frame N` block**:
|
||||
- `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
|
||||
- `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
|
||||
- `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
|
||||
- `transition_in` — informational. The injector stamps it at the root; **you do not author transitions.**
|
||||
- the **time-coded shot sequence** — your build spec. A sequence of Scene lines (`Scene 1 (0.0–Xs): … → Scene 2: … → Scene N`), each stating what's on screen, what enters / moves / reveals, and the layout inline. Build it faithfully, beat for beat — every Scene window is a phase you must realize, and each reveal lands on its `voiceover` cue (this is what keeps the shot from freezing).
|
||||
- `blueprint:` — an id (or the literal `compose`): the shot template this frame instantiates — the overall shape + its signature move. Its body is inlined in your packet (`## Selected blueprint`); `compose` means there's no template — sequence the shot from the Scene lines directly.
|
||||
- `focal:` / `roles:` — which element is the hero and what each element is. **Semantics are workflow-specific — see the delta.**
|
||||
- `sfx:` — the orchestrator's; you mount no audio.
|
||||
- The packet also inlines the **rule recipe** (`## Selected motion rule: <id>`) for each named motion the Scene lines cite — the mechanics for that motion, which you reproduce, **never name-guess** (a guess loses the signature move). If a cited motion's recipe is missing from your packet, read `RULES_DIR/<id>.md` (`RULES_DIR` is in the packet header); a few recipes link an optional runnable demo in the shared `../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.
|
||||
- `frame.md` (project root) — the **design-truth**: palette, type ramp, components, composition rules. The LOOK. Pull every visual token from here. This is the one file you read outside your packet.
|
||||
- `../references/cut-catalog.md` (the workflow's own copy) — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
|
||||
- Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
|
||||
|
||||
**Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
|
||||
|
||||
**OUTPUT** — `compositions/frames/<frame_id>.html` for each assigned packet: exactly one bare `<template>…</template>` fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. Writing your assigned file(s) (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
|
||||
|
||||
## When a confirmed sketch exists
|
||||
|
||||
In collaborative runs the orchestrator wireframes the board first, so your target file may already exist as the frame's **user-confirmed wireframe** — your dispatch says whether it does (a file found on a retry is your own prior output, not a sketch). Read it first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the finished content where the sketch used stand-in blocks (what that content is — real assets, invented visuals, a code block — is the delta's call), and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed.
|
||||
|
||||
## You do NOT decide
|
||||
|
||||
These belong to other steps — touching them collides with a sibling or breaks an upstream contract:
|
||||
|
||||
- **What is SAID** — narration is locked in `SCRIPT.md` / the `voiceover` line. You only show; you never write or restate narration text.
|
||||
- **Duration** — fixed from real voice timing. Build your shot to land within it; don't stretch or trim it.
|
||||
- **Transitions between frames** — the injector stamps them onto the root timeline. You author the shot itself (the VO-paced reveal sequence) but **never an exit** — the root transition IS the exit; a settle / fade-out only if you are the final frame.
|
||||
- **Audio** (narration / BGM / SFX) — assembled at the root by the orchestrator. **No `<audio>` element in your composition.**
|
||||
- **Design tokens** — palette / fonts / components come from `frame.md`. Don't invent them, and **never lift a word, label, or wordmark out of `frame.md` as your copy** — it is a style spec, not content. Visible text comes from your frame's `scene` / narrative.
|
||||
- **Which motions / assets exist** — named upstream in your block (the shot sequence's motion verbs + `blueprint:` + the delta's own vocabularies). Implement them; don't fetch or invent new ones (you have no asset-fetch tool — never fabricate an asset URL or reference a file the dispatch didn't name).
|
||||
- **The shared `STORYBOARD.md`** — your packet carries your block; never open or write the file itself. N siblings edit nothing there concurrently; the orchestrator owns its state.
|
||||
|
||||
## Frame constraints
|
||||
|
||||
Shared law for every narrative frame, each load-bearing; your workflow's delta adds its own on top:
|
||||
|
||||
- **Caption keep-out — all content in the top ~83%.** A karaoke caption pill owns the bottom ~17% of the canvas. Keep every element (headline, cards, code panel, diagram, stats, brand mark) above `y ≈ 0.83 × height` — compute the pixel cutoff from your canvas (e.g. `≤ 900` on a 1080-tall frame, `≤ 1600` on a 1920-tall portrait). Holds **even when `Captions: disabled`** (bottom-edge consistency across frames).
|
||||
- **Fill the content area — especially portrait.** Compose the whole top-83% region; don't float one small cluster mid-frame. Anchor the hero high (~0.2–0.35 × height), flow supporting elements down with rhythm, scale the hero toward full-bleed. (Landscape's region is short, so vertical centering near 0.42 × height is fine.)
|
||||
- **Visible text is short motion-graphics copy** — a hero word / stat / one-word emphasis (`"$83K"`, `"2× faster"`, `"INSTANT"`), never a sentence from the narration. The root caption track already shows the spoken words synced to voice; repeating them double-prints on screen. (The delta may name exceptions — e.g. real code inside a code block is content, not narration.)
|
||||
- **Build the whole shot — reveal across the full `duration`, never front-load.** Dumping the whole canvas in the first ~25% then holding it is exactly what reads as a PowerPoint slide. Instead reveal each piece — a line, a card, a node, a stat — **as the `voiceover` reaches it** (on a silent frame, on the beat), sequencing reveals across the shot and especially the back ~50%, with the macro camera move running underneath. **Only EXITS are banned** — a non-final frame unmounts mid-frame, so an exit tween truncates and reads as a glitch (the root transition IS the exit); mid-shot reveals are free and seek-safe. The lone exception is a note marked as a deliberate hold / stillness frame: there, an entrance + a quiet settle is right (a held read beats bad motion).
|
||||
- **Implement the shot sequence faithfully — every Scene is a timeline phase.** The Scene lines ARE the build: map each Scene onto a phase of the one timeline, each piece revealing as the `voiceover` reaches it. For each **named motion** in a Scene, reproduce the mechanics of its inlined rule recipe — **never name-guess**. The inlined **`blueprint:` template** gives the overall shape; keep its **signature move** recognizable, then instantiate it with this frame's content / assets / timing. `compose` → no template; sequence the shot straight from the Scene lines. Whichever, never front-load the whole sequence at `t=0` — pace the reveals to the voiceover.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read** — your packet top to bottom (your frame block, the inlined blueprint, the inlined rule recipes), then `frame.md` (the look). Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and the assembled-project `lint` / `check` gate can miss an unwired blank sub-composition.
|
||||
2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe in your packet, the blueprint's signature move kept recognizable. Find a visual idea that reinforces the beat, not a literal restyle of the words.
|
||||
3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously.
|
||||
Prefix authored ids and globally reusable class names with `<frame_id>-` so sibling frames assembled from parallel workers cannot collide. Contract selectors such as `#root` and `.clip` are the only exceptions.
|
||||
4. **Self-check, then finish** — re-read your file against the checklist below and fix in place; then continue to your next assigned packet, if any. You do **not** run the CLI.
|
||||
|
||||
## Self-check before finishing (you do NOT run the CLI)
|
||||
|
||||
You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them after assembly (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back:
|
||||
|
||||
- `missing_template_wrapper` / `missing_composition_id` — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE / full document); root carries `data-composition-id="<frame_id>"`.
|
||||
- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
|
||||
- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
|
||||
- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
|
||||
- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
|
||||
- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
|
||||
- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
|
||||
- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
|
||||
- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
|
||||
- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
|
||||
- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
|
||||
- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
|
||||
- `font_family_without_font_face` — every font you name has a matching `@font-face` **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.
|
||||
- **Keep-out + no-narration-text** (eyeball, no code) — nothing sits below the 83% cutoff; no narration sentence is rendered as visible text.
|
||||
@@ -18,4 +18,9 @@ The shipped narrative workflows implement these stages with their own scripts; a
|
||||
|
||||
The Frames stage follows the plan's citations: a scene planned on a blueprint or on named rules is built by reading that recipe's body (`hyperframes-animation/blueprints/<id>.md`, `rules/<id>.md`) before its motion is written — names come from the indexes, never invented, and a scene the plan left uncited gets its citation at build time, not improvised motion.
|
||||
|
||||
## Scheduling economics (facts you can't see from inside the session)
|
||||
|
||||
- **External generations are independent work.** Image plates, TTS, BGM, video gen: fire every generation whose prompt is already known **concurrently or in the background**, and overlap the wait with reading or building. Three image plates generated one-after-another cost ~3× the wall time of firing them together.
|
||||
- **Attaching an image re-prices your whole context.** A mid-session image inspection (especially at original detail) invalidates the prompt cache — the next request re-sends your entire history at full price. Batch visual checks (one contact sheet beats N single-frame views) and schedule them at phase boundaries, not mid-build.
|
||||
|
||||
Two attach points carry the user's voice into this loop: the plan that starts it was approved at `review-loop.md` § 1 (collaborative) or posted as a heads-up (autonomous), and nothing renders before the § 4 final look. Everything between those two is yours to schedule.
|
||||
|
||||
@@ -11,11 +11,14 @@ YAML block at the top. Unknown keys are kept under `globals.extra`.
|
||||
| Key | Meaning | Example |
|
||||
| ---------- | ----------------------------------------------------------------- | ----------------------------------------- |
|
||||
| `format` | Canvas size | `1920x1080` |
|
||||
| `duration` | The brief's rough length expectation (advisory, not a hard limit) | `22s` |
|
||||
| `message` | One-line thesis | `Ship a launch video in an afternoon` |
|
||||
| `arc` | Narrative arc | `Hook → Problem → Solution → Proof → CTA` |
|
||||
| `audience` | Who it's for | `indie devs on X` |
|
||||
| `mode` | Interaction mode (see `brief-contract.md`; default collaborative) | `autonomous` |
|
||||
|
||||
Set `duration` from the brief's `length` when the storyboard is first written. It is an expectation, not a gate: assembly reports where the cut actually lands against it and flags a large gap — judge whether the drift serves the piece, and update the value when the intended length genuinely changes.
|
||||
|
||||
## Per-frame sections
|
||||
|
||||
One `## Frame N — Title` heading per frame (`Frame` / `Beat` / `Scene` accepted at H2/H3). Metadata as `- key: value` bullets; everything below them until the next heading is the free-form **narrative**.
|
||||
|
||||
@@ -4,7 +4,7 @@ The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-vide
|
||||
|
||||
## The contract (identical on every harness)
|
||||
|
||||
- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named `agents/<role>.md` file** followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
|
||||
- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named role file** (a builder-assembled payload like `.hyperframes/frame-packets/_role.md`, or a workflow's `sub-agents/<role>.md`) followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
|
||||
- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
|
||||
- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
|
||||
|
||||
|
||||
@@ -0,0 +1,188 @@
|
||||
// Shared frame-packet builder — the script half of the frame-worker core/delta split.
|
||||
//
|
||||
// Each narrative workflow ships a thin `scripts/frame-packets.mjs` wrapper that pins
|
||||
// its own paths (animation skill, role delta, design-truth resolution, extra packet
|
||||
// sections) and delegates everything else here, exactly as the markdown half already
|
||||
// does with `references/frame-worker-core.md` + each workflow's delta. One owner for
|
||||
// the packet-building logic; the wrappers own only what genuinely differs per workflow.
|
||||
//
|
||||
// Packet (<frame_id>.md) = project inputs + the frame's exact `## Frame N` block
|
||||
// + the blueprint body + every cited rule recipe, inlined — so a worker never opens
|
||||
// the shared STORYBOARD.md or any skill document. Cited motions are found
|
||||
// mechanically: the explicit `- rules:` field when present, plus every valid rule id
|
||||
// (a filename under the animation skill's rules/) mentioned in the block.
|
||||
//
|
||||
// _role.md = frame-worker-core.md + the workflow's sub-agents/frame-worker.md,
|
||||
// concatenated verbatim — the complete worker role, assembled from the two source
|
||||
// documents so nothing is hand-maintained twice.
|
||||
|
||||
import {
|
||||
existsSync,
|
||||
mkdirSync,
|
||||
readFileSync,
|
||||
readdirSync,
|
||||
realpathSync,
|
||||
writeFileSync,
|
||||
} from "node:fs";
|
||||
import { basename, join, resolve } from "node:path";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
export function field(block, name) {
|
||||
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
|
||||
return match?.[1]?.trim() ?? null;
|
||||
}
|
||||
|
||||
export function splitFrames(storyboard) {
|
||||
const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
|
||||
return matches.map((match, index) => {
|
||||
const start = match.index;
|
||||
const end = matches[index + 1]?.index ?? storyboard.length;
|
||||
return {
|
||||
heading: match[1].trim(),
|
||||
block: storyboard.slice(start, end).trim(),
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
export function frameId(frame) {
|
||||
const src = field(frame.block, "src");
|
||||
if (!src) throw new Error(`${frame.heading}: missing src`);
|
||||
return basename(src).replace(/\.html?$/i, "");
|
||||
}
|
||||
|
||||
export function selectedFile(path, heading) {
|
||||
if (!path || !existsSync(path)) return "";
|
||||
return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
|
||||
}
|
||||
|
||||
function escapeRegExp(id) {
|
||||
return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
}
|
||||
|
||||
export function knownRuleIds(animationDir) {
|
||||
const rulesDir = join(animationDir, "rules");
|
||||
if (!existsSync(rulesDir)) {
|
||||
console.warn(
|
||||
`frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
|
||||
);
|
||||
return [];
|
||||
}
|
||||
return readdirSync(rulesDir)
|
||||
.filter((name) => name.endsWith(".md"))
|
||||
.map((name) => name.replace(/\.md$/, ""));
|
||||
}
|
||||
|
||||
export function citedRules(block, ruleIds) {
|
||||
const explicit = (field(block, "rules") ?? "")
|
||||
.split(/[,\s]+/)
|
||||
.map((rule) => rule.trim())
|
||||
.filter(Boolean);
|
||||
const mentioned = ruleIds.filter((id) =>
|
||||
new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
|
||||
);
|
||||
return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
|
||||
}
|
||||
|
||||
export function resourceSections(block, { animationDir, ruleIds }) {
|
||||
let sections = "";
|
||||
const blueprint = field(block, "blueprint");
|
||||
if (blueprint && blueprint.toLowerCase() !== "compose") {
|
||||
sections += selectedFile(
|
||||
join(animationDir, "blueprints", `${blueprint}.md`),
|
||||
`Selected blueprint: ${blueprint}`,
|
||||
);
|
||||
}
|
||||
for (const rule of citedRules(block, ruleIds)) {
|
||||
sections += selectedFile(
|
||||
join(animationDir, "rules", `${rule}.md`),
|
||||
`Selected motion rule: ${rule}`,
|
||||
);
|
||||
}
|
||||
return sections;
|
||||
}
|
||||
|
||||
export function buildRolePayload({ corePath, deltaPath, outDir }) {
|
||||
const core = readFileSync(corePath, "utf8").trim();
|
||||
const delta = readFileSync(deltaPath, "utf8").trim();
|
||||
const role = `${core}\n\n---\n\n${delta}\n`;
|
||||
mkdirSync(outDir, { recursive: true });
|
||||
const path = join(outDir, "_role.md");
|
||||
writeFileSync(path, role);
|
||||
return { path, bytes: Buffer.byteLength(role) };
|
||||
}
|
||||
|
||||
export function buildFramePackets({
|
||||
projectDir,
|
||||
storyboardPath = join(projectDir, "STORYBOARD.md"),
|
||||
outDir = join(projectDir, ".hyperframes", "frame-packets"),
|
||||
maxPacketBytes = 48_000,
|
||||
animationDir,
|
||||
corePath,
|
||||
deltaPath,
|
||||
// Per-workflow hooks (all optional):
|
||||
// designTruthLine(projectDir) -> the packet's design-truth input line
|
||||
// validateFrame(frame, id) -> throw to reject a frame before packing
|
||||
// extraSections(block) -> extra packet sections appended after the rule recipes
|
||||
designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
|
||||
validateFrame,
|
||||
extraSections,
|
||||
}) {
|
||||
const storyboard = readFileSync(storyboardPath, "utf8");
|
||||
const frames = splitFrames(storyboard);
|
||||
if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
|
||||
const ruleIds = knownRuleIds(animationDir);
|
||||
|
||||
const packets = frames.map((frame) => {
|
||||
const id = frameId(frame);
|
||||
if (validateFrame) validateFrame(frame, id);
|
||||
const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds })}${extraSections ? extraSections(frame.block) : ""}`;
|
||||
const bytes = Buffer.byteLength(packet);
|
||||
if (bytes > maxPacketBytes) {
|
||||
throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
|
||||
}
|
||||
return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
|
||||
});
|
||||
|
||||
mkdirSync(outDir, { recursive: true });
|
||||
for (const { path, packet } of packets) writeFileSync(path, packet);
|
||||
buildRolePayload({ corePath, deltaPath, outDir });
|
||||
return packets.map(({ packet: _packet, ...result }) => result);
|
||||
}
|
||||
|
||||
export function flag(argv, name, fallback) {
|
||||
const index = argv.indexOf(`--${name}`);
|
||||
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
|
||||
}
|
||||
|
||||
// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
|
||||
// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
|
||||
// a raw compare silently skips main() when invoked through any symlinked path.
|
||||
export function isMainModule(importMetaUrl) {
|
||||
if (!process.argv[1]) return false;
|
||||
try {
|
||||
return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
|
||||
const argv = process.argv.slice(2);
|
||||
const projectDir = resolve(flag(argv, "project", "."));
|
||||
const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
|
||||
try {
|
||||
const packets = build({
|
||||
projectDir,
|
||||
storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
|
||||
outDir,
|
||||
});
|
||||
const role = buildRole({ outDir });
|
||||
console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
|
||||
for (const packet of packets)
|
||||
console.log(` ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
|
||||
console.log(` worker role: ${role.bytes} bytes → ${role.path}`);
|
||||
} catch (error) {
|
||||
console.error(`✗ frame packets: ${error.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
+11
-75
@@ -22,16 +22,14 @@ Apply the first matching row; do not evaluate lower state rows:
|
||||
|
||||
| State | Action |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Explicit port of existing Remotion source to HyperFrames | Read the `/remotion-to-hyperframes` section of `references/workflow-catalog.md`, then route directly to that workflow. Skip the intent layer. |
|
||||
| Explicit port of existing Remotion source to HyperFrames | Read `references/routes/remotion-to-hyperframes.md`, then route directly to that workflow. Skip the intent layer. |
|
||||
| Specific operation on an existing HyperFrames project: inspect, diagnose, validate, preview, render, publish, or batch-render | Perform only that operation. Skip intent and workflow routing; load `/hyperframes-cli` and any required domain skills. |
|
||||
| Specific edit to an existing project | Make the edit. Do not run the intent layer. |
|
||||
| `BRIEF.md` exists | Read `workflow` and `flow`. Execute that workflow; `flow: companion` always executes in `/general-video`. Ask no brief questions. |
|
||||
| No brief, but `hyperframes.json` or `STORYBOARD.md` exists | Resume from project files and recorded preferences. Infer the owning workflow from existing artifacts. If it cannot be determined uniquely, ask one routing-only question; do not run the intent interview. |
|
||||
| Fresh creation | Run the intent layer (§ 4), then route once using the rules below. |
|
||||
| Fresh creation | Run the intent layer — `references/intent-interview.md` — then route once using § 2's table. |
|
||||
|
||||
Continue with source adapters in § 2. A direct or resumed workflow route skips §§ 3–4 and proceeds to workflow installation in § 5. A specific operation or edit skips §§ 3–5 and loads only the domain skills it needs from § 6.
|
||||
|
||||
If a fresh request does not identify the subject or input, ask what the video is about before routing. Check preferences and recipes before asking anything (§ 4, step 1).
|
||||
If a fresh request does not identify the subject or input, ask what the video is about before routing. Check preferences and recipes before asking anything (`references/intent-interview.md`, step 1). A `figma.com` input or a named recipe changes intake, not routing — the interview's "Adapt orthogonal inputs" section handles both.
|
||||
|
||||
### Keep the project's CLI current
|
||||
|
||||
@@ -43,20 +41,7 @@ npx hyperframes@latest upgrade --project . --check
|
||||
|
||||
The probe is read-only and reports the pin against the latest release; keep the explicit `.` — on older CLI releases a bare `--project` followed by another flag consumes that flag as its directory value. When it reports the project behind — or any CLI output already shows it (the stderr notice `This project pins hyperframes@… (latest …)`, or `_meta.updateAvailable: true` in a `--json` result from a pinned script) — apply with `npx hyperframes@latest upgrade --project .`, then verify with `npx hyperframes check`. A passing check confirms the project's compositions still validate on the new version — not that rendered output is frame-identical to the old pin — so a successful bump is never silent: name the old and new version in the run's summary. A project with no composition yet needs no verification. If the check fails, revert the `package.json` change, continue on the pinned version, and report which version the project stays on and why. Act on the signal rather than relaying it to the user; never leave a bumped pin unverified.
|
||||
|
||||
## 2. Adapt orthogonal inputs before routing
|
||||
|
||||
A Figma source changes **how assets and design enter the project**, not which workflow owns the deliverable.
|
||||
|
||||
If any input is a `figma.com` URL:
|
||||
|
||||
1. For fresh creation, begin the intent layer (§ 4) and complete its memory and recipe reads.
|
||||
2. During input triage, run `/figma` to extract assets, brand tokens, components, and storyboard frames when present. For an existing-project edit, run `/figma` without reopening intent.
|
||||
3. Route the requested deliverable using the output from `/figma`, then continue only the selected route's unanswered intent questions.
|
||||
4. Do not drive Figma through raw MCP tools. That bypasses SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding.
|
||||
|
||||
A GitHub PR URL is not a website source. A named or adopted recipe already carries its workflow; confirm adoption through the intent layer, then route to that workflow.
|
||||
|
||||
## 3. Route fresh creation
|
||||
## 2. Route fresh creation
|
||||
|
||||
Use the first matching row. Match the requested **deliverable**, not a word or file type mentioned in passing.
|
||||
|
||||
@@ -73,71 +58,22 @@ Use the first matching row. Match the requested **deliverable**, not a word or f
|
||||
| 9 | Explain a topic, article, or notes with invented visuals and no product or site capture | `/faceless-explainer` |
|
||||
| 10 | Any other custom video or composition | `/general-video` |
|
||||
|
||||
Before finalizing the route, read the matching section of `references/workflow-catalog.md`. It is the canonical input/output/trigger contract available before lazy-installed workflow skills are present. If the candidate does not satisfy that entry, continue routing instead of forcing the match.
|
||||
Before finalizing the route, read `references/routes/<workflow>.md` — one small file per route: the canonical input/output/trigger contract (available before lazy-installed workflow skills are present) plus that route's interview entry. If the candidate does not satisfy its contract, continue routing instead of forcing the match. Read only the matched route's file.
|
||||
|
||||
### Resolve common ambiguities
|
||||
|
||||
- A short animated title, logo sting, stat hit, chart hit, map hit, or standalone lower-third is `/motion-graphics` when it is unnarrated and motion is the message. A static title card, narrated sequence, longer montage, or custom loop is `/general-video`.
|
||||
- An explicitly short motion graphic may use a URL, tweet, article, or screenshot as source material. A generic “make a video from this site” request is `/product-launch-video`.
|
||||
- An explicitly short motion graphic may use a URL, tweet, article, or screenshot as source material. A generic "make a video from this site" request is `/product-launch-video`.
|
||||
- Existing footage with captions routes to `/embedded-captions`; footage with designed information cards routes to `/talking-head-recut`. Retiming, reordering, recoloring, reframing, or remixing footage is a custom edit and falls through to `/general-video`.
|
||||
- A music file selects `/music-to-video` only when its beat grid drives the piece. Music used as a bed does not override the subject-matched route.
|
||||
- “I want a storyboard” changes the review process, not the workflow. With no other routing signal, use `/general-video`. A confirmed sketched board may itself be the requested deliverable; the review loop defines that stop point.
|
||||
- "I want a storyboard" changes the review process, not the workflow. With no other routing signal, use `/general-video`. A confirmed sketched board may itself be the requested deliverable; the review loop defines that stop point.
|
||||
- Specialized narrative workflows support up to about 3 minutes and are strongest around 30–90s. Route a clearly longer piece to `/general-video`. Length never overrides an explicit port, deck, caption, overlay, or music-driven deliverable.
|
||||
|
||||
## 4. The intent layer — one conversation, before any workflow runs
|
||||
## 3. Route once, then leave
|
||||
|
||||
Fresh creation only — § 1's state table already decides whether this section runs at all (edits, project operations, briefed and resumable projects, and explicit Remotion ports never enter it). One conversation at the front door turns "make me a video" into a confirmed brief — the route, the must-have answers, the run's shape, and everything else in the user's head — handed to whichever workflow executes and made durable as `BRIEF.md` (shape: `../hyperframes-core/references/brief-format.md`). Workflows own execution; this layer owns understanding. Every workflow's opening rule points back here, so the questions are asked once no matter which door the user came through.
|
||||
For fresh creation the intent layer (`references/intent-interview.md`) runs the full conversation — memory, triage, pitch round, must-haves, run-shape, hand-off — and **ends by writing `BRIEF.md`. The brief is the only routing artifact the workflow reads**; nothing later re-opens this skill or the interview. Answer every later "what did the route require?" from `BRIEF.md`.
|
||||
|
||||
These reads are mandatory when their condition matches; do not replace them with recollection, and read only the matching section when a reference is organized by workflow:
|
||||
|
||||
| Condition | Read before acting |
|
||||
| ----------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| A route is a candidate, before confirming it | Its section in `references/workflow-catalog.md` |
|
||||
| The route is known, before asking route-specific questions | Its section in `references/route-briefs.md` |
|
||||
| Triage judged the request unformed, before any concept work | `references/pitch-round.md` |
|
||||
| Offering optional capabilities or collecting supplied media | The route-filtered rows in `references/capability-menu.md` |
|
||||
| Deriving `flow`, `storyboard`, mode, or canonical fields | `../hyperframes-core/references/brief-contract.md` |
|
||||
|
||||
**1 — Memory before questions.** Two reads, both mandatory, before anything is asked:
|
||||
|
||||
- **Remembered defaults.** Let `<MEDIA_DIR>` be the installed `/media-use` skill directory. For an existing project, `<MEMORY_ROOT>` is its root. Before scaffolding, use a deliberately nonexistent probe path with no `.media`, such as `/tmp/hyperframes-intent-memory-<run-id>`; never use the current workspace. Run `node <MEDIA_DIR>/scripts/prefs.mjs get --hyperframes <MEMORY_ROOT> --json`. Make each remembered value the recommended option and name its source. The pre-project probe sees only the personal tier; do not claim project provenance.
|
||||
- **Recipes.** Run `node <MEDIA_DIR>/scripts/recipe.mjs list --hyperframes <MEMORY_ROOT> --json`. If the user names a recipe, says “like last time,” or a recipe matches the probable route, ask whether to adopt it before other brief questions — and make the offer earn the yes: say why it matches and what adopting saves (“this matches your launch-promo recipe — adopting fills destination, aspect, language, and the design spec; you'd confirm the message and the two run-shape questions”). When several match, list them and include “none.” An adopted recipe locks the fields it contains; ask only its missing fields and the run-shape questions. It does not remove review or render approval gates.
|
||||
|
||||
**2 — Triage the input.** What is the video about — a website (sold or shown), a PR, a topic, a music track, existing footage? And is the request **formed** — the message, the material, and the occasion readable from what the user gave — or **unformed**, a subject with no take on it? Source material doesn't settle this by itself: a site, document, or PR carries its own thesis, but five tellings of that thesis are five different videos — a request whose only shape comes from its source ("make a video about this URL") is formed about the facts and unformed about the telling, and enters the round to pitch the telling. A formed request runs the layer exactly as it always has; nothing below is added for it. An unformed one goes through the pitch round after routing (step 4) and earns one question here, before anything is generated: what is the user already picturing? Their answer seeds the round (`references/pitch-round.md`). A user who says they don't know video at all gets that reference's decision map instead of a question sequence. For a genuinely exploratory request ("we need a video but I'm not sure what kind"), don't interrogate — establish the subject and what exists to show, one question at a time, then close by **recommending** a route plus how the run will review: a text storyboard first, on a live board, with optional wireframe sketches before the full build (`../hyperframes-core/references/review-loop.md`). The user hears the process before any workflow starts.
|
||||
|
||||
**3 — Pick the route** (the route table and ambiguity rules in § 3), then open that route's entry in `references/route-briefs.md`. It lists the must-have questions to ask now, the **deferred asks** to announce, whether the two run-shape questions apply, and which fields the pitch round may answer.
|
||||
|
||||
**4 — The pitch round** — unformed requests only; formed requests and recipe adoptions go straight to the must-haves. Sample five concepts along five genuinely different paths, at least two from the distribution's tail, and present them all before recommending one — pick, mix, and redirect are all answers. Each pitch names the capability or two it rides, in the plain language of `references/capability-menu.md` — the toolbox experienced as concepts, not listed as a menu. On an autonomous run the same gate runs internally, and the heads-up names the direction chosen and the typical one left behind. The procedure — the sampling gate, the presentation discipline, and the decision map for users new to video — is `references/pitch-round.md`. The chosen concept answers the route's pitch-eligible fields and lands in `BRIEF.md` under `## Intent`; the capabilities it named are confirmed with it, under `## Customizations`.
|
||||
|
||||
**5 — The route's must-haves.** One question per field, recommended option first with its receipt (rules: `../hyperframes-core/references/brief-contract.md` § 3). Skip a question only when the request already answered it — inference is not an answer, but a chosen pitch is: fields the pitch round settled are locked with the pitch as their receipt. Then announce the route's deferred asks in one line ("after I probe the clip, I'll offer 2–3 caption identities") so the user hears the run's full shape before it starts.
|
||||
|
||||
**6 — The two run-shape questions** — where the route's entry applies them, asked after the must-haves, each on its own:
|
||||
|
||||
- **(a) Storyboard?** Review the plan, wireframe sketches, and the finished piece pass by pass on a live board (`../hyperframes-core/references/review-loop.md`) — recommended for anything beyond a couple of scenes — or skip the board and get one finished video from the confirmed brief.
|
||||
- **(b) Automation or companion?** **Automation** — the matched workflow's pipeline executes the brief end to end. **Companion** — build it together in `/general-video` with every HyperFrames capability on the table; the route's answers still describe the video, general-video executes them.
|
||||
|
||||
These two are **orthogonal — never merge them into one menu.** All four `flow` × `storyboard` combinations are valid user choices (a companion run reviews on the live board too when `storyboard: yes`); a flattened three-option list ("storyboard review / one shot / companion") silently makes companion-with-storyboard unselectable. When a diagram or source material summarizes the outcomes as three branches, that is the derived behavior (`brief-contract.md` § 1), not the question shape. In a form-style question UI, keep (a) and (b) as two separate selects.
|
||||
|
||||
Signals replace questions, never add them: an ongoing "just build it" / "surprise me" / "don't ask" locks `flow: automation, storyboard: no`, and every unanswered field becomes a decision with a receipt in the heads-up. A storyboard request, however phrased, locks `storyboard: yes`. Remembered `flow` / `storyboard` values reorder the recommendations — they never make either question disappear. The run's collaborative/autonomous execution mode derives from these two answers — the old first question is never asked; the canonical mapping is `../hyperframes-core/references/brief-contract.md` § 1.
|
||||
|
||||
**7 — Nice-to-have: recommend, then show.** Skip this step when the selected route brief says to skip the front-door capability offer. Otherwise, once the must-haves are locked, send one offer, not an interrogation — recommendations first, catalog on request. Capabilities the chosen pitch already named are settled with the concept — this step recommends from what the pitch didn't cover, and after a pitch round it is often just the two open asks and the design ask:
|
||||
|
||||
- **One or two rows** of `references/capability-menu.md` that this brief specifically calls for, each traced to something in the confirmed concept — a key number wants the count-up treatment, product shots want staging and a grade, a music bed means cuts on its grid. A suggestion that would fit any video fails that test; drop it. At most one may be a labeled **challenger**: higher ceiling, named cost (“the standard cut carries it; shader transitions would lift the close, at render-time cost”).
|
||||
- **Material answered on arrival.** When the user hands over a logo, a clip, or data, answer with its concrete use (“the logo could close the video as a sting — want that?”) rather than silently filing it.
|
||||
- **The two open asks stay:** anything here you want, and is there any material of your own (images, clips, logos, data) the video should carry?
|
||||
- **The design spec keeps its own three-state ask** — use an existing spec, pick a shipped preset by eye, or leave the decision to the workflow (`capability-menu.md` § The design ask).
|
||||
|
||||
The full route-filtered slice appears only when the user asks what else is possible. An accepted recommendation is a confirmed answer: when it lands on a preference-backed field (a preset, a voice, a caption identity), it records like any other confirmation, and `/media-use`'s promotion rules make it the next run's recommended default. Capture answers verbatim in `BRIEF.md` under `## Assets`, `## Customizations`, or `## Notes`. One round; silence or “no” moves on.
|
||||
|
||||
**8 — Hand off.** Three disciplines close the conversation (invariants: `../hyperframes-core/references/brief-contract.md` § 3):
|
||||
|
||||
- **One integration check.** Read the combined answers for a consequence no single answer showed — vertical at 90 seconds with a chart-dense concept means charts a phone can't read — and surface it with a proposed adjustment now, not at the sketch pass.
|
||||
- **Stated and inferred, apart.** Present the locked brief as one summary — deferred asks and the run's shape included — with what the user answered and what was inferred or defaulted as two visibly separate groups, receipts on both. The inferred group is where corrections live; an autonomous heads-up is mostly that group.
|
||||
- **Revision is not confirmation.** When the user corrects the summary, fold the change in and present it again; never execute an edited-but-unconfirmed brief.
|
||||
|
||||
Then enter the workflow (`flow: companion` → `/general-video`; otherwise the matched route), installing it first per § 5. The workflow's Setup writes `BRIEF.md` from this summary as its **first action after `hyperframes init`** (never before — `init` refuses a non-empty directory), using canonical frontmatter values and preserving the user's important wording in the body — the chosen pitch, when there is one, under `## Intent`. It then records the preference-backed fields (`../hyperframes-core/references/brief-format.md` names the subset), and asks no brief question again.
|
||||
|
||||
## 5. Install and enter the workflow
|
||||
## 4. Install and enter the workflow
|
||||
|
||||
Before reading the selected workflow, install or refresh it and the core domain skills:
|
||||
|
||||
@@ -147,7 +83,7 @@ npx hyperframes skills update <workflow-name>
|
||||
|
||||
Use the bare name without `/`. If the command fails, surface the error; do not reconstruct the workflow from memory. Everything else about installation — the core-vs-lazy split, what `init` refreshes, diagnosis, CI opt-out, and the no-CLI fallback — lives in `references/skill-lifecycle.md`.
|
||||
|
||||
## 6. Load domain skills on demand
|
||||
## 5. Load domain skills on demand
|
||||
|
||||
| Need | Skill |
|
||||
| ------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Capability menu — what HyperFrames can bring to a video
|
||||
|
||||
One list, three readers. The **pitch round** (`pitch-round.md`) speaks it before anyone reads it as a menu: each pitch names the capability or two its concept rides, phrased from the middle column — the rows experienced inside concepts, which is how most users first learn what they're allowed to want. The **intent layer** (`/hyperframes` § 4, step 7) recommends from it — one or two rows the confirmed concept specifically calls for and the chosen pitch didn't already name, with the route-filtered slice shown when the user asks what else is possible. **`/general-video` in companion mode** uses the same list as its execution map — as its **trigger list**: each row's plain-language line is also the moment to offer it, when the conversation touches what the row does — and as each pass's **upgrade channel**: a plan, sketch, or build checkpoint may carry one or two traced offers pointed at material the user is looking at.
|
||||
One list, three readers. The **pitch round** (`pitch-round.md`) speaks it before anyone reads it as a menu: each pitch names the capability or two its concept rides, phrased from the middle column — the rows experienced inside concepts, which is how most users first learn what they're allowed to want. The **intent layer** (`/hyperframes` → `references/intent-interview.md`, step 7) recommends from it — one or two rows the confirmed concept specifically calls for and the chosen pitch didn't already name, with the route-filtered slice shown when the user asks what else is possible. **`/general-video` in companion mode** uses the same list as its execution map — as its **trigger list**: each row's plain-language line is also the moment to offer it, when the conversation touches what the row does — and as each pass's **upgrade channel**: a plan, sketch, or build checkpoint may carry one or two traced offers pointed at material the user is looking at.
|
||||
|
||||
**Borrowing rule.** Capabilities marked with a home workflow live in that workflow's skill directory, and workflow skills install lazily. Before reaching across, run `npx hyperframes skills update <that-workflow>` with the bare name. Resolve the installed skill directory, invoke its script by absolute path, and pass the project root explicitly when the script accepts one. Keep the working directory at the project root. Never assume a sibling-relative path such as `../media-use` or `../music-to-video`; the project may live anywhere.
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# The intent layer — one conversation, before any workflow runs
|
||||
|
||||
Fresh creation only — the SKILL.md state table already decides whether this layer runs at all (edits, project operations, briefed and resumable projects, and explicit Remotion ports never enter it). One conversation at the front door turns "make me a video" into a confirmed brief — the route, the must-have answers, the run's shape, and everything else in the user's head — handed to whichever workflow executes and made durable as `BRIEF.md`. Workflows own execution; this layer owns understanding. Every workflow's opening rule points back here, so the questions are asked once no matter which door the user came through.
|
||||
|
||||
These reads are mandatory when their condition matches; do not replace them with recollection:
|
||||
|
||||
| Condition | Read before acting |
|
||||
| ----------------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| The route is picked, before confirming or interviewing | `routes/<workflow>.md` — the whole file (contract + interview, ~1KB) |
|
||||
| Triage judged the request unformed, before any concept work | `pitch-round.md` |
|
||||
| Offering optional capabilities or collecting supplied media | The route-filtered rows in `capability-menu.md` |
|
||||
| Question rules or field semantics beyond the schema below | `../../hyperframes-core/references/brief-contract.md` |
|
||||
|
||||
## Adapt orthogonal inputs first
|
||||
|
||||
A Figma source changes **how assets and design enter the project**, not which workflow owns the deliverable. If any input is a `figma.com` URL: complete this layer's memory and recipe reads; during input triage run `/figma` to extract assets, brand tokens, components, and storyboard frames when present; route the requested deliverable using the output from `/figma`, then continue only the selected route's unanswered questions. Do not drive Figma through raw MCP tools — that bypasses SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding.
|
||||
|
||||
A GitHub PR URL is not a website source. A named or adopted recipe already carries its workflow; confirm adoption below, then route to that workflow.
|
||||
|
||||
## The eight steps
|
||||
|
||||
**1 — Memory before questions.** Two reads, both mandatory, before anything is asked:
|
||||
|
||||
- **Remembered defaults.** Let `<MEDIA_DIR>` be the installed `/media-use` skill directory. For an existing project, `<MEMORY_ROOT>` is its root. Before scaffolding, use a deliberately nonexistent probe path with no `.media`, such as `/tmp/hyperframes-intent-memory-<run-id>`; never use the current workspace. Run `node <MEDIA_DIR>/scripts/prefs.mjs get --hyperframes <MEMORY_ROOT> --json`. Make each remembered value the recommended option and name its source. The pre-project probe sees only the personal tier; do not claim project provenance.
|
||||
- **Recipes.** Run `node <MEDIA_DIR>/scripts/recipe.mjs list --hyperframes <MEMORY_ROOT> --json`. If the user names a recipe, says "like last time," or a recipe matches the probable route, ask whether to adopt it before other brief questions — and make the offer earn the yes: say why it matches and what adopting saves ("this matches your launch-promo recipe — adopting fills destination, aspect, language, and the design spec; you'd confirm the message and the two run-shape questions"). When several match, list them and include "none." An adopted recipe locks the fields it contains; ask only its missing fields and the run-shape questions. It does not remove review or render approval gates.
|
||||
|
||||
**2 — Triage the input.** What is the video about — a website (sold or shown), a PR, a topic, a music track, existing footage? And is the request **formed** — the message, the material, and the occasion readable from what the user gave — or **unformed**, a subject with no take on it? Source material doesn't settle this by itself: a site, document, or PR carries its own thesis, but five tellings of that thesis are five different videos — a request whose only shape comes from its source ("make a video about this URL") is formed about the facts and unformed about the telling, and enters the round to pitch the telling. A formed request runs the layer exactly as it always has; nothing below is added for it. An unformed one goes through the pitch round after routing (step 4) and earns one question here, before anything is generated: what is the user already picturing? Their answer seeds the round (`pitch-round.md`). A user who says they don't know video at all gets that reference's decision map instead of a question sequence. For a genuinely exploratory request ("we need a video but I'm not sure what kind"), don't interrogate — establish the subject and what exists to show, one question at a time, then close by **recommending** a route plus how the run will review: a text storyboard first, on a live board, with optional wireframe sketches before the full build (`../../hyperframes-core/references/review-loop.md`). The user hears the process before any workflow starts.
|
||||
|
||||
**3 — Pick the route** (the route table and ambiguity rules in the SKILL.md), then read `routes/<workflow>.md`. Its Interview section lists the must-have questions to ask now, the **deferred asks** to announce, whether the two run-shape questions apply, and which fields the pitch round may answer.
|
||||
|
||||
**4 — The pitch round** — unformed requests only; formed requests and recipe adoptions go straight to the must-haves. Sample five concepts along five genuinely different paths, at least two from the distribution's tail, and present them all before recommending one — pick, mix, and redirect are all answers. Each pitch names the capability or two it rides, in the plain language of `capability-menu.md` — the toolbox experienced as concepts, not listed as a menu. On an autonomous run the same gate runs internally, and the heads-up names the direction chosen and the typical one left behind. The procedure — the sampling gate, the presentation discipline, and the decision map for users new to video — is `pitch-round.md`. The chosen concept answers the route's pitch-eligible fields and lands in `BRIEF.md` under `## Intent`; the capabilities it named are confirmed with it, under `## Customizations`.
|
||||
|
||||
**5 — The route's must-haves.** One question per field, recommended option first with its receipt (rules: `../../hyperframes-core/references/brief-contract.md` § 3). Skip a question only when the request already answered it — inference is not an answer, but a chosen pitch is: fields the pitch round settled are locked with the pitch as their receipt. Then announce the route's deferred asks in one line ("after I probe the clip, I'll offer 2–3 caption identities") so the user hears the run's full shape before it starts.
|
||||
|
||||
**6 — The two run-shape questions** — where the route's entry applies them, asked after the must-haves, each on its own:
|
||||
|
||||
- **(a) Storyboard?** Review the plan, wireframe sketches, and the finished piece pass by pass on a live board (`../../hyperframes-core/references/review-loop.md`) — recommended for anything beyond a couple of scenes — or skip the board and get one finished video from the confirmed brief.
|
||||
- **(b) Automation or companion?** **Automation** — the matched workflow's pipeline executes the brief end to end. **Companion** — build it together in `/general-video` with every HyperFrames capability on the table; the route's answers still describe the video, general-video executes them.
|
||||
|
||||
These two are **orthogonal — never merge them into one menu.** All four `flow` × `storyboard` combinations are valid user choices (a companion run reviews on the live board too when `storyboard: yes`); a flattened three-option list ("storyboard review / one shot / companion") silently makes companion-with-storyboard unselectable. When a diagram or source material summarizes the outcomes as three branches, that is the derived behavior (`brief-contract.md` § 1), not the question shape. In a form-style question UI, keep (a) and (b) as two separate selects.
|
||||
|
||||
Signals replace questions, never add them: an ongoing "just build it" / "surprise me" / "don't ask" locks `flow: automation, storyboard: no`, and every unanswered field becomes a decision with a receipt in the heads-up. A storyboard request, however phrased, locks `storyboard: yes`. Remembered `flow` / `storyboard` values reorder the recommendations — they never make either question disappear. The run's collaborative/autonomous execution mode derives from these two answers — the old first question is never asked; the canonical mapping is `../../hyperframes-core/references/brief-contract.md` § 1.
|
||||
|
||||
**7 — Nice-to-have: recommend, then show.** Skip this step when the selected route file says to skip the front-door capability offer. Otherwise, once the must-haves are locked, send one offer, not an interrogation — recommendations first, catalog on request. Capabilities the chosen pitch already named are settled with the concept — this step recommends from what the pitch didn't cover, and after a pitch round it is often just the two open asks and the design ask:
|
||||
|
||||
- **One or two rows** of `capability-menu.md` that this brief specifically calls for, each traced to something in the confirmed concept — a key number wants the count-up treatment, product shots want staging and a grade, a music bed means cuts on its grid. A suggestion that would fit any video fails that test; drop it. At most one may be a labeled **challenger**: higher ceiling, named cost ("the standard cut carries it; shader transitions would lift the close, at render-time cost").
|
||||
- **Material answered on arrival.** When the user hands over a logo, a clip, or data, answer with its concrete use ("the logo could close the video as a sting — want that?") rather than silently filing it.
|
||||
- **The two open asks stay:** anything here you want, and is there any material of your own (images, clips, logos, data) the video should carry?
|
||||
- **The design spec keeps its own three-state ask** — use an existing spec, pick a shipped preset by eye, or leave the decision to the workflow (`capability-menu.md` § The design ask).
|
||||
|
||||
The full route-filtered slice appears only when the user asks what else is possible. An accepted recommendation is a confirmed answer: when it lands on a preference-backed field (a preset, a voice, a caption identity), it records like any other confirmation, and `/media-use`'s promotion rules make it the next run's recommended default. Capture answers verbatim in `BRIEF.md` under `## Assets`, `## Customizations`, or `## Notes`. One round; silence or "no" moves on.
|
||||
|
||||
**8 — Hand off.** Three disciplines close the conversation (invariants: `../../hyperframes-core/references/brief-contract.md` § 3):
|
||||
|
||||
- **One integration check.** Read the combined answers for a consequence no single answer showed — vertical at 90 seconds with a chart-dense concept means charts a phone can't read — and surface it with a proposed adjustment now, not at the sketch pass.
|
||||
- **Stated and inferred, apart.** Present the locked brief as one summary — deferred asks and the run's shape included — with what the user answered and what was inferred or defaulted as two visibly separate groups, receipts on both. The inferred group is where corrections live; an autonomous heads-up is mostly that group.
|
||||
- **Revision is not confirmation.** When the user corrects the summary, fold the change in and present it again; never execute an edited-but-unconfirmed brief.
|
||||
|
||||
Then enter the workflow (`flow: companion` → `/general-video`; otherwise the matched route), installing it first per the SKILL.md's install step. The workflow's Setup writes `BRIEF.md` from this summary as its **first action after `hyperframes init`** (never before — `init` refuses a non-empty directory), using the canonical frontmatter below and preserving the user's important wording in the body — the chosen pitch, when there is one, under `## Intent`. It then records the preference-backed fields (`../../hyperframes-core/references/brief-format.md` names the subset), and asks no brief question again.
|
||||
|
||||
## BRIEF.md frontmatter — the carry-away artifact
|
||||
|
||||
The interview's deliverable. Every later "what did the route require?" re-reads this ~1KB file, never this document. One key per confirmed field, canonical normalized values (full shape and body sections: `../../hyperframes-core/references/brief-format.md`):
|
||||
|
||||
| Key | Meaning | Example |
|
||||
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------- |
|
||||
| `workflow` | the executing workflow (companion runs record `general-video`) | `faceless-explainer` |
|
||||
| `flow` | `automation` — the matched workflow's pipeline · `companion` — co-creation in `/general-video` | `automation` |
|
||||
| `storyboard` | `yes` — plan, sketches, and build reviewed on the live board · `no` — one shot from the confirmed brief | `yes` |
|
||||
| `message` | the ONE thing the video must communicate | `"Ship it in an afternoon"` |
|
||||
| `destination` / `aspect` / `language` / `audience` / `length` / `angle` … | the registry fields this route confirmed | — |
|
||||
@@ -4,7 +4,7 @@ Everything else in the intent layer converges: recommended options, receipts, on
|
||||
|
||||
## When it runs
|
||||
|
||||
Triage (`/hyperframes` § 4, step 2) marks the request formed or unformed; only unformed requests enter the round, and only on routes whose `route-briefs.md` entry names pitch-eligible fields. A recipe adoption skips the round — the bundle already carries an approved concept. An autonomous signal never skips it; it moves the round inside (§ The gate, alone).
|
||||
Triage (`/hyperframes` → `references/intent-interview.md`, step 2) marks the request formed or unformed; only unformed requests enter the round, and only on routes whose `routes/<workflow>.md` entry names pitch-eligible fields. A recipe adoption skips the round — the bundle already carries an approved concept. An autonomous signal never skips it; it moves the round inside (§ The gate, alone).
|
||||
|
||||
Before generating anything, ask what the user is already picturing. An existing idea seeds the round as a pitch of its own and is never displaced by generated ones; a fully formed picture ends the round before it starts — that picture is the concept, and the layer returns to its questions.
|
||||
|
||||
|
||||
@@ -1,85 +1,11 @@
|
||||
# Route briefs — what the intent layer asks, per route
|
||||
# Route briefs (moved)
|
||||
|
||||
The adaptive half of the intent layer (`/hyperframes` § 4, steps 4–6): each route's entry names the **must-haves** to ask now, the **conditional** questions its input can add, the **deferred asks** to announce (questions that stay in the workflow because their recommendations need pipeline data — a probed clip, a captured site), and whether the two **run-shape questions** (storyboard? · automation or companion?) apply. An entry that names **pitch-eligible** fields sends an unformed request through the pitch round (`pitch-round.md`) after routing; the chosen concept answers those fields. An entry without that line never enters the round. These entries live here, in the router skill, because workflow skills install lazily — at routing time the matched workflow may not be on the machine yet.
|
||||
Each route's interview entry — must-haves, conditional questions, deferred asks,
|
||||
pitch-eligible fields, and whether the run-shape questions apply — now lives in that
|
||||
route's own file, together with its input/output/trigger contract:
|
||||
|
||||
Field semantics and question rules: `hyperframes-core/references/brief-contract.md` § 2–3. Every question: recommended option first, receipt attached; a remembered value becomes the recommendation with its source named. The intro text of the brief always states **message** and **language** (state, don't ask).
|
||||
`references/routes/<workflow>.md` — e.g. `routes/faceless-explainer.md`,
|
||||
`routes/pr-to-video.md` (including the PR-size → length table).
|
||||
|
||||
## `/faceless-explainer`
|
||||
|
||||
- **Must-haves:** **angle** — concept / how-to / listicle / narrative, recommend the one the text's own shape suggests · **length** — inside the 30–90s sweet spot, scaled to how much the text actually teaches · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
|
||||
- **Conditional:** a pasted script adds **`VO_MODE`** — use it verbatim, or restructure per scene?
|
||||
- **Pitch round:** `message` + `angle` — five tellings of the same topic are five different videos.
|
||||
- **Run-shape:** both.
|
||||
|
||||
## `/product-launch-video`
|
||||
|
||||
- **First, sell or show?** One question when the request doesn't say: market the product (a promo), or show the site as-is (a tour / showcase)? A show-it answer is **intent, not a different pipeline**: write it into `BRIEF.md` (`## Intent` / `## Customizations` — "feature the site's own captured screens as the video's assets") and the workflow's normal steps carry it — the captured screens become the featured `asset_candidates`.
|
||||
- **Must-haves:** **angle** — story shapes from the site's / brief's own positioning, recommend one with its basis · **length** — 30–90s sweet spot, scaled to the material · **destination** — as above.
|
||||
- **Conditional:** a show-it-as-is ask adds **what to show** — the whole site, or specific pages/sections (into `BRIEF.md`'s body); a pasted script/brief adds **`VO_MODE`** (verbatim or restructured?); a script that only names a site adds **capture?** — crawl it for brand + assets (default), or text-only / "don't scrape" (no-capture mode, a preset supplies the design system).
|
||||
- **Pitch round:** `message` + `angle`, after sell-or-show is settled — the pitches inherit that intent.
|
||||
- **Run-shape:** both.
|
||||
|
||||
## `/pr-to-video`
|
||||
|
||||
- **Must-haves:** the **PR reference** (URL, `owner/repo#N`, or "this PR") · **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough, recommend the one the PR itself suggests · **audience** — developers (default) · mixed technical · non-technical stakeholders · **length** — from the size table below · **destination** — 16:9 is the default for a code explainer.
|
||||
- **Length comes from the PR's change size**, not a fixed guess — peek once, read-only (the workflow's Step 1 still does the full deterministic fetch):
|
||||
|
||||
```bash
|
||||
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
|
||||
```
|
||||
|
||||
Pick the tier from `additions + deletions` (nudged up by `changedFiles`) and lead with it (hard cap ~3 min):
|
||||
|
||||
| PR change size | Recommended length |
|
||||
| --------------------------------- | ------------------ |
|
||||
| trivial (≲ 50 lines changed) | ~20–40s |
|
||||
| focused (~50–200 lines) | ~40–70s |
|
||||
| substantial (~200–600 lines) | ~70–110s |
|
||||
| large (≳ 600 lines, or 25+ files) | ~110–180s |
|
||||
|
||||
State the basis in one phrase ("~40s — small change, +44/−13 across 12 files"). The tier is a **ceiling** on how much story the diff can support, never a floor to fill: a one-headline story recommends inside 30–90s regardless of tier (the tier's range may still appear as a non-recommended fuller-walkthrough option).
|
||||
|
||||
- **Pitch round:** `angle` and the opening hook — the diff fixes the facts, not the telling.
|
||||
- **Run-shape:** both.
|
||||
|
||||
## `/general-video`
|
||||
|
||||
- **Open-ended requests only:** first derive a one-sentence `message`. Ask `audience` only when it is unclear and would change the story or terminology. Ask `destination` only when it would change aspect or composition. Ask for a priority only when the brief contains a real trade-off. Default to one best version; ask about variations only when the user requests options or comparison.
|
||||
- **Specific requests:** a complete ask such as “a static title card with our logo for a website hero” needs no discovery questions.
|
||||
- **Pitch round:** `message` — the unformed open-ended request is this round's home case.
|
||||
- **Run-shape:** both questions apply. `/general-video` is also the companion host, so `flow: companion` stays on this route with the full toolbox.
|
||||
|
||||
## `/music-to-video`
|
||||
|
||||
- **Must-haves:** the **music source** — a track file, a video to pull audio from, or generate one from a mood description · **destination → aspect**.
|
||||
- **Deferred (announce):** brand (font + palette) and the genre feel are chosen at its Step 3 by design — they emerge from the track's analysis, not from a question up front.
|
||||
- **Pitch round:** `message` — the visual concept riding the beat grid (lyric treatment, montage story, kinetic type); brand and genre feel still land at Step 3.
|
||||
- **Run-shape:** both.
|
||||
|
||||
## `/motion-graphics`
|
||||
|
||||
- Autonomous by design: at most **one** clarifying question, owned by its director step, in the flow. No must-haves here beyond confirming the input; route directly.
|
||||
- **Run-shape:** neither — the piece is seconds long; a board and a companion session have nothing to add.
|
||||
- **Front-door capability offer:** skip it. The director's one-question limit is authoritative.
|
||||
|
||||
## `/slideshow`
|
||||
|
||||
- The one question is the routing confirmation itself — "do you want this as a HyperFrames slideshow?" — asked during triage (it survives every mode: wrong routing is a quality problem). The deck contract owns everything after.
|
||||
- **Run-shape:** neither — the deliverable is a navigable deck, not a rendered video.
|
||||
- **Front-door capability offer:** skip it. After route confirmation, the deck workflow owns all remaining choices.
|
||||
|
||||
## `/embedded-captions`
|
||||
|
||||
- **Must-haves:** which clip (the input file).
|
||||
- **Deferred (announce):** the caption **identity** pick — its Step 0 probes the clip first, then shortlists 2–3 identities from the catalog and recommends one. Say that's coming.
|
||||
- **Run-shape:** neither — the footage is untouched; there is no storyboard to review.
|
||||
|
||||
## `/talking-head-recut`
|
||||
|
||||
- **Must-haves:** which clip (the input file).
|
||||
- **Deferred (announce):** its render-strategy questions — aspect ratio, layout, style group, card count — stay at its Step 7, where the recommendations come from the probed footage and transcript. Say they're coming.
|
||||
- **Run-shape:** neither.
|
||||
|
||||
## `/remotion-to-hyperframes`
|
||||
|
||||
- Not served by the intent layer — a migration with no brief. Route directly.
|
||||
The interview procedure itself (the eight steps) is `references/intent-interview.md`.
|
||||
Field semantics and question rules: `hyperframes-core/references/brief-contract.md` § 2–3.
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Route: embedded-captions
|
||||
|
||||
- **Input:** Existing talking-head footage to caption. It is an actual media file, not a URL or creative brief.
|
||||
- **Output:** The same footage, untouched, with a caption layer and selected caption identity. The subject may occlude embedded captions. Any length.
|
||||
- **Triggers:** "add captions", "add subtitles", "captions behind the subject", "cinematic captions for my clip".
|
||||
|
||||
## Interview
|
||||
|
||||
- **Must-haves:** which clip (the input file).
|
||||
- **Deferred (announce):** the caption **identity** pick — its Step 0 probes the clip first, then shortlists 2–3 identities from the catalog and recommends one. Say that's coming.
|
||||
- **Run-shape:** neither — the footage is untouched; there is no storyboard to review.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Route: faceless-explainer
|
||||
|
||||
- **Input:** A topic, article, notes, or arbitrary text being explained, with no product being marketed and no website to capture.
|
||||
- **Output:** A faceless explainer MP4 with invented typography, abstract graphics, diagrams, or data visualization. Sweet spot 30–90s; hard cap about 3 minutes.
|
||||
- **Triggers:** "faceless explainer about X", "explain how DNS works as a video", "turn this article into an explainer".
|
||||
|
||||
## Interview
|
||||
|
||||
- **Must-haves:** **angle** — concept / how-to / listicle / narrative, recommend the one the text's own shape suggests · **length** — inside the 30–90s sweet spot, scaled to how much the text actually teaches · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
|
||||
- **Conditional:** a pasted script adds **`VO_MODE`** — use it verbatim, or restructure per scene?
|
||||
- **Pitch round:** `message` + `angle` — five tellings of the same topic are five different videos.
|
||||
- **Run-shape:** both.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Route: general-video
|
||||
|
||||
- **Input:** Any custom creation or edit not covered by a specialized route: a static title card, longer brand or sizzle reel, multi-scene montage, static loop/poster, NLE-like footage remix, or freeform composition. It also executes every `flow: companion` brief.
|
||||
- **Output:** A HyperFrames composition of any length or format through design → plan → static layout → animation → check → approval → render.
|
||||
- **Triggers:** "make a static title card", "longer brand reel", "multi-scene composition", "static loop", "custom video", or any unmatched video request.
|
||||
|
||||
## Interview
|
||||
|
||||
- **Open-ended requests only:** first derive a one-sentence `message`. Ask `audience` only when it is unclear and would change the story or terminology. Ask `destination` only when it would change aspect or composition. Ask for a priority only when the brief contains a real trade-off. Default to one best version; ask about variations only when the user requests options or comparison.
|
||||
- **Specific requests:** a complete ask such as "a static title card with our logo for a website hero" needs no discovery questions.
|
||||
- **Pitch round:** `message` — the unformed open-ended request is this round's home case.
|
||||
- **Run-shape:** both questions apply. `/general-video` is also the companion host, so `flow: companion` stays on this route with the full toolbox.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Route: motion-graphics
|
||||
|
||||
- **Input:** A short design-led unit, typically under 10s, with no narration, where motion is the message: kinetic type, stat/count-up, chart hit, logo sting, animated title, lower-third, map, tweet/headline/page highlight, or asset-fusion shot.
|
||||
- **Output:** A short MP4 or transparent alpha WebM/MOV overlay.
|
||||
- **Triggers:** "an 8s logo sting", "animate this stat", "kinetic-type intro", "animate this title", "transparent lower-third overlay".
|
||||
|
||||
## Interview
|
||||
|
||||
- Autonomous by design: at most **one** clarifying question, owned by its director step, in the flow. No must-haves here beyond confirming the input; route directly.
|
||||
- **Run-shape:** neither — the piece is seconds long; a board and a companion session have nothing to add.
|
||||
- **Front-door capability offer:** skip it. The director's one-question limit is authoritative.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Route: music-to-video
|
||||
|
||||
- **Input:** A music track, or a video whose audio becomes the track, with no narration or website capture. User images or videos are optional.
|
||||
- **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines.
|
||||
- **Triggers:** "make a video for this song", "beat-synced video", "lyric video", "music visualizer", "kinetic promo to this beat".
|
||||
|
||||
## Interview
|
||||
|
||||
- **Must-haves:** the **music source** — a track file, a video to pull audio from, or generate one from a mood description · **destination → aspect**.
|
||||
- **Deferred (announce):** brand (font + palette) and the genre feel are chosen at its Step 3 by design — they emerge from the track's analysis, not from a question up front.
|
||||
- **Pitch round:** `message` — the visual concept riding the beat grid (lyric treatment, montage story, kinetic type); brand and genre feel still land at Step 3.
|
||||
- **Run-shape:** both.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Route: pr-to-video
|
||||
|
||||
- **Input:** A GitHub PR URL, `owner/repo#N`, or "this PR", read through `gh`; it is not a website capture request.
|
||||
- **Output:** A changelog, feature reveal, fix explainer, or refactor walkthrough with diff, before/after, file-tree, and impact scenes. Hard cap about 3 minutes; duration follows change size.
|
||||
- **Triggers:** "make a video about this PR", "turn PR #1187 into a changelog video", "release-notes video from this pull request".
|
||||
|
||||
## Interview
|
||||
|
||||
- **Must-haves:** the **PR reference** (URL, `owner/repo#N`, or "this PR") · **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough, recommend the one the PR itself suggests · **audience** — developers (default) · mixed technical · non-technical stakeholders · **length** — from the size table below · **destination** — 16:9 is the default for a code explainer.
|
||||
- **Length comes from the PR's change size**, not a fixed guess — peek once, read-only (the workflow's Step 1 still does the full deterministic fetch):
|
||||
|
||||
```bash
|
||||
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
|
||||
```
|
||||
|
||||
Pick the tier from `additions + deletions` (nudged up by `changedFiles`) and lead with it (hard cap ~3 min):
|
||||
|
||||
| PR change size | Recommended length |
|
||||
| --------------------------------- | ------------------ |
|
||||
| trivial (≲ 50 lines changed) | ~20–40s |
|
||||
| focused (~50–200 lines) | ~40–70s |
|
||||
| substantial (~200–600 lines) | ~70–110s |
|
||||
| large (≳ 600 lines, or 25+ files) | ~110–180s |
|
||||
|
||||
State the basis in one phrase ("~40s — small change, +44/−13 across 12 files"). The tier is a **ceiling** on how much story the diff can support, never a floor to fill: a one-headline story recommends inside 30–90s regardless of tier (the tier's range may still appear as a non-recommended fuller-walkthrough option).
|
||||
|
||||
- **Pitch round:** `angle` and the opening hook — the diff fixes the facts, not the telling.
|
||||
- **Run-shape:** both.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Route: product-launch-video
|
||||
|
||||
- **Input:** A website URL; a script or brief that names a site; or a product-launch script with no derivable site or an explicit "do not scrape" instruction. Capture website assets and brand tokens unless the brief selects no-capture mode. Ask whether supplied script copy is verbatim voice-over or may be restructured.
|
||||
- **Output:** A product promo, launch video, site tour, or showcase MP4. Sweet spot 30–90s; hard cap about 3 minutes. A show-it-as-is brief features captured screens rather than inventing a separate route.
|
||||
- **Triggers:** "launch video for X", "promo for our site", "turn this script into a 60s promo", "text-only launch video", "turn this website into a video", "site tour from this URL".
|
||||
|
||||
## Interview
|
||||
|
||||
- **First, sell or show?** One question when the request doesn't say: market the product (a promo), or show the site as-is (a tour / showcase)? A show-it answer is **intent, not a different pipeline**: write it into `BRIEF.md` (`## Intent` / `## Customizations` — "feature the site's own captured screens as the video's assets") and the workflow's normal steps carry it — the captured screens become the featured `asset_candidates`.
|
||||
- **Must-haves:** **angle** — story shapes from the site's / brief's own positioning, recommend one with its basis · **length** — 30–90s sweet spot, scaled to the material · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
|
||||
- **Conditional:** a show-it-as-is ask adds **what to show** — the whole site, or specific pages/sections (into `BRIEF.md`'s body); a pasted script/brief adds **`VO_MODE`** (verbatim or restructured?); a script that only names a site adds **capture?** — crawl it for brand + assets (default), or text-only / "don't scrape" (no-capture mode, a preset supplies the design system).
|
||||
- **Pitch round:** `message` + `angle`, after sell-or-show is settled — the pitches inherit that intent.
|
||||
- **Run-shape:** both.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Route: remotion-to-hyperframes
|
||||
|
||||
- **Input:** Existing Remotion React source, only when the user explicitly asks to port, convert, or migrate it. A passing Remotion mention is not a trigger.
|
||||
- **Output:** A HyperFrames HTML composition translated from the source and compared with the Remotion render through the migration evaluation harness.
|
||||
- **Triggers:** "port my Remotion project", "convert this Remotion composition", "migrate from Remotion".
|
||||
|
||||
## Interview
|
||||
|
||||
- Not served by the intent layer — a migration with no brief. Route directly.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Route: slideshow
|
||||
|
||||
- **Input:** A brief, outline, or existing page to author as a presentation, pitch deck, or interactive deck. If "slides", "deck", or "convert this page" is ambiguous, confirm that the user wants a HyperFrames slideshow before authoring.
|
||||
- **Output:** A runnable HyperFrames composition plus the JSON island used by `SlideshowController`: discrete slides, fragment reveals, branching, hotspots, presenter mode, and speaker notes. The deliverable is a navigable deck, not an MP4.
|
||||
- **Triggers:** "make a pitch deck", "interactive presentation", "convert this page into slides", "slideshow with presenter mode".
|
||||
|
||||
## Interview
|
||||
|
||||
- The one question is the routing confirmation itself — "do you want this as a HyperFrames slideshow?" — asked during triage (it survives every mode: wrong routing is a quality problem). The deck contract owns everything after.
|
||||
- **Run-shape:** neither — the deliverable is a navigable deck, not a rendered video.
|
||||
- **Front-door capability offer:** skip it. After route confirmation, the deck workflow owns all remaining choices.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Route: talking-head-recut
|
||||
|
||||
- **Input:** Existing talking-head, interview, or podcast footage to package. The underlying clip plays unchanged.
|
||||
- **Output:** The same footage with transcript-synced graphic-overlay cards: kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, or picture-in-picture. Any length.
|
||||
- **Triggers:** "package this video", "add graphic overlays to my talk", "add lower-thirds or data callouts to this interview".
|
||||
|
||||
## Interview
|
||||
|
||||
- **Must-haves:** which clip (the input file).
|
||||
- **Deferred (announce):** its render-strategy questions — aspect ratio, layout, style group, card count — stay at its Step 7, where the recommendations come from the probed footage and transcript. Say they're coming.
|
||||
- **Run-shape:** neither.
|
||||
@@ -1,70 +1,10 @@
|
||||
# Workflow catalog
|
||||
# Workflow catalog (moved)
|
||||
|
||||
Use this catalog while routing, before the selected workflow is lazy-installed. After the routing table in `../SKILL.md` yields a candidate, read that candidate's section and confirm that its input and output match the request.
|
||||
Each workflow's input/output/trigger contract now lives in its own route file — one
|
||||
small read per candidate instead of a whole catalog:
|
||||
|
||||
## Sections
|
||||
`references/routes/<workflow>.md` — e.g. `routes/product-launch-video.md`,
|
||||
`routes/general-video.md`, `routes/remotion-to-hyperframes.md`.
|
||||
|
||||
- [`/product-launch-video`](#product-launch-video), [`/faceless-explainer`](#faceless-explainer), [`/pr-to-video`](#pr-to-video)
|
||||
- [`/embedded-captions`](#embedded-captions), [`/talking-head-recut`](#talking-head-recut)
|
||||
- [`/motion-graphics`](#motion-graphics), [`/music-to-video`](#music-to-video), [`/slideshow`](#slideshow)
|
||||
- [`/general-video`](#general-video), [`/remotion-to-hyperframes`](#remotion-to-hyperframes)
|
||||
|
||||
## `/product-launch-video`
|
||||
|
||||
- **Input:** A website URL; a script or brief that names a site; or a product-launch script with no derivable site or an explicit “do not scrape” instruction. Capture website assets and brand tokens unless the brief selects no-capture mode. Ask whether supplied script copy is verbatim voice-over or may be restructured.
|
||||
- **Output:** A product promo, launch video, site tour, or showcase MP4. Sweet spot 30–90s; hard cap about 3 minutes. A show-it-as-is brief features captured screens rather than inventing a separate route.
|
||||
- **Triggers:** “launch video for X”, “promo for our site”, “turn this script into a 60s promo”, “text-only launch video”, “turn this website into a video”, “site tour from this URL”.
|
||||
|
||||
## `/faceless-explainer`
|
||||
|
||||
- **Input:** A topic, article, notes, or arbitrary text being explained, with no product being marketed and no website to capture.
|
||||
- **Output:** A faceless explainer MP4 with invented typography, abstract graphics, diagrams, or data visualization. Sweet spot 30–90s; hard cap about 3 minutes.
|
||||
- **Triggers:** “faceless explainer about X”, “explain how DNS works as a video”, “turn this article into an explainer”.
|
||||
|
||||
## `/pr-to-video`
|
||||
|
||||
- **Input:** A GitHub PR URL, `owner/repo#N`, or “this PR”, read through `gh`; it is not a website capture request.
|
||||
- **Output:** A changelog, feature reveal, fix explainer, or refactor walkthrough with diff, before/after, file-tree, and impact scenes. Hard cap about 3 minutes; duration follows change size.
|
||||
- **Triggers:** “make a video about this PR”, “turn PR #1187 into a changelog video”, “release-notes video from this pull request”.
|
||||
|
||||
## `/embedded-captions`
|
||||
|
||||
- **Input:** Existing talking-head footage to caption. It is an actual media file, not a URL or creative brief.
|
||||
- **Output:** The same footage, untouched, with a caption layer and selected caption identity. The subject may occlude embedded captions. Any length.
|
||||
- **Triggers:** “add captions”, “add subtitles”, “captions behind the subject”, “cinematic captions for my clip”.
|
||||
|
||||
## `/talking-head-recut`
|
||||
|
||||
- **Input:** Existing talking-head, interview, or podcast footage to package. The underlying clip plays unchanged.
|
||||
- **Output:** The same footage with transcript-synced graphic-overlay cards: kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, or picture-in-picture. Any length.
|
||||
- **Triggers:** “package this video”, “add graphic overlays to my talk”, “add lower-thirds or data callouts to this interview”.
|
||||
|
||||
## `/motion-graphics`
|
||||
|
||||
- **Input:** A short design-led unit, typically under 10s, with no narration, where motion is the message: kinetic type, stat/count-up, chart hit, logo sting, animated title, lower-third, map, tweet/headline/page highlight, or asset-fusion shot.
|
||||
- **Output:** A short MP4 or transparent alpha WebM/MOV overlay.
|
||||
- **Triggers:** “an 8s logo sting”, “animate this stat”, “kinetic-type intro”, “animate this title”, “transparent lower-third overlay”.
|
||||
|
||||
## `/music-to-video`
|
||||
|
||||
- **Input:** A music track, or a video whose audio becomes the track, with no narration or website capture. User images or videos are optional.
|
||||
- **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines.
|
||||
- **Triggers:** “make a video for this song”, “beat-synced video”, “lyric video”, “music visualizer”, “kinetic promo to this beat”.
|
||||
|
||||
## `/slideshow`
|
||||
|
||||
- **Input:** A brief, outline, or existing page to author as a presentation, pitch deck, or interactive deck. If “slides”, “deck”, or “convert this page” is ambiguous, confirm that the user wants a HyperFrames slideshow before authoring.
|
||||
- **Output:** A runnable HyperFrames composition plus the JSON island used by `SlideshowController`: discrete slides, fragment reveals, branching, hotspots, presenter mode, and speaker notes. The deliverable is a navigable deck, not an MP4.
|
||||
- **Triggers:** “make a pitch deck”, “interactive presentation”, “convert this page into slides”, “slideshow with presenter mode”.
|
||||
|
||||
## `/general-video`
|
||||
|
||||
- **Input:** Any custom creation or edit not covered above: a static title card, longer brand or sizzle reel, multi-scene montage, static loop/poster, NLE-like footage remix, or freeform composition. It also executes every `flow: companion` brief.
|
||||
- **Output:** A HyperFrames composition of any length or format through design → plan → static layout → animation → check → approval → render.
|
||||
- **Triggers:** “make a static title card”, “longer brand reel”, “multi-scene composition”, “static loop”, “custom video”, or any unmatched video request.
|
||||
|
||||
## `/remotion-to-hyperframes`
|
||||
|
||||
- **Input:** Existing Remotion React source, only when the user explicitly asks to port, convert, or migrate it. A passing Remotion mention is not a trigger.
|
||||
- **Output:** A HyperFrames HTML composition translated from the source and compared with the Remotion render through the migration evaluation harness.
|
||||
- **Triggers:** “port my Remotion project”, “convert this Remotion composition”, “migrate from Remotion”.
|
||||
The same file carries that route's interview entry (must-haves, conditionals, deferred
|
||||
asks, run-shape), so confirming a route is exactly one read.
|
||||
|
||||
+30
-425
@@ -5,44 +5,30 @@ description: Agent Media OS, the single skill for every media need in a HyperFra
|
||||
|
||||
# media-use
|
||||
|
||||
The media OS for HyperFrames: resolve · generate · operate · remember, every media type, one skill, zero context noise.
|
||||
The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
|
||||
|
||||
## Setup — install heygen first (free-usage path)
|
||||
First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `node <SKILL_DIR>/scripts/resolve.mjs --doctor`. Setup and providers: `references/setup-providers.md`.
|
||||
|
||||
## Resolve — the one verb
|
||||
|
||||
```bash
|
||||
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
|
||||
heygen update # free usage needs the OAuth-capable CLI (v0.3.0+)
|
||||
heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
|
||||
```
|
||||
|
||||
This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
|
||||
Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --doctor
|
||||
```
|
||||
| Type | One-line intent |
|
||||
| ------- | ----------------------------------------------------------------------------------- |
|
||||
| `bgm` | background music (HeyGen catalog, 10k+ tracks) |
|
||||
| `sfx` | sound effects (bundled 19-file library + catalog) |
|
||||
| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors) |
|
||||
| `icon` | icons, symbols (transparent) |
|
||||
| `logo` | official brand marks (svgl → simple-icons → GitHub avatar → favicon; never redrawn) |
|
||||
| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro) |
|
||||
| `grade` | paste-ready HyperFrames `data-color-grading` block |
|
||||
| `lut` | reusable validated `.cube` file |
|
||||
|
||||
## What it owns (the gaps HyperFrames leaves)
|
||||
|
||||
HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
|
||||
|
||||
| HyperFrames gap | media-use owns it via |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Audio-only, no image/icon | `resolve --type image\|icon` (heygen asset search) |
|
||||
| No third-party brand logos | `resolve --type logo` (svgl → simple-icons → GitHub org avatar → domain favicon) |
|
||||
| No voice / audio generation | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`) |
|
||||
| Scattered/duplicated audio engine | one consolidated engine under `audio/` (hyperframes-media retired) |
|
||||
| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs |
|
||||
| No transcript-driven cutting | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists |
|
||||
| No auto-duck / publish loudness | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes |
|
||||
| No cross-project memory | global content-addressed cache + auto-promote (`~/.media`) |
|
||||
| No color-grade authoring | `resolve --type grade` emits a paste-ready `data-color-grading` block; `resolve --type lut` freezes validated `.cube` files |
|
||||
| No image generation | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`) |
|
||||
| No video generation | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
|
||||
| Weak local-model defaults | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`) |
|
||||
|
||||
## When to use
|
||||
|
||||
Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, brand logos, voice, a color grade, or a LUT. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first for media files, resolves official logos through the logo cascade, uses local deterministic color grading for `grade`/`lut`, freezes the best match locally when a file is needed, registers it in a manifest, and hands the agent one line; all search noise stays on disk.
|
||||
Before resolving fresh, list reusable candidates with `--candidates` and judge fit yourself — reuse rules, all flags, ingest (`--from`), and adopt are in `references/resolve.md`.
|
||||
|
||||
## Be proactive — run a media opportunity pass
|
||||
|
||||
@@ -59,397 +45,16 @@ Surface an opportunity only when a concrete signal is present:
|
||||
| A piece over ~10s with no music bed | `bgm` |
|
||||
| Footage that reads under/over-exposed or color-cast | a corrective `grade` (analyze with `grade --for`, preview with `hyperframes grade-compare`) |
|
||||
|
||||
Rules that keep this a help, not nagware:
|
||||
|
||||
- **Grounded, not generic.** No signal → no suggestion. Never open with "want better images?".
|
||||
- **Opinionated + concrete.** Propose the specific fix ("add a VO from your script, swap 3 emoji for real icons, replace the 400×400 hero, whooshes on the 4 cuts"), with defaults chosen — the human just approves **all / some / none**.
|
||||
- **Once per project.** One consolidated ask, top few highest-value items. Respect "leave it" and don't re-raise.
|
||||
- **Surface, never silently mutate.** Color grades especially: propose and preview, never auto-apply — a gray-world "correction" ruins an intentional sunset or neon look.
|
||||
|
||||
## Resolve
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
|
||||
```
|
||||
|
||||
Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
|
||||
|
||||
### Types
|
||||
|
||||
| Type | What it finds | Provider / cascade |
|
||||
| ------- | -------------------------------- | ------------------------------------------------------------ |
|
||||
| `bgm` | Background music | HeyGen audio catalog (10k+ tracks) |
|
||||
| `sfx` | Sound effects | Bundled 19-file library + HeyGen catalog |
|
||||
| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors) |
|
||||
| `icon` | Icons, symbols | HeyGen asset search (type=icon) |
|
||||
| `logo` | Official brand marks | svgl → simple-icons → GitHub org avatar → domain favicon |
|
||||
| `voice` | TTS voiceover | HeyGen TTS free-usage path; optional local Kokoro |
|
||||
| `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |
|
||||
| `lut` | Reusable `.cube` LUT files | Look index params/CDN LUT → deterministic cube |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Background music
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
|
||||
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
|
||||
|
||||
# Sound effect
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
|
||||
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
|
||||
|
||||
# Image
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
|
||||
# → resolved image_001 → .media/images/image_001.jpg (image)
|
||||
|
||||
# Icon
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
|
||||
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
|
||||
|
||||
# Brand logo (official mark — never redrawn by hand)
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project .
|
||||
# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)
|
||||
|
||||
# Color grade block
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
|
||||
# → {"ok":true,"preset":"warm-daylight","grading":{"preset":"warm-daylight","intensity":1},...}
|
||||
|
||||
# LUT file
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
|
||||
# → resolved lut_001 → .media/luts/lut_001.cube (lut)
|
||||
```
|
||||
|
||||
### Flags
|
||||
|
||||
| Flag | Description |
|
||||
| --------------- | ------------------------------------------------------------------------------------ |
|
||||
| `--type, -t` | Media type: bgm, sfx, image, icon, logo, voice, grade, lut |
|
||||
| `--intent, -i` | What you need (natural language) |
|
||||
| `--entity, -e` | Entity name for cache matching (optional) |
|
||||
| `--project, -p` | Project directory (default: .) |
|
||||
| `--candidates` | List reusable assets (project + global cache) for `--type`; no download, no mutation |
|
||||
| `--reuse <sha>` | Import a specific global-cache asset (by content sha/prefix, from `--candidates`) |
|
||||
| `--from` | Freeze a local file or direct public URL (ingest) |
|
||||
| `--for` | Analyze a local image/video and add measured adjust suggestions (`grade` only) |
|
||||
| `--local-only` | Offline: skip every network provider (cache + local only) |
|
||||
| `--provider` | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`) |
|
||||
| `--adopt` | Bulk-import existing assets/ into manifest |
|
||||
| `--doctor` | Check local CLI dependencies; no manifest changes |
|
||||
| `--stats` | Print local usage stats from `.media/` and `~/.media`; no manifest changes |
|
||||
| `--days N` | Limit `--stats` to timestamped records/misses from the last N days |
|
||||
| `--json` | Output JSON instead of one-line result |
|
||||
|
||||
## Reuse before you resolve
|
||||
|
||||
Before resolving bgm/sfx/image/icon/logo/grade/lut, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --candidates --project .
|
||||
# [project] upbeat tech launch (25s, heygen.audio.sounds)
|
||||
# .media/audio/bgm/bgm_001.wav
|
||||
# [global] energetic tech intro (22s, heygen.audio.sounds)
|
||||
# --reuse 06e052c075fd2b80
|
||||
```
|
||||
|
||||
Read the list and judge semantic fit yourself — "upbeat tech launch" ≈ "energetic tech intro" is a call only you can make from the descriptions. Then:
|
||||
|
||||
- **A project candidate fits** → just reference its path in your composition. Nothing else to run.
|
||||
- **A global candidate fits** → `resolve --type bgm --reuse <sha>` copies it into this project (self-contained render) and records it.
|
||||
- **Nothing fits** → resolve fresh (`--type ... --intent ...`).
|
||||
|
||||
**Trust guardrail — when unsure, resolve fresh.** A redundant download is cheap; shipping the wrong asset is not. Judge fit from description + prompt + type + duration/dims. For **brand/entity** assets, reuse a _global_ candidate only when the entity matches exactly — the global cache aggregates every project you have worked on, so a `--candidates` list can surface another client's brand mark and its prompt text. Never reuse a cross-project brand asset on a loose match.
|
||||
|
||||
The deterministic floor still runs automatically: an identical (case/whitespace-insensitive) repeat auto-reuses with no `--candidates` step. `--candidates` is only for the semantic layer above that floor — and a fuzzy match is **never** auto-applied; reuse is always your explicit call. On a resolve that misses the floor and is about to fetch, media-use prints a one-line stderr hint when similar cached assets exist, pointing you back here.
|
||||
|
||||
## Color grading
|
||||
|
||||
Use `grade` when you need the actual HyperFrames `data-color-grading` value to paste onto an `<img>` or `<video>`. Core presets and params-backed library looks resolve locally; future CDN-backed library looks require network unless already frozen:
|
||||
|
||||
**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
|
||||
```
|
||||
|
||||
Preset-first output uses the core runtime vocabulary and does not freeze a file:
|
||||
|
||||
```json
|
||||
{
|
||||
"preset": "warm-daylight",
|
||||
"intensity": 1
|
||||
}
|
||||
```
|
||||
|
||||
Paste it as an attribute value after JSON string escaping:
|
||||
|
||||
```html
|
||||
<video
|
||||
class="clip"
|
||||
src="./media/scene.mp4"
|
||||
data-color-grading='{"preset":"warm-daylight","intensity":1}'
|
||||
></video>
|
||||
```
|
||||
|
||||
Looks beyond the preset vocabulary freeze a validated `.cube` under `.media/luts/` and return a block that references it:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "teal orange blockbuster" --project . --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"intensity": 1,
|
||||
"lut": { "src": ".media/luts/grade_001.cube", "intensity": 0.85 }
|
||||
}
|
||||
```
|
||||
|
||||
Use `lut` when you only need the reusable `.cube` file:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
|
||||
```
|
||||
|
||||
For a describable technical look, author an explicit parametric LUT with `--params`:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --params '{"exposure":0.2}' --project . --json
|
||||
```
|
||||
|
||||
For a LUT generated by your own script, ingest it with `--from`; media-use validates it before registration and rejects invalid or oversized cubes:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --from custom.cube --project .
|
||||
```
|
||||
|
||||
Parametric math (`buildCube`) cannot reproduce real film stocks or emulsion looks. Use a CDN-backed scanned `.cube` entry or ingest a real scanned `.cube` for those.
|
||||
|
||||
For visual selection, list reusable looks with `resolve --type grade --candidates`, write the promising entries to a `grades.json`, run `hyperframes grade-compare --for <frame> --grades grades.json`, then commit the winner with `resolve -t grade` as the final `data-color-grading` block.
|
||||
|
||||
Smart grade is `grade --for <media>`. It runs local `ffmpeg`/`ffprobe` signalstats, merges a bounded `adjust` suggestion into the returned block, and prints the measured evidence to stderr. Stdout remains valid JSON under `--json`; the suggestion is a starting point for the agent to tune, not an automatic neutralization of intentional color.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm cinematic" --for ./frame.png --project . --json
|
||||
```
|
||||
|
||||
Library looks live in `luts/index.json`. Each entry keeps `id`, `description`, `tags`, and `intensity`, then supplies either compact `params` for on-demand `buildCube(params)` generation or a direct CDN `url` for future scanned `.cube` files. Do not commit generated `.cube` bodies; resolve validates generated or downloaded cubes as it freezes them under `.media/luts/`.
|
||||
|
||||
```bash
|
||||
node skills/media-use/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project . --json
|
||||
node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
|
||||
```
|
||||
|
||||
## Providers
|
||||
|
||||
media-use holds no keys; every external tool owns its auth. Generation is
|
||||
centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
|
||||
before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
|
||||
alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
|
||||
transcription, and LTX for local video generation. `resolve` spec-checks
|
||||
AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
|
||||
see the ladder and override.
|
||||
|
||||
| Type | Provider / path |
|
||||
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| bgm/sfx | heygen catalog free-usage path |
|
||||
| image | heygen search free-usage path; optional local mflux; codex `image_gen` upsell |
|
||||
| voice | heygen tts free-usage path; optional local **Kokoro** (free, on-device) |
|
||||
| icon | heygen asset search free-usage path |
|
||||
| logo | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free) |
|
||||
| grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback |
|
||||
| video | heygen avatar video free-usage path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
|
||||
|
||||
Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
|
||||
private, offline once cached). The `codex` CLI remains the ChatGPT-sub image
|
||||
upsell. Cost rule (X4): the agent confirms before an agent-initiated paid call;
|
||||
a user-requested one just runs — `heygen.video` is flagged paid (metered free
|
||||
allowance) so an agent-initiated `resolve --type video` confirms first.
|
||||
|
||||
To force a specific generator (e.g. a user says "make this image with codex"),
|
||||
pass `--provider codex`: it pins resolution to that provider and skips the
|
||||
free-usage default. See `references/operations.md` for the RAM ladders and
|
||||
provider recipes.
|
||||
|
||||
`--local-only` skips every network provider, including the free HeyGen ones,
|
||||
leaving the project + global cache and any installed local provider. For
|
||||
HeyGen-only types, that means no fresh resolve.
|
||||
|
||||
## How it works
|
||||
|
||||
`resolve` runs an automatic floor, then falls through to fetching:
|
||||
|
||||
1. Check project `.media/manifest.jsonl` for a prompt match (case- and whitespace-insensitive) — auto-reuse
|
||||
2. Scan existing `assets/` directory for unregistered files that share a word with the need
|
||||
3. Check global cache `~/.media/` for a reusable asset matched on the same normalized prompt — auto-reuse
|
||||
4. Search via provider (HeyGen audio catalog, HeyGen asset search), or resolve color locally
|
||||
5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`, auto-promote to `~/.media/`
|
||||
|
||||
Steps 1 and 3 are the **deterministic floor**: they only auto-reuse an exact-normalized match, never a fuzzy one. Semantic reuse ("close enough") is the agent's explicit call via [Reuse before you resolve](#reuse-before-you-resolve) — it never happens automatically. The agent gets back **one line**; candidates, scores, provenance stay on disk.
|
||||
|
||||
## Adopt existing projects
|
||||
|
||||
Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
|
||||
# → adopted 9 assets from assets/
|
||||
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
|
||||
# image_001 → assets/images/avatar.jpg (image, 400×400)
|
||||
```
|
||||
|
||||
`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
|
||||
|
||||
## Reading the inventory
|
||||
|
||||
After resolve or adopt, read `.media/index.md` for the full inventory:
|
||||
|
||||
```
|
||||
# .media · 4 assets
|
||||
|
||||
id type dur dims path description
|
||||
bgm_001 bgm 25s - .media/audio/bgm/bgm_001.mp3 upbeat tech launch
|
||||
sfx_001 sfx 0.6s - .media/audio/sfx/sfx_001.mp3 whoosh
|
||||
image_001 image - 1920×1080 .media/images/image_001.jpg gradient tech background
|
||||
icon_001 icon - 200×200 .media/images/icon_001.png rocket
|
||||
```
|
||||
|
||||
## Cross-project reuse
|
||||
|
||||
Assets are cached automatically on resolve. Every resolved/ingested asset is auto-promoted to the global cache at `~/.media/`, so subsequent resolves for the same (or near-identical) prompt, in any project, hit the cache with no re-download and no provider call.
|
||||
|
||||
For a _semantically_ similar (not identical) need in another project, the exact-match floor won't fire — use [Reuse before you resolve](#reuse-before-you-resolve): `--candidates` lists the global assets, and `--reuse <sha>` imports the one you pick. This is how a track resolved in one project gets reused in the next when the wording differs.
|
||||
|
||||
## Preferences — remembered defaults
|
||||
|
||||
The lightweight tier of user memory: confirmed brief answers (destination, aspect, language, flow, storyboard, voice, style preset) persisted on the same two-tier split as assets — project `.media/preferences.json` (committed, the team inherits it) and personal `~/.media/preferences.json`. A value earns the personal tier by being confirmed in **two different projects**, so a one-off choice never pollutes the global defaults.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/prefs.mjs get --hyperframes . --json # merged view (project overrides user)
|
||||
node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --value x-feed
|
||||
node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow faceless-explainer
|
||||
```
|
||||
|
||||
Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes-core/references/brief-contract.md` § 2, Remembered defaults.
|
||||
|
||||
## Recipes — frozen video bundles
|
||||
|
||||
The heavyweight tier of user memory: one approved run frozen as a named, versioned bundle — `frame.md`, the storyboard skeleton (structure kept, content blanked to per-frame fill-ins), the brief skeleton (from `BRIEF.md` when the project has one — reusable frontmatter kept, run-shape and prose blanked), and the confirmed brief values. Same two tiers: project `.media/recipes/<name>/` (committed) and `~/.media/recipes/<name>/` (a freeze is already a confirmed bundle, so it promotes immediately — no two-project rule). Re-freezing a name bumps `version` and archives the old folder as `<name>@v<N>`.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo # workflow read from BRIEF.md (--workflow only for briefless projects)
|
||||
node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-launch-video
|
||||
node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo # also: resolve.mjs --type recipe --entity weekly-promo
|
||||
```
|
||||
|
||||
The freeze is offered once after the final approval (`hyperframes-core/references/review-loop.md` § 4), and the intent layer (`/hyperframes` § 4) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
|
||||
|
||||
## Usage stats
|
||||
|
||||
Use `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --stats --project . --days 7
|
||||
# media-use stats
|
||||
# total resolves: 12
|
||||
# misses: 2
|
||||
# hit rate: 86%
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
- `.media/manifest.jsonl`: machine SSOT, one JSON record per line
|
||||
- `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)
|
||||
- `.media/preferences.json`: the project's remembered defaults (committed)
|
||||
- `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)
|
||||
- `~/.media/preferences.json`: personal remembered defaults (promoted after two projects)
|
||||
- `.media/recipes/<name>/`: frozen video bundles — recipe.json + frame.md + storyboard skeleton (committed)
|
||||
- `~/.media/recipes/<name>/`: personal recipe tier (promoted on freeze)
|
||||
- `~/.media/misses.jsonl`: local-only resolve misses, including intent text for `--stats`
|
||||
|
||||
## Audio engine: voiceover, music, SFX, captions, transcription
|
||||
|
||||
For a full audio pass (TTS voiceover + background music + sound effects in one
|
||||
shot), use the shared engine at `audio/scripts/audio.mjs`. It takes a neutral
|
||||
`audio_request.json` and writes `audio_meta.json` plus assets under
|
||||
`.media/audio/{voice,bgm,sfx}`:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./audio_meta.json
|
||||
```
|
||||
|
||||
- **Request** `{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
|
||||
- **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
|
||||
- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `node <SKILL_DIR>/scripts/resolve.mjs --doctor` before assuming retrieval or TTS will work.
|
||||
- If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
|
||||
|
||||
Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).
|
||||
|
||||
## Operating on media (cut, reframe, transform)
|
||||
|
||||
media-use resolves + remembers; for **operating** on assets see
|
||||
`references/operations.md`: local-tool recipes (ffmpeg trim/reframe/montage,
|
||||
auto-editor, scenedetect) and the local-vs-HeyGen transform table (background
|
||||
removal, upscale, lipsync, translate). Run the tool, then register the output
|
||||
with `resolve --from <output> --type <type>` so it joins the ledger + global
|
||||
cache.
|
||||
|
||||
HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
|
||||
input video) or for **preview** (auto-proxy transcodes and caches an H.264
|
||||
copy on first use, disable with `--no-proxy` or `media.autoProxy: false` in
|
||||
hyperframes.json). A manual H.264 proxy via `ffmpeg -i in.mp4 -c:v libx264
|
||||
-crf 18 proxy.mp4`, registered with `resolve --from`, remains available for
|
||||
edge cases (e.g. auto-proxy disabled, or ffmpeg unavailable at preview time).
|
||||
|
||||
## CLI tools used (what to run, and how to enable each)
|
||||
|
||||
`resolve` auto-cascades; each provider shells one CLI. HeyGen is the
|
||||
free-usage path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar
|
||||
video, so those capabilities need `heygen` installed and authenticated. Local
|
||||
tools are OPT-IN alternatives where they exist; install one to unlock its free,
|
||||
private, on-device path instead of or ahead of HeyGen for that type. Only
|
||||
`ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
|
||||
|
||||
| Tool | Serves | Install |
|
||||
| ------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
|
||||
| `heygen` | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | `curl -fsSL https://static.heygen.ai/cli/install.sh \| bash` then `heygen auth login --oauth` (needs >= v0.3.0) |
|
||||
| `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
|
||||
| `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
|
||||
| `parakeet-mlx` | local transcription (default ASR, best) | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
|
||||
| `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
|
||||
| `npx hyperframes` | Kokoro TTS (voice), whisper.cpp (transcribe fallback), remove-background | via the hyperframes CLI; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake), models download from HuggingFace |
|
||||
|
||||
The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
|
||||
`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
|
||||
to see which model fits this machine). Without a tool on PATH, its provider
|
||||
prints a one-line diagnostic to stderr and resolve falls through where another
|
||||
provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
|
||||
|
||||
`heygen asset search` is a pre-launch command hidden from `heygen --help`, but it
|
||||
runs. Every media-use call that shells `heygen` — catalog search AND every
|
||||
generating call (TTS, avatar video) — tags requests with the allowlisted
|
||||
`X-HeyGen-Client-Source: media-use` header (v0.3.0+), sourced from one shared
|
||||
constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`) so a
|
||||
future call site can't silently ship untagged. Read-only discovery calls
|
||||
(`voice list`, `avatar list`) are intentionally left untagged.
|
||||
|
||||
## Telemetry
|
||||
|
||||
`resolve` and the edit tools (transcribe / transcript-cut / audio-duck) send an
|
||||
anonymous usage event to PostHog (`scripts/lib/telemetry.mjs`), so we can see
|
||||
which capabilities are actually used. It records only the media TYPE, the
|
||||
resolution SOURCE, and the winning PROVIDER: never the intent text, file names,
|
||||
or paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a
|
||||
resolve never waits on or fails from telemetry).
|
||||
|
||||
Opt out with `DO_NOT_TRACK=1` or `HYPERFRAMES_NO_TELEMETRY=1` (also off in CI and
|
||||
dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
|
||||
|
||||
## Privacy
|
||||
|
||||
media-use uses the same shared install id as the `hyperframes` CLI/studio
|
||||
(`~/.hyperframes/config.json`). When you are signed in to HeyGen, usage is
|
||||
linked to your account email, or username when email is unavailable, matching
|
||||
the CLI behavior. The events stay coarse: media type, source, provider, and
|
||||
small counts only; intent text and paths stay local. Disable telemetry with
|
||||
`HYPERFRAMES_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.
|
||||
Rules that keep this a help, not nagware: **grounded, not generic** (no signal → no suggestion); **opinionated + concrete** (propose the specific fix with defaults chosen — the human approves **all / some / none**); **once per project** (one consolidated ask; respect "leave it"); **surface, never silently mutate** (color grades especially: propose and preview — a gray-world "correction" ruins an intentional sunset or neon look).
|
||||
|
||||
## Where to look — read only the file your task needs
|
||||
|
||||
| Task | Read |
|
||||
| ------------------------------------------------------------------------- | ------------------------------- |
|
||||
| resolve / reuse / adopt / ingest, flags, cascade, inventory | `references/resolve.md` |
|
||||
| color grading, LUTs, smart grade (`--for`), grade-compare | `references/grading.md` |
|
||||
| voiceover / TTS, music, SFX, captions, transcription (audio engine) | `references/audio.md` |
|
||||
| cut / reframe / transform existing media, HEVC proxies, avatar video | `references/operations.md` |
|
||||
| install + auth, provider table, RAM ladders, `--local-only`, `--provider` | `references/setup-providers.md` |
|
||||
| remembered preferences + frozen recipes (user memory) | `references/memory.md` |
|
||||
| ownership matrix, usage stats, telemetry, privacy (maintainer-facing) | `references/meta.md` |
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Audio engine — voiceover, music, SFX, captions, transcription
|
||||
|
||||
For a full audio pass (TTS voiceover + background music + sound effects in one
|
||||
shot), use the shared engine at `audio/scripts/audio.mjs`. It takes a neutral
|
||||
`audio_request.json` and writes `audio_meta.json` plus assets under
|
||||
`.media/audio/{voice,bgm,sfx}`:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./audio_meta.json
|
||||
```
|
||||
|
||||
- **Request** `{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
|
||||
- **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
|
||||
- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `node <SKILL_DIR>/scripts/resolve.mjs --doctor` before assuming retrieval or TTS will work.
|
||||
- If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
|
||||
|
||||
Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).
|
||||
|
||||
Transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`).
|
||||
@@ -0,0 +1,77 @@
|
||||
# Color grading — grade blocks and LUTs
|
||||
|
||||
Use `grade` when you need the actual HyperFrames `data-color-grading` value to paste onto an `<img>` or `<video>`. Core presets and params-backed library looks resolve locally; future CDN-backed library looks require network unless already frozen:
|
||||
|
||||
**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
|
||||
```
|
||||
|
||||
Preset-first output uses the core runtime vocabulary and does not freeze a file:
|
||||
|
||||
```json
|
||||
{
|
||||
"preset": "warm-daylight",
|
||||
"intensity": 1
|
||||
}
|
||||
```
|
||||
|
||||
Paste it as an attribute value after JSON string escaping:
|
||||
|
||||
```html
|
||||
<video
|
||||
class="clip"
|
||||
src="./media/scene.mp4"
|
||||
data-color-grading='{"preset":"warm-daylight","intensity":1}'
|
||||
></video>
|
||||
```
|
||||
|
||||
Looks beyond the preset vocabulary freeze a validated `.cube` under `.media/luts/` and return a block that references it:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "teal orange blockbuster" --project . --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"intensity": 1,
|
||||
"lut": { "src": ".media/luts/grade_001.cube", "intensity": 0.85 }
|
||||
}
|
||||
```
|
||||
|
||||
Use `lut` when you only need the reusable `.cube` file:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
|
||||
```
|
||||
|
||||
For a describable technical look, author an explicit parametric LUT with `--params`:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --params '{"exposure":0.2}' --project . --json
|
||||
```
|
||||
|
||||
For a LUT generated by your own script, ingest it with `--from`; media-use validates it before registration and rejects invalid or oversized cubes:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --from custom.cube --project .
|
||||
```
|
||||
|
||||
Parametric math (`buildCube`) cannot reproduce real film stocks or emulsion looks. Use a CDN-backed scanned `.cube` entry or ingest a real scanned `.cube` for those.
|
||||
|
||||
For visual selection, list reusable looks with `resolve --type grade --candidates`, write the promising entries to a `grades.json`, run `hyperframes grade-compare --for <frame> --grades grades.json`, then commit the winner with `resolve -t grade` as the final `data-color-grading` block.
|
||||
|
||||
Smart grade is `grade --for <media>`. It runs local `ffmpeg`/`ffprobe` signalstats, merges a bounded `adjust` suggestion into the returned block, and prints the measured evidence to stderr. Stdout remains valid JSON under `--json`; the suggestion is a starting point for the agent to tune, not an automatic neutralization of intentional color.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm cinematic" --for ./frame.png --project . --json
|
||||
```
|
||||
|
||||
Library looks live in `luts/index.json`. Each entry keeps `id`, `description`, `tags`, and `intensity`, then supplies either compact `params` for on-demand `buildCube(params)` generation or a direct CDN `url` for future scanned `.cube` files. Do not commit generated `.cube` bodies; resolve validates generated or downloaded cubes as it freezes them under `.media/luts/`.
|
||||
|
||||
```bash
|
||||
node skills/media-use/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project . --json
|
||||
node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
|
||||
```
|
||||
@@ -0,0 +1,36 @@
|
||||
# User memory — preferences and recipes
|
||||
|
||||
## Preferences — remembered defaults
|
||||
|
||||
The lightweight tier of user memory: confirmed brief answers (destination, aspect, language, flow, storyboard, voice, style preset) persisted on the same two-tier split as assets — project `.media/preferences.json` (committed, the team inherits it) and personal `~/.media/preferences.json`. A value earns the personal tier by being confirmed in **two different projects**, so a one-off choice never pollutes the global defaults.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/prefs.mjs get --hyperframes . --json # merged view (project overrides user)
|
||||
node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --value x-feed
|
||||
node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow faceless-explainer
|
||||
```
|
||||
|
||||
Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes-core/references/brief-contract.md` § 2, Remembered defaults.
|
||||
|
||||
## Recipes — frozen video bundles
|
||||
|
||||
The heavyweight tier of user memory: one approved run frozen as a named, versioned bundle — `frame.md`, the storyboard skeleton (structure kept, content blanked to per-frame fill-ins), the brief skeleton (from `BRIEF.md` when the project has one — reusable frontmatter kept, run-shape and prose blanked), and the confirmed brief values. Same two tiers: project `.media/recipes/<name>/` (committed) and `~/.media/recipes/<name>/` (a freeze is already a confirmed bundle, so it promotes immediately — no two-project rule). Re-freezing a name bumps `version` and archives the old folder as `<name>@v<N>`.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo # workflow read from BRIEF.md (--workflow only for briefless projects)
|
||||
node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-launch-video
|
||||
node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo # also: resolve.mjs --type recipe --entity weekly-promo
|
||||
```
|
||||
|
||||
The freeze is offered once after the final approval (`hyperframes-core/references/review-loop.md` § 4), and the intent layer (`/hyperframes` → `references/intent-interview.md`, step 1) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
|
||||
|
||||
## Files
|
||||
|
||||
- `.media/manifest.jsonl`: machine SSOT, one JSON record per line
|
||||
- `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)
|
||||
- `.media/preferences.json`: the project's remembered defaults (committed)
|
||||
- `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)
|
||||
- `~/.media/preferences.json`: personal remembered defaults (promoted after two projects)
|
||||
- `.media/recipes/<name>/`: frozen video bundles — recipe.json + frame.md + storyboard skeleton (committed)
|
||||
- `~/.media/recipes/<name>/`: personal recipe tier (promoted on freeze)
|
||||
- `~/.media/misses.jsonl`: local-only resolve misses, including intent text for `--stats`
|
||||
@@ -0,0 +1,61 @@
|
||||
# Ownership matrix, usage stats, telemetry, privacy
|
||||
|
||||
Maintainer-facing reference. Nothing here changes how you resolve or operate on media.
|
||||
|
||||
## What it owns (the gaps HyperFrames leaves)
|
||||
|
||||
HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
|
||||
|
||||
| HyperFrames gap | media-use owns it via |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Audio-only, no image/icon | `resolve --type image\|icon` (heygen asset search) |
|
||||
| No third-party brand logos | `resolve --type logo` (svgl → simple-icons → GitHub org avatar → domain favicon) |
|
||||
| No voice / audio generation | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`) |
|
||||
| Scattered/duplicated audio engine | one consolidated engine under `audio/` (hyperframes-media retired) |
|
||||
| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs |
|
||||
| No transcript-driven cutting | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists |
|
||||
| No auto-duck / publish loudness | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes |
|
||||
| No cross-project memory | global content-addressed cache + auto-promote (`~/.media`) |
|
||||
| No color-grade authoring | `resolve --type grade` emits a paste-ready `data-color-grading` block; `resolve --type lut` freezes validated `.cube` files |
|
||||
| No image generation | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`) |
|
||||
| No video generation | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
|
||||
| Weak local-model defaults | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`) |
|
||||
|
||||
## Usage stats
|
||||
|
||||
Use `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --stats --project . --days 7
|
||||
# media-use stats
|
||||
# total resolves: 12
|
||||
# misses: 2
|
||||
# hit rate: 86%
|
||||
```
|
||||
|
||||
## Telemetry
|
||||
|
||||
`resolve` and the edit tools (transcribe / transcript-cut / audio-duck) send an
|
||||
anonymous usage event to PostHog (`scripts/lib/telemetry.mjs`), so we can see
|
||||
which capabilities are actually used. It records only the media TYPE, the
|
||||
resolution SOURCE, and the winning PROVIDER: never the intent text, file names,
|
||||
or paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a
|
||||
resolve never waits on or fails from telemetry).
|
||||
|
||||
Opt out with `DO_NOT_TRACK=1` or `HYPERFRAMES_NO_TELEMETRY=1` (also off in CI and
|
||||
dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
|
||||
|
||||
HeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog
|
||||
search) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced
|
||||
from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`)
|
||||
so a future call site can't silently ship untagged. Read-only discovery calls
|
||||
(`voice list`, `avatar list`) are intentionally left untagged.
|
||||
|
||||
## Privacy
|
||||
|
||||
media-use uses the same shared install id as the `hyperframes` CLI/studio
|
||||
(`~/.hyperframes/config.json`). When you are signed in to HeyGen, usage is
|
||||
linked to your account email, or username when email is unavailable, matching
|
||||
the CLI behavior. The events stay coarse: media type, source, provider, and
|
||||
small counts only; intent text and paths stay local. Disable telemetry with
|
||||
`HYPERFRAMES_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.
|
||||
@@ -280,3 +280,12 @@ reuse across many scripts, create a reusable **Photo Avatar** once instead
|
||||
(`heygen avatar create`). Ledger the result with
|
||||
`resolve --from <downloaded.mp4> --type video`. Docs:
|
||||
<https://developers.heygen.com/image-to-video>.
|
||||
|
||||
## HEVC / H.265 sources
|
||||
|
||||
HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
|
||||
input video) or for **preview** (auto-proxy transcodes and caches an H.264
|
||||
copy on first use, disable with `--no-proxy` or `media.autoProxy: false` in
|
||||
hyperframes.json). A manual H.264 proxy via `ffmpeg -i in.mp4 -c:v libx264
|
||||
-crf 18 proxy.mp4`, registered with `resolve --from`, remains available for
|
||||
edge cases (e.g. auto-proxy disabled, or ffmpeg unavailable at preview time).
|
||||
|
||||
@@ -0,0 +1,139 @@
|
||||
# Resolve — command, flags, reuse, adopt, inventory
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
|
||||
```
|
||||
|
||||
Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
|
||||
|
||||
## Types
|
||||
|
||||
| Type | What it finds | Provider / cascade |
|
||||
| ------- | -------------------------------- | ------------------------------------------------------------ |
|
||||
| `bgm` | Background music | HeyGen audio catalog (10k+ tracks) |
|
||||
| `sfx` | Sound effects | Bundled 19-file library + HeyGen catalog |
|
||||
| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors) |
|
||||
| `icon` | Icons, symbols | HeyGen asset search (type=icon) |
|
||||
| `logo` | Official brand marks | svgl → simple-icons → GitHub org avatar → domain favicon |
|
||||
| `voice` | TTS voiceover | HeyGen TTS free-usage path; optional local Kokoro |
|
||||
| `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |
|
||||
| `lut` | Reusable `.cube` LUT files | Look index params/CDN LUT → deterministic cube |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Background music
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
|
||||
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
|
||||
|
||||
# Sound effect
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
|
||||
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
|
||||
|
||||
# Image
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
|
||||
# → resolved image_001 → .media/images/image_001.jpg (image)
|
||||
|
||||
# Icon
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
|
||||
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
|
||||
|
||||
# Brand logo (official mark — never redrawn by hand)
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project .
|
||||
# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)
|
||||
|
||||
# Color grade block
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type grade --intent "warm daylight" --project . --json
|
||||
# → {"ok":true,"preset":"warm-daylight","grading":{"preset":"warm-daylight","intensity":1},...}
|
||||
|
||||
# LUT file
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuster" --project .
|
||||
# → resolved lut_001 → .media/luts/lut_001.cube (lut)
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Description |
|
||||
| --------------- | ------------------------------------------------------------------------------------ |
|
||||
| `--type, -t` | Media type: bgm, sfx, image, icon, logo, voice, grade, lut |
|
||||
| `--intent, -i` | What you need (natural language) |
|
||||
| `--entity, -e` | Entity name for cache matching (optional) |
|
||||
| `--project, -p` | Project directory (default: .) |
|
||||
| `--candidates` | List reusable assets (project + global cache) for `--type`; no download, no mutation |
|
||||
| `--reuse <sha>` | Import a specific global-cache asset (by content sha/prefix, from `--candidates`) |
|
||||
| `--from` | Freeze a local file or direct public URL (ingest) |
|
||||
| `--for` | Analyze a local image/video and add measured adjust suggestions (`grade` only) |
|
||||
| `--local-only` | Offline: skip every network provider (cache + local only) |
|
||||
| `--provider` | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`) |
|
||||
| `--adopt` | Bulk-import existing assets/ into manifest |
|
||||
| `--doctor` | Check local CLI dependencies; no manifest changes |
|
||||
| `--stats` | Print local usage stats from `.media/` and `~/.media`; no manifest changes |
|
||||
| `--days N` | Limit `--stats` to timestamped records/misses from the last N days |
|
||||
| `--json` | Output JSON instead of one-line result |
|
||||
|
||||
## Reuse before you resolve
|
||||
|
||||
Before resolving bgm/sfx/image/icon/logo/grade/lut, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --candidates --project .
|
||||
# [project] upbeat tech launch (25s, heygen.audio.sounds)
|
||||
# .media/audio/bgm/bgm_001.wav
|
||||
# [global] energetic tech intro (22s, heygen.audio.sounds)
|
||||
# --reuse 06e052c075fd2b80
|
||||
```
|
||||
|
||||
Read the list and judge semantic fit yourself — "upbeat tech launch" ≈ "energetic tech intro" is a call only you can make from the descriptions. Then:
|
||||
|
||||
- **A project candidate fits** → just reference its path in your composition. Nothing else to run.
|
||||
- **A global candidate fits** → `resolve --type bgm --reuse <sha>` copies it into this project (self-contained render) and records it.
|
||||
- **Nothing fits** → resolve fresh (`--type ... --intent ...`).
|
||||
|
||||
**Trust guardrail — when unsure, resolve fresh.** A redundant download is cheap; shipping the wrong asset is not. Judge fit from description + prompt + type + duration/dims. For **brand/entity** assets, reuse a _global_ candidate only when the entity matches exactly — the global cache aggregates every project you have worked on, so a `--candidates` list can surface another client's brand mark and its prompt text. Never reuse a cross-project brand asset on a loose match.
|
||||
|
||||
The deterministic floor still runs automatically: an identical (case/whitespace-insensitive) repeat auto-reuses with no `--candidates` step. `--candidates` is only for the semantic layer above that floor — and a fuzzy match is **never** auto-applied; reuse is always your explicit call. On a resolve that misses the floor and is about to fetch, media-use prints a one-line stderr hint when similar cached assets exist, pointing you back here.
|
||||
|
||||
## How it works
|
||||
|
||||
`resolve` runs an automatic floor, then falls through to fetching:
|
||||
|
||||
1. Check project `.media/manifest.jsonl` for a prompt match (case- and whitespace-insensitive) — auto-reuse
|
||||
2. Scan existing `assets/` directory for unregistered files that share a word with the need
|
||||
3. Check global cache `~/.media/` for a reusable asset matched on the same normalized prompt — auto-reuse
|
||||
4. Search via provider (HeyGen audio catalog, HeyGen asset search), or resolve color locally
|
||||
5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`, auto-promote to `~/.media/`
|
||||
|
||||
Steps 1 and 3 are the **deterministic floor**: they only auto-reuse an exact-normalized match, never a fuzzy one. Semantic reuse ("close enough") is the agent's explicit call via [Reuse before you resolve](#reuse-before-you-resolve) — it never happens automatically. The agent gets back **one line**; candidates, scores, provenance stay on disk.
|
||||
|
||||
## Adopt existing projects
|
||||
|
||||
Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
|
||||
# → adopted 9 assets from assets/
|
||||
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
|
||||
# image_001 → assets/images/avatar.jpg (image, 400×400)
|
||||
```
|
||||
|
||||
`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
|
||||
|
||||
## Reading the inventory
|
||||
|
||||
After resolve or adopt, read `.media/index.md` for the full inventory:
|
||||
|
||||
```
|
||||
# .media · 4 assets
|
||||
|
||||
id type dur dims path description
|
||||
bgm_001 bgm 25s - .media/audio/bgm/bgm_001.mp3 upbeat tech launch
|
||||
sfx_001 sfx 0.6s - .media/audio/sfx/sfx_001.mp3 whoosh
|
||||
image_001 image - 1920×1080 .media/images/image_001.jpg gradient tech background
|
||||
icon_001 icon - 200×200 .media/images/icon_001.png rocket
|
||||
```
|
||||
|
||||
## Cross-project reuse
|
||||
|
||||
Assets are cached automatically on resolve. Every resolved/ingested asset is auto-promoted to the global cache at `~/.media/`, so subsequent resolves for the same (or near-identical) prompt, in any project, hit the cache with no re-download and no provider call.
|
||||
|
||||
For a _semantically_ similar (not identical) need in another project, the exact-match floor won't fire — use [Reuse before you resolve](#reuse-before-you-resolve): `--candidates` lists the global assets, and `--reuse <sha>` imports the one you pick. This is how a track resolved in one project gets reused in the next when the wording differs.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Setup and providers — install, auth, RAM ladders, forcing a provider
|
||||
|
||||
## Setup — install heygen first (free-usage path)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
|
||||
heygen update # free usage needs the OAuth-capable CLI (v0.3.0+)
|
||||
heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
|
||||
```
|
||||
|
||||
This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/resolve.mjs --doctor
|
||||
```
|
||||
|
||||
## Providers
|
||||
|
||||
media-use holds no keys; every external tool owns its auth. Generation is
|
||||
centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
|
||||
before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
|
||||
alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
|
||||
transcription, and LTX for local video generation. `resolve` spec-checks
|
||||
AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
|
||||
see the ladder and override.
|
||||
|
||||
| Type | Provider / path |
|
||||
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| bgm/sfx | heygen catalog free-usage path |
|
||||
| image | heygen search free-usage path; optional local mflux; codex `image_gen` upsell |
|
||||
| voice | heygen tts free-usage path; optional local **Kokoro** (free, on-device) |
|
||||
| icon | heygen asset search free-usage path |
|
||||
| logo | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free) |
|
||||
| grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback |
|
||||
| video | heygen avatar video free-usage path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
|
||||
|
||||
Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
|
||||
private, offline once cached). The `codex` CLI remains the ChatGPT-sub image
|
||||
upsell. Cost rule (X4): the agent confirms before an agent-initiated paid call;
|
||||
a user-requested one just runs — `heygen.video` is flagged paid (metered free
|
||||
allowance) so an agent-initiated `resolve --type video` confirms first.
|
||||
|
||||
To force a specific generator (e.g. a user says "make this image with codex"),
|
||||
pass `--provider codex`: it pins resolution to that provider and skips the
|
||||
free-usage default. See `references/operations.md` for the RAM ladders and
|
||||
provider recipes.
|
||||
|
||||
`--local-only` skips every network provider, including the free HeyGen ones,
|
||||
leaving the project + global cache and any installed local provider. For
|
||||
HeyGen-only types, that means no fresh resolve.
|
||||
|
||||
## CLI tools used (what to run, and how to enable each)
|
||||
|
||||
`resolve` auto-cascades; each provider shells one CLI. HeyGen is the
|
||||
free-usage path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar
|
||||
video, so those capabilities need `heygen` installed and authenticated. Local
|
||||
tools are OPT-IN alternatives where they exist; install one to unlock its free,
|
||||
private, on-device path instead of or ahead of HeyGen for that type. Only
|
||||
`ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
|
||||
|
||||
| Tool | Serves | Install |
|
||||
| ------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |
|
||||
| `heygen` | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | `curl -fsSL https://static.heygen.ai/cli/install.sh \| bash` then `heygen auth login --oauth` (needs >= v0.3.0) |
|
||||
| `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |
|
||||
| `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |
|
||||
| `parakeet-mlx` | local transcription (default ASR, best) | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |
|
||||
| `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |
|
||||
| `npx hyperframes` | Kokoro TTS (voice), whisper.cpp (transcribe fallback), remove-background | via the hyperframes CLI; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake), models download from HuggingFace |
|
||||
|
||||
The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
|
||||
`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
|
||||
to see which model fits this machine). Without a tool on PATH, its provider
|
||||
prints a one-line diagnostic to stderr and resolve falls through where another
|
||||
provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
|
||||
|
||||
`heygen asset search` is a pre-launch command hidden from `heygen --help`, but it
|
||||
runs; providers tag requests with the allowlisted `X-HeyGen-Client-Source` header
|
||||
(v0.3.0+).
|
||||
@@ -7,7 +7,7 @@ import { listTypes, getProviders } from "./registry.mjs";
|
||||
import { CAPABILITIES, listModels } from "./local-models.mjs";
|
||||
|
||||
// Capstone: media-use must actually OWN each hyperframes media weakness. This
|
||||
// test enforces the weakness→owner matrix in SKILL.md so a claim can't rot — if
|
||||
// test enforces the weakness→owner matrix in references/meta.md so a claim can't rot — if
|
||||
// a capability's entrypoint disappears, this fails.
|
||||
|
||||
const SKILL = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
|
||||
|
||||
@@ -1033,7 +1033,7 @@ function runDoctor() {
|
||||
fix: nodeOk ? "" : `upgrade Node to >= v${MIN_NODE_VERSION}`,
|
||||
});
|
||||
|
||||
// ffmpeg AND ffprobe are both strictly required (see SKILL.md); the exit code
|
||||
// ffmpeg AND ffprobe are both strictly required (see references/setup-providers.md); the exit code
|
||||
// must reflect that so a script gating on `--doctor` doesn't pass with ffprobe
|
||||
// missing and then break at the first probe call.
|
||||
const ffmpeg = checks.find((check) => check.name === "ffmpeg on PATH");
|
||||
|
||||
@@ -19,7 +19,7 @@ description: >
|
||||
|
||||
> **The front door is `/hyperframes`.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). Anything longer, narrated, or multi-scene — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
|
||||
|
||||
This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review. The intent layer (`/hyperframes` § 4) routes here directly without run-shape questions; a storyboard and companion session add little to a piece this short. Rendering is still user-gated: after checks and proof snapshots pass, ask the canonical “preview first, or render?” question from `../hyperframes-core/references/brief-contract.md`. When a `BRIEF.md` exists, read it before the director's question.
|
||||
This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review. The intent layer (`/hyperframes` → `references/intent-interview.md`) routes here directly without run-shape questions; a storyboard and companion session add little to a piece this short. Rendering is still user-gated: after checks and proof snapshots pass, ask the canonical “preview first, or render?” question from `../hyperframes-core/references/brief-contract.md`. When a `BRIEF.md` exists, read it before the director's question.
|
||||
|
||||
A short design-led motion graphic. **Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities. All artifacts go to `PROJECT_DIR = videos/<project-name>/` (created in Step 0); all paths below are relative to it.
|
||||
|
||||
|
||||
@@ -26,14 +26,14 @@ Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze
|
||||
|
||||
Goal: Establish the music source, create the HyperFrames project, and note any user-supplied media.
|
||||
|
||||
**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (§ 4): it confirms this route's must-haves (the music source, destination → aspect — `route-briefs.md` § /music-to-video) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.
|
||||
**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it confirms this route's must-haves (the music source, destination → aspect — `../hyperframes/references/routes/music-to-video.md`) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.
|
||||
|
||||
The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`references/bgm.md`). Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply one branch:
|
||||
|
||||
- **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider.
|
||||
- **Autonomous:** state the status and continue through the available local provider.
|
||||
|
||||
If no offline provider can satisfy the required music capability, surface the blocker. Never write keys into a per-repo `.env`. Auth ownership and offline fallbacks live in `/media-use` § Providers. The resulting track lands at `assets/bgm.mp3`. Stage supplied images or videos so frames can use them on the beat grid; otherwise typography carries the video.
|
||||
If no offline provider can satisfy the required music capability, surface the blocker. Never write keys into a per-repo `.env`. Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers. The resulting track lands at `assets/bgm.mp3`. Stage supplied images or videos so frames can use them on the beat grid; otherwise typography carries the video.
|
||||
|
||||
**Lyric videos:** for lyrics synced to the vocals, get word/line timing by transcribing the track via `/media-use`, or ask the user for the lyrics text and place lines on the beat grid.
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extrac
|
||||
|
||||
Goal: Enter with a confirmed brief — including the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo) — create the HyperFrames project, and make the brief durable. The style is always **claude** (fixed at Step 2, never asked).
|
||||
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (§ 4): it checks recipes and remembered defaults, and conducts this route's questions — including the PR-size → length doctrine, which lives whole in `../hyperframes/references/route-briefs.md` § /pr-to-video — then hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it checks recipes and remembered defaults, and conducts this route's questions — including the PR-size → length doctrine, which lives whole in `../hyperframes/references/routes/pr-to-video.md` — then hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
|
||||
Resolve the project directory before doing any other work. Preserve a user-supplied project directory; otherwise use the durable external cache location printed by the resolver. Never create `videos/` in the caller repository:
|
||||
|
||||
@@ -53,7 +53,7 @@ Every relative-path command below runs with `$PROJECT_DIR` as its working direct
|
||||
- **Collaborative:** wait for the user to sign in or explicitly choose `offline` / `go`.
|
||||
- **Autonomous:** state the status and continue through the available local engines.
|
||||
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` § Providers.
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` `references/setup-providers.md` § Providers.
|
||||
|
||||
**Gate:** `hyperframes.json` and `BRIEF.md` exist; the PR ref is captured in the brief; the preference-backed answers were recorded (brief contract § 2); sign-in status was shown (signed in, or continuing offline).
|
||||
|
||||
@@ -111,7 +111,7 @@ The script copies the claude preset's `FRAME.md` → `frame.md`, remixes it onto
|
||||
|
||||
Goal: Turn the PR into an approved frame-by-frame explanation plan.
|
||||
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.
|
||||
|
||||
Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except the `credits` close (1–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.
|
||||
|
||||
@@ -175,17 +175,17 @@ Duration sync is mechanical: real voice duration wins; silent frames keep estima
|
||||
|
||||
`for b in <each registry block named in the storyboard>; do npx hyperframes add "$b"; done`
|
||||
|
||||
Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Build bounded packets:
|
||||
Before dispatch, read `../hyperframes-core/references/subagent-dispatch.md`. Build bounded packets and the worker role payload:
|
||||
|
||||
```bash
|
||||
node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"
|
||||
```
|
||||
|
||||
The packet builder hard-fails a code frame without the upstream-selected `### Source excerpt`, and hard-caps packet bytes. Dispatch **at most three workers total**, balanced across the packet paths; each worker may build multiple assigned frames sequentially and reads shared instructions once. Workers read only their packet(s) and `frame.md`. They never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`. Each worker writes only its assigned `compositions/frames/NN-*.html`; workers never edit `STORYBOARD.md`. When a frame has a **confirmed sketch** on disk (collaborative runs — review loop § 3), say so in that worker's dispatch context: the sketch is the existing `compositions/frames/NN-*.html`, and the worker dresses that layout rather than redrawing it (frame-worker § When a confirmed sketch exists).
|
||||
The packet builder hard-fails a code frame without the upstream-selected `### Source excerpt`, and hard-caps packet bytes. It also writes `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch **at most three workers total**, balanced across the packet paths; each worker's prompt carries `_role.md` and its assigned packet paths — paste the role in full or hand its path (equivalent; the worker starts from exactly those documents) — and each worker may build multiple assigned frames sequentially, reading the role once. Workers read only their packet(s) and `frame.md`. They never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`. Each worker writes only its assigned `compositions/frames/NN-*.html`; workers never edit `STORYBOARD.md`. When a frame has a **confirmed sketch** on disk (collaborative runs — review loop § 3), say so in that worker's dispatch context: the sketch is the existing `compositions/frames/NN-*.html`, and the worker dresses that layout rather than redrawing it (frame-worker core § When a confirmed sketch exists).
|
||||
|
||||
On a failed frame, re-dispatch **that frame only**, with its existing packet plus the exact validator/lint finding. One retry maximum. Do not replay a whole batch and do not retry without a concrete finding.
|
||||
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes-core/references/frame-worker-core.md`.)
|
||||
|
||||
As each worker returns, mark that frame `animated` in `STORYBOARD.md`.
|
||||
|
||||
@@ -263,6 +263,7 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue
|
||||
| `[references/motion-language.md](references/motion-language.md)` | Step 4: the motion vocabulary + the motion doctrine. |
|
||||
| `[references/cut-catalog.md](references/cut-catalog.md)` | Step 4-5: the cut catalog (worker builds within-frame seams). |
|
||||
| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions. |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: dispatch per-frame workers. |
|
||||
| `[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md)` | Step 5: the shared worker contract (packet builder prepends it to the delta). |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: the workflow's frame-worker delta. |
|
||||
| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)` | Step 5: dispatch sub-agents safely. |
|
||||
| `[../hyperframes-creative/frame-presets/claude/FRAME.md](../hyperframes-creative/frame-presets/claude/FRAME.md)` | Step 2: the claude preset (fixed style). |
|
||||
|
||||
@@ -324,6 +324,33 @@ for (const m of mounted) {
|
||||
acc += m.durationSeconds;
|
||||
}
|
||||
const TOTAL = r3(acc);
|
||||
|
||||
// ---------- duration expectation (advisory) ----------
|
||||
// Frontmatter `duration:` carries the brief's rough length expectation
|
||||
// (storyboard-format.md § Frontmatter). Never blocks the build: report where
|
||||
// the cut lands, and flag a large gap so the agent judges whether the drift
|
||||
// serves the piece.
|
||||
let durationNote = "";
|
||||
const rawTarget = manifest.globals.extra?.duration;
|
||||
if (rawTarget != null && String(rawTarget).trim() !== "") {
|
||||
const targetMatch = String(rawTarget).match(/(\d+(?:\.\d+)?)/);
|
||||
const target = targetMatch ? parseFloat(targetMatch[1]) : NaN;
|
||||
if (!Number.isFinite(target) || target <= 0) {
|
||||
anomalies.push(
|
||||
`frontmatter duration "${rawTarget}" is not parseable (e.g. "22s") — skipped the expectation check`,
|
||||
);
|
||||
} else {
|
||||
const diff = r3(TOTAL - target);
|
||||
durationNote = ` (expected ~${target}s, ${diff >= 0 ? "+" : ""}${diff}s)`;
|
||||
const pct = Math.abs((diff / target) * 100);
|
||||
if (pct > 10) {
|
||||
anomalies.push(
|
||||
`total ${TOTAL}s lands ${Math.round(pct)}% ${diff > 0 ? "over" : "under"} the brief's ~${target}s expectation — ` +
|
||||
`judge whether the drift serves the piece (pacing, narration fit); re-pace, or update \`duration:\` if the new length is intended`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
const startOfFrameNumber = new Map();
|
||||
for (const m of mounted) if (m.frame.number != null) startOfFrameNumber.set(m.frame.number, m);
|
||||
|
||||
@@ -568,7 +595,7 @@ console.log(` bgm (track 11): ${bgmEmitted ? "yes" + bgmNote : "no"}`);
|
||||
console.log(` captions (track 2): ${captionsEmitted ? "yes" : "no"}`);
|
||||
console.log(` sfx (track 20+): ${sfxEmitted}`);
|
||||
console.log(` assets staged: ${staged}/${wanted.size}`);
|
||||
console.log(` total duration: ${TOTAL}s`);
|
||||
console.log(` total duration: ${TOTAL}s${durationNote}`);
|
||||
if (repairs.length) {
|
||||
console.log(`\nrepaired (frame files updated in place):`);
|
||||
for (const rp of repairs) console.log(` - ${rp}`);
|
||||
|
||||
@@ -1,48 +1,32 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { basename, dirname, join, resolve } from "node:path";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
// Thin wrapper over the shared packet builder in hyperframes-core — this file pins
|
||||
// this workflow's paths plus its two behavioral differences: a code frame must carry
|
||||
// an upstream-selected `### Source excerpt`, and code frames get a code-vocabulary
|
||||
// excerpt appended to their packet. Everything else has one owner:
|
||||
// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
|
||||
|
||||
const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
|
||||
const SKILL_DIR = resolve(SCRIPT_DIR, "..");
|
||||
const ANIMATION_DIR = resolve(SKILL_DIR, "../hyperframes-animation");
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { dirname, join, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
|
||||
|
||||
function field(block, name) {
|
||||
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
|
||||
return match?.[1]?.trim() ?? null;
|
||||
}
|
||||
|
||||
function splitFrames(storyboard) {
|
||||
const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
|
||||
return matches.map((match, index) => {
|
||||
const start = match.index;
|
||||
const end = matches[index + 1]?.index ?? storyboard.length;
|
||||
return {
|
||||
heading: match[1].trim(),
|
||||
block: storyboard.slice(start, end).trim(),
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
function frameId(frame) {
|
||||
const src = field(frame.block, "src");
|
||||
if (!src) throw new Error(`${frame.heading}: missing src`);
|
||||
return basename(src).replace(/\.html?$/i, "");
|
||||
}
|
||||
const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
|
||||
function sourceExcerpt(block) {
|
||||
const match = block.match(/^### Source excerpt\s*\n+(```[^\n]*\n[\s\S]*?\n```)/im);
|
||||
return match?.[1] ?? null;
|
||||
}
|
||||
|
||||
function selectedFile(path, heading) {
|
||||
if (!path || !existsSync(path)) return "";
|
||||
return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
|
||||
function validateFrame(frame) {
|
||||
const codeFrame = /\bcode-[a-z0-9-]+\b/i.test(core.field(frame.block, "focal") ?? "");
|
||||
if (codeFrame && !sourceExcerpt(frame.block)) {
|
||||
throw new Error(`${frame.heading}: code frame requires an upstream-selected Source excerpt`);
|
||||
}
|
||||
}
|
||||
|
||||
function codeVocabularySection(block) {
|
||||
const focal = field(block, "focal") ?? "";
|
||||
const focal = core.field(block, "focal") ?? "";
|
||||
const codeId = focal.match(/\b(code-[a-z0-9-]+)\b/i)?.[1];
|
||||
if (!codeId) return "";
|
||||
const vocabPath = join(SKILL_DIR, "references", "code-vocabulary.md");
|
||||
@@ -59,84 +43,20 @@ function codeVocabularySection(block) {
|
||||
return `\n## Code block excerpt (${codeId})\n\n${matchingLines.join("\n").trim()}\n`;
|
||||
}
|
||||
|
||||
function resourceSections(block) {
|
||||
let sections = "";
|
||||
const blueprint = field(block, "blueprint");
|
||||
if (blueprint && blueprint.toLowerCase() !== "compose") {
|
||||
sections += selectedFile(
|
||||
join(ANIMATION_DIR, "blueprints", `${blueprint}.md`),
|
||||
`Selected blueprint: ${blueprint}`,
|
||||
);
|
||||
}
|
||||
const rules = (field(block, "rules") ?? "")
|
||||
.split(/[,\s]+/)
|
||||
.map((rule) => rule.trim())
|
||||
.filter(Boolean);
|
||||
for (const rule of rules) {
|
||||
sections += selectedFile(
|
||||
join(ANIMATION_DIR, "rules", `${rule}.md`),
|
||||
`Selected motion rule: ${rule}`,
|
||||
);
|
||||
}
|
||||
return sections;
|
||||
const CONFIG = {
|
||||
animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
|
||||
corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
|
||||
deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
|
||||
validateFrame,
|
||||
extraSections: codeVocabularySection,
|
||||
};
|
||||
|
||||
export function buildRolePayload({ outDir }) {
|
||||
return core.buildRolePayload({ ...CONFIG, outDir });
|
||||
}
|
||||
|
||||
const COMPACT_CONTRACT = `- Output exactly one bare \`<template>…</template>\` fragment; never emit DOCTYPE, html, head, or body.
|
||||
- The first composition root must carry the exact frame id, positive duration, width, and height.
|
||||
- Register exactly one paused GSAP timeline under the exact frame id.
|
||||
- Write only the requested frame file. Do not read the full PR diff or the full storyboard.`;
|
||||
|
||||
export function buildFramePackets({
|
||||
projectDir,
|
||||
storyboardPath = join(projectDir, "STORYBOARD.md"),
|
||||
outDir = join(projectDir, ".hyperframes", "frame-packets"),
|
||||
maxPacketBytes = 48_000,
|
||||
}) {
|
||||
const storyboard = readFileSync(storyboardPath, "utf8");
|
||||
const frames = splitFrames(storyboard);
|
||||
if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
|
||||
|
||||
const packets = frames.map((frame) => {
|
||||
const id = frameId(frame);
|
||||
const codeFrame = /\bcode-[a-z0-9-]+\b/i.test(field(frame.block, "focal") ?? "");
|
||||
const excerpt = sourceExcerpt(frame.block);
|
||||
if (codeFrame && !excerpt) {
|
||||
throw new Error(`${frame.heading}: code frame requires an upstream-selected Source excerpt`);
|
||||
}
|
||||
const packet = `# Frame packet: ${id}\n\n## Structural contract\n\n${COMPACT_CONTRACT}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n- Design tokens: ${join(resolve(projectDir), "frame.md")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block)}${codeVocabularySection(frame.block)}`;
|
||||
const bytes = Buffer.byteLength(packet);
|
||||
if (bytes > maxPacketBytes) {
|
||||
throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
|
||||
}
|
||||
return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
|
||||
});
|
||||
|
||||
mkdirSync(outDir, { recursive: true });
|
||||
for (const { path, packet } of packets) writeFileSync(path, packet);
|
||||
return packets.map(({ packet: _packet, ...result }) => result);
|
||||
export function buildFramePackets(options) {
|
||||
return core.buildFramePackets({ ...CONFIG, ...options });
|
||||
}
|
||||
|
||||
function flag(argv, name, fallback) {
|
||||
const index = argv.indexOf(`--${name}`);
|
||||
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
|
||||
}
|
||||
|
||||
function main() {
|
||||
const argv = process.argv.slice(2);
|
||||
const projectDir = resolve(flag(argv, "project", "."));
|
||||
try {
|
||||
const packets = buildFramePackets({
|
||||
projectDir,
|
||||
storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
|
||||
outDir: resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets"))),
|
||||
});
|
||||
console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
|
||||
for (const packet of packets)
|
||||
console.log(` ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
|
||||
} catch (error) {
|
||||
console.error(`✗ frame packets: ${error.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
if (pathToFileURL(process.argv[1] ?? "").href === import.meta.url) main();
|
||||
if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { realpathSync } from "node:fs";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
export function hasCliCommand(helpText, command) {
|
||||
@@ -35,4 +36,16 @@ function main() {
|
||||
}
|
||||
}
|
||||
|
||||
if (pathToFileURL(process.argv[1] ?? "").href === import.meta.url) main();
|
||||
// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
|
||||
// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
|
||||
// a raw compare silently skips main() when invoked through any symlinked path.
|
||||
function isMainModule() {
|
||||
if (!process.argv[1]) return false;
|
||||
try {
|
||||
return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
if (isMainModule()) main();
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
import { homedir } from "node:os";
|
||||
import { join, resolve } from "node:path";
|
||||
import { realpathSync } from "node:fs";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
function safeSegment(value) {
|
||||
@@ -76,4 +77,16 @@ function main() {
|
||||
}
|
||||
}
|
||||
|
||||
if (pathToFileURL(process.argv[1] ?? "").href === import.meta.url) main();
|
||||
// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
|
||||
// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
|
||||
// a raw compare silently skips main() when invoked through any symlinked path.
|
||||
function isMainModule() {
|
||||
if (!process.argv[1]) return false;
|
||||
try {
|
||||
return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
if (isMainModule()) main();
|
||||
|
||||
@@ -100,6 +100,10 @@ test("#1092 packets contain selected excerpts but never the full diff", () => {
|
||||
assert.doesNotMatch(codePacket, /code-scroll/);
|
||||
assert.ok(Buffer.byteLength(codePacket) < 32_000);
|
||||
assert.ok(result.every((packet) => packet.path.endsWith(".md")));
|
||||
|
||||
const role = readFileSync(join(project, ".hyperframes", "frame-packets", "_role.md"), "utf8");
|
||||
assert.match(role, /# Frame worker — core contract/);
|
||||
assert.match(role, /# Frame worker — PR-to-video delta/);
|
||||
});
|
||||
|
||||
test("packet validation is atomic and leaves no partial output on overflow", () => {
|
||||
|
||||
@@ -1,36 +1,16 @@
|
||||
# Frame worker — PR-to-video per-frame composition author
|
||||
# Frame worker — PR-to-video delta
|
||||
|
||||
> You build the small batch of frame composition files assigned to you and nothing else. At most three workers run; each reads shared context once, then builds its packet paths sequentially. The **structural composition contract** is compacted into each packet. This file carries only what's specific to a PR-to-video frame.
|
||||
> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a PR-to-video frame.
|
||||
|
||||
**INPUT** — your dispatch context provides `PROJECT_DIR` plus one or more bounded packet paths under `.hyperframes/frame-packets/`. Read shared `frame.md` once, then process the packets in order. Never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`; the orchestrator already selected the exact source excerpt and put it in each code frame's packet.
|
||||
## Batch dispatch — you build a small packet batch
|
||||
|
||||
Each packet provides:
|
||||
At most three workers run; your dispatch assigns **one or more** bounded packet paths under `.hyperframes/frame-packets/`. Read this role and shared `frame.md` **once**, then process the packets in order — for each, use its exact frame block, inlined blueprint / rule excerpts, and (for a code beat) the selected code-block / source excerpts. Never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`; the orchestrator already selected the exact source excerpt and put it in each code frame's packet. After the last assigned file passes the self-check, stop.
|
||||
|
||||
- `PROJECT_DIR` — the project root; all paths are relative to it.
|
||||
- `frame_id` — e.g. `04-the-fix`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/04-the-fix.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
|
||||
- Your exact **`## Frame N` block** (already extracted from `STORYBOARD.md`; never write to that file — see below):
|
||||
- `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
|
||||
- `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
|
||||
- `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
|
||||
- `transition_in` — informational. The injector stamps it at the root; **you do not author transitions.**
|
||||
- the **time-coded shot sequence** — your build spec. A sequence of Scene lines (`Scene 1 (0.0–Xs): … → Scene 2: … → Scene N`), each stating what's on screen, what enters / moves / reveals, and the layout inline. Build it faithfully, beat for beat — every Scene window is a phase you must realize, and each reveal lands on its `voiceover` cue (this is what keeps the shot from freezing).
|
||||
- `blueprint:` — an id (or the literal `compose`). The id points to `../hyperframes-animation/blueprints/<id>.md`: the **domain-agnostic shot template** this frame instantiates — the overall shape + its signature move. Read it for the shape; `compose` means there's no template (common for a code beat — the `code-*` block is the shape), sequence the shot from the Scene lines directly.
|
||||
- `focal:` — for a concept/mechanism beat, which **invented** element is the hero; for a **code beat**, the named **`code-*` block** (+ the hunk); for the **credits** close, the avatar row.
|
||||
- `roles:` — each element's role: `foreground subject` / `background` full-bleed / `supporting`. Most are invented elements you design; the only real assets are the credits `assets/<login>.png` avatars.
|
||||
- `sfx:` — the orchestrator's; you mount no audio.
|
||||
- `frame.md` (project root) — the **design-truth**: palette (claude), type ramp, components, composition rules. The LOOK. Pull every visual token from here.
|
||||
- `RULES_DIR` — absolute path to this skill's local `../hyperframes-animation/rules/`. The **named motion verbs in the Scene lines** (and the moves the blueprint cites) resolve to rule recipes here: `RULES_DIR/<id>.md` is the mechanics for a motion. The blueprint templates are the sibling `../hyperframes-animation/blueprints/<id>.md`; an optional runnable demo is `../hyperframes-animation/examples/<id>.html`.
|
||||
- `code-vocabulary.md` — absolute path provided in your dispatch. For a **code beat**, read it for the named `code-*` block's exact inputs (`window.__TOKENS`, `window.__BLOCK`, line indexing).
|
||||
- `../references/cut-catalog.md` — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall) for a within-frame seam. You never author the between-frame transition — story's `transition_in` + the injector own that.
|
||||
- Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
|
||||
Extra inputs beyond the core contract:
|
||||
|
||||
**Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
|
||||
|
||||
**OUTPUT** — one `compositions/frames/<frame_id>.html` per assigned packet, each a bare template fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. After the last assigned file passes the self-check, stop — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator validates the files before assembly and marks their `status`.
|
||||
|
||||
## When a confirmed sketch exists
|
||||
|
||||
In collaborative runs the orchestrator wireframes the board first, so your target file may already exist as the frame's **user-confirmed wireframe** — your dispatch says whether it does (a file found on a retry is your own prior output, not a sketch). Read it first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the `code-*` block where the sketch held plain code, the finished invented visuals where it used plain blocks, and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed.
|
||||
- `code-vocabulary.md` — absolute path provided in your dispatch. For a **code beat**, read it for the named `code-*` block's exact inputs (`window.__TOKENS`, `window.__BLOCK`, line indexing); your packet carries the matching excerpt.
|
||||
- `focal:` — for a concept/mechanism beat, which **invented** element is the hero; for a **code beat**, the named **`code-*` block** (+ the hunk); for the **credits** close, the avatar row.
|
||||
- `roles:` — each element's role: `foreground subject` / `background` full-bleed / `supporting`. Most are invented elements you design; the only real assets are the credits `assets/<login>.png` avatars.
|
||||
|
||||
## Mostly invented — you build the visual (except code blocks + the credits avatars)
|
||||
|
||||
@@ -38,64 +18,21 @@ A PR video is **mostly invented**: there are **no screenshots and no captured UI
|
||||
|
||||
## PR code beats, mechanism beats + the credits close
|
||||
|
||||
- **Code beats (`diff` / `before_after` / a new-code reveal) — use the named `code-*` block, don't hand-build code motion.** Your `## Frame N` `scene` / `focal` names which block (e.g. `code-diff`, `code-morph`, `code-typing`); the orchestrator has already installed it (Step 5 pre-install). Read **`code-vocabulary.md`** (path in your dispatch) for that block's exact inputs, then:
|
||||
- **Code beats (`diff` / `before_after` / a new-code reveal) — use the named `code-*` block, don't hand-build code motion.** Your `## Frame N` `scene` / `focal` names which block (e.g. `code-diff`, `code-morph`, `code-typing`); the orchestrator has already installed it (pre-install step). Read the `code-vocabulary.md` excerpt in your packet for that block's exact inputs, then:
|
||||
- Use only the packet's `### Source excerpt`. It is the real before/after hunk selected upstream. Never reopen the full diff or brief.
|
||||
- Fill the block's `window.__TOKENS` with that real code (the baked Shiki tokens) and set `window.__BLOCK` (effect, `line`, `duration`) **so the full block completes within the frame's `data-duration`** — a long snippet at the block's default per-character cadence overruns a short frame (the code never finishes typing). `code-diff` / `code-morph` need **2 states** (before, after); the others take one. **Line indexing differs — `code-highlight` is 0-based, `code-scroll` 1-based** — don't off-by-one.
|
||||
- Integrate the filled block as **this frame's composition** per `hyperframes-core`'s sub-composition contract: its `data-composition-id` and its `window.__timelines[...]` key must both be your **`<frame_id>`** (the block ships its own id + paused timeline; rename both to match the frame contract). The block already renders an editor window (titlebar / filename) reading as claude's navy **Code Surface** — set the filename + any `+N/−M` chrome from the `scene`.
|
||||
- Integrate the filled block as **this frame's composition** per the core sub-composition contract: its `data-composition-id` and its `window.__timelines[...]` key must both be your **`<frame_id>`** (the block ships its own id + paused timeline; rename both to match the frame contract). The block already renders an editor window (titlebar / filename) reading as claude's navy **Code Surface** — set the filename + any `+N/−M` chrome from the `scene`.
|
||||
- **The block owns the code animation; your Scene windows choreograph the surrounding Code Surface** — the navy window seating in, the file header typing on, the camera settling onto the hunk, a coral underline on the landed line. **Do not re-specify the code motion** (the block is the development beat). A code beat is usually `blueprint: compose`.
|
||||
- **The block has no caption-safe band.** When `Captions: enabled`, inset/scale the code panel into the top ~83% so it clears the keep-out band; never let code run under the caption pill.
|
||||
- **Mechanism beats (`mechanism`) — build an invented animated diagram of the behavior; the build _is_ the shot.** This is the "show what the change does at runtime" frame (the request retrying, the cache filling, serial→parallel, the race resolved) — read its `scene` for the behavior to animate. Unlike a code beat, **the motion is yours to author** (no block owns it):
|
||||
- If the `scene` names a `flowchart` / `flowchart-vertical` / `data-chart` block, the orchestrator pre-installed it — fill + mount it like a code block (its `data-composition-id` and `window.__timelines[...]` key both become your `<frame_id>`). Otherwise **hand-build the diagram in SVG / HTML / GSAP** from `frame.md`'s atoms.
|
||||
- **Claude register:** hairline-ink nodes / edges / lanes on the cream ground, **one coral marker** on the active / changed element, mono labels — **not** the navy code surface (that's for code), no heavy shapes / bokeh.
|
||||
- **Choreograph the Scene windows:** the nodes / lanes draw on (Scene 1); **the flow runs** as the VO names each step (middle Scenes — the request hops, the lane splits, the front advances, the bars race) — this _is_ the teaching, so it must play across the shot, never enter-then-freeze; the resolved state + the one coral emphasis lands (final Scene). Keep it in the top ~83% (caption keep-out).
|
||||
- **The `credits` close — the one frame with real assets.** Its `asset_candidates` names 2–6 `assets/<login>.png` avatars (downloaded in Step 1). Render them as `<img>` in hairline-ringed chips — an avatar row with each contributor's name + role in mono (an "approved" mark if the close calls for it), staggered in across the Scene windows. Avatars appear **only** here, never decorating a code frame.
|
||||
- **The `credits` close — the one frame with real assets.** Its `asset_candidates` names 2–6 `assets/<login>.png` avatars (downloaded upstream). Render them as `<img>` in hairline-ringed chips — an avatar row with each contributor's name + role in mono (an "approved" mark if the close calls for it), staggered in across the Scene windows. Avatars appear **only** here, never decorating a code frame.
|
||||
|
||||
## You do NOT decide
|
||||
## PR-specific self-check additions
|
||||
|
||||
These belong to other steps — touching them collides with a sibling or breaks an upstream contract:
|
||||
|
||||
- **What is SAID** — narration is locked in `SCRIPT.md` / the `voiceover` line. You only show; you never write or restate narration text.
|
||||
- **Duration** — fixed from real voice timing. Build your shot to land within it; don't stretch or trim it.
|
||||
- **Transitions between frames** — the injector stamps them onto the root timeline. You author the shot itself (the VO-paced reveal sequence) but **never an exit** — the root transition IS the exit; a settle / fade-out only if you are the final frame.
|
||||
- **Audio** (narration / BGM / SFX) — assembled at the root by the orchestrator. **No `<audio>` element in your composition.**
|
||||
- **Design tokens** — palette / fonts / components come from `frame.md`. Don't invent them, and **never lift a word, label, or wordmark out of `frame.md` as your copy** — it is a style spec, not content. Visible text comes from your frame's `scene` / narrative (and the real code, for a code beat).
|
||||
- **Which motions exist** — named upstream in your block (the shot sequence's motion verbs + `blueprint:` + the `code-*` block). Implement them; don't invent new ones.
|
||||
- **The shared `STORYBOARD.md`** — read your block, never write it. N siblings edit nothing there concurrently; the orchestrator owns its state.
|
||||
|
||||
## Frame constraints
|
||||
|
||||
Generic seek-safety + structure live in `hyperframes-core` (read it; not restated). These are the **PR-to-video deltas**, each load-bearing:
|
||||
|
||||
- **Caption keep-out — all content in the top ~83%.** A karaoke caption pill owns the bottom ~17% of the canvas. Keep every element (headline, code panel, diagram, labels) above `y ≈ 0.83 × height` — compute the pixel cutoff from your canvas (e.g. `≤ 900` on a 1080-tall frame, `≤ 1600` on a 1920-tall portrait). Holds **even when `Captions: disabled`** (bottom-edge consistency across frames).
|
||||
- **Fill the content area — especially portrait.** Compose the whole top-83% region; don't float one small cluster mid-frame. Anchor the hero high (~0.2–0.35 × height), flow supporting elements down with rhythm, scale the hero / code panel / diagram toward full-bleed. (Landscape's region is short, so vertical centering near 0.42 × height is fine.)
|
||||
- **Visible text is short motion-graphics copy** — a hero word, a stat (`"+1,204"`, `"2× faster"`), a file/label — never a sentence from the narration. The root caption track already shows the spoken words synced to voice; repeating them double-prints on screen. (Real code inside a `code-*` block is the exception — that is the content, not narration.)
|
||||
- **Build the whole shot — reveal across the full `duration`, never front-load.** Dumping the whole canvas in the first ~25% then holding it is exactly what reads as a PowerPoint slide. Instead reveal each piece — a file chip, the hunk, a node, a stat — **as the `voiceover` reaches it**, sequencing reveals across the shot and especially the back ~50%, with the macro camera move running underneath. **Only EXITS are banned** — a non-final frame unmounts mid-frame, so an exit tween truncates (the root transition IS the exit); mid-shot reveals are free and seek-safe. The lone exception is a note marked as a deliberate hold / stillness frame: there, an entrance + a quiet settle is right.
|
||||
- **Implement the shot sequence faithfully — every Scene is a timeline phase.** The Scene lines ARE the build: map each Scene onto a phase of the one timeline, each piece revealing as the `voiceover` reaches it. For each **named motion** in a Scene, open its rule recipe under `RULES_DIR/<id>.md` and reproduce its mechanics — **never name-guess** (a guess loses the signature move). The **`blueprint:` template** (`../hyperframes-animation/blueprints/<id>.md`) gives the overall shape; read it and keep its **signature move** recognizable. `compose` → no template; sequence the shot straight from the Scene lines (a code beat composes the surround around the block). Whichever, never front-load the whole sequence at `t=0`.
|
||||
- **Realize each element by its `roles`** (the `focal` is the hero): a `foreground subject` is the thing the eye lands on — respect the 83% keep-out and lay text around it; a `background` is a full-bleed field / gradient / grid dimmed ~30–50% so foreground content stays legible; `supporting` elements are labels, secondary shapes, ambient layers. Invented elements are HTML/CSS/SVG you build; a `code-*` block / `flowchart` / `data-chart` is filled + mounted per the section above; the credits avatars render as `<img>`.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read once, then build sequentially** — read the compact structural contract and `frame.md` once. For each assigned packet, use its exact frame block, selected blueprint/rule excerpts, and (for code) selected code-block/source excerpts. Do not reopen the source documents those excerpts came from. Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`.
|
||||
2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe you just read, the blueprint's signature move kept recognizable. Build the invented hero (diagram / type / number-lockup), or fill + mount the `code-*` block and choreograph the surround.
|
||||
3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously — per the core contract.
|
||||
4. **Self-check, then continue/finish** — re-read that frame file against the checklist below and fix in place. Continue to the next assigned packet; after the final file, stop. You do **not** run the CLI.
|
||||
|
||||
## Self-check before finishing (you do NOT run the CLI)
|
||||
|
||||
You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them at **Step 6, after assembly** (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back (the rules behind them live in `hyperframes-core`):
|
||||
|
||||
- `missing_template_wrapper` / `missing_composition_id` — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE/full document); its first element carries `data-composition-id="<frame_id>"` and a positive `data-duration` matching the packet.
|
||||
- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
|
||||
- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
|
||||
- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
|
||||
- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
|
||||
- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
|
||||
- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
|
||||
- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
|
||||
- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
|
||||
- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
|
||||
- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
|
||||
- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
|
||||
- The composition root also carries a **positive `data-duration` matching the packet**.
|
||||
- **Code-block cadence fits `data-duration`** — for a code beat, the `code-*` block's internal cadence is set so the full block completes within the frame's `data-duration` (a long snippet at the default per-character speed overruns — the code never finishes and the chrome beats never play; see `code-vocabulary.md`).
|
||||
- `font_family_without_font_face` — every font you name has a matching local `@font-face` **inside this template**. Copy the auto-generated block from `frame.md`; the Claude preset's EB Garamond, Inter, and JetBrains Mono faces live in `assets/fonts/`. Never link Google Fonts and never name a family without a project file, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is clean headless Chrome, so absent faces silently fall back. For non-Latin visible text, use a shipped face that covers the script or romanize/transliterate it; otherwise it is out of scope.
|
||||
- **Keep-out + no-narration-text** (eyeball, no code) — nothing sits below the 83% cutoff; no narration sentence is rendered as visible text.
|
||||
- Fonts: copy the auto-generated `@font-face` block from `frame.md`; the Claude preset's EB Garamond, Inter, and JetBrains Mono faces live in `assets/fonts/`. Never link Google Fonts.
|
||||
- Visible-text exception: real code inside a `code-*` block is the content, not narration.
|
||||
|
||||
@@ -25,7 +25,7 @@ Workflow: Step 0 setup -> `hyperframes.json`; Step 1 capture -> `capture/`; Step
|
||||
|
||||
Goal: Enter with a confirmed brief, create the HyperFrames project, and make the brief durable.
|
||||
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (§ 4): it checks recipes and remembered defaults, conducts this route's questions (`../hyperframes/references/route-briefs.md`), and hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it checks recipes and remembered defaults, conducts this route's questions (`../hyperframes/references/routes/product-launch-video.md`), and hands back the locked brief. Edit requests skip all of this — go do the edit.
|
||||
|
||||
Initialize only if `hyperframes.json` is missing. Name `<project>` from the brand or domain in kebab-case, such as `acme-promo`; never use workspace name or timestamp.
|
||||
|
||||
@@ -40,7 +40,7 @@ After init, let `<PROJECT_ROOT>` be `videos/<project>` and run every subsequent
|
||||
- **Collaborative:** wait for the user to sign in or explicitly choose `offline` / `go`.
|
||||
- **Autonomous:** state the status and continue through the available local engines.
|
||||
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` § Providers.
|
||||
Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` `references/setup-providers.md` § Providers.
|
||||
|
||||
**Gate:** `hyperframes.json` and `BRIEF.md` exist; the preference-backed answers were recorded (brief contract § 2); sign-in status was shown (signed in, or continuing offline).
|
||||
|
||||
@@ -84,7 +84,7 @@ The script does the rest deterministically: copies the preset's `FRAME.md` → `
|
||||
|
||||
Goal: Turn the brief and captured material into an approved frame-by-frame story plan.
|
||||
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
|
||||
Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.
|
||||
|
||||
Use `story-design.md` for story blueprint, hook, persuasion logic, beats, `VO_MODE`, and asset choices. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, note a candidate blueprint id when one fits. Story truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Choose each visual frame's `asset_candidates` from `capture/extracted/asset-descriptions.md` (the canonical inventory) — don't browse raw `capture/assets/`. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
|
||||
|
||||
@@ -148,11 +148,15 @@ Wait for Step 3.1 audio to finish if audio was started. Then sync durations and
|
||||
|
||||
Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
|
||||
|
||||
Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame.
|
||||
Before dispatch, read `../hyperframes-core/references/subagent-dispatch.md`. Build the per-frame packets and the worker role payload:
|
||||
|
||||
Each worker context must include `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the confirmed sketch when one exists (keep its layout — frame-worker § When a confirmed sketch exists), the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
|
||||
`node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"`
|
||||
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
|
||||
The builder writes one bounded packet per frame under `.hyperframes/frame-packets/` (the frame's exact storyboard block + the blueprint body + every cited rule recipe, inlined) and `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame: its prompt carries `_role.md` and that frame's packet — paste both in full, or hand the two file paths for the worker to read first (equivalent; the worker starts from exactly those two documents either way) — plus a dispatch context with `PROJECT_DIR`, `frame_id`, whether the frame has a **confirmed sketch** on disk (the worker dresses that layout rather than redrawing it — frame-worker core § When a confirmed sketch exists), canvas size, and caption status + keep-out band if captions are enabled.
|
||||
|
||||
Workers read only their packet and `frame.md`; they never open `STORYBOARD.md` or the skill documents (the packet inlines what was selected upstream). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
|
||||
|
||||
**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes-core/references/frame-worker-core.md`.)
|
||||
|
||||
As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
|
||||
|
||||
@@ -225,5 +229,6 @@ The reusable, product-agnostic shot shapes live in `../hyperframes-animation/blu
|
||||
| `[references/motion-language.md](references/motion-language.md)` | Step 4: the motion vocabulary + the motion doctrine. |
|
||||
| `[references/cut-catalog.md](references/cut-catalog.md)` | Step 4-5: the cut catalog (worker builds within-frame seams). |
|
||||
| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions. |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: dispatch per-frame workers. |
|
||||
| `[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md)` | Step 5: the shared worker contract (packet builder prepends it to the delta). |
|
||||
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)` | Step 5: the workflow's frame-worker delta. |
|
||||
| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)` | Step 5: dispatch sub-agents safely. |
|
||||
|
||||
@@ -441,6 +441,33 @@ for (const m of mounted) {
|
||||
acc += m.durationSeconds;
|
||||
}
|
||||
const TOTAL = r3(acc);
|
||||
|
||||
// ---------- duration expectation (advisory) ----------
|
||||
// Frontmatter `duration:` carries the brief's rough length expectation
|
||||
// (storyboard-format.md § Frontmatter). Never blocks the build: report where
|
||||
// the cut lands, and flag a large gap so the agent judges whether the drift
|
||||
// serves the piece.
|
||||
let durationNote = "";
|
||||
const rawTarget = manifest.globals.extra?.duration;
|
||||
if (rawTarget != null && String(rawTarget).trim() !== "") {
|
||||
const targetMatch = String(rawTarget).match(/(\d+(?:\.\d+)?)/);
|
||||
const target = targetMatch ? parseFloat(targetMatch[1]) : NaN;
|
||||
if (!Number.isFinite(target) || target <= 0) {
|
||||
anomalies.push(
|
||||
`frontmatter duration "${rawTarget}" is not parseable (e.g. "22s") — skipped the expectation check`,
|
||||
);
|
||||
} else {
|
||||
const diff = r3(TOTAL - target);
|
||||
durationNote = ` (expected ~${target}s, ${diff >= 0 ? "+" : ""}${diff}s)`;
|
||||
const pct = Math.abs((diff / target) * 100);
|
||||
if (pct > 10) {
|
||||
anomalies.push(
|
||||
`total ${TOTAL}s lands ${Math.round(pct)}% ${diff > 0 ? "over" : "under"} the brief's ~${target}s expectation — ` +
|
||||
`judge whether the drift serves the piece (pacing, narration fit); re-pace, or update \`duration:\` if the new length is intended`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
const startOfFrameNumber = new Map();
|
||||
for (const m of mounted) if (m.frame.number != null) startOfFrameNumber.set(m.frame.number, m);
|
||||
|
||||
@@ -705,7 +732,7 @@ console.log(` bgm (track 11): ${bgmEmitted ? "yes" + bgmNote : "no"}`);
|
||||
console.log(` captions (track 2): ${captionsEmitted ? "yes" : "no"}`);
|
||||
console.log(` sfx (track 20+): ${sfxEmitted}`);
|
||||
console.log(` assets staged: ${staged}/${wanted.size}`);
|
||||
console.log(` total duration: ${TOTAL}s`);
|
||||
console.log(` total duration: ${TOTAL}s${durationNote}`);
|
||||
if (repairs.length) {
|
||||
console.log(`\nrepaired (frame files updated in place):`);
|
||||
for (const rp of repairs) console.log(` - ${rp}`);
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
// Thin wrapper over the shared packet builder in hyperframes-core — this file only
|
||||
// pins the paths that are specific to this workflow skill. The logic (frame
|
||||
// splitting, rule citation, packet bounds, `_role.md` assembly) has one owner:
|
||||
// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
|
||||
|
||||
import { dirname, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
|
||||
|
||||
const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const CONFIG = {
|
||||
animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
|
||||
corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
|
||||
deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
|
||||
};
|
||||
|
||||
export function buildRolePayload({ outDir }) {
|
||||
return core.buildRolePayload({ ...CONFIG, outDir });
|
||||
}
|
||||
|
||||
export function buildFramePackets(options) {
|
||||
return core.buildFramePackets({ ...CONFIG, ...options });
|
||||
}
|
||||
|
||||
if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });
|
||||
@@ -0,0 +1,66 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { dirname, join } from "node:path";
|
||||
import test from "node:test";
|
||||
|
||||
import { buildFramePackets } from "./frame-packets.mjs";
|
||||
|
||||
function write(path, contents) {
|
||||
mkdirSync(dirname(path), { recursive: true });
|
||||
writeFileSync(path, contents);
|
||||
}
|
||||
|
||||
test("packets inline the blueprint body and the Scene-cited rule recipes", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "plv-packets-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n- blueprint: dataviz-countup\n- scene: hero stat punches in\n\nScene 1 (0.0–1.5s): the stat enters via spring-pop-entrance, then counting-dynamic-scale runs the tally.\n\n## Frame 2 — Freeform\n\n- duration: 4s\n- src: compositions/frames/02-freeform.html\n- blueprint: compose\n\nScene 1 (0.0–4.0s): a quiet hold, no named motion.\n`,
|
||||
);
|
||||
|
||||
const result = buildFramePackets({ projectDir: project });
|
||||
assert.equal(result.length, 2);
|
||||
|
||||
const hook = readFileSync(result[0].path, "utf8");
|
||||
assert.match(hook, /## Selected blueprint: dataviz-countup/);
|
||||
assert.match(hook, /## Selected motion rule: spring-pop-entrance/);
|
||||
assert.match(hook, /## Selected motion rule: counting-dynamic-scale/);
|
||||
assert.match(hook, /RULES_DIR: /);
|
||||
|
||||
const freeform = readFileSync(result[1].path, "utf8");
|
||||
assert.doesNotMatch(freeform, /## Selected blueprint/);
|
||||
assert.doesNotMatch(freeform, /## Selected motion rule/);
|
||||
});
|
||||
|
||||
test("_role.md is the core contract + this workflow's delta, verbatim", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "plv-role-"));
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n`,
|
||||
);
|
||||
|
||||
buildFramePackets({ projectDir: project });
|
||||
const rolePath = join(project, ".hyperframes", "frame-packets", "_role.md");
|
||||
assert.ok(existsSync(rolePath));
|
||||
const role = readFileSync(rolePath, "utf8");
|
||||
assert.match(role, /# Frame worker — core contract/);
|
||||
assert.match(role, /# Frame worker — product-launch delta/);
|
||||
});
|
||||
|
||||
test("packet validation is atomic and leaves no partial output on overflow", () => {
|
||||
const project = mkdtempSync(join(tmpdir(), "plv-atomic-"));
|
||||
const outDir = join(project, ".hyperframes", "frame-packets");
|
||||
write(join(project, "frame.md"), "# tokens\n");
|
||||
write(
|
||||
join(project, "STORYBOARD.md"),
|
||||
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Big\n\n- duration: 3s\n- src: compositions/frames/01-big.html\n\n${"padding line\n".repeat(300)}`,
|
||||
);
|
||||
|
||||
assert.throws(
|
||||
() => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
|
||||
/limit 2000/,
|
||||
);
|
||||
assert.equal(existsSync(outDir), false);
|
||||
});
|
||||
@@ -1,81 +1,15 @@
|
||||
# Frame worker — product-launch per-frame composition author
|
||||
# Frame worker — product-launch delta
|
||||
|
||||
> You build **one** frame's composition HTML and nothing else. You run N-up, one frame each — siblings build the others. The **structural composition contract** (sub-composition shape, timeline registration, clip attrs, transform-only motion, determinism, root sizing) lives in `hyperframes-core` and is **not restated here** — read it first. This file carries only what's specific to a product-launch frame. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in `hyperframes-core`.
|
||||
> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a product-launch frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
|
||||
|
||||
**INPUT** — your dispatch context provides:
|
||||
## Your `focal:` / `roles:` — real captured media
|
||||
|
||||
- `PROJECT_DIR` — the project root; all paths are relative to it.
|
||||
- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-feature.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
|
||||
- Your **`## Frame N` block** in `STORYBOARD.md` (read it; never write to that file — see below):
|
||||
- `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
|
||||
- `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
|
||||
- `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
|
||||
- `transition_in` — informational. The injector stamps it at the root; **you do not author transitions.**
|
||||
- the **time-coded shot sequence** — your build spec. A sequence of Scene lines (`Scene 1 (0.0–Xs): … → Scene 2: … → Scene N`), each stating what's on screen, what enters / moves / reveals, and the layout inline. Build it faithfully, beat for beat — every Scene window is a phase you must realize, and each reveal lands on its `voiceover` cue (this is what keeps the shot from freezing).
|
||||
- `blueprint:` — an id (or the literal `compose`). The id points to `../hyperframes-animation/blueprints/<id>.md`: the **product-agnostic shot template** this frame instantiates — the overall shape + its signature move. Read it for the shape; `compose` means there's no template, sequence the shot from the Scene lines directly.
|
||||
- `focal:` — which candidate is the hero.
|
||||
- `roles:` — each candidate's role: `cutout` foreground / `background` full-bleed / supporting — plus the real media available (each `public/<basename> — description`; a **`[video]`** tag marks a `.mp4` motion source that cannot be mounted by this sub-composition worker).
|
||||
- `sfx:` — the orchestrator's; you mount no audio.
|
||||
- `frame.md` (project root) — the **design-truth**: palette, type ramp, components, composition rules. The LOOK. Pull every visual token from here.
|
||||
- **Asset paths are project-root relative everywhere.** This includes HTML attributes and CSS `url(...)` values such as `@font-face src`: use `assets/...` (or the supplied `capture/assets/...` path), never `../` or `../../`. Stage shared fonts before dispatch so every parallel frame resolves the same local files; never fall back to a network `@import`.
|
||||
- `RULES_DIR` — absolute path to this skill's local `../hyperframes-animation/rules/`. The **named motion verbs in the Scene lines** (and the moves the blueprint cites) resolve to rule recipes here: `RULES_DIR/<id>.md` is the mechanics for a motion. (A few rules link an optional runnable demo in the shared `../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.)
|
||||
- `../references/cut-catalog.md` — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
|
||||
- Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
|
||||
- `focal:` — which candidate is the hero.
|
||||
- `roles:` — each candidate's role: `cutout` foreground / `background` full-bleed / supporting — plus the real media available (each `public/<basename> — description`; a **`[video]`** tag marks a `.mp4` motion source that cannot be mounted by this sub-composition worker).
|
||||
- **Asset paths are project-root relative everywhere.** This includes HTML attributes and CSS `url(...)` values such as `@font-face src`: use `assets/...` (or the supplied `capture/assets/...` path), never `../` or `../../`. Shared fonts are staged before dispatch so every parallel frame resolves the same local files; never fall back to a network `@import`.
|
||||
|
||||
**Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
|
||||
## Placing candidates (product-launch constraint)
|
||||
|
||||
**OUTPUT** — `compositions/frames/<frame_id>.html`, one self-contained sub-composition. Writing it (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
|
||||
**Place each candidate by its `roles`** (the `focal` is the hero): a `cutout` is a foreground subject — respect the 83% keep-out, lay text around it, not over its face; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible. Frame files are sub-compositions. Audio remains orchestrator-owned: never author `<audio>` in a frame. An approved `[video]` candidate may be declared as a frame-local `<video data-frame-video="approved" data-start="..." data-duration="..." data-track-index="...">`; `assemble-index.mjs` hoists it to the host root and translates its timing. Give every approved video explicit host geometry with numeric `data-frame-video-x`, `data-frame-video-y`, `data-frame-video-width`, and `data-frame-video-height`; optionally set `data-frame-video-fit="cover|contain|fill|none|scale-down"` (default `cover`). The assembler converts only those values to host CSS: frame-local classes and inline styles do not cross the hoist boundary. Do not use this declaration for audio, unapproved URLs, or videos without explicit timing and geometry. If no approved video is supplied, use an explicitly supplied static still/key art (`[video-still]` or another image candidate) as `<img>`; do not extract a frame, fabricate a URL, or silently embed an unapproved clip.
|
||||
|
||||
## When a confirmed sketch exists
|
||||
|
||||
In collaborative runs the orchestrator wireframes the board first, so your target file may already exist as the frame's **user-confirmed wireframe** — your dispatch says whether it does (a file found on a retry is your own prior output, not a sketch). Read it first and **keep its composition**: the placement, hierarchy, and copy were approved — don't move or drop them. Everything else is yours to finish: the full `frame.md` treatment (the sketch is deliberately unstyled), the real assets where the sketch used stand-in blocks, and the motion — map each Scene onto a timeline phase, reveal each piece on its `voiceover` cue with `fromTo` entrances, adding DOM only where a phase needs it. The frame's landed state must still read as the approved wireframe, fully dressed.
|
||||
|
||||
## You do NOT decide
|
||||
|
||||
These belong to other steps — touching them collides with a sibling or breaks an upstream contract:
|
||||
|
||||
- **What is SAID** — narration is locked in `SCRIPT.md` / the `voiceover` line. You only show; you never write or restate narration text.
|
||||
- **Duration** — fixed from real voice timing. Build your entrance to land within it; don't stretch or trim it.
|
||||
- **Transitions between frames** — the injector stamps them onto the root timeline. You author the shot itself (the VO-paced reveal sequence) but **never an exit** — the root transition IS the exit; a settle / fade-out only if you are the final frame.
|
||||
- **Audio** (narration / BGM / SFX) — assembled at the root by the orchestrator. **No `<audio>` element in your composition.**
|
||||
- **Design tokens** — palette / fonts / components come from `frame.md`. Don't invent them, and **never lift a word, label, or wordmark out of `frame.md` as your copy** — it is a style spec, not the product's content. Brand text comes from your frame's `scene` / narrative.
|
||||
- **Which motions / assets exist** — named upstream in your block (the shot sequence's motion verbs + `blueprint:`, the candidate media in `roles:` / `focal:`). Implement them; don't fetch or invent new ones (you have no asset-fetch tool — never fabricate an image URL).
|
||||
- **The shared `STORYBOARD.md`** — read your block, never write it. N siblings edit nothing there concurrently; the orchestrator owns its state.
|
||||
|
||||
## Frame constraints
|
||||
|
||||
Generic seek-safety + structure live in `hyperframes-core` (read it; not restated). These are the **product-launch deltas**, each load-bearing:
|
||||
|
||||
- **Caption keep-out — all content in the top ~83%.** A karaoke caption pill owns the bottom ~17% of the canvas. Keep every element (headline, cards, CTA, stats, brand mark) above `y ≈ 0.83 × height` — compute the pixel cutoff from your canvas (e.g. `≤ 900` on a 1080-tall frame, `≤ 1600` on a 1920-tall portrait). Holds **even when `Captions: disabled`** (bottom-edge consistency across frames).
|
||||
- **Fill the content area — especially portrait.** Compose the whole top-83% region; don't float one small cluster mid-frame. Anchor the hero high (~0.2–0.35 × height), flow supporting elements down with rhythm, scale hero type toward full-bleed. (Landscape's region is short, so vertical centering near 0.42 × height is fine.)
|
||||
- **Visible text is short motion-graphics copy** — headline / stat / one-word emphasis (`"$83K"`, `"INSTANT"`), never a sentence from the narration. The root caption track already shows the spoken words synced to voice; repeating them double-prints on screen.
|
||||
- **Build the whole shot — reveal across the full `duration`, never front-load.** Dumping the whole canvas in the first ~25% then holding it is exactly what reads as a PowerPoint slide. Instead reveal each piece — a line, a card, a stat, an icon — **as the `voiceover` reaches it**, sequencing reveals across the shot and especially the back ~50%, with the macro camera move running underneath. **Only EXITS are banned** — a non-final frame unmounts mid-frame, so an exit tween truncates and reads as a glitch (the root transition IS the exit); mid-shot reveals are free and seek-safe. The lone exception is a note marked as a deliberate hold / stillness frame: there, an entrance + a quiet settle is right (a held read beats bad motion).
|
||||
- **Implement the shot sequence faithfully — every Scene is a timeline phase.** The Scene lines ARE the build: map each Scene onto a phase of the one timeline, each piece revealing as the `voiceover` reaches it. For each **named motion** in a Scene, open its rule recipe under `RULES_DIR/<id>.md` and reproduce its mechanics — **never name-guess** (a guess loses the signature move). The **`blueprint:` template** (`../hyperframes-animation/blueprints/<id>.md`) gives the overall shape; read it and keep its **signature move** recognizable, then instantiate it with this frame's content / assets / timing. `compose` → no template; sequence the shot straight from the Scene lines. Whichever, never front-load the whole sequence at `t=0` — pace the reveals to the voiceover.
|
||||
- **Place each candidate by its `roles`** (the `focal` is the hero): a `cutout` is a foreground subject — respect the 83% keep-out, lay text around it, not over its face; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible. Frame files are sub-compositions. Audio remains orchestrator-owned: never author `<audio>` in a frame. An approved `[video]` candidate may be declared as a frame-local `<video data-frame-video="approved" data-start="..." data-duration="..." data-track-index="...">`; `assemble-index.mjs` hoists it to the host root and translates its timing. Give every approved video explicit host geometry with numeric `data-frame-video-x`, `data-frame-video-y`, `data-frame-video-width`, and `data-frame-video-height`; optionally set `data-frame-video-fit="cover|contain|fill|none|scale-down"` (default `cover`). The assembler converts only those values to host CSS: frame-local classes and inline styles do not cross the hoist boundary. Do not use this declaration for audio, unapproved URLs, or videos without explicit timing and geometry. If no approved video is supplied, use an explicitly supplied static still/key art (`[video-still]` or another image candidate) as `<img>`; do not extract a frame, fabricate a URL, or silently embed an unapproved clip.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Read** — `hyperframes-core`'s composition contract (the structural law), then `frame.md` (the look) and your `## Frame N` block (the shot sequence + `blueprint:` / `focal:` / `roles:` / assets). **Then read the blueprint template** `../hyperframes-animation/blueprints/<id>.md` (skip if `compose`) for the shot's shape and signature move, and **open the rule recipe `RULES_DIR/<id>.md` for every named motion** in the Scene lines (plus the shared `../hyperframes-animation/examples/<id>.html` when the recipe is unclear): you reproduce these mechanics, not improvise them. Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and the assembled-project `lint` / `check` gate can miss an unwired blank sub-composition.
|
||||
2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe you just read, the blueprint's signature move kept recognizable. Place the named assets, and find a visual idea that reinforces the beat, not a literal restyle of the words.
|
||||
3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously — per the core contract.
|
||||
Prefix authored ids and globally reusable class names with `<frame_id>-` so sibling frames assembled from parallel workers cannot collide. Contract selectors such as `#root` and `.clip` are the only exceptions.
|
||||
4. **Self-check, then finish** — re-read your file against the checklist below and fix in place. Writing the file is your terminal action; you do **not** run the CLI.
|
||||
|
||||
## Self-check before finishing (you do NOT run the CLI)
|
||||
|
||||
You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them at **Step 6, after assembly** (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back (the rules behind them live in `hyperframes-core`):
|
||||
|
||||
- `missing_template_wrapper` / `missing_composition_id` — root is `<template>`-wrapped and carries `data-composition-id="<frame_id>"`.
|
||||
- **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
|
||||
- `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
|
||||
- **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
|
||||
- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
|
||||
- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
|
||||
- `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
|
||||
- `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
|
||||
- **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
|
||||
- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
|
||||
- **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
|
||||
- **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
|
||||
- `font_family_without_font_face` — every font you name has a matching `@font-face` (or `@import`) **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.
|
||||
- **Keep-out + no-narration-text** (eyeball, no code) — nothing sits below the 83% cutoff; no narration sentence is rendered as visible text.
|
||||
Brand text comes from your frame's `scene` / narrative — never from `frame.md` (a style spec, not the product's content). Place the named assets, and never invent new ones.
|
||||
|
||||
Reference in New Issue
Block a user