hyperframes/skills/hyperframes-core/references/frame-worker-core.md

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.