docs(atelier): recognize HyperFrames as natively bespoke
Building the in-a-hurry showcase video surfaced a real workflow gap:
bespoke-composition.md was Remotion-flavored throughout. A fresh agent
reading it for a music-driven hero piece would be routed straight to
Remotion atelier — missing that HyperFrames has no cut-schema and is
already atelier by its nature (every HF composition is a hand-authored
index.html with data-* timing and a GSAP timeline you write).
This commit reframes the doctrine to be runtime-aware:
- New "Atelier and the two runtimes" subsection explicitly separates
Remotion (atelier as escape hatch from cut-schema registry) from
HyperFrames (always atelier; composition_mode "atelier" is implicit).
Same principles apply in both cases; the rendering path differs.
- Step 3 (vocabulary) now routes to /hyperframes-animation for HF
projects — 36+ atomic rules (kinetic-beat-slam, 3d-text-depth-layers,
motion-blur-streak, ...), 15+ scene blueprints, 16 transition families,
7 runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI /
TypeGPU), and the html-in-canvas-patterns headline capability for 1–3
cinematic hero beats per video. Also points at /hyperframes-creative,
/hyperframes-media, /media-use, /hyperframes-cli.
- Step 4 (engine mechanics) adds HF-side gotchas alongside Remotion:
the data-* contract, mandatory class="clip", paused-timeline + seek
rule, lint/validate/snapshot verification primitives, stable-id
selectors over nth-of-type.
- Step 5 (render) split into per-runtime paths:
* Remotion atelier — auto-stage copy + bespoke contract (unchanged).
* HyperFrames — npx hyperframes init scaffold, beats workflow,
lint+validate+snapshot verification, npx hyperframes render.
Flags the known gap (F13): hyperframes_compose.render still requires
cuts[] from the templated path; call npx directly until the tool
grows a bespoke branch parallel to _render_via_atelier.
- Worked precedents section now lists both runtimes — Phantom Reach /
Compound Snowball / Library of Alexandria for Remotion atelier, plus
in-a-hurry for HyperFrames (kinetic-beat-slam + 3d-text-depth-layers
+ motion-blur-streak + css-distortion + html-in-canvas + Three.js
bloom).
This commit is contained in:
calesthio
@@ -14,7 +14,7 @@ need so that what you build is correct, and distinct.
|
||||
|
||||
## When to use this skill (authoring mode is a proposal decision)
|
||||
|
||||
OpenMontage now separates three orthogonal axes, all locked at proposal:
|
||||
OpenMontage separates three orthogonal axes, all locked at proposal:
|
||||
|
||||
- `renderer_family` — creative grammar
|
||||
- `render_runtime` — technical engine (remotion / hyperframes / ffmpeg)
|
||||
@@ -26,8 +26,16 @@ output, localization variants, quick drafts, low-stakes internal clips — place
|
||||
sameness is fine and bespoke cost is unjustified. Present the choice to the user at proposal and
|
||||
log it in `decision_log` (`category: "composition_mode"`), the same way you present runtime.
|
||||
|
||||
If atelier is chosen, the stock scene-type catalog, the `hyperframes-registry` blocks, fixtures,
|
||||
and any finished component are **off-limits** — they are frozen looks and reintroduce sameness.
|
||||
### Atelier and the two runtimes
|
||||
|
||||
The two runtimes treat "bespoke" differently — read this before assuming the doctrine maps the same way to both:
|
||||
|
||||
- **Remotion** ships a `cut.type` registry of stock scenes (`text_card`, `stat_card`, `bar_chart`, …) dispatched by the `Explainer`/`CinematicRenderer` compositions. That's the templated default. **Atelier mode is the escape hatch** — `composition_mode: "atelier"` routes the render to `_render_via_atelier` and bypasses the registry entirely, so the agent hand-writes its own React composition under `projects/<slug>/`.
|
||||
- **HyperFrames is inherently atelier.** There is no cut-schema in HF — every composition is a hand-authored `index.html` with `data-*` timing attributes and a GSAP timeline you wrote. The registry (`hyperframes add`) is a *block* registry (grain overlays, transitions) — it's optional inputs to your composition, not a scene catalog dispatching the whole render. **When `render_runtime: "hyperframes"` is chosen, the piece is already atelier-style; `composition_mode: "atelier"` is implicit.** The principles in this skill (art direction, scene distinctness, no hero-component spine, distinctness review) apply equally. Render via `hyperframes_compose` (or `npx hyperframes render` for hand-authored compositions — see section 5).
|
||||
|
||||
So: if `render_runtime == "remotion"` and the piece is hero work, log a `composition_mode: "atelier"` decision. If `render_runtime == "hyperframes"`, atelier is the default behavior and you don't need to argue for it; this skill still routes you through the same principles before you write the composition.
|
||||
|
||||
If atelier is in play (either runtime), the stock Remotion `cut.type` catalog, `hyperframes-registry` finished blocks consumed as scenes (vs as raw inputs), fixtures, and any pre-baked creative component are **off-limits** — they are frozen looks and reintroduce sameness.
|
||||
|
||||
## The construction route
|
||||
|
||||
@@ -82,19 +90,49 @@ Reach for **principle** skills, never finished animations:
|
||||
- The HyperFrames `references/motion-principles.md` — easing as emotion, timing as weight.
|
||||
|
||||
### 3. Reach for a richer vocabulary only when the concept demands it
|
||||
Most scenes are Remotion primitives. Escalate when the *idea* needs it, not by default:
|
||||
`gsap-*` (kinetic typography via SplitText, shape morph via MorphSVG, curved motion via
|
||||
MotionPath, line-draw via DrawSVG, custom easing), `threejs-*` (3D), `d3-viz` (data-driven
|
||||
custom charts — build the chart by hand; do **not** drop in the stock `bar_chart`/`line_chart`),
|
||||
`manim-*` (math), `canvas-procedural-animation` (particles/weather).
|
||||
|
||||
**On Remotion** — most scenes are Remotion primitives. Escalate when the *idea* needs it, not
|
||||
by default: `gsap-*` (kinetic typography via SplitText, shape morph via MorphSVG, curved
|
||||
motion via MotionPath, line-draw via DrawSVG, custom easing), `threejs-*` (3D), `d3-viz`
|
||||
(data-driven custom charts — build the chart by hand; do **not** drop in the stock
|
||||
`bar_chart`/`line_chart`), `manim-*` (math), `canvas-procedural-animation` (particles/weather).
|
||||
|
||||
**On HyperFrames** — the vocabulary lives in `/hyperframes-animation`: 36+ atomic motion
|
||||
**rules** (`kinetic-beat-slam`, `3d-text-depth-layers`, `motion-blur-streak`,
|
||||
`physics-press-reaction`, `multi-phase-camera`, `depth-of-field-blur`, …), 15+ scene
|
||||
**blueprints** (`kinetic-type-beats`, `comparison-split`, `dataviz-countup`,
|
||||
`constellation-hub`, `ticker-takeover`, `device-surface-showcase`, …), 16 **transition**
|
||||
families (`css-distortion`, `css-destruction`, `css-radial`, `css-light`, `css-mechanical`,
|
||||
…), and **7 runtime adapters** under one composition: GSAP default, plus Lottie, Three.js,
|
||||
Anime.js, CSS keyframes, WAAPI, and TypeGPU (GPU compute). The headline capability is
|
||||
`adapters/html-in-canvas-patterns.md` — capture live HTML/CSS as a GPU texture and render
|
||||
through WebGL/Three.js for cinematic bloom, shatter, liquid, portal effects. Use it for 1–3
|
||||
hero beats per video, not every beat. **Compose 2–4 distinct atomic rules per beat** and use
|
||||
**at least 3 different easings across the piece** — that's the doctrine baked into the
|
||||
animation skill, not optional polish.
|
||||
|
||||
For HF creative direction (palette/type/narration/beat planning) read `/hyperframes-creative`.
|
||||
For HF assets (TTS/BGM/SFX/transcription/background-removal) read `/hyperframes-media` or
|
||||
`/media-use`. For HF CLI workflow (init/lint/validate/inspect/snapshot/beats/render) read
|
||||
`/hyperframes-cli`. The `/hyperframes` router skill maps it all.
|
||||
|
||||
### 4. Get the engine mechanics right — the gotcha codex
|
||||
This is the only place you "reuse": the engine's solved problems. These are facts about how
|
||||
Remotion works, not looks. Study `.agents/skills/remotion-best-practices` (19 rule files:
|
||||
timing, transitions, text-animations, transparent video, fonts, audio, sequencing, measuring
|
||||
text). You may also read the stock components in `remotion-composer/src/components/` **as a
|
||||
the framework works, not looks.
|
||||
|
||||
**For Remotion**, study `.agents/skills/remotion-best-practices` (19 rule files: timing,
|
||||
transitions, text-animations, transparent video, fonts, audio, sequencing, measuring text).
|
||||
You may also read the stock components in `remotion-composer/src/components/` **as a
|
||||
mechanics codex — to learn idioms, never to import or imitate a look.**
|
||||
|
||||
**For HyperFrames**, the composition contract is in `/hyperframes-core` (the `data-*`
|
||||
timing attributes — `data-start`, `data-duration`, `data-track-index` — plus the
|
||||
mandatory `class="clip"`, `data-composition-id`, `window.__timelines` registration, sub-
|
||||
composition mounts). Run `npx hyperframes lint && npx hyperframes validate` after every
|
||||
change — they catch missing root attrs, missing clip ids, GSAP-target unresolved, overlapping
|
||||
tweens, and contrast failures before render. Use `npx hyperframes snapshot . --at <times>`
|
||||
to spot-check beats visually before committing to a full render.
|
||||
|
||||
Recurring mechanics that bite if you don't know them:
|
||||
- **Determinism**: no `Math.random()` / `Date.now()` per frame — use Remotion `random(seed)` or a
|
||||
seeded helper, or particles/easing flicker across the render.
|
||||
@@ -105,7 +143,14 @@ Recurring mechanics that bite if you don't know them:
|
||||
public dir and reference via `staticFile`. Mirror the `resolveAsset` helper.
|
||||
- **GSAP-in-Remotion**: use a `paused` timeline and `.seek(frame/fps)` — never `requestAnimationFrame`
|
||||
— so frames render deterministically.
|
||||
- **Fonts**: `loadFont()` from `@remotion/google-fonts/<Name>` at module scope, once.
|
||||
- **Fonts (Remotion)**: `loadFont()` from `@remotion/google-fonts/<Name>` at module scope, once.
|
||||
- **HF data-* contract**: every timed element needs `data-start`, `data-duration`,
|
||||
`data-track-index`, AND `class="clip"` — without `clip` the framework won't manage
|
||||
visibility and your element will be onscreen the whole timeline. Root `<body>` needs
|
||||
`data-composition-id`, `data-start="0"`, `data-duration`, `data-width`, `data-height`.
|
||||
Every timeline must be `gsap.timeline({ paused: true })` and registered as
|
||||
`window.__timelines["<composition-id>"]`. Use stable `id` attributes on clips and on
|
||||
GSAP targets — `nth-of-type` selectors are flaky at validate time.
|
||||
- **Captions vs on-screen text — pick one role, never both for the same content.** Decide
|
||||
once per piece, before authoring: are captions adding meaning the spoken words can't carry
|
||||
(a number, a name, a translation, a quote attribution), OR are they accessibility subtitles
|
||||
@@ -114,26 +159,30 @@ Recurring mechanics that bite if you don't know them:
|
||||
amateurish even when the rest of the scene is beautiful. Empty `captions=[]` in props, or
|
||||
scope captions only to scenes where the on-screen text differs from what's being said.
|
||||
|
||||
### 5. Render through the atelier path (project-local, throwaway)
|
||||
Bespoke scenes are **throwaway and project-local** — they never enter the shared `src/` registry.
|
||||
### 5. Render through the runtime-appropriate bespoke path
|
||||
Bespoke compositions are **throwaway and project-local** — they never enter any shared registry.
|
||||
|
||||
- Author under `remotion-composer/projects/<slug>/` (gitignored). It needs its own Remotion entry
|
||||
(`index.tsx` + a `Root` registering only this composition) so it reuses the composer's
|
||||
`node_modules` and stays out of the global `Root.tsx`. The entry MUST live under
|
||||
`remotion-composer/` for the bundler to resolve `remotion`.
|
||||
- Keep media in a small per-project public dir and pass it as `public_dir` so renders don't copy
|
||||
the bloated shared `public/`.
|
||||
- Render via `video_compose` `operation="render"` with:
|
||||
#### Remotion atelier path
|
||||
- Author under `projects/<slug>/` (gitignored). The render tool auto-stages your `.tsx`/`.ts`
|
||||
source into `remotion-composer/projects/<slug>/` via mtime-skip copy so webpack can resolve
|
||||
`node_modules` — your source-of-truth stays under `projects/`.
|
||||
- Scaffold with `python scripts/scaffold_atelier_project.py <slug>` — emits engine
|
||||
plumbing only (entry / Root / blank `Composition.tsx` / `art-direction.md` / props
|
||||
template / README). Zero creative content; the placeholder is a deliberately ugly black
|
||||
screen so the post-render review correctly refuses to ship the scaffold unauthored.
|
||||
- Keep media in `projects/<slug>/public/` and pass that as `bespoke.public_dir`.
|
||||
- Render via `video_compose` `operation="render"`:
|
||||
|
||||
```json
|
||||
edit_decisions = {
|
||||
"render_runtime": "remotion",
|
||||
"composition_mode": "atelier",
|
||||
"bespoke": {
|
||||
"entry": "remotion-composer/projects/<slug>/index.tsx",
|
||||
"entry": "projects/<slug>/index.tsx",
|
||||
"composition_id": "<id registered in that entry's Root>",
|
||||
"props_path": "<absolute path to props.json>",
|
||||
"public_dir": "<absolute path to the project's public dir>",
|
||||
"props_path": "<absolute path to artifacts/props.json>",
|
||||
"public_dir": "<absolute path to projects/<slug>/public/>",
|
||||
"art_direction": "<short note or path to art-direction.md — REQUIRED>",
|
||||
"scale": 0.5, // 0.5 for a fast draft; drop for the 1080p final
|
||||
"crf": 18, // crisp final
|
||||
"concurrency": 8
|
||||
@@ -142,6 +191,26 @@ edit_decisions = {
|
||||
```
|
||||
|
||||
No `asset_manifest` or `cuts` are required in atelier mode — the composition owns its own assets.
|
||||
The tool's `_run_atelier_checks` fails the render if any source file imports from the stock
|
||||
registry (`src/components`, `src/Explainer`, etc.), and warns if `art_direction` is missing.
|
||||
|
||||
#### HyperFrames path
|
||||
- Scaffold with `npx hyperframes init <slug>` (run from `projects/`). HF init generates
|
||||
`index.html`, `meta.json`, `package.json`, and a per-project `CLAUDE.md` that auto-routes
|
||||
the agent into `/hyperframes` — so the next session knows exactly which sub-skills to load.
|
||||
- Author `index.html` by hand. Every clip needs `class="clip"` + the three `data-*` timing
|
||||
attrs + a stable `id`. Mount sub-compositions via `data-composition-src` once the timeline
|
||||
on one file grows past 4 clips (the lint catches density).
|
||||
- For music-driven pieces, run `npx hyperframes beats .` after dropping the track in
|
||||
`assets/` — it emits `beats/<audio>.json` with `{time, strength}` per beat so the agent
|
||||
can land scenes on real drops (not guesses).
|
||||
- Verify before render: `npx hyperframes lint . && npx hyperframes validate . && npx hyperframes snapshot . --at <times>`.
|
||||
Snapshot is HF's native visual-spotcheck (contact-sheet of PNG frames at chosen
|
||||
timestamps) — use it the same way an atelier `final_review.visual_spotcheck` would.
|
||||
- **Render**: `npx hyperframes render . --output renders/<name>.mp4`.
|
||||
> Known gap (F13): `hyperframes_compose.render` currently requires `edit_decisions.cuts[]`
|
||||
> from the templated path. For hand-authored HF compositions it errors; call `npx` directly
|
||||
> until the tool grows a bespoke branch.
|
||||
|
||||
## Guardrails so this doesn't backfire
|
||||
|
||||
@@ -158,14 +227,30 @@ No `asset_manifest` or `cuts` are required in atelier mode — the composition o
|
||||
for approval BEFORE generating assets, then a footage/asset checkpoint, then a first-render
|
||||
checkpoint. Do not batch-generate ahead of sign-off.
|
||||
|
||||
## Worked precedent (for the *workflow*, not the look)
|
||||
## Worked precedents (for the *workflow*, not the look)
|
||||
|
||||
The first atelier piece was the Phantom Reach explainer (`projects/phantom-reach-explainer/`):
|
||||
Playwright-captured app footage with a PII-blur layer → per-sentence TTS stitched with silence
|
||||
beats → free Pixabay music → hand-authored Remotion scenes (custom intro, score-ring, agentic
|
||||
flow, CTA) on a one-off violet theme. Study its **process** (capture → timing → props builder →
|
||||
bespoke scenes → render). **Do not reproduce its visual language** — the next piece must look
|
||||
nothing like it. That is the whole point.
|
||||
Two reference pieces — one per runtime — to study **processes**, never visual languages:
|
||||
|
||||
- **Remotion atelier** — Phantom Reach explainer (`projects/phantom-reach-explainer/`):
|
||||
Playwright-captured app footage with a PII-blur layer → per-sentence TTS stitched with
|
||||
silence beats → free Pixabay music → hand-authored Remotion scenes (custom intro,
|
||||
score-ring, agentic flow, CTA) on a one-off violet theme.
|
||||
Compound Snowball (`projects/compound-snowball/`) and Library of Alexandria
|
||||
(`projects/alexandria-fire/`) are two more — three Remotion atelier pieces, three
|
||||
completely different visual languages.
|
||||
|
||||
- **HyperFrames** — `in-a-hurry` (`projects/in-a-hurry/`): a music-driven kinetic-typography
|
||||
piece using the new HF 0.7 `beats` command to lock scene timing to real drops. Exercises
|
||||
**5 categories** of `/hyperframes-animation`: `kinetic-beat-slam`, `3d-text-depth-layers`
|
||||
(stacked extrusion), `motion-blur-streak` (echo-ghost trails), `transitions/css-distortion`
|
||||
(chromatic-aberration RGB-split), and `adapters/html-in-canvas-patterns` (Three.js +
|
||||
UnrealBloom on a hero punchline). Each beat uses a distinct easing (`expo.out`,
|
||||
`back.out(2)`, `circ.out`, `sine.inOut`).
|
||||
|
||||
**Do not reproduce any of their visual languages** — the next piece must look nothing like
|
||||
any of them. That is the whole point. Study only the *process* (decisions, ordering, gates,
|
||||
verification).
|
||||
|
||||
See also: `skills/meta/animation-runtime-selector.md` (runtime + library routing),
|
||||
`AGENT_GUIDE.md` → "Composition Authoring Mode".
|
||||
`AGENT_GUIDE.md` → "Composition Authoring Mode", `/hyperframes` (the HF router and
|
||||
capability map).
|
||||
|
||||
Reference in New Issue
Block a user