mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 12:54:29 +00:00

Files

T

Miguel Ángel 9da422fd7f feat(cli): run a managed background preview in every launch mode (#3310 )

`--background` was rejected outside the embedded server. It now re-execs the
CLI in foreground, which makes it mode-agnostic by construction: whichever
server the child resolves to serves the config endpoint the readiness probe
looks for. `--foreground` is its counterpart, for a non-interactive shell that
wants to stay attached, and a bare launch keeps the same promise — attached in
an interactive terminal, managed in an agent session.

That generalization exposed an existing hole. Local-studio mode runs Vite with
the studio package as its cwd and needs that package's own Vite config, which
the published tarball does not carry, but resolving the package was treated as
proof the mode was usable. An npm-installed studio therefore took a path that
can never come up — previously a clear error, now a ten-second silent timeout.
The predicate becomes "can this studio actually be served", so a published
install falls back to embedded mode, which works.

Over the 1k line budget at ~1.3k. The overage is one command file and its
tests carrying one invariant, and the seam that would split it further is
inside a single request-handling function — a split there would produce two
PRs neither of which starts a preview on its own.

2026-08-19 17:02:44 -04:00

11 KiB

Raw Blame History

name, description

name	description
hyperframes-core	The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

HyperFrames Core

HyperFrames renders video from HTML. A composition is an HTML file whose DOM declares timing with data-* attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.

This skill is the technical contract — how to build one hyperframes project. The body below is the build guide; per-topic detail lives in references/ (index next), read on demand. Other concerns live in the sibling domain skills — hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. The capability map in /hyperframes says what each one covers.

References

File	Read it to…
`references/minimal-composition.md`	start from the smallest renderable composition skeleton
`references/composition-patterns.md`	choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype
`references/data-attributes.md`	look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`
`references/tracks-and-clips.md`	pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another
`references/creator-editing-recipes.md`	copy truthful cut/trim/reorder/retime/freeze/camera/mask/crossfade/audio editing recipes and their limits
`references/sub-compositions.md`	wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it
`references/variables-and-media.md`	declare variables; place `<video>`/`<audio>`, set volume, trim
`references/determinism-rules.md`	build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit
`references/full-screen-motion.md`	author full-frame motion with shared backgrounds
`references/storyboard-format.md`	author a `STORYBOARD.md` plan (+ the parsed manifest)
`references/review-loop.md`	run the plan → sketch → build review passes on a live board — shared by every storyboard-planning workflow
`references/production-loop.md`	take an approved plan to a delivered video — the stage dependencies (audio, frames, assembly, transitions, captions, verify, deliver) a freeform build follows directly
`references/brief-contract.md`	the brief's ground rules — mode derivation (collaborative / autonomous), shared field registry, question invariants (the asking itself lives in `/hyperframes` → the intent layer)
`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.

Building a composition

Two root forms (not interchangeable)

Standalone (top-level index.html) — root <div data-composition-id="…"> sits directly in <body>, no <template> wrapper (wrapping it hides all content and breaks rendering).
Sub-composition (loaded via data-composition-src) — root must be wrapped in <template>.

⚠ Transport rule: the runtime only clones <template> contents; everything outside (incl. <head> styles/scripts) is discarded — put <style>/<script> inside the template. ⚠ Host-id rule: the host slot's data-composition-id must exactly equal the inner template's data-composition-id and the window.__timelines["<id>"] key — no -mount/-slot/-host suffix.

File shape, host wiring, and the pre-render checklist → references/sub-compositions.md.

Root must be sized (silent layout bug)

The standalone root needs an explicit sized box (width/height in px), and every ancestor down to a height:100% element must have a resolved height — otherwise a flex/100% child collapses to ~0 and content piles into the top-left corner. Do not rely on automated gates alone to catch this; inspect a snapshot. Skeleton → references/minimal-composition.md.

One paused timeline

Each composition registers exactly one gsap.timeline({ paused: true }) at window.__timelines["<id>"] (key = root data-composition-id), built synchronously at page load. Render duration = root data-duration, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → references/determinism-rules.md + hyperframes-animation/adapters/.

First-pass lint gotchas (a guaranteed first build failure)

Two rules that lint does catch, but only after the fact — write them right the first time:

The root composition element must carry data-start="0" (alongside data-composition-id/data-width/data-height); omitting it fails lint with root_composition_missing_data_start.
Never pair a CSS initial transform with a GSAP tween on the same property — the CSS value and the tween's start fight and lint rejects it with gsap_css_transform_conflict. Set the initial state inside the tween with gsap.fromTo(el, { x: -40 }, { x: 0 }) instead of a CSS transform: translateX(-40px).

Non-negotiable rules (silent bugs automated gates may miss)

Surfaced here; full rationale in the linked reference. Do not violate:

No render-time clocks / unseeded Math.random / network / input-state; no repeat: -1 (use a finite count). → determinism-rules.md
Animate only the visual-property allowlist; never tween display or raw visibility. GSAP autoAlpha and zero-duration timeline boundary sets are the only visibility exceptions, and only on non-clip elements or wrappers inside a clip. The framework alone controls .clip visibility. Do not gsap.set later-scene clips at page load. → determinism-rules.md
No <br> in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → determinism-rules.md
<video>/<audio> work at any nesting depth (including inside a sub-comp <template> or wrapper); the framework owns playback and seeks/decodes media wherever it lives. The one caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → variables-and-media.md
Every id must be unique across the assembled page; inside a sub-comp, prefix ids with the composition id (#<id>-hero). Duplicate <video>/<img> ids render blank — the producer injects frames by getElementById, and cross-file dupes slip past lint. → composition-patterns.md
A full-screen scene fill goes on a full-bleed child (position:absolute; inset:0), never on the composition root itself — the producer's frame compositing can drop the root element's own background (the frame renders black) even though preview/snapshot show it correctly. → composition-patterns.md

Editing existing compositions

Read the files first. Preserve unrelated timing, tracks, IDs, variables, media paths.
Match existing composition IDs and timeline keys.
Adding a clip: pick a non-overlapping data-track-index or adjust surrounding timing intentionally.
data-hidden on any composition element hides it in BOTH preview and render, overriding its time window; it is non-destructive/reversible and toggled by Studio's timeline eye icon.
Adding a sub-composition: verify its internal data-composition-id before wiring the host.

Validation

Use hyperframes-cli for command details

npx hyperframes check passes (0 findings across lint, runtime, layout, motion, and contrast)
Projects with sub-compositions: npx hyperframes snapshot --at <midpoints> and eyeball each frame
npx hyperframes preview --background for review (the user can edit anything in Studio's timeline, and the server survives the invoking command)
npx hyperframes render only after the user approves

11 KiB Raw Blame History