hyperframes

# HyperFrames — read this first **Start here for any HyperFrames task** — especially with no project agent config (`CLAUDE.md` / `AGENTS.md` / `.cursorrules`) present. Capability map + video router below. ## Capability map — which skill for which intent | You want to… | Go to | | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | | **Make a video** (from a URL, brief, topic, GitHub PR, existing footage, or a single element to animate) | the **video router below** (§ Video routing) | | **Author / edit an HTML composition** — the `data-*` contract, clips, tracks, sub-compositions, variables | `/hyperframes-core` | | **Animate** — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | `/hyperframes-animation` | | **Creative direction** — `design.md`, palettes, typography, narration, beat planning, audio-reactive | `/hyperframes-creative` | | **Media preprocessing** — TTS voiceover, background music, transcription, background removal, captions | `/hyperframes-media` | | **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor | `/hyperframes-cli` | | **Install registry blocks / components** (`hyperframes add`) | `/hyperframes-registry` | > The composition **authoring contract** (every timed element needs `data-start` / `data-duration` / `data-track-index`; timed elements need `class="clip"`; GSAP timelines are paused and registered on `window.__timelines`; deterministic logic only — no `Date.now()` / `Math.random()` / network) is **not duplicated here** — it lives in `/hyperframes-core`. Read that before writing composition HTML. ## What HyperFrames cannot do — check this first HyperFrames authors an HTML composition and renders it to MP4 **from code**. That model has hard outer edges. A request past one of them is not a routing choice — it is **out of scope**, so decline (or point at the right tool) instead of reaching for a workflow. These follow from the architecture, not from any single request: - **The render is deterministic and self-contained.** Every value, asset, and piece of text is baked in when you author; the render does no network call and no live / at-render-time data pull (core rule: no `Date.now()` / `Math.random()` / network). "Refresh the numbers live at render time" is out — fetch the data once at author time and bake it in, or decline. - **Existing video is overlaid, never edited.** HyperFrames composes frames _on top of_ a source clip — `/embedded-captions` adds a caption layer, `/graphic-overlays` adds designed graphic cards (lower-thirds, data callouts, titles) — and the clip plays unchanged underneath, but neither post-processes the encoded video stream. Changing the footage _itself_ (its timing, color, framing, order, or audio) is NLE-style editing and out of scope. - **Remotion import is one-way.** `/remotion-to-hyperframes` translates the _Remotion framework's_ source into HyperFrames. There is no reverse (HyperFrames → Remotion, or → any other framework — out of scope), and a non-Remotion React / web-animation source has no Remotion source to translate — re-create it via `/general-video`. - **It cannot produce inputs it does not have.** No screen / session recording, no camera capture, no AI talking-head / lip-synced avatar generation. If the footage or asset does not exist yet, HyperFrames cannot conjure it — ask the user to supply it (or use the right capture tool) first. Everything else — a video from a URL, brief, topic, PR, footage-to-annotate, or a single element to animate — is in scope; route it below. --- # Video routing This section knows ONLY top-level workflows. It does not load workflow-internal phases, domain skills (`hyperframes-*` — see the capability map above), or technical references. ## Decision table **INPUT type (intent) is the primary axis; OUTPUT length is only a ceiling, not a gate.** For a matching input, the specialized workflows handle anything **up to ~3 min** — _which_ workflow you enter is decided by intent (the input type, and for text the subject), not by length. Length matters only at the top end: a genuinely longer piece (a 3-5 min tutorial, a 5 min+ deep dive) is a different register and routes to `/general-video`. Within the ≤~3 min band, a third axis splits the two text-fed workflows — the **subject**: a product being _marketed_ vs a topic being _explained_ (see the disambiguation rule in step 3 below). | Length / Input | Product launch (URL / brief / script) | General website / URL | GitHub PR / code change | Topic / article / notes (no product, no URL) | Existing video (talking-head) † | | --------------- | ------------------------------------- | --------------------- | ----------------------- | -------------------------------------------- | -------------------------------------------- | | **≤ ~3 min** | `/product-launch-video` | `/website-to-video` | `/pr-to-video` | `/faceless-explainer` | `/embedded-captions` · `/graphic-overlays` † | | 3-5min tutorial | `/general-video` | `/general-video` | `/general-video` | `/general-video` | `/embedded-captions` · `/graphic-overlays` † | | 5min+ deep dive | `/general-video` | `/general-video` | `/general-video` | `/general-video` | `/embedded-captions` · `/graphic-overlays` † | | Static / loop | `/general-video` | `/general-video` | `/general-video` | `/general-video` | `/general-video` | Coverage today: the **≤ ~3 min** band has dedicated workflows for **product-launch / general-website / GitHub-PR / topic** inputs (a URL splits by _kind_ then _intent_ — see step 3), and the **existing video** column is covered at **any length** — by `/embedded-captions` (captions / subtitles) or `/graphic-overlays` (designed graphic overlays), split by intent (see step 2). **Every other cell is `/general-video`** — the general HTML-composition authoring flow (input- and length-agnostic): everything **longer than ~3 min** (the 3-5 min / 5 min+ rows) and every **static / loop** format. The router never dead-ends on a creatable video; the only true "general / none" answer is a request outside HyperFrames itself (e.g. NLE-style editing of a finished video file — re-timing, recoloring, reframing, reordering, audio). † **Existing footage splits by intent, not length.** Captions / subtitles → `/embedded-captions`; designed graphic overlays / packaging — lower-thirds, data callouts, titled cards, pull-quotes — → `/graphic-overlays`. Both overlay the clip, which plays unchanged underneath; neither edits the footage itself. **Genre short-circuit (precedes the table).** A short (~under 10s), unnarrated, design-led **motion graphic** — kinetic type, a stat / chart hit, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight — routes to `/motion-graphics` regardless of input. It is an OUTPUT genre, not an input type, so it takes precedence over the input-type table above when the ask is clearly motion-first with no narration (see step 2). A longer or narrated treatment routes by input type, or `/general-video`. ## Migrating an existing composition (special case) The table above is for **creating** a video from an input. One workflow sits outside it: if the user explicitly asks to **port / convert / migrate an existing Remotion (React) composition** into HyperFrames → `/remotion-to-hyperframes`. This is source translation, not creation-from-input, so it has no INPUT × LENGTH cell. Route here ONLY on explicit migration language ("port my Remotion project", "convert this Remotion comp", "rewrite this as HyperFrames") — a passing mention of Remotion is not a trigger; default to the creation table or `/hyperframes-core`. ## Routing procedure 1. **Determine INPUT type + target length.** Routing needs to know **what the video is about** — its subject and input. If the subject itself is unspecified (e.g. "make a video about our thing" with no URL, named product, topic, or asset to work from), or the input type is unknown, **ask before entering any workflow** — clarify first; do not invoke a workflow Skill and then ask, since committing to a workflow is itself the routing decision. Ask at most 2 clarifying questions: - "What's your input — a product (URL or brief), a general website / URL, a GitHub PR / code change, a topic or article to explain, or an existing talking-head video to caption?" - "Target length — about 3 minutes or under, or longer (a 3-5 min tutorial / 5 min+ deep dive)?" - **Spec defaults — state, don't ask** (these do NOT affect the route, so never block routing on them): **aspect** 16:9 (the engine also supports **9:16** vertical — switch only if the user names a vertical destination like TikTok / Reels / Shorts); narration / caption **language** = the user's. Confirm only if the user pushes back; the chosen workflow re-confirms its own specifics at its Step 0. 2. **Pick by INPUT type (intent) first; length is only a ceiling, not a gate.** - **Short design-led motion graphic (genre short-circuit, precedes the input table)** — the motion itself is the message: kinetic type, a stat / number count-up, a chart hit, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; typically under ~10s, **no narration / voice-over** → `/motion-graphics`. This is an OUTPUT genre, not an input type — when the ask is clearly a quick, unnarrated, design-led motion piece, route here regardless of input. A **longer or narrated** treatment of the same material is NOT this (route by input type, or `/general-video`). - **Existing talking-head video** (the user has a clip and wants something added over it) → split by intent, at **any length** (input type wins over length): **captions / subtitles** (the spoken words as readable text) → `/embedded-captions`; **designed graphic overlays** — lower-thirds, data callouts, titled info-cards, pull-quotes, a graphics-packaged edit → `/graphic-overlays`. (Editing the footage _itself_ — re-timing, recolor, reframe, reorder, audio — is NLE-style and out of scope; see § What HyperFrames cannot do.) - **GitHub PR / code change** (a `github.com/<owner>/<repo>/pull/<N>` link, an `owner/repo#N` ref, or "this PR") → `/pr-to-video` (up to ~3 min). - **Otherwise** (product URL / brief / topic text): intent picks the workflow via step 3, and it handles anything **up to ~3 min** — a short 15-30 s promo and a ~100 s explainer both route by intent, not by length. Route to `/general-video` (the length-agnostic fallback — see step 4) only when the target is clearly **longer than ~3 min** (a 3-5 min tutorial, a 5 min+ deep dive). Never force a genuinely long piece into a ≤~3 min workflow — intent decides within the band, `/general-video` covers the rest. 3. **Disambiguate the ≤~3 min URL / text inputs (the intent split).** Two splits: - **URL kind + intent** — a URL no longer auto-wins for PLV; its _kind_ then _intent_ decides: a **GitHub PR** link (`.../pull/<N>`, `owner/repo#N`, "this PR") → `/pr-to-video`; otherwise a website URL splits by intent — **marketing / launching / promoting a specific product or SaaS** → `/product-launch-video`; a **general site → video** (site tour, portfolio / blog / landing-page showcase, a social clip from the site's own visuals, or just "turn this site into a video") → `/website-to-video`. Both crawl with headless Chrome; PR URLs are read via `gh`. When it's genuinely unclear whether a site URL is a product launch or a general-site video, ask one question. - **Product vs topic** (text, no URL) — the decisive question is **what the video is about**, not the input format: - A specific **product / company / SaaS / app / website** being **marketed, launched, or promoted** → `/product-launch-video`. - A **concept / topic / article / how-something-works** being **explained**, with **no product and no URL** → `/faceless-explainer`. - Tie-breakers: "Promote / launch / sell / our product" wording → PLV. "Explain / teach / how X works / what is X" with no product → faceless. The shipped style for faceless is always `pin-and-paper`. - **A named site without a pasted URL is still PLV.** A script that mentions a product or its website ("our site is acme.io", "promote <brand>") routes to PLV even with no clickable link — PLV can web-search the site and crawl it for brand assets (unless the user opts out, → no-capture preset mode). Not pasting the URL does **not** make it a faceless / no-capture job. The verbatim-vs-restructure choice for a supplied script is internal to PLV and never changes the route. - **Conflicting cues → ask, don't guess.** If the supplied source is a product's **own marketing** (its landing page, a promo blog about _their_ platform) yet the user explicitly asks to **strip the promotion** — a _neutral_ explainer of the underlying concept, _not an ad_ — treat it as genuinely ambiguous (is the video about _their product_, or the _general concept_?) and **ask one question**, rather than resolving to faceless on the "neutral" cue alone. Contrast: a general topic where a product is merely an aside the user says to _exclude_ ("explain how OAuth works — we sell an auth product but don't mention it") is unambiguously **faceless** — no need to ask. - Still unclear after reading the request → ask exactly one question: _"Is this promoting a specific product, making a video from a general website, explaining a topic/concept, walking through a GitHub PR, or adding captions to an existing video?"_ 4. **Fall back to `/general-video`.** When no specialized workflow above matches, route to `/general-video` — the general HTML-composition authoring flow (the original `hyperframes` flow: design system → plan → layout-before-animation → build → validate), which is input- and length-agnostic. Do **not** _fake-route_ into a specialized workflow (don't force a tutorial into PLV); `/general-video` is the correct general home, not a near-fit. The only genuine "no workflow / general" answer is a request outside HyperFrames itself — e.g. NLE-style cutting/editing of a finished video file (captioning a talking-head clip is `/embedded-captions`; overlaying designed graphics on it is `/graphic-overlays`). ## Workflow descriptions (for disambiguation) ### `/product-launch-video` - **Input:** A product being marketed, supplied as one of: **(a) a product URL** → crawled with headless Chrome for assets, brand tokens, page structure; **(b) a script / brief that names a product site** (even without a pasted link) → PLV resolves the site by web search and crawls it for brand tokens + assets, _unless_ the user opts out of searching; **(c) a script / brief with no derivable site** (or an explicit "don't scrape") → no-capture mode, you pick a style preset that supplies the palette + design system (text/typography scenes, no scraped assets). A supplied script can be used **verbatim as the voice-over** or **restructured** into punchier per-scene narration — PLV asks which. - **Output:** product launch / SaaS explainer / promo video as a HyperFrames composition rendered to MP4 — **up to ~3 min** (sweet spot ~30-90s; longer still when a verbatim script runs long — verbatim length follows the script)