AIpkgs · box · detail

box

Hyperframes

“HeyGen's HyperFrames toolkit — write HTML, render video: compositions, GSAP/anime.js/Lottie/Three animations, captions, voiceovers, and website-to-video capture.”

editionv0.1.0

imprinthyperframes

manifest1 ln · 381 B

leaves171 · 2.1 MB

Hyperframes

HeyGen's HyperFrames packaged as an AIpkgs box: 15 Claude Code skills for turning HTML into rendered video. Covers compositions, runtime animation adapters (GSAP, anime.js, Lottie, Three.js, WAAPI, CSS, TypeGPU), Tailwind styling, captions/voiceovers and media handling, the HyperFrames CLI, the registry, and website/Remotion → HyperFrames conversion.

Skills

hyperframes, hyperframes-cli, hyperframes-registry, hyperframes-media, website-to-hyperframes, remotion-to-hyperframes, contribute-catalog, gsap, animejs, lottie, three, typegpu, waapi, css-animations, tailwind.

Attribution

Imported from heygen-com/hyperframes by HeyGen. Licensed under Apache-2.0 (see LICENSE.txt). Several skills drive the hyperframes CLI, which is installed separately.

Install

aipkg install hyperframes/Hyperframes

tree2.1 MB

skills168
- animejs01
- contribute-catalog02
- css-animations01
- gsap03
  - references01
  - scripts01
- hyperframes48
  - palettes09
  - references30
    transitions14
  - scripts03
  - templates01
- hyperframes-cli01
- hyperframes-media01
- hyperframes-registry08
  - examples02
  - references05
- lottie01
- remotion-to-hyperframes66
  - assets47
    test-corpus46
    tier-1-title-card09
    hf-src01
    remotion-src06
    src03
    tier-2-multi-scene10
    hf-src01
    remotion-src06
    src03
    tier-3-data-driven15
    hf-src01
    remotion-src12
    src09
    components03
    scenes03
    tier-4-escape-hatch11
    cases08
  - references11
  - scripts07
    tests03
    fixtures02
- tailwind01
- three01
- typegpu01
- waapi01
- website-to-hyperframes32
  - assets21
    sfx21
  - references09
  - scripts01

txtLICENSE.txt

11 kB

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,

and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by

the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all

other entities that control, are controlled by, or are under common

control with that entity. For the purposes of this definition,

"control" means (i) the power, direct or indirect, to cause the

direction or management of such entity, whether by contract or

otherwise, or (ii) ownership of fifty percent (50%) or more of the

outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity

exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,

including but not limited to software source code, documentation

source, and configuration files.

"Object" form shall mean any form resulting from mechanical

transformation or translation of a Source form, including but

not limited to compiled object code, generated documentation,

and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or

Object form, made available under the License, as indicated by a

(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object

form, that is based on (or derived from) the Work and for which the

editorial revisions, annotations, elaborations, or other modifications

represent, as a whole, an original work of authorship. For the purposes

of this License, Derivative Works shall not include works that remain

separable from, or merely link (or bind by name) to the interfaces of,

the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including

the original version of the Work and any modifications or additions

to that Work or Derivative Works thereof, that is intentionally

submitted to the Licensor for inclusion in the Work by the copyright owner

or by an individual or Legal Entity authorized to submit on behalf of

the copyright owner. For the purposes of this definition, "submitted"

means any form of electronic, verbal, or written communication sent

to the Licensor or its representatives, including but not limited to

communication on electronic mailing lists, source code control systems,

and issue tracking systems that are managed by, or on behalf of, the

Licensor for the purpose of discussing and improving the Work, but

excluding communication that is conspicuously marked or otherwise

designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity

on behalf of whom a Contribution has been received by the Licensor and

subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of

this License, each Contributor hereby grants to You a perpetual,

worldwide, non-exclusive, no-charge, royalty-free, irrevocable

publicly display, publicly perform, sublicense, and distribute the

Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of

this License, each Contributor hereby grants to You a perpetual,

worldwide, non-exclusive, no-charge, royalty-free, irrevocable

(except as stated in this section) patent license to make, have made,

use, offer to sell, sell, import, and otherwise transfer the Work,

where such license applies only to those patent claims licensable

by such Contributor that are necessarily infringed by their

Contribution(s) alone or by combination of their Contribution(s)

with the Work to which such Contribution(s) was submitted. If You

institute patent litigation against any entity (including a

cross-claim or counterclaim in a lawsuit) alleging that the Work

or a Contribution incorporated within the Work constitutes direct

or contributory patent infringement, then any patent licenses

granted to You under this License for that Work shall terminate

as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the

Work or Derivative Works thereof in any medium, with or without

modifications, and in Source or Object form, provided that You

meet the following conditions:

(a) You must give any other recipients of the Work or

Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices

stating that You changed the files; and

that You distribute, all copyright, patent, trademark, and

attribution notices from the Source form of the Work,

excluding those notices that do not pertain to any part of

the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its

distribution, then any Derivative Works that You distribute must

include a readable copy of the attribution notices contained

within such NOTICE file, excluding any notices that do not

pertain to any part of the Derivative Works, in at least one

of the following places: within a NOTICE text file distributed

as part of the Derivative Works; within the Source form or

documentation, if provided along with the Derivative Works; or,

within a display generated by the Derivative Works, if and

wherever such third-party notices normally appear. The contents

of the NOTICE file are for informational purposes only and

do not modify the License. You may add Your own attribution

notices within Derivative Works that You distribute, alongside

or as an addendum to the NOTICE text from the Work, provided

that such additional attribution notices cannot be construed

as modifying the License.

You may add Your own copyright statement to Your modifications and

may provide additional or different license terms and conditions

for use, reproduction, or distribution of Your modifications, or

for any such Derivative Works as a whole, provided Your use,

reproduction, and distribution of the Work otherwise complies with

the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,

any Contribution intentionally submitted for inclusion in the Work

by You to the Licensor shall be under the terms and conditions of

this License, without any additional terms or conditions.

Notwithstanding the above, nothing herein shall supersede or modify

the terms of any separate license agreement you may have executed

with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade

names, trademarks, service marks, or product names of the Licensor,

except as required for reasonable and customary use in describing the

origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or

agreed to in writing, Licensor provides the Work (and each

Contributor provides its Contributions) on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or

implied, including, without limitation, any warranties or conditions

of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A

PARTICULAR PURPOSE. You are solely responsible for determining the

appropriateness of using or redistributing the Work and assume any

risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,

whether in tort (including negligence), contract, or otherwise,

unless required by applicable law (such as deliberate and grossly

negligent acts) or agreed to in writing, shall any Contributor be

liable to You for damages, including any direct, indirect, special,

incidental, or consequential damages of any character arising as a

result of this License or out of the use or inability to use the

Work (including but not limited to damages for loss of goodwill,

work stoppage, computer failure or malfunction, or any and all

other commercial damages or losses), even if such Contributor

has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing

the Work or Derivative Works thereof, You may choose to offer,

and charge a fee for, acceptance of support, warranty, indemnity,

or other liability obligations and/or rights consistent with this

License. However, in accepting such obligations, You may act only

on Your own behalf and on Your sole responsibility, not on behalf

of any other Contributor, and only if You agree to indemnify,

defend, and hold each Contributor harmless for any liability

incurred by, or claims asserted against, such Contributor by reason

of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

mdREADME.md

921 B

# Hyperframes

HeyGen's **HyperFrames** packaged as an AIpkgs box: 15 Claude Code skills for

turning HTML into rendered video. Covers compositions, runtime animation

adapters (GSAP, anime.js, Lottie, Three.js, WAAPI, CSS, TypeGPU), Tailwind

styling, captions/voiceovers and media handling, the HyperFrames CLI, the

registry, and website/Remotion → HyperFrames conversion.

## Skills

`hyperframes`, `hyperframes-cli`, `hyperframes-registry`, `hyperframes-media`,

`website-to-hyperframes`, `remotion-to-hyperframes`, `contribute-catalog`,

`gsap`, `animejs`, `lottie`, `three`, `typegpu`, `waapi`, `css-animations`,

`tailwind`.

## Attribution

Imported from [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes)

by HeyGen. Licensed under Apache-2.0 (see `LICENSE.txt`). Several skills drive

the `hyperframes` CLI, which is installed separately.

## Install

```sh

aipkg install hyperframes/Hyperframes

```

mdskills/animejs/SKILL.md

3.2 kB

---

description: Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

---

# Anime.js for HyperFrames

HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.

## Contract

- Create animations or timelines synchronously during composition initialization.

- Set `autoplay: false` so Anime.js does not advance on its own clock.

- Register every returned animation or timeline on `window.__hfAnime`.

- Use finite durations and loop counts.

- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.

The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time in milliseconds.

## Basic Pattern

```html

const anim = anime({

targets: ".mark",

translateX: 280,

rotate: "1turn",

opacity: [0, 1],

duration: 1200,

easing: "easeOutExpo",

autoplay: false,

});

window.__hfAnime = window.__hfAnime || [];

window.__hfAnime.push(anim);

</script>

```

## Timeline Pattern

```html

const tl = anime.timeline({

autoplay: false,

easing: "easeOutCubic",

});

tl.add({

targets: ".title",

translateY: [40, 0],

opacity: [0, 1],

duration: 650,

}).add(

{

targets: ".accent",

scaleX: [0, 1],

duration: 450,

250,

);

window.__hfAnime = window.__hfAnime || [];

window.__hfAnime.push(tl);

</script>

```

## Module Builds

If you use an ES module build, the adapter does not care how the instance was created. It only needs the returned object to expose `seek()`, `pause()`, and preferably `play()`:

```html

import { animate } from "https://cdn.jsdelivr.net/npm/animejs/+esm";

const anim = animate(".chip", {

x: "18rem",

duration: 900,

autoplay: false,

});

window.__hfAnime = window.__hfAnime || [];

window.__hfAnime.push(anim);

</script>

```

## Good Uses

- Small SVG and DOM flourishes where Anime.js syntax is compact.

- Imported Anime.js examples that can be made seek-driven.

- Multiple independent micro-animations pushed into the same registry.

Use GSAP for complex scene sequencing unless the user specifically asks for Anime.js. GSAP is still the primary HyperFrames authoring path.

## Avoid

- Leaving `autoplay` at the Anime.js default.

- Depending on `anime.running` auto-discovery instead of explicit `window.__hfAnime.push(...)`.

- Infinite loops. Compute a finite repeat count from the composition duration.

- Building animations in timers, promises, event handlers, or after async asset loads.

## Validation

After editing a composition that uses Anime.js:

```bash

npx hyperframes lint

npx hyperframes validate

```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/animejs.ts`.

- Anime.js documentation for `autoplay`, `pause()`, and `seek()`: https://animejs.com/documentation/

mdskills/contribute-catalog/SKILL.md

7.1 kB

---

description: Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

---

# Contribute to HyperFrames Registry

Guide the user from idea to merged PR for a new registry block or component.

## Workflow

```

1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship

```

### Step 1: Clarify

Ask what they're building. The registry has two item types:

- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.

- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.

Then ask:

- One-sentence description of the effect

- Visual reference (URL, screenshot, or description)

- Who uses this and when?

### Step 2: Scaffold

Create the registry structure:

**For blocks:**

```

registry/blocks/{block-name}/

{block-name}.html

registry-item.json

```

**For components:**

```

registry/components/{component-name}/

{component-name}.html

registry-item.json

```

**Naming convention:**

| Item name | ID prefix | Example IDs |

| ---------------- | --------- | ---------------------- |

| `cap-hormozi` | `hz` | `hz-cg-0`, `hz-cw-3` |

| `cap-typewriter` | `tw` | `tw-cg-0`, `tw-ch-0-5` |

| `vfx-chrome` | `vc` | `vc-canvas` |

Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

**registry-item.json for blocks:**

```json

{

"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",

"name": "{block-name}",

"type": "hyperframes:block",

"title": "{Human Title}",

"description": "{one sentence}",

"dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social

"duration": 10, // adjust for your composition

"tags": ["{category}", "{subcategory}"],

"files": [

{

"path": "{block-name}.html",

"target": "compositions/{block-name}.html",

"type": "hyperframes:composition"

}

]

}

```

**registry-item.json for components** (no `dimensions` or `duration`):

```json

{

"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",

"name": "{component-name}",

"type": "hyperframes:component",

"title": "{Human Title}",

"description": "{one sentence}",

"tags": ["{category}"],

"files": [

{

"path": "{component-name}.html",

"target": "compositions/components/{component-name}.html",

"type": "hyperframes:snippet"

}

]

}

```

### Step 3: Build

Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.

#### Caption blocks

**Non-negotiable caption rules:**

- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).

- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`

- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group

- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`

- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group

- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.

**Per-character animation** (typewriter, scramble):

- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`

- Stagger via `tl.set` at computed intervals from word timestamps

- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)

**Positioning variants:**

- Centered: `display: flex; align-items: center; justify-content: center;`

- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`

- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`

#### VFX blocks (Three.js)

- Use `three@0.147.0` from CDN (global script)

- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame

- State proxy pattern: GSAP animates plain JS object, render function reads it

- Seeded PRNG (`mulberry32`) for randomness

#### All types

- `data-composition-id` MUST match `window.__timelines["id"]`

- All element IDs prefixed with block abbreviation

- `gsap.timeline({ paused: true })` — always paused

- No `Math.random()`, no `Date.now()`

### Step 4: Validate

```bash

hyperframes lint # 0 errors required

hyperframes validate --no-contrast # 0 console errors required

```

### Step 5: Preview

```bash

# Render preview video

hyperframes render -o preview.mp4

# Snapshot for visual QA

hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publish to hyperframes.dev for review

npx hyperframes publish

```

**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:

- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)

- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

### Step 6: Ship

**All steps are required. Missing any one produces a broken catalog entry.**

`{kind}` is `blocks` or `components` depending on what you built in Step 1.

```bash

# 1. Create branch

git checkout -b feat/registry-{name}

# 2. Format HTML

npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:

# { "name": "{name}", "type": "hyperframes:block" } (or "hyperframes:component")

# 4. Generate catalog docs page

npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to hyperframes.dev so reviewers can preview

npx hyperframes publish

# 6. Stage everything

git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

# 7. Commit

git commit -m "feat(registry): add {name} — {one sentence}"

# 8. Push and open PR with hyperframes.dev link

git push origin feat/registry-{name}

gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"

```

**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.

## Quality Gate

- [ ] `hyperframes lint` → 0 errors

- [ ] `hyperframes validate` → 0 console errors

- [ ] `npx oxfmt --check` passes

- [ ] `registry/registry.json` updated with new entry

- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)

- [ ] `npx hyperframes publish` run (claim your project URL)

- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)

- [ ] All IDs unique and prefixed

mdskills/contribute-catalog/templates.md

11 kB

# Contribute Templates

Copy-paste starter templates for each component type. These embed the proven patterns that pass lint and validate.

## Caption Template

```html

<!doctype html>

<head>

<link

href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800;900&display=swap"

rel="stylesheet"

<style>

*::before,

*::after {

margin: 0;

padding: 0;

box-sizing: border-box;

}

body {

background: #111;

overflow: hidden;

}

#root-BLOCKNAME {

position: relative;

width: 1920px;

height: 1080px;

overflow: hidden;

background: #111;

}

.cap-container {

position: absolute;

top: 0;

left: 0;

width: 100%;

height: 100%;

display: flex;

align-items: center;

justify-content: center;

}

.cg {

position: absolute;

display: flex;

align-items: center;

justify-content: center;

gap: 32px;

max-width: 1700px;

overflow: visible;

opacity: 0;

visibility: hidden;

}

.cw {

font-family: "Montserrat", sans-serif;

font-weight: 900;

font-size: 128px;

color: #ffffff;

text-transform: uppercase;

line-height: 1;

display: inline-block;

-webkit-text-stroke: 3px rgba(0, 0, 0, 0.8);

paint-order: stroke fill;

text-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);

}

</style>

</head>

<body>

<div

id="root-BLOCKNAME"

data-composition-id="BLOCKNAME"

data-start="0"

data-duration="9"

data-width="1920"

data-height="1080"

<div

id="drv-BLOCKNAME"

class="clip"

data-start="0"

data-duration="9"

data-track-index="0"

style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"

></div>

</div>

(function () {

window.__timelines = window.__timelines || {};

// REPLACE with actual transcript data

var WORDS = [

{ text: "Welcome", start: 0.3, end: 0.65 },

{ text: "to", start: 0.65, end: 0.8 },

{ text: "the", start: 0.8, end: 0.95 },

{ text: "future", start: 0.95, end: 1.4 },

// ... add all words

];

var GROUPS = [

{ start: 0.3, end: 1.3, wordStart: 0, wordEnd: 3, text: "Welcome to the future" },

// ... add all groups

];

var container = document.getElementById("cc-BLOCKNAME");

GROUPS.forEach(function (g, gi) {

var groupEl = document.createElement("div");

groupEl.id = "PREFIX-cg-" + gi;

groupEl.className = "cg";

for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {

var wordEl = document.createElement("span");

wordEl.id = "PREFIX-cw-" + wi;

wordEl.className = "cw";

wordEl.textContent = WORDS[wi].text;

groupEl.appendChild(wordEl);

}

// Pretext overflow prevention

if (window.__hyperframes && window.__hyperframes.fitTextFontSize) {

var _fit = window.__hyperframes.fitTextFontSize(g.text.toUpperCase(), {

fontFamily: "Montserrat",

fontWeight: 900,

maxWidth: 1550,

baseFontSize: 128,

minFontSize: 48,

});

if (_fit.fontSize < 128) {

for (var _fi = 0; _fi < groupEl.children.length; _fi++) {

groupEl.children[_fi].style.fontSize = _fit.fontSize + "px";

}

container.appendChild(groupEl);

});

var tl = gsap.timeline({ paused: true });

GROUPS.forEach(function (g, gi) {

var groupEl = document.getElementById("PREFIX-cg-" + gi);

// SHOW — set opacity to 1 (never use tl.from with opacity:0 here)

tl.set(groupEl, { opacity: 1, visibility: "visible" }, g.start);

// ENTRANCE — customize this per style

tl.from(groupEl, { scale: 1.3, duration: 0.15, ease: "back.out(2)" }, g.start);

// KARAOKE — highlight each word

for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {

var wordEl = document.getElementById("PREFIX-cw-" + wi);

tl.to(wordEl, { color: "#FFD700", scale: 1.1, duration: 0.06 }, WORDS[wi].start);

tl.to(wordEl, { color: "#FFFFFF", scale: 1, duration: 0.08 }, WORDS[wi].end);

}

// EXIT

tl.to(groupEl, { opacity: 0, scale: 0.9, duration: 0.1 }, g.end - 0.1);

// HARD KILL (mandatory)

tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end);

});

window.__timelines["BLOCKNAME"] = tl;

})();

</script>

</body>

</html>

```

**Replace checklist:**

- `BLOCKNAME` → your block name (e.g., `cap-swoosh`)

- `PREFIX` → short unique prefix for IDs (e.g., `sw`)

- Font family, weight, size → your style's typography

- Entrance animation → your style's entrance

- Karaoke highlight → your style's active word treatment

- Colors → your style's palette

---

## VFX Template

```html

<!doctype html>

<head>

<style>

*::before,

*::after {

margin: 0;

padding: 0;

box-sizing: border-box;

}

body {

background: #030308;

overflow: hidden;

}

#root-BLOCKNAME {

position: relative;

width: 1920px;

height: 1080px;

overflow: hidden;

background: #030308;

}

#canvas-BLOCKNAME {

position: absolute;

top: 0;

left: 0;

width: 1920px;

height: 1080px;

}

</style>

</head>

<body>

<div

id="root-BLOCKNAME"

data-composition-id="BLOCKNAME"

data-start="0"

data-duration="10"

data-width="1920"

data-height="1080"

<div

id="drv-BLOCKNAME"

class="clip"

data-start="0"

data-duration="10"

data-track-index="0"

style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"

></div>

</div>

(function () {

window.__timelines = window.__timelines || {};

// Seeded PRNG — NEVER use Math.random()

function mulberry32(a) {

return function () {

a |= 0;

a = (a + 0x6d2b79f5) | 0;

var t = Math.imul(a ^ (a >>> 15), 1 | a);

t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;

return ((t ^ (t >>> 14)) >>> 0) / 4294967296;

};

}

var rng = mulberry32(42);

var W = 1920,

H = 1080;

var canvas = document.getElementById("canvas-BLOCKNAME");

var renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });

renderer.setSize(W, H);

renderer.setPixelRatio(1);

renderer.toneMapping = THREE.ACESFilmicToneMapping;

renderer.toneMappingExposure = 1.1;

var scene = new THREE.Scene();

scene.background = new THREE.Color(0x030308);

var camera = new THREE.PerspectiveCamera(50, W / H, 0.1, 100);

camera.position.set(0, 0, 8);

// YOUR SCENE SETUP HERE

// - lights

// - geometry

// - materials

// State proxy — GSAP animates this, render reads it

var st = {

rotY: 0,

camZ: 8,

// add your animated properties

};

var tl = gsap.timeline({ paused: true });

// YOUR TWEENS HERE

tl.to(st, { rotY: Math.PI * 2, duration: 10, ease: "none" }, 0);

window.__timelines["BLOCKNAME"] = tl;

function renderScene() {

// Apply state to Three.js objects

camera.position.z = st.camZ;

// mesh.rotation.y = st.rotY;

renderer.render(scene, camera);

}

// Render via onUpdate — NO requestAnimationFrame

tl.eventCallback("onUpdate", renderScene);

renderScene();

})();

</script>

</body>

</html>

```

**Replace checklist:**

- `BLOCKNAME` → your block name (e.g., `vfx-chrome-blob`)

- Scene setup → your geometry, lights, materials

- State proxy → your animated properties

- Tweens → your animation timeline

- renderScene → apply state to your Three.js objects

---

## registry-item.json Templates

**For blocks:**

```json

{

"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",

"name": "BLOCKNAME",

"type": "hyperframes:block",

"title": "Human-Readable Title",

"description": "One sentence: what it does and who uses it",

"dimensions": { "width": 1920, "height": 1080 },

"duration": 10,

"tags": ["category", "subcategory"],

"files": [

{

"path": "BLOCKNAME.html",

"target": "compositions/BLOCKNAME.html",

"type": "hyperframes:composition"

}

]

}

```

**For components** (no `dimensions` or `duration`):

```json

{

"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",

"name": "COMPONENTNAME",

"type": "hyperframes:component",

"title": "Human-Readable Title",

"description": "One sentence: what it does",

"tags": ["category"],

"files": [

{

"path": "COMPONENTNAME.html",

"target": "compositions/components/COMPONENTNAME.html",

"type": "hyperframes:snippet"

}

]

}

```

Tags by category:

- Captions: `captions`, `viral`, `professional`, `karaoke`, `minimal`

- VFX: `three-js`, `particles`, `shader`, `gpu`

- Transitions: `transition`, `shader`, `wipe`, `dissolve`

- Blocks: `lower-third`, `social`, `title-card`, `data-viz`

- Components: `effect`, `overlay`, `text-treatment`

---

## Component Template

```html

<!doctype html>

<head>

<style>

*::before,

*::after {

margin: 0;

padding: 0;

box-sizing: border-box;

}

body {

background: transparent;

overflow: hidden;

}

.COMPNAME-wrap {

position: absolute;

inset: 0;

overflow: hidden;

pointer-events: none;

}

</style>

</head>

<body>

</div>

(function () {

// Component snippet — no data-composition-id, no __timelines.

// The parent composition controls timing.

// Keep all class names and IDs prefixed with COMPNAME.

})();

</script>

</body>

</html>

```

**Replace checklist:**

- `COMPNAME` → your component name (e.g., `shimmer-sweep`)

- Background should be `transparent` so it overlays cleanly

- No `data-composition-id` or `window.__timelines` — the parent owns timing

mdskills/css-animations/SKILL.md

3.8 kB

---

description: CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

---

# CSS Animations for HyperFrames

HyperFrames can seek CSS keyframe animations through its `css` runtime adapter. Use this for simple repeated motifs, background motion, shimmer, glow, masks, and non-sequenced decoration.

For scene choreography, GSAP is usually clearer. CSS animations work best when the motion belongs to one element and has a fixed duration.

## Contract

- Put the animated element in the DOM before runtime initialization finishes.

- Give timed elements a `data-start` value so local animation time matches the clip.

- Use finite `animation-duration` and `animation-iteration-count` because the negative-delay fallback cannot represent unbounded duration in environments without WAAPI-backed CSS animations.

- Prefer `animation-fill-mode: both` so seeked states hold before and after active motion.

- Avoid wall-clock JavaScript, hover-triggered state, and class toggles that depend on user events.

The adapter discovers elements with computed `animation-name`, seeks their browser `Animation` handles when available, and falls back to pausing with negative `animation-delay`.

## Basic Pattern

```html

<div

id="pulse-ring"

class="clip pulse-ring"

data-start="0"

data-duration="4"

data-track-index="2"

></div>

<style>

.pulse-ring {

width: 280px;

height: 280px;

border: 4px solid rgba(255, 255, 255, 0.7);

border-radius: 50%;

animation-name: pulse-ring;

animation-duration: 1200ms;

animation-timing-function: cubic-bezier(0.2, 0, 0, 1);

animation-iteration-count: 3;

animation-fill-mode: both;

}

@keyframes pulse-ring {

from {

opacity: 0;

transform: scale(0.82);

}

35% {

opacity: 1;

}

to {

opacity: 0;

transform: scale(1.18);

}

</style>

```

## Stagger Pattern

Use CSS custom properties to avoid duplicating keyframes:

```html

</div>

<style>

.dots span {

display: inline-block;

width: 18px;

height: 18px;

margin-right: 10px;

border-radius: 50%;

background: currentColor;

animation: dot-pop 900ms ease-out both;

animation-delay: calc(var(--i) * 120ms);

}

@keyframes dot-pop {

from {

opacity: 0;

transform: translateY(18px) scale(0.75);

}

to {

opacity: 1;

transform: translateY(0) scale(1);

}

</style>

```

## Good Uses

- Decorative loops with a known repeat count.

- Mask, glow, shimmer, grain, and subtle parallax layers.

- Simple one-element entrances where a full JS timeline would be excessive.

## Avoid

- Infinite CSS animations unless you have verified the browser exposes seekable WAAPI-backed CSS animation handles. Prefer a finite iteration count covering the visible duration.

- Animating layout properties like `top`, `left`, `width`, or `height` when transforms work.

- Relying on hover, focus, scroll, or media queries to trigger render-critical motion.

- Changing animation classes after startup unless another deterministic timeline controls that change.

## Validation

After editing CSS animation compositions:

```bash

npx hyperframes lint

npx hyperframes validate

```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/css.ts`.

- MDN CSS animation documentation: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation

- MDN `animation-fill-mode`: https://developer.mozilla.org/en-US/docs/Web/CSS/animation-fill-mode

mdskills/gsap/references/effects.md

8.6 kB

# GSAP Effects for HyperFrames

Drop-in animation patterns for HyperFrames compositions. Each effect is self-contained with HTML, CSS, and code.

All effects follow HyperFrames composition rules — deterministic, no randomness, timelines registered via `window.__timelines`.

## Table of Contents

- [Typewriter](#typewriter)

- [Audio Visualizer](#audio-visualizer)

---

## Typewriter

Reveal text character by character using GSAP's TextPlugin.

### Required Plugin

```html

gsap.registerPlugin(TextPlugin);

</script>

```

### Basic Typewriter

```js

const text = "Hello, world!";

const cps = 10; // chars per second: 3-5 dramatic, 8-12 conversational, 15-20 energetic

tl.to(

"#typed-text",

{ text: { value: text }, duration: text.length / cps, ease: "none" },

startTime,

);

```

### With Blinking Cursor

Three rules:

1. **One cursor visible at a time** — hide previous before showing next.

2. **Cursor must blink when idle** — after typing, during pauses.

3. **No gap between text and cursor** — elements must be flush in HTML.

```html

```

```css

@keyframes blink {

0%,

100% {

opacity: 1;

}

50% {

opacity: 0;

}

.cursor-blink {

animation: blink 0.8s step-end infinite;

}

.cursor-solid {

animation: none;

opacity: 1;

}

.cursor-hide {

animation: none;

opacity: 0;

}

```

Pattern: blink → solid (typing starts) → type → solid → blink (typing done).

```js

tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], startTime);

tl.to("#typed-text", { text: { value: text }, duration: dur, ease: "none" }, startTime);

tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], startTime + dur);

```

### Backspacing

TextPlugin removes from front — wrong for backspace. Use manual substring removal:

```js

function backspace(tl, selector, word, startTime, cps) {

const el = document.querySelector(selector);

const interval = 1 / cps;

for (let i = word.length - 1; i >= 0; i--) {

tl.call(

() => {

el.textContent = word.slice(0, i);

[],

startTime + (word.length - i) * interval,

);

}

return word.length * interval;

}

```

### Spacing with Static Text

When a typewriter word sits next to static text, use `margin-left` on a wrapper span. Don't use flex gap (spaces cursor from text) or trailing space in static text (collapses when dynamic is empty).

```html

<span style="font-size:40px; color:#555;">Ship something</span>

</div>

```

### Word Rotation

Type → hold → backspace → next word. Cursor blinks during every idle moment (holds, after backspace).

```js

words.forEach((word, i) => {

const typeDur = word.length / 10;

// Solid while typing

tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);

tl.to("#typed-text", { text: { value: word }, duration: typeDur, ease: "none" }, offset);

// Blink during hold

tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + typeDur);

offset += typeDur + 1.5; // hold

if (i < words.length - 1) {

tl.call(() => cursor.classList.replace("cursor-blink", "cursor-solid"), [], offset);

const clearDur = backspace(tl, el, word, offset, 20);

tl.call(() => cursor.classList.replace("cursor-solid", "cursor-blink"), [], offset + clearDur);

offset += clearDur + 0.3;

}

});

```

### Appending Words

Build a sentence word-by-word into the same element:

```js

let accumulated = "";

words.forEach((word) => {

const target = accumulated + (accumulated ? " " : "") + word;

const newChars = target.length - accumulated.length;

tl.to("#typed-text", { text: { value: target }, duration: newChars / 10, ease: "none" }, offset);

accumulated = target;

offset += newChars / 10 + 0.3;

});

```

### Multi-Line Cursor Handoff

When handing off between typewriter lines: hide previous → blink new → pause → solid when typing. Never go hidden→solid (skips idle state).

```js

tl.call(

() => {

prevCursor.classList.replace("cursor-blink", "cursor-hide");

nextCursor.classList.replace("cursor-hide", "cursor-blink");

[],

handoffTime,

);

const typeStart = handoffTime + 0.5; // brief blink pause

tl.call(() => nextCursor.classList.replace("cursor-blink", "cursor-solid"), [], typeStart);

tl.to("#next-text", { text: { value: text }, duration: dur, ease: "none" }, typeStart);

tl.call(() => nextCursor.classList.replace("cursor-solid", "cursor-blink"), [], typeStart + dur);

```

### Timing Guide

| CPS | Feel | Good for |

| ----- | ---------------- | -------------------------- |

| 3-5 | Slow, deliberate | Dramatic reveals, suspense |

| 8-12 | Natural typing | Dialogue, narration |

| 15-20 | Fast, energetic | Tech demos, code |

| 30+ | Near-instant | Filling long blocks |

---

## Audio Visualizer

Pre-extract audio data, drive canvas/DOM rendering from GSAP timeline.

### Extract Audio Data

```bash

python scripts/extract-audio-data.py audio.mp3 -o audio-data.json

python scripts/extract-audio-data.py video.mp4 --fps 30 --bands 16 -o audio-data.json

```

Requires ffmpeg and numpy.

### Data Format

```json

{

"fps": 30, "totalFrames": 5415,

"frames": [{ "time": 0.0, "rms": 0.42, "bands": [0.8, 0.6, 0.3, ...] }]

}

```

- **rms** (0-1): overall loudness, normalized across track

- **bands[]** (0-1): frequency magnitudes. Index 0 = bass, higher = treble. Each normalized independently.

### Loading the Data

```js

// Option A: inline (small files, under ~500KB)

var AUDIO_DATA = {

/* paste audio-data.json contents */

};

// Option B: sync XHR (large files — must be synchronous for deterministic timeline construction)

var xhr = new XMLHttpRequest();

xhr.open("GET", "audio-data.json", false);

xhr.send();

var AUDIO_DATA = JSON.parse(xhr.responseText);

```

**Do NOT use async `fetch()` to load audio data.** HyperFrames requires synchronous timeline construction — the capture engine reads `window.__timelines` synchronously after page load. Building timelines inside `.then()` callbacks means the timeline isn't ready when capture starts.

### Rendering Approaches

**Canvas 2D** (most common — bars, waveforms, circles, gradients):

```js

for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {

tl.call(

() => {

const frame = AUDIO_DATA.frames[f];

ctx.clearRect(0, 0, canvas.width, canvas.height);

// draw using frame.rms and frame.bands

[],

f / AUDIO_DATA.fps,

);

}

```

**WebGL / Three.js** — HyperFrames patches `THREE.Clock` for deterministic time. Update uniforms from audio data each frame.

**DOM Elements** — fine for < 20 elements, less performant than Canvas for many.

### Spatial Mapping

- **Horizontal**: bass left, treble right (iterate bands left-to-right)

- **Vertical**: bass bottom, treble top

- **Circular**: bass at 12 o'clock, wrap clockwise; mirror for full circle

### Smoothing

```js

let prev = null;

const smoothing = 0.25; // 0.1-0.2 snappy, 0.3-0.5 flowing

function smooth(f) {

const raw = AUDIO_DATA.frames[f];

if (!prev) {

prev = { rms: raw.rms, bands: [...raw.bands] };

return prev;

}

prev = {

rms: prev.rms * smoothing + raw.rms * (1 - smoothing),

bands: raw.bands.map((b, i) => prev.bands[i] * smoothing + b * (1 - smoothing)),

};

return prev;

}

```

### Motion Principles

- **Bass drives big moves** — scale, glow, position shifts

- **Treble drives detail** — shimmer, flicker, edge effects

- **RMS drives globals** — background brightness, overall energy

- Pick 2-3 properties to animate. More looks noisy.

- Keep minimums above zero — quiet sections need life.

### Band Count

| Bands | Detail | Good for |

| ----- | --------- | -------------------------- |

| 4 | Low | Background glow, pulsing |

| 8 | Medium | Bar charts, basic spectrum |

| 16 | High | Detailed EQ (default) |

| 32 | Very high | Dense radial layouts |

### Layering

Layer multiple canvases with CSS z-index for depth — a background layer driven by bass/rms and a foreground layer driven by individual bands creates depth without complexity.

```html

```

pyskills/gsap/scripts/extract-audio-data.py

6.3 kB

#!/usr/bin/env python3

"""

Extract per-frame audio visualization data from an audio or video file.

Outputs JSON with RMS amplitude and frequency band data at the target FPS,

ready to embed in a HyperFrames composition.

Usage:

python extract-audio-data.py input.mp3 -o audio-data.json

python extract-audio-data.py input.mp4 --fps 30 --bands 16 -o audio-data.json

Requirements:

- Python 3.9+

- ffmpeg (for decoding audio)

- numpy (pip install numpy)

"""

import argparse

import json

import subprocess

import sys

import numpy as np

# ---------------------------------------------------------------------------

# FFT parameters

# A 4096-sample window gives ~10.8 Hz per bin at 44100Hz — enough to resolve

# low-frequency bands cleanly. The per-frame audio slice (44100/30 = 1470

# samples at 30fps) is too small and causes low bands to map to the same bins.

# Frequency range 30Hz–16kHz covers the useful range for music. Below 30Hz is

# sub-bass most speakers can't reproduce; above 16kHz is noise/harmonics that

# don't contribute to perceived rhythm or melody.

# ---------------------------------------------------------------------------

SAMPLE_RATE = 44100

FFT_SIZE = 4096

MIN_FREQ = 30.0

MAX_FREQ = 16000.0

def decode_audio(path: str) -> np.ndarray:

"""Decode audio to mono float32 samples via ffmpeg."""

cmd = [

"ffmpeg", "-i", path,

"-vn", "-ac", "1", "-ar", str(SAMPLE_RATE),

"-f", "s16le", "-acodec", "pcm_s16le",

"-loglevel", "error",

"pipe:1",

]

result = subprocess.run(cmd, capture_output=True)

if result.returncode != 0:

print(f"ffmpeg error: {result.stderr.decode()}", file=sys.stderr)

sys.exit(1)

return np.frombuffer(result.stdout, dtype=np.int16).astype(np.float32) / 32768.0

def compute_band_edges(n_bands: int) -> np.ndarray:

"""Logarithmically-spaced frequency band edges from MIN_FREQ to MAX_FREQ."""

return np.array([

MIN_FREQ * (MAX_FREQ / MIN_FREQ) ** (i / n_bands)

for i in range(n_bands + 1)

])

def compute_fft_bands(

windowed: np.ndarray, freq_per_bin: float, n_bins: int,

band_edges: np.ndarray, n_bands: int,

) -> np.ndarray:

"""Compute peak magnitude in logarithmically-spaced frequency bands."""

magnitudes = np.abs(np.fft.rfft(windowed))

bands = np.zeros(n_bands)

for b in range(n_bands):

low_bin = max(0, int(band_edges[b] / freq_per_bin))

high_bin = min(n_bins, int(band_edges[b + 1] / freq_per_bin))

if high_bin <= low_bin:

high_bin = low_bin + 1

# Clamp to valid range to avoid empty slices

low_bin = min(low_bin, n_bins - 1)

high_bin = min(high_bin, n_bins)

bands[b] = np.max(magnitudes[low_bin:high_bin])

return bands

def extract(path: str, fps: int, n_bands: int) -> dict:

"""Extract per-frame audio data."""

print(f"Decoding audio from {path}...", file=sys.stderr)

samples = decode_audio(path)

duration = len(samples) / SAMPLE_RATE

frame_step = SAMPLE_RATE // fps

total_frames = int(duration * fps)

print(f"Duration: {duration:.1f}s, {total_frames} frames at {fps}fps", file=sys.stderr)

print(f"FFT window: {FFT_SIZE} samples ({SAMPLE_RATE / FFT_SIZE:.1f} Hz/bin)", file=sys.stderr)

print(f"Frequency range: {MIN_FREQ:.0f}-{MAX_FREQ:.0f} Hz, {n_bands} bands", file=sys.stderr)

# Precompute constants

hann = np.hanning(FFT_SIZE)

band_edges = compute_band_edges(n_bands)

freq_per_bin = SAMPLE_RATE / FFT_SIZE

n_bins = FFT_SIZE // 2 + 1

half_fft = FFT_SIZE // 2

# Pass 1: extract raw values

rms_values = np.zeros(total_frames)

band_values = np.zeros((total_frames, n_bands))

for f in range(total_frames):

# RMS from the frame's audio slice

rms_start = f * frame_step

rms_end = rms_start + frame_step

frame_slice = samples[rms_start:min(rms_end, len(samples))]

if len(frame_slice) > 0:

rms_values[f] = np.sqrt(np.mean(frame_slice ** 2))

# FFT from a centered 4096-sample window

center = rms_start + frame_step // 2

win_start = center - half_fft

win_end = center + half_fft

if win_start >= 0 and win_end <= len(samples):

window = samples[win_start:win_end] * hann

else:

# Zero-pad at edges

padded = np.zeros(FFT_SIZE)

src_start = max(0, win_start)

src_end = min(len(samples), win_end)

dst_start = src_start - win_start

dst_end = dst_start + (src_end - src_start)

padded[dst_start:dst_end] = samples[src_start:src_end]

window = padded * hann

band_values[f] = compute_fft_bands(window, freq_per_bin, n_bins, band_edges, n_bands)

# Pass 2: normalize

peak_rms = rms_values.max() if total_frames > 0 else 1.0

if peak_rms > 0:

rms_values /= peak_rms

# Per-band normalization so treble is visible alongside louder bass

band_peaks = band_values.max(axis=0)

band_peaks[band_peaks == 0] = 1.0

band_values /= band_peaks

# Build output

frames = []

for f in range(total_frames):

frames.append({

"time": round(f / fps, 4),

"rms": round(float(rms_values[f]), 4),

"bands": [round(float(b), 4) for b in band_values[f]],

})

return {

"duration": round(duration, 4),

"fps": fps,

"bands": n_bands,

"totalFrames": total_frames,

"frames": frames,

}

def main():

parser = argparse.ArgumentParser(description="Extract per-frame audio visualization data")

parser.add_argument("input", help="Audio or video file")

parser.add_argument("-o", "--output", default="audio-data.json", help="Output JSON path")

parser.add_argument("--fps", type=int, default=30, help="Frames per second (default: 30)")

parser.add_argument("--bands", type=int, default=16, help="Number of frequency bands (default: 16)")

args = parser.parse_args()

if args.fps < 1:

parser.error("--fps must be at least 1")

if args.bands < 1:

parser.error("--bands must be at least 1")

data = extract(args.input, args.fps, args.bands)

with open(args.output, "w") as f:

json.dump(data, f)

print(f"Wrote {args.output} ({data['totalFrames']} frames, {data['bands']} bands)", file=sys.stderr)

if __name__ == "__main__":

main()

mdskills/gsap/SKILL.md

7.6 kB

---

description: GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

---

# GSAP

## HyperFrames Contract

HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.

```html

window.__timelines = window.__timelines || {};

const tl = gsap.timeline({ paused: true });

tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);

tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root

</script>

```

- The registry key must match the composition root's `data-composition-id`.

- Do not call `tl.play()` for render-critical motion.

- Do not build timelines inside async code, timers, or event handlers.

- Keep loops finite. HyperFrames renders finite video durations.

## Core Tween Methods

- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.

- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).

- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.

- **gsap.set(targets, vars)** — apply immediately (duration 0).

Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).

## Common vars

- **duration** — seconds (default 0.5).

- **delay** — seconds before start.

- **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.

- **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.

- **overwrite** — `false` (default), `true`, or `"auto"`.

- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration. **yoyo** — alternates direction with repeat.

- **onComplete**, **onStart**, **onUpdate** — callbacks.

- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.

## Transforms and CSS

Prefer GSAP's **transform aliases** over raw `transform` string:

| GSAP property | Equivalent |

| --------------------------- | ------------------- |

| `x`, `y`, `z` | translateX/Y/Z (px) |

| `xPercent`, `yPercent` | translateX/Y in % |

| `scale`, `scaleX`, `scaleY` | scale |

| `rotation` | rotate (deg) |

| `rotationX`, `rotationY` | 3D rotate |

| `skewX`, `skewY` | skew |

| `transformOrigin` | transform-origin |

- **autoAlpha** — prefer over `opacity`. At 0: also sets `visibility: hidden`.

- **CSS variables** — `"--hue": 180`.

- **svgOrigin** _(SVG only)_ — global SVG coordinate space origin. Don't combine with `transformOrigin`.

- **Directional rotation** — `"360_cw"`, `"-170_short"`, `"90_ccw"`.

- **clearProps** — `"all"` or comma-separated; removes inline styles on complete.

- **Relative values** — `"+=20"`, `"-=10"`, `"*=2"`.

## Function-Based Values

```javascript

gsap.to(".item", {

x: (i, target, targets) => i * 50,

stagger: 0.1,

});

```

## Easing

Built-in eases: `power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`.

## Defaults

```javascript

gsap.defaults({ duration: 0.6, ease: "power2.out" });

```

## Controlling Tweens

```javascript

const tween = gsap.to(".box", { x: 100 });

tween.pause();

tween.play();

tween.reverse();

tween.kill();

tween.progress(0.5);

tween.time(0.2);

```

## gsap.matchMedia() (Responsive + Accessibility)

Runs setup only when a media query matches; auto-reverts when it stops matching.

```javascript

let mm = gsap.matchMedia();

mm.add(

{

isDesktop: "(min-width: 800px)",

reduceMotion: "(prefers-reduced-motion: reduce)",

(context) => {

const { isDesktop, reduceMotion } = context.conditions;

gsap.to(".box", {

rotation: isDesktop ? 360 : 180,

duration: reduceMotion ? 0 : 2,

});

);

```

---

## Timelines

### Creating a Timeline

```javascript

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });

tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

```

### Position Parameter

Third argument controls placement:

- **Absolute**: `1` — at 1s

- **Relative**: `"+=0.5"` — after end; `"-=0.2"` — before end

- **Label**: `"intro"`, `"intro+=0.3"`

- **Alignment**: `"<"` — same start as previous; `">"` — after previous ends; `"<0.2"` — 0.2s after previous starts

```javascript

tl.to(".a", { x: 100 }, 0);

tl.to(".b", { y: 50 }, "<"); // same start as .a

tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts

```

### Labels

```javascript

tl.addLabel("intro", 0);

tl.to(".a", { x: 100 }, "intro");

tl.addLabel("outro", "+=0.5");

tl.play("outro");

tl.tweenFromTo("intro", "outro");

```

### Timeline Options

- **paused: true** — create paused; call `.play()` to start.

- **repeat**, **yoyo** — apply to whole timeline.

- **defaults** — vars merged into every child tween.

### Nesting Timelines

```javascript

const master = gsap.timeline();

const child = gsap.timeline();

child.to(".a", { x: 100 }).to(".b", { y: 50 });

master.add(child, 0);

```

### Playback Control

`tl.play()`, `tl.pause()`, `tl.reverse()`, `tl.restart()`, `tl.time(2)`, `tl.progress(0.5)`, `tl.kill()`.

---

## Performance

### Prefer Transform and Opacity

Animating `x`, `y`, `scale`, `rotation`, `opacity` stays on the compositor. Avoid `width`, `height`, `top`, `left` when transforms achieve the same effect.

### will-change

```css

will-change: transform;

```

Only on elements that actually animate.

### gsap.quickTo() for Frequent Updates

```javascript

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),

yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });

container.addEventListener("mousemove", (e) => {

xTo(e.pageX);

yTo(e.pageY);

});

```

### Stagger > Many Tweens

Use `stagger` instead of separate tweens with manual delays.

### Cleanup

Pause or kill off-screen animations.

---

## References (loaded on demand)

- **[references/effects.md](references/effects.md)** — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.

## Best Practices

- Use camelCase property names; prefer transform aliases and autoAlpha.

- Prefer timelines over chaining with delay; use the position parameter.

- Add labels with `addLabel()` for readable sequencing.

- Pass defaults into timeline constructor.

- Store tween/timeline return value when controlling playback.

## Do Not

- Animate layout properties (width/height/top/left) when transforms suffice.

- Use both svgOrigin and transformOrigin on the same SVG element.

- Chain animations with delay when a timeline can sequence them.

- Create tweens before the DOM exists.

- Skip cleanup — always kill tweens when no longer needed.

- Use infinite repeat values in HyperFrames compositions. Use finite repeat counts computed from the visible duration.

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.

- GSAP documentation: https://gsap.com/docs/v3/

- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/

mdskills/hyperframes-cli/SKILL.md

8.7 kB

---

description: HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

---

# HyperFrames CLI

Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.

## Workflow

1. **Scaffold** — `npx hyperframes init my-video`

2. **Write** — author HTML composition (see the `hyperframes` skill)

3. **Lint** — `npx hyperframes lint`

4. **Visual inspect** — `npx hyperframes inspect`

5. **Preview** — `npx hyperframes preview`

6. **Render** — `npx hyperframes render`

Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.

## Scaffolding

```bash

npx hyperframes init my-video # interactive wizard

npx hyperframes init my-video --example warm-grain # pick an example

npx hyperframes init my-video --video clip.mp4 # with video file

npx hyperframes init my-video --audio track.mp3 # with audio file

npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime

npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)

```

Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.

`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.

When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.

## Linting

```bash

npx hyperframes lint # current directory

npx hyperframes lint ./my-project # specific project

npx hyperframes lint --verbose # info-level findings

npx hyperframes lint --json # machine-readable

```

Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).

## Visual Inspect

```bash

npx hyperframes inspect # inspect rendered layout over the timeline

npx hyperframes inspect ./my-project # specific project

npx hyperframes inspect --json # agent-readable findings

npx hyperframes inspect --samples 15 # denser timeline sweep

npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps

```

Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:

- Text extending outside the nearest visual container or bubble

- Text clipped by its own fixed-width/fixed-height box

- Text extending outside the composition canvas

- Children escaping clipping containers

Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.

`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.

## Previewing

```bash

npx hyperframes preview # serve current directory

npx hyperframes preview --port 4567 # custom port (default 3002)

```

Hot-reloads on file changes. Opens the studio in your browser automatically.

When handing a project back to the user, use the Studio project URL, not the

source `index.html` path:

```text

http://localhost:<port>/#project/<project-name>

```

Use the actual port from the preview output and the project directory name. For

example, after `npx hyperframes preview --port 3017` in `codex-openai-video`,

report `http://localhost:3017/#project/codex-openai-video`.

Treat `index.html` as source-code context only. It is fine to link it as an

implementation file, but do not label it as the project or preview surface.

## Rendering

```bash

npx hyperframes render # standard MP4

npx hyperframes render --output final.mp4 # named output

npx hyperframes render --quality draft # fast iteration

npx hyperframes render --fps 60 --quality high # final delivery

npx hyperframes render --format webm # transparent WebM

npx hyperframes render --docker # byte-identical

```

| -------------------- | --------------------- | -------------------------- | ------------------------------------------------------------------ |

| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |

| `--gpu` | flag | off | GPU-accelerated encoding |

**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.

**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `hyperframes` skill for the full pattern.)

## Asset Preprocessing

`npx hyperframes tts`, `transcribe`, and `remove-background` produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the `.en`-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the `hyperframes-media` skill.

## Troubleshooting

```bash

npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)

npx hyperframes browser # manage bundled Chrome

npx hyperframes info # version and environment details

npx hyperframes upgrade # check for updates

```

Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.

## Other

```bash

npx hyperframes compositions # list compositions in project

npx hyperframes docs # open documentation

npx hyperframes benchmark . # benchmark render performance

```

mdskills/hyperframes-media/SKILL.md

14 kB

---

description: Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

---

# HyperFrames Media Preprocessing

Three CLI commands that produce assets for compositions: `tts` (speech), `transcribe` (timestamps), and `remove-background` (transparent video). Each downloads a model on first run and caches it under `~/.cache/hyperframes/`. Drop the output into the project, then reference it from the composition HTML — see the `hyperframes` skill for the audio/video element conventions.

## Text-to-Speech (`tts`)

Generate speech audio locally with Kokoro-82M. No API key.

```bash

npx hyperframes tts "Text here" --voice af_nova --output narration.wav

npx hyperframes tts script.txt --voice bf_emma --output narration.wav

npx hyperframes tts --list # all 54 voices

```

### Voice Selection

Match voice to content. Default is `af_heart`.

| Content type | Voice | Why |

| ----------------- | --------------------- | ----------------------------- |

| Product demo | `af_heart`/`af_nova` | Warm, professional |

| Tutorial / how-to | `am_adam`/`bf_emma` | Neutral, easy to follow |

| Marketing / promo | `af_sky`/`am_michael` | Energetic or authoritative |

| Documentation | `bf_emma`/`bm_george` | Clear British English, formal |

| Casual / social | `af_heart`/`af_sky` | Approachable, natural |

### Multilingual

Voice IDs encode language in the first letter: `a`=American English, `b`=British English, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin. The CLI auto-detects the phonemizer locale from the prefix — no `--lang` needed when the voice matches the text.

```bash

npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav

npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav

```

Use `--lang` only to override auto-detection (stylized accents). Valid codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` system-wide (`brew install espeak-ng` / `apt-get install espeak-ng`).

### Speed

- `0.7-0.8` — tutorial, complex content, accessibility

- `1.0` — natural pace (default)

- `1.1-1.2` — intros, transitions, upbeat content

- `1.5+` — rarely appropriate; test carefully

### Long Scripts

For more than a few paragraphs, write to a `.txt` file and pass the path. Inputs over ~5 minutes of speech may benefit from splitting into segments.

### Requirements

Python 3.8+ with `kokoro-onnx` and `soundfile` (`pip install kokoro-onnx soundfile`). Model downloads on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`).

## Transcription (`transcribe`)

Produce a normalized `transcript.json` with word-level timestamps.

```bash

npx hyperframes transcribe audio.mp3

npx hyperframes transcribe video.mp4 --model small --language es

npx hyperframes transcribe subtitles.srt # import existing

npx hyperframes transcribe subtitles.vtt

npx hyperframes transcribe openai-response.json

```

### Language Rule (Non-Negotiable)

**Never use `.en` models unless the user explicitly states the audio is English.** `.en` models (`small.en`, `medium.en`) **translate** non-English audio into English instead of transcribing it. This silently destroys the original language.

1. Language known and non-English → `--model small --language <code>` (no `.en` suffix)

2. Language known and English → `--model small.en`

3. Language unknown → `--model small` (no `.en`, no `--language`) — whisper auto-detects

**Default model is `small`, not `small.en`.**

### Model Sizes

| ---------- | ------ | -------- | ------------------------------------- |

Music with vocals: start at `medium` minimum; produced tracks often need manual SRT/VTT import. For caption-quality checks (mandatory after every transcription), the cleaning JS, retry rules, and the OpenAI/Groq API import path, see [hyperframes/references/transcript-guide.md](../hyperframes/references/transcript-guide.md).

### Output Shape

Compositions consume a flat array of word objects. The `id` field (`w0`, `w1`, ...) is added during normalization for stable references in caption overrides; it's optional for backwards compatibility.

```json

[

{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },

{ "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }

]

```

## Background Removal (`remove-background`)

Remove the background from a video or image so the subject (typically a person — avatar, presenter, talking head) sits as a transparent overlay in a composition.

```bash

npx hyperframes remove-background subject.mp4 -o transparent.webm # default: VP9 alpha WebM

npx hyperframes remove-background subject.mp4 -o transparent.mov # ProRes 4444 (editing)

npx hyperframes remove-background portrait.jpg -o cutout.png # single-image cutout

npx hyperframes remove-background subject.mp4 -o subject.webm \

--background-output plate.webm # both layers in one pass

npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu

npx hyperframes remove-background --info # detected providers

```

Uses `u2net_human_seg` (MIT). First run downloads ~168 MB of weights to `~/.cache/hyperframes/background-removal/models/`.

### Layer separation (`--background-output`)

Pass `--background-output` (or `-b`) to emit a **second** transparent video alongside the cutout: same source RGB, alpha is `255 − mask` instead of `mask`. The cutout is the subject with a transparent background; the plate is the original surroundings with a transparent hole where the subject was.

| File | Alpha is… | Use it for |

| -------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------- |

| `-o subject.webm` | The mask — subject opaque, background transparent | Foreground layer, place on top |

| `--background-output plate.webm` | Inverse — surroundings opaque, subject region transparent | Bottom layer; put text or graphics between this and the subject |

Both outputs share the same `--quality` preset and run from a single inference pass — encode cost roughly doubles, segmentation cost stays the same. Only valid for video inputs and `.webm`/`.mov` outputs.

**Hole-cut plate, not an inpainted clean plate.** The subject region in `plate.webm` is fully transparent — composite something opaque under it to fill the hole. The single test for whether `--background-output` is the right tool: _will anything ever be visible through the subject's silhouette where the subject used to be?_

| Use case | Right tool |

| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |

| Text/graphics between the cutout and the plate (this command's reason for existing) | **Hole-cut** (`--background-output`) |

| Subject onto an unrelated scene | Just `subject.webm`; ignore the plate |

| Show the room _without_ the person, alone over no other content | **Clean plate** — needs an inpainter (LaMa, ProPainter, E2FGVI). Not this command. |

| Replace the subject with a different subject | **Clean plate** — same as above |

If a user asks for "the room with the person removed" and intends to display it standalone, do **not** reach for `--background-output`. Tell them they need an inpainter.

Typical layered composition (the canonical hole-cut use case):

```html

<video

src="plate.webm"

data-start="0"

data-duration="6"

data-track-index="0"

muted

playsinline

></video>

<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>

<video

src="subject.webm"

data-start="0"

data-duration="6"

data-track-index="1"

muted

playsinline

></video>

</div>

```

This is functionally equivalent to the text-behind-subject pattern below, but you don't need the original `presenter.mp4` in the project — the plate replaces it. Useful when you want to ship just the two transparent layers and let the user drop arbitrary content between them.

### Output Format

| Format | When |

| --------------------- | ------------------------------------------------------------- |

| `.webm` (VP9 + alpha) | Default. Compositions play this directly via `<video>`. |

| `.mov` (ProRes 4444) | Editing in DaVinci/Premiere/FCP. Large files. |

| `.png` | Single-image cutout (still subject, layered over a backdrop). |

Chrome decodes VP9 alpha natively, so the `.webm` plugs into a composition like any other muted-autoplay video — see the `hyperframes` skill for the `<video>` track conventions.

### Quality presets

`--quality fast|balanced|best` controls only the VP9 encoder's CRF — segmentation quality is fixed.

| Preset | CRF | When |

| ---------- | --- | ----------------------------------------------------- |

| `fast` | 30 | Iterating, smaller file, looser color match |

| `balanced` | 18 | Default. Visually identical for most uses |

| `best` | 12 | Master / final delivery. Largest file, tightest match |

### Compositing patterns — pick the right one

The cutout webm is a **re-encoded copy** of the source mp4's RGB. That choice has consequences depending on what you put behind it:

| Pattern | What's behind the cutout | Result |

| -------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| **Cutout over a different scene** (most common) | Static image, gradient, or unrelated video | Looks great. The cutout's RGB is the only source of the subject — no doubling, no edge halo. This is what `remove-background` is built for. |

| **Cutout over its own source mp4** (text-behind-subject) | Same mp4 the cutout was generated from | Two RGB sources for the same person. At default `--quality balanced` (crf 18) the doubling is barely visible; at `--quality fast` (crf 30) you'll see a faint color shift / edge halo. Use `--quality best` (crf 12) for masters. |

| **Cutout over a _different_ take of the same person** | Footage of the same subject | Will look like two separate people overlapping. Don't do this. |

**Text-behind-subject** (headline behind a presenter):

```html

<video

src="presenter.mp4"

id="bg"

data-start="0"

data-duration="6"

data-track-index="0"

muted

playsinline

></video>

<h1 id="headline" style="z-index:2; ...">MAKE IT IN HYPERFRAMES</h1>

<video

src="presenter.webm"

data-start="0"

data-duration="6"

data-track-index="1"

muted

playsinline

></video>

</div>

```

Two key rules:

1. **Wrap the cutout video in a non-timed `<div>`** and animate the wrapper's opacity, not the video element's. The framework forces opacity:1 on active clips (any element with `data-start`/`data-duration`), so animating the video's opacity directly is silently overridden. The wrapper has no `data-*` attributes, so it's owned by your CSS/GSAP.

2. **Both videos use `data-start="0"` and `data-media-start="0"`** so the framework decodes them in sync from t=0. Late-mounting the cutout (`data-start=3.3`) introduces a seek + warm-up that lands a frame off the base mp4 — visible as one frame of misalignment at the cut.

Then GSAP-flip the wrapper opacity at the cut: `tl.set(cutoutWrap, { opacity: 1 }, 3.3)`.

## TTS → Transcribe → Captions

When there's no pre-recorded voiceover, generate one and transcribe it back to get word-level timestamps for captions:

```bash

npx hyperframes tts script.txt --voice af_heart --output narration.wav

npx hyperframes transcribe narration.wav # → transcript.json

```

Whisper extracts precise word boundaries from the generated audio, so caption timing matches delivery without hand-tuning.

mdskills/hyperframes-registry/references/demo-html-pattern.md

1.8 kB

# The demo.html Convention

## Why components ship demo.html

Every component in the registry ships a companion `demo.html` file alongside its snippet. The demo serves two purposes:

1. **Preview fixture** — the CI preview pipeline renders the demo to generate thumbnail images and preview videos for the catalog docs page.

2. **Usage example** — the demo shows the component effect applied to representative content, serving as a working reference.

## Demo structure

A demo is a complete, standalone HTML composition:

```html

<!doctype html>

<head>

<title>Component Name — Demo</title>

<style>

/* reset + canvas size */

</style>

</head>

<body>

<div data-composition-id="<name>-demo" data-width="1920" data-height="1080" data-duration="N">

</div>

// GSAP timeline demonstrating the effect

window.__timelines = window.__timelines || {};

window.__timelines["<name>-demo"] = tl;

</script>

</body>

</html>

```

Key conventions:

- `data-composition-id` is `<component-name>-demo` to avoid collisions

- The demo is self-contained — all CSS and JS from the snippet is inlined

- The GSAP timeline is registered on `window.__timelines`

- Duration should be long enough to showcase the effect (typically 5-8 seconds)

## Blocks don't need demo.html

Blocks are already standalone compositions that can be rendered directly. Only components need the demo wrapper.

## Demos are not installed

The `demo.html` is NOT installed by `hyperframes add` — it exists only in the registry for preview generation and as a reference.

mdskills/hyperframes-registry/references/discovery.md

2.6 kB

# Registry Discovery

## Reading the registry manifest

The top-level `registry.json` lists all available items:

```bash

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

```

Each entry has `name` and `type` (`hyperframes:example`, `hyperframes:block`, or `hyperframes:component`).

## Reading an item's manifest

Each item has a `registry-item.json` with full metadata:

```

<base>/<type-dir>/<name>/registry-item.json

```

Where `<type-dir>` is `examples`, `blocks`, or `components`.

## Item manifest fields

| ---------------------- | -------- | -------- | ---------------------------------------------- |

| `dimensions` | object | blocks | `{ width, height }` — blocks only |

## Available items

### Blocks

| Name | Description | Tags |

| ------------ | ----------------------------------------------- | ------------------------------- |

| `data-chart` | Animated bar + line chart with staggered reveal | data, chart, statistics |

| `flowchart` | Decision tree with SVG connectors and cursor | diagram, flowchart, interactive |

| `logo-outro` | Cinematic logo reveal with tagline | branding, outro, logo |

### Components

| Name | Description | Tags |

| -------------------- | --------------------------------------- | -------------------------------- |

| `grain-overlay` | Animated film grain texture overlay | texture, grain, overlay, film |

| `shimmer-sweep` | CSS gradient light sweep for AI accents | text, shimmer, highlight, effect |

| `grid-pixelate-wipe` | Grid dissolve transition between scenes | transition, wipe, grid, pixelate |

mdskills/hyperframes-registry/references/wiring-blocks.md

3.1 kB

# Wiring Blocks

Blocks are standalone compositions with their own `data-composition-id`, dimensions, duration, and GSAP timeline. Include them in a host composition using `data-composition-src` on a `<div>`.

## Basic wiring

After `hyperframes add data-chart`, wire it into your `index.html`:

```html

<div

data-composition-id="data-chart"

data-composition-src="compositions/data-chart.html"

data-start="2"

data-duration="15"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

</div>

```

## Required attributes

| Attribute | Description |

| ---------------------- | -------------------------------------------------------------------- |

| `data-composition-src` | Path to the block HTML file (relative to index.html) |

| `data-composition-id` | Unique ID matching the block's internal composition ID |

| `data-start` | When the block appears in the host timeline (seconds) |

| `data-duration` | How long the block plays (seconds, at most the block's own duration) |

| `data-track-index` | Layer ordering — higher numbers render in front |

| `data-width` | Block canvas width (match the block's dimensions) |

| `data-height` | Block canvas height (match the block's dimensions) |

## Timeline coordination

The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its `window.__timelines` registration, and seeks the block in sync with the host, offset by `data-start`. You do NOT need to reference the block's timeline in your host's GSAP code.

## Positioning blocks

To position a block in a specific area of the screen, add CSS:

```html

<div

data-composition-id="data-chart"

data-composition-src="compositions/data-chart.html"

data-start="2"

data-duration="15"

data-track-index="1"

data-width="1920"

data-height="1080"

style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"

></div>

```

## Multiple blocks

Include multiple blocks sequentially or overlapping:

```html

<div

data-composition-id="data-chart"

data-composition-src="compositions/data-chart.html"

data-start="0"

data-duration="15"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

<div

data-composition-id="flowchart"

data-composition-src="compositions/flowchart.html"

data-start="15"

data-duration="12"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

<div

data-composition-id="logo-outro"

data-composition-src="compositions/logo-outro.html"

data-start="27"

data-duration="6"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

```

mdskills/hyperframes-registry/references/wiring-components.md

2.3 kB

# Wiring Components

Components are effect snippets — HTML, CSS, and optionally JS that you merge directly into an existing composition. Unlike blocks, components have no standalone timeline; they participate in the host composition's timeline.

## General process

1. Run `hyperframes add <component-name>`

2. Open the installed file (e.g., `compositions/components/grain-overlay.html`)

3. Read the comment header for usage instructions

4. Copy the parts into your host composition:

- **HTML elements** — inside your `<div data-composition-id="...">`

- **CSS styles** — into your composition's `<style>` block

- **JS setup** — into your composition's `<script>`, before your timeline code

- **Timeline calls** — into your GSAP timeline (if the component exposes them)

## Example: grain-overlay (CSS-only, no timeline integration)

```html

<div

id="grain-overlay"

style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;"

</div>

```

Then paste the CSS keyframes and `.grain-texture` rule into your styles. No GSAP timeline calls needed — the grain animates via CSS `@keyframes`.

## Example: shimmer-sweep (needs timeline integration)

Wrap target elements, paste CSS and JS, then drive the sweep from your timeline:

```js

tl.fromTo(

".shimmer-sweep-target",

{

"--shimmer-pos": "-20%",

{

"--shimmer-pos": "120%",

duration: 1.2,

ease: "power2.inOut",

stagger: 0.15,

2.0,

);

```

## Example: grid-pixelate-wipe (scene transition)

Paste the overlay HTML and CSS, then drive `.grid-cell` scale in your timeline:

```js

// Cover screen

tl.to(

".grid-cell",

{ scale: 1, duration: 0.6, stagger: { amount: 0.6, from: "center" }, ease: "power2.inOut" },

5.0,

);

// Swap scenes

tl.set("#scene-a", { opacity: 0 }, 5.6);

tl.set("#scene-b", { opacity: 1 }, 5.6);

// Reveal

tl.to(

".grid-cell",

{ scale: 0, duration: 0.6, stagger: { amount: 0.6, from: "edges" }, ease: "power2.inOut" },

5.6,

);

```

## Key principles

- Components inherit the host composition's dimensions and duration

- Place component HTML at the appropriate z-index relative to your content

- Read the comment header in each snippet for customizable values

- Run `hyperframes lint` after wiring to catch structural issues

mdskills/hyperframes-registry/SKILL.md

4.2 kB

---

description: Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

---

# HyperFrames Registry

The registry provides reusable blocks and components installable via `hyperframes add <name>`.

- **Blocks** — standalone sub-compositions (own dimensions, duration, timeline). Included via `data-composition-src` in a host composition.

- **Components** — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.

## When to use this skill

- User mentions `hyperframes add`, "block", "component", or `hyperframes.json`

- Output from `hyperframes add` appears in the session (file paths, clipboard snippet)

- You need to wire an installed item into an existing composition

- You want to discover what's available in the registry

## Quick reference

```bash

hyperframes add data-chart # install a block

hyperframes add grain-overlay # install a component

hyperframes add shimmer-sweep --dir . # target a specific project

hyperframes add data-chart --json # machine-readable output

hyperframes add data-chart --no-clipboard # skip clipboard (CI/headless)

```

After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add `data-composition-id` (must match the block's internal composition ID), `data-start`, and `data-track-index` attributes when wiring blocks.

Note: `hyperframes add` only works for blocks and components. For examples, use `hyperframes init <dir> --example <name>` instead.

## Install locations

Blocks install to `compositions/<name>.html` by default.

Components install to `compositions/components/<name>.html` by default.

These paths are configurable in `hyperframes.json`:

```json

{

"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",

"paths": {

"blocks": "compositions",

"components": "compositions/components",

"assets": "assets"

}

```

See [install-locations.md](./references/install-locations.md) for full details.

## Wiring blocks

Blocks are standalone compositions — include them via `data-composition-src` in your host `index.html`:

```html

<div

data-composition-id="data-chart"

data-composition-src="compositions/data-chart.html"

data-start="2"

data-duration="15"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

```

Key attributes:

- `data-composition-src` — path to the block HTML file

- `data-composition-id` — must match the block's internal ID

- `data-start` — when the block appears in the host timeline (seconds)

- `data-duration` — how long the block plays

- `data-width` / `data-height` — block canvas dimensions

- `data-track-index` — layer ordering (higher = in front)

See [wiring-blocks.md](./references/wiring-blocks.md) for full details.

## Wiring components

Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):

1. Read the installed file (e.g., `compositions/components/grain-overlay.html`)

2. Copy the HTML elements into your composition's `<div data-composition-id="...">`

3. Copy the `<style>` block into your composition's styles

4. Copy any `<script>` content into your composition's script (before your timeline code)

5. If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline

See [wiring-components.md](./references/wiring-components.md) for full details.

## Discovery

Browse available items:

```bash

# Read the registry manifest

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

```

Each item's `registry-item.json` contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.

See [discovery.md](./references/discovery.md) for details on filtering by type and tags.

mdskills/hyperframes/house-style.md

4.9 kB

# House Style

Creative direction for compositions when no `design.md` is provided. These are starting points — override anything that doesn't serve the content. When a `design.md` exists, its brand values take precedence; house-style fills gaps.

## Before Writing HTML

1. **Interpret the prompt.** Generate real content. A recipe lists real ingredients. A HUD has real readouts.

2. **Pick a palette.** Light or dark? Declare bg, fg, accent before writing code.

3. **Pick typefaces.** Run the font discovery script in [references/typography.md](references/typography.md) — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.

## Lazy Defaults to Question

These patterns are AI design tells — the first thing every LLM reaches for. If you're about to use one, pause and ask: is this a deliberate choice for THIS content, or am I defaulting?

- Gradient text (`background-clip: text` + gradient)

- Left-edge accent stripes on cards/callouts

- Cyan-on-dark / purple-to-blue gradients / neon accents

- Pure `#000` or `#fff` (tint toward your accent hue instead)

- Identical card grids (same-size cards repeated)

- Everything centered with equal weight (lead the eye somewhere)

- Banned fonts (see [references/typography.md](references/typography.md) for full list)

If the content genuinely calls for one of these — centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match — use it. The goal is intentionality, not avoidance.

## Color

- Match light/dark to content: food, wellness, kids → light. Tech, cinema, finance → dark.

- One accent hue. Same background across all scenes.

- Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).

- **Contrast:** enforced by `hyperframes validate` (WCAG AA). Text must be readable with decoratives removed.

- Declare palette up front. Don't invent colors per-element.

## Background Layer

Every scene needs visual depth — persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.

Ideas (mix and match, 2-5 per scene):

- Radial glows (accent-tinted, low opacity, breathing scale)

- Ghost text (theme words at 3-8% opacity, very large, slow drift)

- Accent lines (hairline rules, subtle pulse)

- Grain/noise overlay, geometric shapes, grid patterns

- Thematic decoratives (orbit rings for space, vinyl grooves for music, grid lines for data)

All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead.

**Decorative count vs motion count.** The "2-5 per scene" count refers to decorative _elements_. If a project's `design.md` says "single ambient motion per scene", it means one looping motion applied to these decoratives (a shared breath/drift/pulse) — not one element total. A scene with 4 decoratives sharing one breathing motion is correct; a scene with 1 decorative is under-dressed.

## Motion

See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.

## Typography

See [references/typography.md](references/typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.

## Palettes

Declare one background, one foreground, one accent before writing HTML.

| Category | Use for | File |

| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |

| Bold / Energetic | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md) |

| Warm / Editorial | Storytelling, documentaries, case studies | [palettes/warm-editorial.md](palettes/warm-editorial.md) |

| Dark / Premium | Tech, finance, luxury, cinematic | [palettes/dark-premium.md](palettes/dark-premium.md) |

| Clean / Corporate | Explainers, tutorials, presentations | [palettes/clean-corporate.md](palettes/clean-corporate.md) |

| Nature / Earth | Sustainability, outdoor, organic | [palettes/nature-earth.md](palettes/nature-earth.md) |

| Neon / Electric | Gaming, tech, nightlife | [palettes/neon-electric.md](palettes/neon-electric.md) |

| Pastel / Soft | Fashion, beauty, lifestyle, wellness | [palettes/pastel-soft.md](palettes/pastel-soft.md) |

| Jewel / Rich | Luxury, events, sophisticated | [palettes/jewel-rich.md](palettes/jewel-rich.md) |

| Monochrome | Dramatic, typography-focused | [palettes/monochrome.md](palettes/monochrome.md) |

Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

mdskills/hyperframes/patterns.md

5.4 kB

# Composition Patterns

## Picture-in-Picture (Video in a Frame)

Animate a wrapper div for position/size. The video fills the wrapper. The wrapper has NO data attributes.

```html

<div

id="pip-frame"

style="position:absolute;top:0;left:0;width:1920px;height:1080px;z-index:50;overflow:hidden;"

<video

id="el-video"

data-start="0"

data-duration="60"

data-track-index="0"

src="talking-head.mp4"

muted

playsinline

></video>

</div>

```

```js

tl.to(

"#pip-frame",

{ top: 700, left: 1360, width: 500, height: 280, borderRadius: 16, duration: 1 },

10,

);

tl.to("#pip-frame", { left: 40, duration: 0.6 }, 30);

```

## Text Behind Subject (transparent webm overlay)

Put a headline _behind_ a presenter so their silhouette occludes the text. Requires a transparent cutout produced by `npx hyperframes remove-background presenter.mp4 -o presenter.webm`.

Three layers, plus one critical rule:

```html

<video

id="cf-base"

data-start="0"

data-duration="6"

data-media-start="0"

data-track-index="0"

src="presenter.mp4"

muted

playsinline

></video>

<h1

id="cf-headline"

style="position:absolute;top:50%;left:50%;

transform:translate(-50%,-50%); z-index:2; font-size:220px; font-weight:900;

color:#fff; text-shadow:0 6px 32px rgba(0,0,0,.55); clip-path:inset(0 0 100% 0);"

MAKE IT IN HYPERFRAMES

</h1>

<video

id="cf-cutout"

data-start="0"

data-duration="6"

data-media-start="0"

data-track-index="1"

src="presenter.webm"

muted

playsinline

></video>

</div>

```

```js

const tl = gsap.timeline({ paused: true });

const CUT = 3.3;

// Reveal headline early

tl.to("#cf-headline", { clipPath: "inset(0 0 0% 0)", duration: 0.6, ease: "expo.out" }, 0.25);

// At the cut, flip the cutout wrapper visible — the presenter's silhouette

// punches through the headline.

tl.set(".cutout-wrap", { opacity: 1 }, CUT);

// Sentinel: extend timeline to the composition's full duration so the

// renderer doesn't bail past the last meaningful tween.

tl.set({}, {}, 6);

window.__timelines["cover-flip"] = tl;

```

**Why a wrapper div, not opacity on the video itself?**

The framework forces `opacity: 1` on any element with `data-start`/`data-duration` while it's "active" — that's how it manages clip lifecycles. A CSS `opacity: 0` on the video element is silently overwritten. Wrap the video in a div with no `data-*` attributes; the wrapper is owned by your CSS/GSAP.

**Why both videos at `data-start="0"`?**

So both decode in sync from t=0. Late-mounting the cutout (`data-start=3.3`) makes Chrome do a seek + decoder warm-up at mount, which can land a frame off the base mp4 — visible as a one-frame jitter at the cut.

**Color match:** `remove-background` defaults to `--quality balanced` (crf 18) which keeps the cutout's RGB nearly identical to the source mp4 — minimal edge halo or color shift when overlaid. Use `--quality best` (crf 12) for hero shots; only drop to `--quality fast` (crf 30) when the cutout sits over a _different_ background and the size matters.

## Title Card with Fade

```html

<div

id="title-card"

data-start="0"

data-duration="5"

data-track-index="5"

style="display:flex;align-items:center;justify-content:center;background:#111;z-index:60;"

<h1 style="font-size:64px;color:#fff;opacity:0;">My Video Title</h1>

</div>

```

```js

tl.to("#title-card h1", { opacity: 1, duration: 0.6 }, 0.3);

tl.to("#title-card", { opacity: 0, duration: 0.5 }, 4);

```

## Slide Show with Section Headers

Use separate elements on the same track, each with its own time range. Slides auto-mount/unmount based on `data-start`/`data-duration`.

```html

```

## Top-Level Composition Example

```html

<div

id="comp-1"

data-composition-id="my-video"

data-start="0"

data-duration="60"

data-width="1920"

data-height="1080"

<video

id="el-1"

data-start="0"

data-duration="10"

data-track-index="0"

src="..."

muted

playsinline

></video>

<video

id="el-2"

data-start="el-1"

data-duration="8"

data-track-index="0"

src="..."

muted

playsinline

></video>

<div

id="el-5"

data-composition-id="intro-anim"

data-composition-src="compositions/intro-anim.html"

data-start="0"

data-track-index="3"

></div>

<div

id="el-6"

data-composition-id="captions"

data-composition-src="compositions/caption-overlay.html"

data-start="0"

data-track-index="4"

></div>

// Just register the timeline — framework auto-nests sub-compositions

const tl = gsap.timeline({ paused: true });

window.__timelines["my-video"] = tl;

</script>

</div>

```

mdskills/hyperframes/references/audio-reactive.md

3.0 kB

# Audio-Reactive Animation

Drive visuals from music, voice, or sound. Any GSAP-animatable property can respond to pre-extracted audio data.

## Audio Data Format

```js

var AUDIO_DATA = {

fps: 30,

totalFrames: 900,

frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...]

};

```

- `frames[i].bands[]` — frequency band amplitudes, 0-1. Index 0 = bass, higher = treble.

- Each band normalized independently across the full track.

## Mapping Audio to Visuals

| Audio signal | Visual property | Effect |

| ---------------------- | --------------------------------- | -------------------------- |

| Bass (bands[0]) | `scale` | Pulse on beat |

| Treble (bands[12-14]) | `textShadow`, `boxShadow` | Glow intensity |

| Overall amplitude | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |

| Mid-range (bands[4-8]) | `borderRadius`, `width` | Shape morphing |

Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties.

## Content, Not Medium

Audio provides **timing and intensity**. The visual vocabulary comes from the narrative.

**Never add:** equalizer bars, spectrum analyzers, waveform displays, musical notes clip art, generic particle systems, rainbow color cycling, strobing white on beats, abstract pulsing orbs.

**Instead:** Let content guide the visual and audio drive its behavior. Bass makes warmth _swell_. Treble sharpens _contrast_. The visual choice comes from "what does this piece feel like?"

## Sampling Pattern

Audio reactivity requires per-frame sampling via a `for` loop with `tl.call()`, not a single tween:

```js

// ✅ Correct — sample every frame

for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {

tl.call(

(function (frame) {

return function () {

draw(frame);

};

})(AUDIO_DATA.frames[f]),

[],

f / AUDIO_DATA.fps,

);

}

// ❌ Wrong — single tween, doesn't react to audio

gsap.to(".el", { scale: 1.2, duration: totalDuration });

```

Without per-frame sampling, the composition doesn't actually react to audio.

## textShadow Gotcha

`textShadow` on a parent container with semi-transparent children (e.g., inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind all children. Fix: apply `scale` to the container for beat pulse, but apply `textShadow` to individual active words only.

## Guidelines

- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.

- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.

- **Match the energy** — corporate = subtle; music video = dramatic.

- **Deterministic** — pre-extracted data, no Web Audio API, no runtime analysis.

## Constraints

- All audio data must be pre-extracted (use `extract-audio-data.py` from the gsap skill's scripts/)

- No `Math.random()` or `Date.now()`

- Audio reactivity runs on the same GSAP timeline as everything else

mdskills/hyperframes/references/beat-direction.md

13 kB

# Beat Direction

How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video.

---

## Per-Beat Direction

Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:

**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."

**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."

The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.

Each beat should have:

**For text animations:** pick a named effect from the [`text-effects.md`](text-effects.md) reference and name it by ID in the storyboard. Don't describe "text fades in" — write `soft-blur-in` or `kinetic-center-build`. The catalog is maintained as a separate skill (`pixel-point/animate-text`); see `text-effects.md` for how sub-agents load it and find the implementation specs.

---

### Concept

The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.

### Mood direction

Cultural and design references, not hex codes:

- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."

- "Warm workspace. Nice notebook energy, not technical blueprint."

- "Cinematic title sequence. The kind of opening where you lean forward."

### Animation choreography

Specific motion verbs per element — not "it animates in" but HOW. Verbs come from the beat's concept and content, not from an energy bucket. A wellness brand's "slow" beat might still have something that DROPS if the content is about letting go. A stats beat might FLOAT if the brand's identity is weightless.

The vocabulary of motion verbs (organized by physical character, not by energy level):

**Impact / weight:** SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS, DROPS (with force)

**Directional / deliberate:** SLIDES, PUSHES, PULLS, WIPES, CUTS

**Reveals / builds:** DRAWS, FILLS, GROWS, EXPANDS, ASSEMBLES, COUNTS UP

**Organic / ambient:** FLOATS, DRIFTS, BREATHES, PULSES, ORBITS, MORPHS

**Mechanical / precise:** TYPES ON, CLICKS, LOCKS IN, SNAPS, STEPS

Every element gets a verb. If you can't name the verb, the element is not yet designed. The verb should follow from the beat's concept — not from a lookup of what "high energy" or "low energy" beats use.

### Transition

How this beat hands off to the next. Specify the type and parameters.

**When to pick which:**

| Choose shader transition for | Choose CSS transition for | Choose hard cut for |

| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |

| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |

| Any moment the music/VO punctuates with a downbeat or SFX hit | Beats that ease from one composition into the next with shared motion vocabulary | Sequences of 3+ quick tempo-matched switches |

| Brand moments where the transition itself _is_ the visual | Minimal/editorial pacing | Anytime a 0.3-0.8s transition would feel too slow |

Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, a CSS crossfade is fine. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) — too many flatten their impact.

**Mixing shader and CSS crossfade transitions in one composition is supported.** Omit `shader` on any transition entry to get a smooth opacity crossfade. HyperShader manages all scene visibility regardless:

```js

var tl = HyperShader.init({

bgColor: "#0a0a0f",

scenes: ["s1", "s2", "s3", "s4"],

transitions: [

{ time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader

{ time: 8.5, duration: 0.8 }, // no shader → CSS crossfade

{ time: 13.0, shader: "domain-warp", duration: 0.6 },

});

// Add beat animations to the returned tl AFTER init()

tl.fromTo("#hero", { opacity: 0 }, { opacity: 1, duration: 0.6 }, 0.2);

window.__timelines["main"] = tl;

```

Let HyperShader create the timeline — don't pass a pre-built `timeline:` option. Add all composition tweens to the returned `tl` after the call.

**CSS transitions** — 30+ patterns across 13 categories. Full code in `skills/hyperframes/references/transitions/`. Pick based on the energy and feel:

| Category | Patterns | Motion character |

| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |

| **Push / slide** | Push slide, vertical push, elastic push, squeeze | Content moves through the frame as if on a continuous surface |

| **Scale / zoom** | Zoom through, zoom out | Perspective shifts — moving toward or away from content |

| **Radial / clip** | Circle iris, diamond iris, diagonal split | Geometric reveal — content emerges or is covered by a shape |

| **3D** | 3D card flip | Physical — content flips like a tangible object |

| **Dissolve** | Crossfade, blur crossfade, focus pull, color dip | Overlap and blend — both scenes exist simultaneously during the transition |

| **Cover / blinds** | Staggered color blocks, horizontal blinds (6/12 strips), vertical blinds | Structural — content is sliced, layered, or covered |

| **Light** | Light leak overlays, overexposure burn, film burn | Organic film — light bleeds across the frame |

| **Distortion** | Glitch (CSS RGB jitter), chromatic aberration, ripple, VHS tape | Instability — the image itself appears to malfunction |

| **Blur** | Blur through, directional blur | Soft defocus — content blurs in or out |

| **Mechanical** | Shutter (two-half), clock wipe (9-point wedge) | Precision — transitions with visible mechanical logic |

| **Grid** | Grid dissolve (12/120 cells) | Fragmentation — the frame breaks into pieces |

| **Destruction** | Page burn (SVG clip-path + canvas rim) | Dramatic decay — the previous scene is destroyed |

| **Other** | Gravity drop, morph circle | Physical or shape-based motion that doesn't fit other categories |

Common quick-picks:

- **Velocity-matched upward**: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`

- **Whip pan**: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`

- **Blur through**: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`

- **Zoom through**: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`

- **Hard cut / smash cut**: instant, for rapid-fire sequences

Timing presets: snappy (0.2s), smooth (0.4s), gentle (0.6s), dramatic (0.5s), instant (0.15s), luxe (0.7s).

**Shader transitions** — 14 built-in WebGL GPU effects. Install with `npx hyperframes add <name>`. Full API in shader-transitions docs.

| Shader | Visual description | Duration range |

| ----------------------- | ---------------------------------------------------------------------------------------------- | -------------- |

| **domain-warp** | Organic FBM dissolve — both scenes warp toward each other with an accent flash at the midpoint | 0.5–0.8s |

| **ridged-burn** | Multifractal mask reveals the incoming scene through a burn ramp with sparks at the edge | 0.5–0.8s |

| **whip-pan** | 10-sample horizontal motion blur + lateral crossfade — reads like a camera pan between shots | 0.3–0.5s |

| **sdf-iris** | Circle SDF expands from center, with accent-tinted glow rings at the expanding edge | 0.5–0.7s |

| **ripple-waves** | Radial standing-wave UV displacement — content ripples outward as scenes cross | 0.6–1.0s |

| **gravitational-lens** | Pinch pull toward center + R/B chromatic separation — content bends inward then releases | 0.6–1.0s |

| **cinematic-zoom** | 12 RGB-offset radial zoom blur samples — motion streak radiating from center | 0.4–0.6s |

| **chromatic-split** | R/B radial channel shift outward, G fixed — channels separate then rejoin | 0.3–0.5s |

| **swirl-vortex** | CCW swirl with FBM noise — content spirals away and the new scene spirals in | 0.5–0.8s |

| **thermal-distortion** | Vertical sine + FBM horizontal displacement — heat-haze shimmer across the frame | 0.5–0.8s |

| **flash-through-white** | Fade through white midpoint — almost invisible at 0.01s, noticeable at 0.3s | 0.01s–0.3s |

| **cross-warp-morph** | FBM vector field displaces both scenes; a third FBM biases the wipe direction | 0.5–0.8s |

| **light-leak** | Fixed off-frame light source with exponential falloff, warmth, and a ridge flare | 0.5–0.8s |

| **glitch** | Line displacement + RGB lateral split + scan modulation + posterization + flicker | 0.3–0.5s |

**You are not limited to what's listed here.** These are the built-in options, but you can and should:

- **Write custom GLSL shaders** from scratch for unique transition effects

- **Search online** for shader code (ShaderToy, GLSL Sandbox, GitHub) and adapt it

- **Build custom CSS transitions** that aren't in any category — combine clip-path, transforms, filters in new ways

- **Ask the user** to provide or find specific effects if you need something specialized

If the storyboard calls for an effect that doesn't exist yet — build it. The framework renders anything a browser can run.

### Depth layers

What's in foreground, midground, and background. Every beat should have at least 2 layers:

- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."

### SFX cues

What sounds at what moment:

- "On the capture pulse — a soft, warm analog shutter click."

- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."

---

## Rhythm Planning

Before writing HTML, declare your scene rhythm: which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern — fast-fast-SLOW-fast-SHADER-hold — before implementing.

**Derive the rhythm from the storyboard and the brand, not from a lookup.** A 15-second social ad for an architectural firm and a 15-second social ad for a gaming brand have different rhythms — both are 15 seconds, but one is slow-reveal-hold-CTA and the other is rapid-fire-SLAM-hook. Video type sets constraints (duration, approximate beat count); the brand and content determine whether those beats are slow or fast, sparse or dense, dramatic or controlled.

Questions that drive rhythm decisions:

- What emotional journey should the viewer take? Where is the peak moment?

- Where does the narration land its heaviest emphasis? That's usually where energy should peak.

- What does the brand's own visual pacing suggest — unhurried or urgent?

- How many beats can the duration actually support without feeling rushed or padded?

A social ad that tries to hook in 2s, showcase 3 features, and end with a CTA in 15s will feel like noise. Sometimes "hook-hold-CTA" with one strong feature is the right rhythm for 15 seconds. Name the rhythm you've planned before implementing.

---

## Velocity-Matched Transitions

Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.

mdskills/hyperframes/references/captions.md

7.7 kB

# Captions

## Language Rule (Non-Negotiable)

**Never use `.en` models unless the user explicitly states the audio is English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.

1. User says the language → `--model small --language <code>` (no `.en`)

2. User says English → `--model small.en`

3. Language unknown → `--model small` (no `.en`, no `--language`) — auto-detects

---

Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.

## Transcript Source

```json

[

{ "text": "Hello", "start": 0.0, "end": 0.5 },

{ "text": "world.", "start": 0.6, "end": 1.2 }

]

```

For transcription commands, whisper models, external APIs, see [transcript-guide.md](transcript-guide.md).

## Style Detection (When No Style Specified)

Read the full transcript before choosing. Four dimensions:

**1. Visual feel** — corporate→clean; energetic→bold; storytelling→elegant; technical→precise; social→playful.

**2. Color palette** — dark+bright for energy; muted for professional; high contrast for clarity; one accent color.

**3. Font mood** — heavy/condensed for impact; clean sans for modern; rounded for friendly; serif for elegance.

**4. Animation character** — scale-pop for punchy; gentle fade for calm; word-by-word for emphasis; typewriter for technical.

## Per-Word Styling

Scan for words deserving distinct treatment:

- **Brand/product names** — larger size, unique color

- **ALL CAPS** — scale boost, flash, accent color

- **Numbers/statistics** — bold weight, accent color

- **Emotional keywords** — exaggerated animation (overshoot, bounce)

- **Call-to-action** — highlight, underline, color pop

- **Marker highlight** — for beyond-color emphasis, see [css-patterns.md](css-patterns.md)

## Script-to-Style Mapping

| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |

## Word Grouping

- **High energy:** 2-3 words. Quick turnover.

- **Conversational:** 3-5 words. Natural phrases.

- **Measured/calm:** 4-6 words. Longer groups.

Break on sentence boundaries, 150ms+ pauses, or max word count.

## Positioning

- **Landscape (1920x1080):** Bottom 80-120px, centered

- **Portrait (1080x1920):** Lower middle ~600-700px from bottom, centered

- Never cover the subject's face

- `position: absolute` — never relative

- One caption group visible at a time

## Text Overflow Prevention

Use `window.__hyperframes.fitTextFontSize()`:

```js

var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {

fontFamily: "Outfit",

fontWeight: 900,

maxWidth: 1600,

});

el.style.fontSize = result.fontSize + "px";

```

Options: `maxWidth` (1600 landscape, 900 portrait), `baseFontSize` (78), `minFontSize` (42), `fontWeight`, `fontFamily`, `step` (2).

CSS safety nets: `max-width` on container, `overflow: visible` (**not** `hidden` — hidden clips scaled emphasis words and glow effects), `position: absolute`, explicit `height`. When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom.

**Container pattern:** Full-width absolute container, centered. Do **not** use `left: 50%; transform: translateX(-50%)` — causes clipping at composition edges.

## Caption Exit Guarantee

Every group **must** have a hard kill after exit animation:

```js

tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);

tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill

```

Self-lint after building timeline — place **before** `window.__timelines[id] = tl` so it runs at composition init:

```js

GROUPS.forEach(function (group, gi) {

var el = document.getElementById("cg-" + gi);

if (!el) return;

tl.seek(group.end + 0.01);

var computed = window.getComputedStyle(el);

if (computed.opacity !== "0" && computed.visibility !== "hidden") {

console.warn(

"[caption-lint] group " + gi + " still visible at t=" + (group.end + 0.01).toFixed(2) + "s",

);

}

});

tl.seek(0);

```

## Pre-Built Caption Components

Before building caption styles from scratch, check the registry — 15 ready-to-use caption components cover the most common styles. Install with `npx hyperframes add <name>` and use as a sub-composition via `data-composition-src`.

```bash

npx hyperframes catalog --tag caption-style # list all caption components

npx hyperframes add caption-highlight # install a specific one

```

| Style | Component | Best for |

| ------------------------- | ---------------------------- | ---------------------------- |

| TikTok-style highlight | `caption-highlight` | Social, high-energy |

| Karaoke pill | `caption-pill-karaoke` | Music, lyric videos |

| Cinematic editorial | `caption-editorial-emphasis` | Documentary, storytelling |

| Glitch / cyber | `caption-glitch-rgb` | Tech, gaming |

| Full-screen slam | `caption-kinetic-slam` | Hype, announcements |

| Neon glow | `caption-neon-glow` | Night, club, neon aesthetics |

| Neon accent (multi-color) | `caption-neon-accent` | Colorful, playful |

| Wipe reveal | `caption-clip-wipe` | Clean, modern |

| Gradient fill | `caption-gradient-fill` | Vibrant, eye-catching |

| Matrix decode | `caption-matrix-decode` | Sci-fi, tech reveals |

| Emoji pop | `caption-emoji-pop` | Social, casual |

| Parallax layers | `caption-parallax-layers` | Depth, cinematic |

| Particle burst | `caption-particle-burst` | Celebration, impact keywords |

| Lava texture | `caption-texture` | Bold, dramatic |

| Weight shift | `caption-weight-shift` | Elegant, typographic |

Browse all with previews: [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog)

Caption components ship with transparent backgrounds — they're pure overlays. If the underlying video is bright or busy, add a contrast layer (e.g. a semi-transparent dark div) in the host composition beneath the caption sub-composition, not inside the component itself.

## Further References

- [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation

- [transcript-guide.md](transcript-guide.md) — transcription commands, whisper models, external APIs

- [css-patterns.md](css-patterns.md) — CSS+GSAP marker highlighting (deterministic, fully seekable)

## Constraints

- Deterministic. No `Math.random()`, no `Date.now()`.

- Sync to transcript timestamps.

- One group visible at a time.

- Every group must have a hard `tl.set` kill at `group.end`.

- The compiler embeds supported fonts automatically — just declare `font-family` in CSS.

mdskills/hyperframes/references/css-patterns.md

8.1 kB

# CSS Patterns for Marker Highlighting

Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.

## Table of Contents

- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text

- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text

- [3. Burst Mode](#3-burst-mode) — Radiating lines from text

- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text

- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline

## 1. Highlight Mode

Yellow marker sweep behind text. The most common mode.

```html

<span class="mh-highlight-text">highlighted text</span>

</span>

```

```css

.mh-highlight-wrap {

position: relative;

display: inline;

}

.mh-highlight-bar {

position: absolute;

top: 0;

left: -6px;

right: -6px;

bottom: 0;

background: #fdd835;

opacity: 0.35;

transform: scaleX(0);

transform-origin: left center;

border-radius: 3px;

z-index: 0;

}

.mh-highlight-text {

position: relative;

z-index: 1;

}

```

```js

// Sweep in from left

tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);

// Optional: skew for hand-drawn feel

// gsap.set("#hl-1", { skewX: -2 });

```

### Multi-line Highlight

Stagger bars across multiple lines:

```js

tl.to(

".mh-highlight-bar",

{

scaleX: 1,

duration: 0.5,

ease: "power2.out",

stagger: 0.3,

0.6,

);

```

## 2. Circle Mode

Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.

```html

<span class="mh-circle-text" id="circle-word">IMPORTANT</span>

</span>

```

```css

.mh-circle-wrap {

position: relative;

display: inline;

}

.mh-circle-text {

position: relative;

z-index: 1;

}

.mh-circle-ring {

position: absolute;

top: 50%;

left: 50%;

width: 130%;

height: 160%;

transform: translate(-50%, -50%) rotate(-3deg) scale(0);

border: 3px solid #e53935;

border-radius: 50%;

pointer-events: none;

z-index: 0;

}

```

```js

// Circle scales in with a wobble

tl.to(

"#circle-1",

{

scale: 1,

rotation: -3,

duration: 0.6,

ease: "back.out(1.7)",

transformOrigin: "center center",

0.7,

);

```

### Variations

```css

/* Tighter circle (for short words) */

.mh-circle-ring.tight {

width: 150%;

height: 180%;

}

/* Squared circle (rounded rectangle) */

.mh-circle-ring.rounded {

border-radius: 30%;

width: 120%;

height: 140%;

}

/* Ellipse (wider than tall) */

.mh-circle-ring.ellipse {

width: 150%;

height: 130%;

border-radius: 50%;

}

```

## 3. Burst Mode

Radiating lines from text center. Each line is a positioned div rotated to its angle.

```html

</span>

```

```css

.mh-burst-wrap {

position: relative;

display: inline;

}

.mh-burst-text {

position: relative;

z-index: 2;

}

.mh-burst-container {

position: absolute;

top: 50%;

left: 50%;

width: 0;

height: 0;

z-index: 1;

}

.mh-burst-line {

position: absolute;

display: block;

width: 3px;

height: var(--len);

background: #1e88e5;

left: -1.5px;

top: calc(-1 * var(--len));

transform: rotate(var(--angle));

transform-origin: bottom center;

opacity: 0;

}

```

```js

// All lines burst outward simultaneously with slight stagger

tl.fromTo(

"#burst-1 .mh-burst-line",

{ scaleY: 0, opacity: 0 },

{ scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },

0.7,

);

```

**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.

## 4. Scribble Mode

Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.

```html

<span class="mh-scribble-text">underlined text</span>

<path

id="scribble-1"

d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"

fill="none"

stroke="#FDD835"

stroke-width="3"

stroke-linecap="round"

</svg>

</div>

```

```css

.mh-scribble-wrap {

position: relative;

display: inline;

}

.mh-scribble-text {

position: relative;

z-index: 1;

}

.mh-scribble-svg {

position: absolute;

left: 0;

bottom: -6px;

width: 100%;

height: 24px;

z-index: 0;

}

```

```js

// Measure path length and set initial dash state

var path = document.querySelector("#scribble-1");

var len = path.getTotalLength();

gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });

// Draw the line

tl.to(

"#scribble-1",

{

strokeDashoffset: 0,

duration: 0.8,

ease: "power1.inOut",

0.7,

);

```

### Strikethrough Variant

Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.

### Wavy Path Generator

Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:

- **Tight waves**: smaller x-increments (25px per half-wave)

- **Loose waves**: larger x-increments (50px per half-wave)

- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)

## 5. Sketchout Mode

Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.

```html

<span class="mh-sketchout-text">old price</span>

</span>

```

```css

.mh-sketchout-wrap {

position: relative;

display: inline;

}

.mh-sketchout-text {

position: relative;

z-index: 0;

}

.mh-sketchout-lines {

position: absolute;

top: 0;

left: -4px;

right: -4px;

bottom: 0;

overflow: hidden;

z-index: 1;

}

.mh-sketchout-line {

position: absolute;

display: block;

top: 50%;

left: 0;

width: 100%;

height: 2px;

background: #e53935;

transform-origin: left center;

transform: scaleX(0);

}

.mh-sketchout-fwd {

transform: scaleX(0) rotate(-12deg);

}

.mh-sketchout-bwd {

transform: scaleX(0) rotate(12deg);

}

```

```js

// Forward slash draws first

tl.to(

"#sketchout-1 .mh-sketchout-fwd",

{

scaleX: 1,

duration: 0.3,

ease: "power2.out",

1.0,

);

// Backward slash follows

tl.to(

"#sketchout-1 .mh-sketchout-bwd",

{

scaleX: 1,

duration: 0.3,

ease: "power2.out",

1.15,

);

```

## Combining Modes in Captions

Use mode cycling for visual variety across caption groups:

```js

var MODES = ["highlight", "circle", "burst", "scribble"];

GROUPS.forEach(function (group, gi) {

var mode = MODES[gi % MODES.length];

// Apply the mode's CSS pattern to emphasis words in this group

group.emphasisWords.forEach(function (word) {

applyMode(word.el, mode, tl, word.start);

});

```

Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.

mdskills/hyperframes/references/design-picker.md

12 kB

# Design Picker

Two-phase visual picker: mood boards first (pick a complete direction), then fine-tune individual categories.

## Prerequisites

Read these before generating options — they define the rules your options must follow:

- [typography.md](typography.md)

- [../house-style.md](../house-style.md)

- [video-composition.md](video-composition.md)

- [../visual-styles.md](../visual-styles.md)

- [beat-direction.md](beat-direction.md)

## Building the picker

1. Generate options **deeply contextual to the user's prompt**. Every category — not just architectures — must reflect the specific product, brand, audience, and mood. Generic options that could appear on any picker are a failure.

**Mood boards** — as many as the creative space warrants (4-8). Every board must tell a different STORY about the brand, not just reshuffle the same elements. Ask: "what are the genuinely different ways to position this product?" A cat food brand might be: playful chaos, premium positioning, comfort/cozy, social-native, flavor showcase, humor-led, sensory/appetizing. Each is a different narrative, not a different font on the same layout.

**Architectures** — one per mood board minimum, each visually distinct. Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens. If the user provided media assets, use them as background images (use `url(path)` without quotes — single quotes inside `style='...'` break the attribute).

**Palettes** (5-6) — named after the brand's world, not generic moods. The palette names and colors should feel like they belong to THIS specific product. Always mix dark + light + tinted. **Every palette must be visually distinct at swatch size.** If two palettes share the same background lightness AND a similar accent hue, cut one. Test: would a user see the difference in a 14px swatch chip? If not, they're duplicates.

**Type pairings** (5-6) — **RUN the font discovery script from typography.md BEFORE generating pairings.** This is not optional. Download Google Fonts metadata, run the script, and pick from its output. You will otherwise reach for the same 8 fonts every time (Bricolage Grotesque, Instrument Serif, Fraunces, Archivo Black, DM Serif Display, Space Grotesk, Fredoka) — that's your training data default, not a contextual choice. Match the brand's energy and audience. Cross-category per typography.md (never two sans-serifs).

2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`.

3. Replace these placeholders using Python (don't hand-escape quotes in sed):

- `__ARCHITECTURES_JSON__` — array of architecture objects

- `__PALETTES_JSON__` — array of palette objects

- `__TYPEPAIRS_JSON__` — array of type pairing objects

- `__MOODBOARDS_JSON__` — array of mood board objects (see format below)

- `__PROMPT_JSON__` — object with prompt context (see format below)

### Architecture data format

Each architecture object must include a `preview_html` field — the HTML that renders in the preview panel. Use token placeholders that the template replaces at runtime: `{{bg}}`, `{{fg}}`, `{{ac}}`, `{{mt}}`, `{{hf}}`, `{{hw}}`, `{{bf}}`, `{{bw}}`, `{{cr}}` (corner radius), `{{pad}}`, `{{gap}}`, `{{shadow}}`, `{{g}}` (grid line color), `{{fg3}}`/`{{fg6}}`/`{{fg8}}`/`{{fg15}}` (fg at opacity), `{{ac3}}`/`{{ac5}}`/`{{ac25}}` (accent at opacity).

**Every token must be used.** Apply `{{cr}}` to all cards, buttons, and containers. Apply `{{shadow}}` to elevated elements (cards, buttons, code blocks). Apply `{{pad}}` and `{{gap}}` to control spacing. If a token isn't used in the preview_html, that option will have no visible effect.

**Density matters.** Each architecture preview must include 15+ distinct elements to give the user a real sense of the layout. Include: headline, subhead, body paragraph, label/overline, stat with number, secondary stat, quote/testimonial, attribution, card with title+body, second card (different treatment), code/command block, primary button, secondary button, list or tags, accent divider/rule, and a data element (table row, progress bar, or chart).

Optionally include `components` (component styling rules) and `dos` (do's and don'ts) as strings — these appear in the generated design.md.

**Layout constraint:** All preview HTML must use percentage widths or `max-width: 100%`. Use `flex-wrap: wrap` on all flex rows. Absolute-positioned decoratives must stay within a parent with `overflow: hidden`.

**Security:** Architecture `preview_html` must not contain `<script>` tags, event handlers (`onclick`, `onerror`, etc.), or `javascript:` URLs. It is injected via `innerHTML`.

**Image URLs:** When using background images in `preview_html`, use `url(path/to/image.jpg)` WITHOUT quotes around the path. Single quotes like `url('path.jpg')` break because `preview_html` is inside a `style='...'` attribute — the inner single quotes terminate the outer attribute.

**Palette variety:** Always include a mix of light, dark, and tinted backgrounds across the 6 palettes — even for calm/wellness prompts.

### Example architecture object

```json

{

"name": "Editorial Stack",

"description": "Vertical rhythm with large type, pull quotes, and data callouts",

"tag": "editorial / longform / narrative",

"mood": "Confident, unhurried, typographically driven",

"preview_html": "<div style='background:{{bg}};color:{{fg}};padding:{{pad}};min-height:100vh;font-family:\"{{bf}}\",sans-serif;font-weight:{{bw}};'><div style='max-width:100%;display:flex;flex-direction:column;gap:{{gap}};'><div style='font-size:10px;text-transform:uppercase;letter-spacing:0.12em;color:{{mt}};'>Overline Label</div><div style='font-family:\"{{hf}}\",serif;font-weight:{{hw}};font-size:48px;line-height:1.1;letter-spacing:-0.02em;'>The Headline Goes Here</div><div style='font-size:20px;color:{{mt}};max-width:70%;line-height:1.5;'>Subheading text that introduces the narrative arc of this composition with enough words to fill two lines.</div><div style='font-size:15px;line-height:1.7;color:{{fg}};max-width:65%;'>Body paragraph with real sentences. The quick brown fox jumps over the lazy dog. This gives a sense of text density and reading rhythm at the chosen type size.</div><div style='display:flex;gap:{{gap}};flex-wrap:wrap;'><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{ac}};'>2.4M</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Primary Stat</div></div><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{fg}};'>87%</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Secondary Stat</div></div></div><div style='border-left:3px solid {{ac}};padding:12px {{pad}};background:{{ac3}};border-radius:0 {{cr}} {{cr}} 0;'><div style='font-size:18px;font-style:italic;color:{{fg}};line-height:1.5;'>\"A pull quote that captures the key insight of the piece.\"</div><div style='font-size:12px;color:{{mt}};margin-top:8px;'>— Attribution Name</div></div><div style='background:{{fg3}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};margin-bottom:8px;'>Card Title</div><div style='font-size:13px;color:{{mt}};line-height:1.5;'>Card body text with a different treatment than the main content area.</div></div><div style='background:{{ac5}};border:1px solid {{ac25}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};color:{{ac}};margin-bottom:8px;'>Accent Card</div><div style='font-size:13px;color:{{fg}};line-height:1.5;'>Second card with a tinted accent treatment for variety.</div></div><div style='font-family:monospace;font-size:13px;background:{{fg8}};border-radius:{{cr}};padding:{{pad}};color:{{fg15}};box-shadow:{{shadow}};'>$ hyperframes render --output video.mp4</div><div style='display:flex;gap:12px;flex-wrap:wrap;'><button style='background:{{ac}};color:{{bg}};border:none;padding:10px 24px;border-radius:{{cr}};font-size:14px;font-weight:600;box-shadow:{{shadow}};cursor:pointer;'>Primary Action</button><button style='background:transparent;color:{{fg}};border:1px solid {{fg15}};padding:10px 24px;border-radius:{{cr}};font-size:14px;cursor:pointer;'>Secondary</button></div><div style='display:flex;gap:8px;flex-wrap:wrap;'><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag One</span><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag Two</span><span style='background:{{ac5}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{ac}};'>Accent Tag</span></div><div style='height:1px;background:linear-gradient(to right,{{ac25}},{{fg6}},{{ac25}});'></div><div style='display:flex;justify-content:space-between;font-size:12px;color:{{mt}};border-bottom:1px solid {{g}};padding:8px 0;'><span>Data row label</span><span style='color:{{fg}};font-weight:600;'>1,234</span></div></div></div>"

}

```

### Mood board data format

Each mood board pre-selects one option from each category. The user picks a mood board in Phase 1, then fine-tunes in Phase 2 with those selections pre-filled.

```json

{

"name": "Terminal Precision",

"description": "Code-forward, data-dense, CLI energy. Dark canvas, monospace body, sharp corners.",

"theme": "dark",

"arch_index": 0,

"palette_index": 0,

"type_index": 0,

"corners_index": 0,

"density_index": 0,

"depth_index": 1,

"easing_index": 0,

"corners": "0px",

"padding": "12px",

"gap": "8px",

"shadow": "0 2px 16px rgba(0,230,255,0.15)"

}

```

Indices reference into the ARCHITECTURES, PALETTES, and TYPEPAIRS arrays. The template renders a mini preview of each mood board using its architecture's `preview_html` with the mood board's palette/type applied.

### Prompt context data format

```json

{

"title": "AI Coding Assistant",

"headline": "Your Code, Understood.",

"subline": "An AI coding assistant that reads your entire codebase.",

"section_desc": "Layout options for your product launch"

}

```

`title` appears in the Phase 1 header. `headline` and `subline` replace `{{prompt_headline}}` and `{{prompt_sub}}` in architecture preview_html so previews show real content.

### Content tokens in preview_html

In addition to the standard design tokens (`{{bg}}`, `{{fg}}`, `{{ac}}`, etc.), architecture `preview_html` can use:

- `{{prompt_headline}}` — the user's actual headline text

- `{{prompt_sub}}` — the user's actual subline text

This makes previews contextual — the user sees their own content styled, not generic placeholders.

## Serving and user selection

4. Serve the file: `cd <project-dir> && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it.

5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it verbatim to `design.md` in the project root — it's already in spec format (YAML frontmatter + prose sections). After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction.

The picker outputs a [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec-compliant file: YAML frontmatter with `colors`, `typography`, `rounded`, and `spacing` tokens, followed by `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation`, `## Components`, and `## Do's and Don'ts` prose sections.

mdskills/hyperframes/references/dynamic-techniques.md

7.6 kB

# Dynamic Caption Techniques

You are here because SKILL.md told you to read this file before writing animation code. Pick your technique combination from the table below based on the energy level you detected from the transcript, then implement using standard GSAP patterns.

## Technique Selection by Energy

Captions are a constrained surface — the highlight and exit technique is closely tied to how much intensity the spoken content carries. The table below is a calibration reference. If DESIGN.md or the storyboard specifies a caption style, that overrides anything here.

The core principle: **all energy levels use karaoke highlight as the baseline.** The difference is intensity — not the technique type.

**What changes with energy:**

- **Highlight intensity:** high energy gets accent color + glow + 15% scale pop on active words. Low energy gets a gentle white shift with 3% scale. The karaoke behavior is the same; the amplitude is different.

- **Exit style:** high energy exits scatter or drop (the word leaves with motion). Low energy exits collapse (the word simply fades or shrinks). The exit should express the same energy as the content.

- **Cycle variation:** high energy alternates highlight styles every 2 groups for variety. Low energy uses a single consistent style, varying only the ease. Variation itself creates energy; consistency creates calm.

Calibration reference (starting points, not rules):

| ------------ | ----------------------------------- | ------------------- | --------------- |

**All energy levels use karaoke highlight as the baseline.** The difference is intensity — high energy gets accent color + glow + 15% scale pop on active words, low energy gets a gentle white shift with 3% scale.

**Emphasis words always break the pattern.** When a word is flagged as emphasis (emotional keyword, ALL CAPS, brand name), give it a stronger animation than surrounding words (larger scale, accent color, overshoot ease). This creates contrast.

**Marker highlight modes add a visual layer on top of karaoke.** For emphasis words that need more than color/scale, add a marker-style effect — highlight sweep, circle, burst, or scribble — using the `/marker-highlight` skill. Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.

## Audio-Reactive Captions (Mandatory for Music)

**If the source audio is music (vocals over instrumentation, beats, any musical content), you MUST extract audio data and add audio-reactive animations.** This is not optional — music without audio reactivity looks disconnected. Even low-energy ballads get subtle bass pulse and treble glow.

No special wiring is needed. The group loop already iterates over every caption group to build entrance, karaoke, and exit tweens. At that point, read the audio data for each group's time range and use it to modulate the group's animation intensity with regular GSAP tweens.

```js

// Load audio data inline (same pattern as TRANSCRIPT)

var AUDIO = JSON.parse(audioDataJson); // { fps, totalFrames, frames: [{ bands: [...] }] }

GROUPS.forEach(function (group, gi) {

var groupEl = document.getElementById("cg-" + gi);

if (!groupEl) return;

// Read peak energy for this group's time range

var startFrame = Math.floor(group.start * AUDIO.fps);

var endFrame = Math.min(Math.floor(group.end * AUDIO.fps), AUDIO.totalFrames - 1);

var peakBass = 0;

var peakTreble = 0;

for (var f = startFrame; f <= endFrame; f++) {

var frame = AUDIO.frames[f];

if (!frame) continue;

peakBass = Math.max(peakBass, frame.bands[0] || 0, frame.bands[1] || 0);

peakTreble = Math.max(peakTreble, frame.bands[6] || 0, frame.bands[7] || 0);

}

// Modulate entrance — louder groups enter bigger and glowier

tl.to(

groupEl,

{

scale: 1 + peakBass * 0.06,

textShadow:

"0 0 " + Math.round(peakTreble * 12) + "px rgba(255,255,255," + peakTreble * 0.4 + ")",

duration: 0.3,

ease: "power2.out",

group.start,

);

// Reset at exit so audio-driven values don't persist

tl.set(groupEl, { scale: 1, textShadow: "none" }, group.end - 0.15);

});

```

This shapes the animation at build time, not playback time — no per-frame callbacks, no `tl.call()` loops, no async fetch timing issues. Loud groups come in with more weight and glow; quiet groups come in soft. The audio data modulates _how much_, the content determines _what_.

Keep audio reactivity subtle — 3-6% scale variation and soft glow. Heavy pulsing makes text unreadable.

To generate the audio data file:

```bash

python3 skills/gsap-effects/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json

```

## Combining Techniques

Don't use the same highlight animation on every group — cycle through styles using the group index. Don't combine multiple competing animations on the same word at the same timestamp. Vary techniques across groups to match the content's pace changes.

**Marker highlight effects** (from the `/marker-highlight` skill) layer well with karaoke — use karaoke for the word-by-word reveal, then add a marker effect on emphasis words only. For example: karaoke highlights each word in white, but brand names get a yellow highlight sweep and stats get a red circle. Cycle marker modes across groups for visual variety (see the mode-to-energy mapping in the marker-highlight skill).

## Available Tools

These tools are available in the HyperFrames runtime. Use them when they solve a real problem — not every composition needs all of them.

| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |

| **pretext** | Pure-arithmetic text measurement without DOM reflow. 0.0002ms per call. | `window.__hyperframes.pretext.prepare(text, font)` / `.layout(prepared, maxWidth, lineHeight)` | Per-frame text reflow, shrinkwrap containers, computing layout before render |

| **fitTextFontSize** | Finds the largest font size that fits text on one line. Built on pretext. | `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` | Overflow prevention for long phrases, portrait mode, large base sizes |

| **audio data** | Pre-extracted per-frame RMS energy and frequency bands. | Extract with `extract-audio-data.py`, load inline or via `fetch("audio-data.json")` | Audio-reactive visuals — modulate intensity based on the music |

mdskills/hyperframes/references/html-in-canvas-patterns.md

17 kB

# HTML-in-Canvas Patterns

HyperFrames' most powerful visual capability. Capture ANY live HTML/CSS as a GPU texture, then render it through WebGL shaders, Three.js 3D scenes, or post-processing effects — at 60fps, pixel-perfect, with every CSS feature supported.

**Read this file when a beat deserves cinematic treatment beyond flat GSAP animations.** Use for 1-3 hero beats per video, not every beat. The rest can use standard GSAP — the contrast between flat beats and HTML-in-Canvas beats IS part of the visual storytelling.

---

## Core Boilerplate (same in every HTML-in-Canvas composition)

Every HTML-in-Canvas effect shares this structure. Learn this once, adapt it for any effect.

```html

<canvas

id="hic-source"

layoutsubtree

width="1920"

height="1080"

style="position:absolute;inset:0;opacity:0;"

</div>

</canvas>

```

```js

// 3. Feature detection — always check, always provide fallback

function isHiCSupported() {

var tc = document.createElement("canvas");

if (!("layoutSubtree" in tc)) return false;

tc.setAttribute("layoutsubtree", "");

var ctx = tc.getContext("2d");

return ctx && typeof ctx.drawElementImage === "function";

}

var apiOk = isHiCSupported();

// 4. Capture function — call this every frame in onUpdate

var capCanvas = document.getElementById("hic-source");

var capCtx = capCanvas.getContext("2d");

function captureContent() {

if (apiOk) {

capCtx.drawElementImage(document.getElementById("hic-content"), 0, 0, 1920, 1080);

}

// 5. Drive from GSAP timeline — capture + render every frame

tl.to(

proxy,

{

/* your animation properties */

duration: BEAT_DURATION,

ease: "sine.inOut",

onUpdate: function () {

captureContent();

// render your effect here (Three.js or WebGL2)

);

```

**Fallback:** When `drawElementImage` is not available (preview without Chrome flag), draw a solid-color placeholder or use Canvas 2D text. The HyperFrames renderer auto-enables the flag — the effect WILL work in the final video. See the liquid-glass block for a complete fallback example.

---

## Effect Catalog

### 1. 3D Rotation with Bloom (Three.js)

**What it looks like:** Content floats in 3D space, slowly rotating with cinematic glow around bright edges. Like a product screenshot displayed in a dark theater.

**When to use:** Hero product showcase, feature reveal, CTA with premium feel.

**Key Three.js components:** `PlaneGeometry` + `CanvasTexture` + `EffectComposer` + `UnrealBloomPass`

```js

// After the boilerplate above, add:

var scene3d = new THREE.Scene();

var camera = new THREE.PerspectiveCamera(45, 1920 / 1080, 0.1, 100);

camera.position.set(0, 0, 4);

var renderer = new THREE.WebGLRenderer({

canvas: document.getElementById("hic-output"),

antialias: true,

alpha: true,

});

renderer.setSize(1920, 1080);

var texture = new THREE.CanvasTexture(capCanvas);

var mesh = new THREE.Mesh(

new THREE.PlaneGeometry(3.6, 2.2),

new THREE.MeshBasicMaterial({ map: texture }),

);

scene3d.add(mesh);

// Post-processing: bloom for cinematic glow.

// EffectComposer / RenderPass / UnrealBloomPass are ES-module named imports

// (see the import block below) — they're NOT properties of THREE in modern

// versions. Three.js r150+ removed the UMD `examples/js/` globals.

var composer = new EffectComposer(renderer);

composer.addPass(new RenderPass(scene3d, camera));

composer.addPass(new UnrealBloomPass(new THREE.Vector2(1920, 1080), 0.3, 0.4, 0.85));

var proxy = { rotY: -0.12, zoom: 4.2 };

tl.to(

proxy,

{

rotY: 0.12,

zoom: 3.6,

duration: BEAT_DURATION,

ease: "sine.inOut",

onUpdate: function () {

captureContent();

texture.needsUpdate = true;

mesh.rotation.y = proxy.rotY;

camera.position.z = proxy.zoom;

composer.render();

);

```

**Load Three.js and post-processing via ESM (use a `type="module"` script):**

```html

import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm";

import { EffectComposer } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/EffectComposer.js";

import { RenderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/RenderPass.js";

import { ShaderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/ShaderPass.js";

import { UnrealBloomPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/UnrealBloomPass.js";

// ... rest of composition code using these imports

</script>

```

The `examples/js/` path was removed in Three.js r152. Use `examples/jsm/` (ES modules) with `three@0.181.2` — the version used by the HyperFrames Three.js adapter.

---

### 2. Magnetic Cursor Distortion (Raw WebGL2)

**What it looks like:** Content warps and bends toward a moving point, like a magnet pulling on pixels. Chromatic aberration splits RGB channels at the distortion site.

**When to use:** Interactive feel, product demo with cursor, "look at THIS feature" moment.

**Key technique:** Custom fragment shader with Gaussian warp + chromatic split. No Three.js needed — just raw WebGL2.

```js

// WebGL2 setup

var gl = document.getElementById("hic-output").getContext("webgl2", {

alpha: false,

preserveDrawingBuffer: true,

});

// Vertex shader — full-screen quad

var VS = `#version 300 es

in vec2 a_pos;

out vec2 v_uv;

void main() {

v_uv = a_pos * 0.5 + 0.5;

gl_Position = vec4(a_pos, 0.0, 1.0);

}`;

// Fragment shader — magnetic warp + chromatic aberration

var FS = `#version 300 es

precision highp float;

in vec2 v_uv;

out vec4 fragColor;

uniform sampler2D u_tex;

uniform vec2 u_cursor; // cursor position (0-1)

uniform float u_strength; // warp strength (0-1)

void main() {

vec2 uv = v_uv;

vec2 delta = uv - u_cursor;

float dist = length(delta);

float warp = u_strength * exp(-dist * dist * 8.0);

vec2 warped = uv - delta * warp * 0.3;

// Chromatic aberration at distortion site

float aberration = warp * 0.008;

float r = texture(u_tex, warped + vec2(aberration, 0.0)).r;

float g = texture(u_tex, warped).g;

float b = texture(u_tex, warped - vec2(aberration, 0.0)).b;

fragColor = vec4(r, g, b, 1.0);

}`;

// Compile, link, setup quad geometry, upload texture...

// (See registry/blocks/vfx-magnetic/vfx-magnetic.html for complete implementation)

// Drive cursor position from GSAP

var proxy = { cx: 0.2, cy: 0.5, strength: 0.0 };

tl.to(

proxy,

{

cx: 0.8,

cy: 0.4,

strength: 1.0,

duration: BEAT_DURATION,

ease: "power2.inOut",

onUpdate: function () {

captureContent();

// Upload texture, set uniforms, draw

gl.uniform2f(cursorLoc, proxy.cx, proxy.cy);

gl.uniform1f(strengthLoc, proxy.strength);

gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);

);

```

---

### 3. Shatter / Fragment Explosion (Three.js)

**What it looks like:** Content breaks into geometric fragments that fly apart, revealing what's behind.

**When to use:** Dramatic transition, "breaking free" moment, tension release.

**Key technique:** Subdivide the source texture into triangle mesh fragments using BufferGeometry, then animate each fragment's position/rotation with GSAP.

Study `registry/blocks/vfx-shatter/vfx-shatter.html` for the complete 1156-line implementation. The core idea:

```js

// 1. Capture content to texture (same boilerplate)

// Seeded PRNG for determinism — Math.random() is banned

function mulberry32(seed) {

return function () {

seed |= 0;

seed = (seed + 0x6d2b79f5) | 0;

var t = Math.imul(seed ^ (seed >>> 15), 1 | seed);

t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);

return ((t ^ (t >>> 14)) >>> 0) / 4294967296;

};

}

var rng = mulberry32(42);

// 2. Create N triangle fragments from the texture

var fragments = [];

for (var i = 0; i < NUM_FRAGMENTS; i++) {

var geom = new THREE.BufferGeometry();

var mesh = new THREE.Mesh(geom, new THREE.MeshBasicMaterial({ map: texture }));

scene3d.add(mesh);

fragments.push({ mesh: mesh, targetPos: randomExplosionVector(rng), delay: rng() * 0.5 });

}

// 3. Animate: first hold still, then EXPLODE

tl.to({}, { duration: holdTime }, 0);

fragments.forEach(function (frag) {

tl.to(

frag.mesh.position,

{

x: frag.targetPos.x,

y: frag.targetPos.y,

z: frag.targetPos.z,

duration: 0.8,

ease: "power3.in",

holdTime + frag.delay,

);

tl.to(

frag.mesh.rotation,

{ x: rng() * 4, y: rng() * 4, duration: 0.8, ease: "power2.in" },

holdTime + frag.delay,

);

});

```

---

### 4. Liquid / Fluid Surface (Three.js)

**What it looks like:** Content floats above a rippling liquid surface with real-time wave dynamics. Or content IS the surface, undulating like water.

**When to use:** Organic/premium feel, ambient background, "living" product showcase.

**Key technique:** Subdivided PlaneGeometry with vertex displacement driven by noise functions in a vertex shader.

Study `registry/blocks/vfx-liquid-background/vfx-liquid-background.html` for the 1244-line implementation. Core idea:

```js

// Custom vertex shader with wave displacement

var vertexShader = `

varying vec2 vUv;

uniform float u_time;

void main() {

vUv = uv;

vec3 pos = position;

// Sine wave displacement

pos.z += sin(pos.x * 3.0 + u_time * 2.0) * 0.15;

pos.z += cos(pos.y * 2.5 + u_time * 1.5) * 0.1;

gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);

}

var mesh = new THREE.Mesh(

new THREE.PlaneGeometry(4, 3, 64, 64), // heavily subdivided for smooth waves

new THREE.ShaderMaterial({

vertexShader: vertexShader,

fragmentShader: `varying vec2 vUv; uniform sampler2D u_tex;

void main() { gl_FragColor = texture2D(u_tex, vUv); }`,

uniforms: {

u_tex: { value: texture },

u_time: { value: 0 },

}),

);

```

---

### 5. Portal / Dimensional Reveal (Three.js)

**What it looks like:** A glowing circular portal opens and content emerges through it from another dimension.

**When to use:** Product reveal, "entering the app" moment, hero feature introduction.

Study `registry/blocks/vfx-portal/vfx-portal.html` for the complete 863-line implementation.

---

## When to Use HTML-in-Canvas vs Standard GSAP

| Scenario | Use | Why |

| -------------------------------- | ------------------------------------ | ------------------------------------ |

| Hero product screenshot showcase | HTML-in-Canvas (3D rotation + bloom) | Makes flat UI feel cinematic |

| Feature list / stats | Standard GSAP | Content-focused, doesn't need 3D |

| CTA / brand reveal | HTML-in-Canvas (portal or magnetic) | Makes the moment memorable |

| Social proof / logos | Standard GSAP | Orderly cascade, trust is steady |

| Transition between acts | HTML-in-Canvas (shatter) | Dramatic act break |

| Background atmosphere | HTML-in-Canvas (liquid surface) | Premium ambient feel |

| Quick feature cards | Standard GSAP | Speed matters, 3D would slow it down |

---

## More Effects You Can Build

These aren't in the VFX blocks — build them yourself from the core boilerplate + a custom fragment shader. Each effect is a single GLSL function applied to the captured texture.

### 6. Noise Dissolve

Content dissolves into noise particles, revealing what's behind. Great for transitions.

```glsl

// Fragment shader — noise-based dissolve

uniform float u_progress; // 0.0 = fully visible, 1.0 = fully dissolved

uniform sampler2D u_tex;

float hash(vec2 p) {

return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);

}

void main() {

vec2 uv = v_uv;

float noise = hash(uv * 50.0);

float threshold = u_progress;

if (noise < threshold) {

// Edge glow at the dissolve boundary

float edge = smoothstep(threshold - 0.05, threshold, noise);

fragColor = vec4(1.0, 0.6, 0.2, 1.0) * (1.0 - edge); // orange edge glow

} else {

fragColor = texture(u_tex, uv);

}

```

### 7. Holographic / Iridescent

Content gets a rainbow-shifting holographic sheen that moves with time. Premium, futuristic feel.

```glsl

uniform float u_time;

uniform sampler2D u_tex;

void main() {

vec4 color = texture(u_tex, v_uv);

// Iridescent color shift based on position + time

float angle = v_uv.x * 6.28 + v_uv.y * 3.14 + u_time * 0.5;

vec3 holo = vec3(

sin(angle) * 0.5 + 0.5,

sin(angle + 2.094) * 0.5 + 0.5,

sin(angle + 4.189) * 0.5 + 0.5

);

// Blend holographic over content (subtle overlay)

fragColor = vec4(mix(color.rgb, holo, 0.15 + 0.1 * sin(u_time)), color.a);

}

```

### 8. Scan Lines + CRT

Retro CRT monitor look — scan lines, slight curvature, phosphor glow. Great for "code" or "terminal" beats.

```glsl

uniform sampler2D u_tex;

uniform float u_time;

void main() {

vec2 uv = v_uv;

// Barrel distortion (CRT curvature)

vec2 centered = uv - 0.5;

float dist = dot(centered, centered);

uv = uv + centered * dist * 0.15;

vec4 color = texture(u_tex, uv);

// Scan lines

float scanline = sin(uv.y * 800.0) * 0.04;

color.rgb -= scanline;

// Slight RGB offset (phosphor)

color.r = texture(u_tex, uv + vec2(0.001, 0.0)).r;

color.b = texture(u_tex, uv - vec2(0.001, 0.0)).b;

// Vignette

float vignette = 1.0 - dist * 2.0;

fragColor = vec4(color.rgb * vignette, 1.0);

}

```

### 9. Frosted Glass Blur

Content behind frosted glass — visible but softened, with subtle light refraction. Good for "behind the scenes" or "coming soon" moments.

```glsl

uniform sampler2D u_tex;

uniform float u_blur; // 0.0 = clear, 1.0 = full frost

void main() {

vec2 uv = v_uv;

vec4 color = vec4(0.0);

// Box blur with offset

float radius = u_blur * 0.015;

for (float x = -2.0; x <= 2.0; x += 1.0) {

for (float y = -2.0; y <= 2.0; y += 1.0) {

color += texture(u_tex, uv + vec2(x, y) * radius);

}

color /= 25.0;

// Add frost noise texture

float frost = fract(sin(dot(uv * 200.0, vec2(12.9898, 78.233))) * 43758.5453);

color.rgb += frost * 0.03 * u_blur;

fragColor = color;

}

```

### 10. Pixel Sort / Glitch Art

Pixels rearrange themselves in vertical or horizontal strips — digital art aesthetic. Great for tech/creative brands.

```glsl

uniform sampler2D u_tex;

uniform float u_intensity; // 0-1

void main() {

vec2 uv = v_uv;

// Random horizontal displacement per row

float row = floor(uv.y * 80.0);

float noise = fract(sin(row * 127.1) * 43758.5);

float displace = step(0.7, noise) * u_intensity * 0.1;

// Shift UV with RGB split

float r = texture(u_tex, uv + vec2(displace, 0.0)).r;

float g = texture(u_tex, uv).g;

float b = texture(u_tex, uv - vec2(displace * 0.5, 0.0)).b;

fragColor = vec4(r, g, b, 1.0);

}

```

---

## Creating ANY Custom Effect

The fragment shaders above are templates. The pattern is always:

1. **Capture your HTML content** with `drawElementImage` (the boilerplate at the top)

2. **Upload the captured canvas as a WebGL texture**

3. **Write a fragment shader** that reads from the texture and outputs modified colors

4. **Drive shader uniforms from GSAP** via `onUpdate`

Any GLSL effect from ShaderToy, The Book of Shaders, CodePen, or anywhere else can be adapted:

1. Find an effect you like (search "GLSL [effect name]" or browse shadertoy.com)

2. Copy the fragment shader

3. Replace `iResolution` with `vec2(1920.0, 1080.0)`, `iTime` with your `u_time` uniform

4. Add `uniform sampler2D u_tex;` for the captured content texture

5. Wire the uniforms to GSAP proxy values

**Geometry ideas beyond flat planes:**

- `SphereGeometry` — content mapped onto a globe (world map, global reach)

- `CylinderGeometry` — content on a rotating cylinder (carousel/scroll feel)

- `TorusGeometry` — content wrapped around a ring (infinity, cycle)

- `BoxGeometry` — content on a 3D box (product packaging, dice)

- GLTF models — content mapped as screen texture on phone, laptop, monitor (see `vfx-iphone-device`)

**Post-processing stacking** (Three.js EffectComposer):

- Bloom + film grain = cinematic

- Bloom + chromatic aberration = lens effect

- Depth of field + vignette = focused attention

- Film grain + scan lines = retro

- Multiple passes stack — add as many as you want

**You are not limited to the effects listed here.** If you can imagine a visual treatment, you can build it. The HTML-in-Canvas API gives you the source material (any HTML rendered as a texture), and WebGL/Three.js gives you unlimited creative control over how that material is presented.

mdskills/hyperframes/references/motion-principles.md

11 kB

# Motion Principles

## Common defaults that produce monoculture

These are the patterns LLMs reach for without thinking. None of them are wrong in isolation — they're wrong as defaults. If every scene of every video lands on the same easing, the same speed, and the same entrance direction, the compositions blur into one another no matter what the brand is.

- **Same ease on every tween.** `power2.out` is the most common default. Aim for variety: no more than two independent tweens sharing an ease within a scene. Eases are like font weights — vary them deliberately.

- **Same speed on every tween.** 0.4–0.5s is a common default that flattens rhythm. The slowest motion in a scene should be roughly 3× slower than the fastest. Vary duration so the eye can tell what's important.

- **Same entrance direction.** `y: 30, opacity: 0` is the universal LLM entrance. The same scene can use entrances from left, from right, from scale, from blur, opacity-only, letter-spacing — each one says something different about the element.

- **Same stagger across scenes.** Each scene should have its own rhythm. A 0.08s stagger in beat 1 and a 0.15s stagger in beat 2 makes the two beats feel like different moments.

- **Ambient zoom on every scene.** Slow-scale-up is the default ambient motion and it telegraphs "LLM-generated video." Vary the ambient motion per scene: slow pan, subtle rotation, color temperature shift, gentle drift — and sometimes nothing. Stillness after motion has real weight.

- **First animation at t=0.** Zero-delay feels like a jump cut. Offset the opening 0.1–0.3s so the scene reads as composed rather than thrown together.

## Easing is emotion, not technique

The motion is the verb. The easing is the adverb. A slide-in with `expo.out` feels confident. With `sine.inOut`, dreamy. With `elastic.out`, playful. Same motion, three different meanings. Choose the adverb deliberately.

**Direction rules:**

- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is the default for entrances.

- `.in` for elements leaving. Starts slow, accelerates away. Sends them off with momentum.

- `.inOut` for elements moving between positions, neither entering nor leaving the scene.

Ease-in on an entrance feels sluggish. Ease-out on an exit feels reluctant. These are the most common reversals and they're worth checking your work against.

## Speed expresses weight

Duration is one of the most direct ways a composition communicates what it values. Faster motion reads as confident, urgent, kinetic — it gives the viewer less time to study what's happening, which means the work has to land in fewer frames. Slower motion reads as deliberate, considered, weighty — the viewer has time to take in the element, which means each element has to earn that attention.

Useful calibration ranges (not prescriptions — what a duration _expresses_ depends on what surrounds it):

- **0.15–0.3s** — quick, percussive, kinetic. The motion reads as something happening _to_ the frame.

- **0.3–0.5s** — comfortable, professional. The motion reads as composed and reliable.

- **0.5–0.8s** — deliberate. The motion has visible weight and asks for attention.

- **0.8s+** — atmospheric. The motion becomes part of what the scene _is_, not something happening within it.

A composition that uses only one of these ranges feels one-note. Mix them — a scene where the headline takes 0.7s to settle and the supporting details land in 0.25s creates contrast that reinforces hierarchy without needing different colors or sizes.

## Scene structure: build, breathe, resolve

Every scene has three phases. The most common failure is dumping everything into the build and leaving nothing for the other two.

- **Build (0–30%)** — elements enter, staggered. Not all at once.

- **Breathe (30–70%)** — content visible, alive with one ambient motion. The viewer reads, registers, settles.

- **Resolve (70–100%)** — exit or decisive end. Exits are faster than entrances (see Asymmetry below).

A scene that's all build feels like a slideshow. A scene with no breathe phase doesn't let the content land.

## Transitions carry meaning

The transition type tells the viewer how two scenes relate:

- **Crossfade** — "this continues." Connective tissue between related ideas.

- **Hard cut** — "wake up" or a register shift. Disruption, surprise, percussive emphasis.

- **Slow dissolve** — "drift with me." Atmospheric, meditative, between-thoughts.

Crossfade is the default and it's defensible most of the time. The thing to watch for is using it for everything — when every transition is a crossfade, the viewer stops registering scene changes as meaningful. Hard cuts and slow dissolves are tools for the moments where the change in scene _is_ the message.

## Choreography is hierarchy

The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for one entrance to complete before starting the next — overlap entries. Total stagger sequence under 500ms regardless of item count keeps the scene from feeling like a slow drip.

## Asymmetry between entrances and exits

Entrances need longer than exits. A card might take 0.4s to appear but 0.25s to disappear — entrances build presence, exits remove it, and remove takes less time than build.

## Visual composition

Video frames are not web pages. Web layout patterns that work on a scrollable page often look broken in a fixed-frame composition.

- **Two focal points minimum per scene.** The eye needs somewhere to travel. A single text block floating in empty space reads as unfinished.

- **Fill the frame.** Hero text typically wants 60–80% of frame width. Web type sizes — 16px body, 32px headlines — disappear at video distance.

- **Three layers minimum.** Background treatment (glow, oversized faded type, color panel), foreground content, accent elements (dividers, labels, data bars). A scene with only one layer reads flat.

- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid `#000` reads as "nothing loaded."

- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern that looks lost on a 16:9 canvas.

- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts beat centered stacks.

- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (`scaleX` from 0).

## Image motion treatment

Embedded images shouldn't sit flat — every image earns some motion treatment:

- **Perspective tilt** — `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` plus a `box-shadow` creates depth. Do NOT use CSS `transform: perspective(...)`; GSAP will overwrite it.

- **Slow zoom (Ken Burns)** — GSAP `scale: 1` → `1.04` over beat duration. Makes photos feel cinematic rather than pasted in.

- **Device frame** — wrap in a laptop or phone shape using `border-radius` and `box-shadow`.

- **Floating UI** — extract a key element and animate it at a different z-depth for parallax.

- **Scroll reveal** — clip the image to a viewport window and animate `y` position.

## Load-Bearing GSAP Rules

Rules below came out of two independent website-to-hyperframes builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.

- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.

- **Never stack two transform tweens on the same element.** A common failure: a `y` entrance plus a `scale` Ken Burns on the same `<img>`. The second tween's `immediateRender: true` writes the element's initial state at construction time, overwriting whatever the first tween set — leaving the element invisible or offscreen with no lint warning. A secondary mechanism: `tl.from()` resets to its declared "from" state when the playhead is seeked past the timeline's end, so an element that looked correct in linear playback vanishes in the capture engine's non-linear seek. Fix one of two ways:

```html

tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);

tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance

</script>

tl.fromTo(

".hero",

{ y: 50, opacity: 0, scale: 1.0 },

{ y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },

);

</script>

tl.from(".hero-wrap", { y: 50, opacity: 0, duration: 0.6 }, 0); // entrance on parent

tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child

</script>

```

- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:

```js

// BRITTLE: immediateRender interacts badly with scene boundaries

tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);

// DETERMINISTIC: state is defined at both ends, no immediateRender surprise

tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);

```

- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:

```js

// BAD: lives outside the timeline, never renders in capture

gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });

// GOOD: seekable, deterministic, renders

tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);

```

- **Hard-kill every scene boundary, not just captions.** The same hard-kill pattern from `captions.md` generalizes to all elements with exit animations: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:

```js

tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd);

tl.set(el, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // deterministic kill

```

These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.

mdskills/hyperframes/references/narration.md

3.4 kB

# Narration & Script

How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.

## Pacing

- **2.5 words per second** is natural speaking pace

- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words

- Leave room for pauses. Silence between sentences is a feature, not dead air

- The script should feel SHORTER than the video — visual breathing room matters

## Tone

Write like a person, not a brochure:

- Use contractions: "it's", "you'll", "that's", "we've"

- Vary sentence length — short punchy phrases mixed with longer flowing ones

- Read it out loud. If it sounds robotic, rewrite it

- Avoid jargon unless the audience expects it

## Number Pronunciation

Write what you want the voice to say. TTS reads literally.

| In the product | Write in script as |

| -------------- | --------------------------------- |

| 135+ | more than one hundred thirty five |

| $1.9T | nearly two trillion dollars |

| 99.999% | ninety nine point nine percent |

| 200M+ | over two hundred million |

| 10x | ten times |

| API | A P I |

| stripe.com | stripe dot com |

The visual can show the exact figure while the voice rounds it.

## Structure

For product videos:

1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.

2. **Story** — what does the product do? Who uses it? Keep it concrete.

3. **Proof** — stats, customer names, social proof. Real numbers from the product.

4. **CTA** — what should the viewer do? "Start building at stripe dot com."

Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.

## The Opening Line

The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.

Patterns that work:

- **A bold claim**: "The financial infrastructure that powers the internet economy."

- **A question that provokes**: "What if your database could think?"

- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."

- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)

If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.

## Example

From a 62-second product launch video (team reference):

```

Your AI agent already knows how to make videos.

It just needs the right format.

This is Hyperframes. An open source framework. HTML in, video out.

A div is a keyframe. Data attributes are your timeline.

CSS is your look. G-Sap is your animation engine.

Anything a browser can render can be a frame in your video.

CSS animations. G-Sap. Lottie. Shaders. Three.js.

Drop in music, sound effects, footage — it all composes together.

No new framework for the agent to learn.

Just HTML.

The agent writes it. The renderer captures every frame as MP4.

It's deterministic. Identical outputs, every time.

Give your agent the CLI. Tell it what to make.

Watch it build.

Hyperframes. Go make something.

```

Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.

mdskills/hyperframes/references/prompt-expansion.md

5.5 kB

# Prompt Expansion

Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.

Runs AFTER design direction is established (Step 1). The expansion consumes design.md (if present) and produces output that cites its exact values.

## Prerequisites

Read before generating:

- `DESIGN.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.

- [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.

- [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically.

- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.

If `DESIGN.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.

## Why always run it

**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.

Even a detailed 7-scene brief lacks things only the expansion adds:

- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.

- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.

- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.

- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.

- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.

- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess.

Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.

The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.

**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.

## What to generate

Expand into a full production prompt with these sections:

1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.

2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. Derive the rhythm from the brand and the storyboard's emotional arc — see [beat-direction.md](beat-direction.md) for the considerations that drive this decision.

3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).

4. **Per-scene beats** — for each scene, use the beat-direction format:

- **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?

- **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")

- **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.

- **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.

- **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."

5. **Recurring motifs** — visual threads across scenes from the brand palette.

6. **Negative prompt** — what to avoid, informed by design.md's constraints if present.

## Output

Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.

Tell the user:

> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`

> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."

Only move to construction after the user approves or says to continue.

mdskills/hyperframes/references/techniques.md

21 kB

# Visual Techniques Reference

13 primitive animation techniques from production HyperFrames videos — SVG drawing, kinetic typography, variable fonts, WebGL shaders, motion-path, etc. Compose these into beats; they are the building blocks, not finished recipes. Each entry includes a minimal code pattern you can adapt.

These are NOT advanced — they're standard motion design patterns that every composition should use at least 2-3 of. For pre-built UI templates (terminal chrome, device mockups, moodboard layouts), look in the `registry/blocks/` directory instead — those are recipes, not techniques.

**These are starting points, not copy-paste templates.** Every code pattern below is a minimal working example from a real production video. Adapt them to your needs — change colors, sizes, timings, easings, element counts, layout. Combine techniques, mix parts from different patterns, invent variations. The goal is to understand the PRINCIPLE behind each technique so you can build something original, not to reproduce these examples exactly.

## Table of Contents

**Named text animation effects** (per-character, per-word, per-line, whole-element) — 24 effects with exact GSAP specs come from the separate `pixel-point/animate-text` skill. See [`text-effects.md`](text-effects.md) for the effect-name vocabulary and instructions for loading the upstream skill. Use those for all headline and label animations instead of inventing timing from scratch.

**HTML-in-Canvas patterns** (live DOM as GPU texture: iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor — using `drawElementImage` + `layoutsubtree`) are in [`html-in-canvas-patterns.md`](html-in-canvas-patterns.md) — 504 lines, one shared boilerplate + ~6 effect recipes. Use for 1–3 hero beats per video, not every beat.

---

| --- | --------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- |

---

## 1. SVG Path Drawing

A path draws itself in real-time, like someone tracing with a pen. Use for revealing diagrams, arrows, connector lines, or brand marks.

```html

<path

class="draw-path"

d="M 50 100 L 200 50 L 350 100"

stroke="#c84f1c"

stroke-width="4"

fill="none"

stroke-linecap="round"

</svg>

<style>

.draw-path {

stroke-dasharray: 280;

stroke-dashoffset: 280;

}

</style>

tl.to(".draw-path", { strokeDashoffset: 0, duration: 0.7, ease: "power2.out" }, 0.5);

</script>

```

Use `path.getTotalLength()` to calculate the dasharray value dynamically.

---

## 2. Canvas 2D Procedural Art

Animated noise, particle fields, data visualizations — anything that evolves frame-by-frame. Drive it with a GSAP proxy.

```html

var canvas = document.getElementById("proc-canvas");

var ctx = canvas.getContext("2d");

function hash(x, y) {

var n = x * 374761393 + y * 668265263;

n = (n ^ (n >> 13)) * 1274126177;

return ((n ^ (n >> 16)) & 0x7fffffff) / 0x7fffffff;

}

function drawFrame(t) {

ctx.fillStyle = "#0a0a0a";

ctx.fillRect(0, 0, 1920, 1080);

for (var i = 0; i < 200; i++) {

var x = hash(i, 0) * 1920;

var y = hash(i, 1) * 1080;

var brightness = hash(i, Math.floor(t * 10)) * 255;

ctx.fillStyle = "rgba(255, 255, 255, " + brightness / 255 + ")";

ctx.beginPath();

ctx.arc(x, y, 2, 0, Math.PI * 2);

ctx.fill();

}

var proxy = { time: 0 };

tl.to(

proxy,

{

time: 5,

duration: 5,

ease: "none",

onUpdate: function () {

drawFrame(proxy.time);

);

</script>

```

The `hash()` function is deterministic — same frame renders identically every time.

---

## 3. CSS 3D Transforms

Perspective rotations create depth. Use for product showcases, card flips, architectural reveals.

```html

<div class="face front">Product</div>

<div class="face back" style="transform: rotateY(180deg);">Details</div>

</div>

tl.to(".card-3d", { rotationY: 360, rotationX: 15, duration: 1.2, ease: "sine.inOut" }, 0);

</script>

```

Always set `perspective` on the parent, `transform-style: preserve-3d` on the animated element.

---

## 4. Per-Word Kinetic Typography

Words appear one-by-one, synced to transcript.json timestamps. The core technique for narration-driven videos.

```html

<span class="word w-0">Anything</span>

<span class="word w-2">browser</span>

<span class="word w-4">render</span>

</div>

<style>

.word {

display: inline-block;

opacity: 0;

margin: 0 0.12em;

}

</style>

// Word onset times from transcript.json (seconds relative to beat start)

var timings = [0.0, 0.23, 0.28, 0.63, 0.78];

var slides = [80, 60, 50, 25, 12]; // horizontal slide decay (px)

document.querySelectorAll(".word").forEach(function (word, i) {

tl.from(

word,

{

x: slides[i],

y: 14,

opacity: 0,

duration: 0.35,

ease: "power2.out",

timings[i],

);

});

</script>

```

The slide distance DECAYS per word (80→12px) — mimics a camera settling.

---

## 5. Lottie Animation

Vector animations that play inside a composition. Use for logos, character animations, icons.

```html

<!-- The web-component package is `@lottiefiles/dotlottie-wc` (the SDK

`@lottiefiles/dotlottie-web` does NOT expose a custom element).

The element tag is <dotlottie-wc>. -->

<script

src="https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-wc/dist/dotlottie-wc.js"

type="module"

></script>

<dotlottie-wc

class="lottie"

src="capture/assets/lottie/animation-0.json"

autoplay

loop

speed="1.5"

style="width:500px;height:500px;"

</dotlottie-wc>

gsap.set(".lottie", { scale: 0.3, opacity: 0 });

tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);

</script>

```

Or use lottie-web for more control:

```javascript

var anim = lottie.loadAnimation({

container: document.getElementById("anim"),

renderer: "svg",

loop: false,

autoplay: false,

path: "capture/assets/lottie/animation-0.json",

});

```

---

## 6. Video Compositing

Embed real video footage inside compositions. Videos must be `muted` with `playsinline`.

```html

<video

id="footage"

src="capture/assets/videos/clip.mp4"

muted

playsinline

style="width:100%;height:100%;object-fit:cover;"

></video>

</div>

// Video playback is controlled by the framework — don't call play() manually

tl.from(".video-frame", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.out" }, 0);

</script>

```

The HyperFrames runtime handles video seeking and playback.

---

## 7. Character-by-Character Typing

Terminal typing effect using `tl.call()` to update text content character by character.

```html

</div>

var CMD = "npx hyperframes init";

var typed = document.getElementById("typed-text");

// Cursor blinks

tl.to(".cursor", { opacity: 0, duration: 0.12, yoyo: true, repeat: 20, ease: "steps(1)" }, 0);

// Type each character

for (var i = 0; i < CMD.length; i++) {

(function (idx) {

tl.call(

function () {

typed.textContent = CMD.substring(0, idx + 1);

null,

(idx / CMD.length) * 0.9,

);

})(i);

}

</script>

```

Use `ease: "steps(1)"` for cursor blink — creates discrete on/off.

---

## 8. Variable Font Axis Animation

Animate font-variation-settings to reshape glyphs in real-time. Works with variable fonts that have axes like optical size (opsz), weight (wght), softness (SOFT).

```html

<style>

/* Load the captured local variable font — do NOT use Google Fonts @import.

Replace this placeholder with an @font-face pointing to capture/assets/fonts/. */

@font-face {

font-family: "Fraunces";

src: url("capture/assets/fonts/Fraunces-Variable.woff2") format("woff2");

font-weight: 100 900;

font-style: normal;

font-display: block;

}

.wordmark {

--opsz: 144;

--wght: 440;

font-family: "Fraunces", serif;

font-variation-settings:

"opsz" var(--opsz),

"wght" var(--wght);

font-size: 200px;

}

</style>

tl.to(".wordmark", { "--opsz": 72, "--wght": 300, duration: 0.45, ease: "power2.out" }, 0);

</script>

```

The glyph subtly reshapes as axes animate — optical size adjusts detail, weight changes thickness.

---

## 9. GSAP MotionPathPlugin

Animate an element along an arbitrary SVG path. Use for sliders following curves, particles along trajectories, guided reveals.

```html

gsap.registerPlugin(MotionPathPlugin);

tl.to(

".dot",

{

motionPath: { path: "M 12 300 C 280 280 520 80 820 50 S 1200 48 1308 38" },

duration: 1.5,

ease: "power2.out",

);

</script>

```

---

## 10. Velocity-Matched Transitions

Exit one beat and enter the next with matched velocities — creates perceived continuous motion.

```javascript

// EXIT (in outgoing composition): accelerating with blur

tl.to(

".content",

{

y: -150,

filter: "blur(30px)",

opacity: 0,

duration: 0.33,

ease: "power2.in", // accelerates

parseFloat(root.dataset.duration) - 0.33, // start exit 0.33s before beat ends

);

// ENTRY (in incoming composition): decelerating from blur

gsap.set(".content", { y: 150, filter: "blur(30px)" });

tl.to(

".content",

{

y: 0,

filter: "blur(0px)",

duration: 1.0,

ease: "power2.out", // decelerates

);

```

The fastest point of both curves meets at the cut — the viewer perceives smooth camera motion. Match ease families: `.in` for exits, `.out` for entries.

---

## 11. Audio-Reactive Animation

Drive any GSAP-tweenable property from the playing audio. Bass pulses a logo on kick drums. Treble glows a CTA on cymbals. Amplitude breathes a background during quiet phrases. The result: motion that feels locked to the track in a way pre-authored tweens never can.

**When to use:** Any video with music or dramatic narration — brand reels, product launches, hype edits. Skip for calm/tutorial pacing.

**How it works:** Pre-extract audio frequency bands into a JSON file, then sample per-frame via `tl.call()`:

```js

// audio-data.json: { fps: 30, totalFrames: 900, frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...] }

for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {

tl.call(

(function (frame) {

return function () {

var bass = frame.bands[0]; // 0–1

var treble = frame.bands[13];

gsap.set(".logo", { scale: 1 + bass * 0.04 }); // 3–4% pulse on bass

gsap.set(".cta", { filter: `drop-shadow(0 0 ${treble * 24}px #00C3FF)` });

};

})(AUDIO_DATA.frames[f]),

[],

f / AUDIO_DATA.fps,

);

}

```

Per-frame sampling is required — a single tween will not react. Use the extract script:

```bash

python3 skills/gsap/scripts/extract-audio-data.py narration.wav --fps 30 --bands 16 -o audio-data.json

```

Keep text/logo intensity subtle (≤5% scale, ≤30% glow) — audio-reactive motion on tiny elements reads as jitter. Bigger backgrounds can push to 10–30%.

**Never do:** equalizer bars, spectrum analyzers, waveform displays, strobing, rainbow color cycling. The audio provides _timing and intensity_; the visual vocabulary still comes from the brand. See `skills/hyperframes/references/audio-reactive.md` for the full API and anti-patterns.

---

## 12. Clip-Path Reveal Masks

A fixed window that content slides through — text or images enter from one side and are clipped by an invisible boundary. Different from SVG path drawing: the mask is static, the content moves.

```html

<div id="reveal-content">Your headline text here</div>

</div>

<style>

#reveal-mask {

position: absolute;

inset: 0;

clip-path: inset(0 200px 0 0); /* clips 200px from right */

display: flex;

align-items: center;

justify-content: center;

}

#reveal-content {

font-size: 108px;

white-space: nowrap;

}

</style>

// Content starts offscreen right, slides left through the mask window

gsap.set("#reveal-content", { x: 400, opacity: 0 });

tl.to("#reveal-content", { x: 0, opacity: 1, duration: 1, ease: "power2.out" }, 0);

</script>

```

Variations: `clip-path: circle(0% at 50% 50%)` → `circle(100%)` for iris reveals. `clip-path: polygon(...)` for custom shapes.

---

## 13. WebGL Fragment Shader Art

Full GPU generative backgrounds — domain-warped FBM noise, cosine palette coloring, iridescent organic patterns. Far richer than Canvas 2D.

```html

var canvas = document.getElementById("shader-bg");

var gl = canvas.getContext("webgl");

if (!gl) {

/* fallback to gradient */

}

var fsrc = `

precision mediump float;

varying vec2 v_uv;

uniform float u_time;

uniform vec2 u_res;

float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }

float noise(vec2 p) {

vec2 i = floor(p), f = fract(p);

f = f * f * (3.0 - 2.0 * f);

return mix(mix(hash(i), hash(i+vec2(1,0)), f.x),

mix(hash(i+vec2(0,1)), hash(i+vec2(1,1)), f.x), f.y);

}

float fbm(vec2 p) {

float v = 0.0, a = 0.5;

mat2 R = mat2(0.8, 0.6, -0.6, 0.8);

for (int i = 0; i < 5; i++) { v += a*noise(p); p = R*p*2.02; a *= 0.5; }

return v;

}

vec3 palette(float t) {

return vec3(0.5)+vec3(0.5)*cos(6.28318*(vec3(1)*t+vec3(0.0,0.33,0.67)));

}

void main() {

vec2 uv = v_uv; uv.x *= u_res.x/u_res.y;

float t = u_time * 0.4;

vec2 q = vec2(fbm(uv*3.0+t*0.3), fbm(uv*3.0+vec2(5.2,1.3)+t*0.2));

vec2 r = vec2(fbm(uv*3.0+q*4.0+vec2(1.7,9.2)+t*0.15), fbm(uv*3.0+q*4.0+vec2(8.3,2.8)+t*0.1));

float n = fbm(uv*3.0+r*2.0);

vec3 col = palette(n*2.0+t*0.2);

col = mix(col, palette(length(q)*3.0+t*0.1), 0.4);

col *= 0.7+0.3*n;

float vig = 1.0-0.4*length(v_uv-0.5);

gl_FragColor = vec4(col*vig, 1.0);

}

// Compile, link, set up fullscreen quad, then render via GSAP proxy:

var proxy = { time: 0.5 };

tl.to(

proxy,

{

time: 5,

duration: BEAT_DUR,

ease: "none",

onUpdate: function () {

gl.uniform1f(uTime, proxy.time);

gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);

);

</script>

```

Always include a Canvas 2D gradient fallback for environments without WebGL.

---

## Easing Vocabulary

GSAP offers a deep easing library. Every composition should use at least 3 different easings — using `power2.out` for everything produces flat, monotonous motion. Think of easings as tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging.

**The full palette** (each family has `.in`, `.out`, `.inOut` variants):

| Family | Character | Typical use |

| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |

| `power1`–`power4` | Gentle (1) to aggressive (4) acceleration curves | General purpose. power2 is the workhorse, power4 for dramatic snaps |

| `back(N)` | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Logo reveals, badge pops, card entrances. `back.out(2.5)` for playful, `back.out(1.2)` for elegant |

| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed | Panel scatter, energetic drops, fun reveals |

| `bounce` | Ball-drop bouncing | Physical interactions, icons landing, score counters |

| `expo` | Extreme acceleration curve (much steeper than power4) | Premium/luxury reveals, dramatic entrances |

| `sine` | Smooth, organic, no hard edges | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion |

| `circ` | Circular acceleration (starts very fast, ends very gentle or vice versa) | Camera moves, scene transitions, orbital motion |

| `steps(N)` | Discrete N-step jumps, no interpolation | Typing effects, cursor blink, counter ticks, retro/digital aesthetics |

**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical. The storyboard's mood description should guide which character fits — not a formula.

---

## Choosing techniques

Don't match techniques to video type on autopilot — match them to the **concept of the specific beat**. Ask: what visual treatment makes this exact idea land? A beat about speed needs motion that communicates speed; a beat about precision needs geometry and structure; a beat about warmth needs texture and organic drift.

Read the storyboard beat's concept and mood, then scan this list for techniques whose _visual character_ serves that concept. Any technique can appear in any video type — the question is whether it earns its place in this beat.

mdskills/hyperframes/references/text-effects.md

4.0 kB

# Text Effects — Reference

For deterministic text-animation specs (e.g., `typewriter` at exact `240ms / 46ms stagger / steps(1, end) easing`), this skill defers to the separate **`animate-text`** skill maintained by Pixel Point at [github.com/pixel-point/animate-text](https://github.com/pixel-point/animate-text). It provides a catalog of 24 named text effects with portable contracts and per-library implementation recipes (GSAP, Anime.js, WAAPI).

**We do NOT ship the catalog inside this repo.** Pixel Point's `animate-text` is the source of truth; vendoring its files here would violate the upstream's licensing (no explicit license declared upstream as of this writing). Loading the skill separately keeps the legal picture clean while giving you the same catalog.

## How to use it

When a beat needs a deterministic text animation, load the upstream skill alongside this one:

```bash

# In your project root, install the upstream skill into .agents/skills/

npx skills add pixel-point/animate-text

```

Or in Claude Code / a skill-aware agent runtime, the skill is invoked by name:

```

/animate-text

```

Once installed, the specs live at:

```

.agents/skills/animate-text/assets/effects/<id>.json # per-library implementation recipe

.agents/skills/animate-text/assets/specs/<id>.json # portable motion contract

```

Sub-agents reading those files get exact GSAP timings, easing strings, DOM split rules, and stagger algorithms — no creative invention needed.

## When you don't need the upstream skill

If a beat's text animation is simple enough to describe in prose ("headline fades up word-by-word, 80ms stagger"), implement it inline using the GSAP knowledge already in this skill ([motion-principles.md](motion-principles.md), [beat-direction.md](beat-direction.md), [techniques.md](techniques.md) — see entry #4 "Per-Word Kinetic Typography"). The upstream catalog is most valuable when:

- You want a specific NAMED effect across multiple beats (so they feel like one design system, not one-offs)

- You're choosing between several similar effects (typewriter vs per-character-rise vs bottom-up-letters) and want to see all 24 in one place

- You need layout-aware effects (`kinetic-center-build`, `short-slide-right`, `short-slide-down`) where parameters alone aren't enough — those ship with custom layout algorithms

## Effect names — vocabulary (do NOT use this as the implementation source)

For convenience while writing storyboards: the upstream skill provides 24 effects. Their IDs are listed here so you can name them in `STORYBOARD.md` even before loading the upstream skill. **The implementation specs are in the upstream skill, not here.**

- **Per-character (7):** soft-blur-in, per-character-rise, typewriter, bottom-up-letters, top-down-letters, stagger-from-center, stagger-from-edges

- **Per-word (8):** per-word-crossfade, spring-scale-in, shared-axis-y, blur-out-up, kinetic-center-build, short-slide-right, short-slide-down, depth-parallax-words

- **Per-line (2):** mask-reveal-up, line-by-line-slide

- **Whole element (7):** micro-scale-fade, shimmer-sweep, fade-through, shared-axis-z, scale-down-fade, focus-blur-resolve, shared-axis-x

For descriptions, durations, easing curves, and the per-library recipes: load `/animate-text` and read its own catalog page.

## In the storyboard

Every text element in every beat can name an effect by ID, e.g.:

```markdown

**Text Animations:**

- Main headline: `kinetic-center-build`

- Eyebrow label: `soft-blur-in`

- Body copy 3 lines: `mask-reveal-up`

```

Sub-agents implementing the beat will load `/animate-text` if it's not already loaded, then read the spec for each named effect from the upstream skill's files.

If the upstream skill isn't available (offline build, network restrictions, agent runtime that doesn't support skill loading), sub-agents fall back to implementing the effect from the description alone — using GSAP knowledge plus the effect ID as a description of intent (e.g., "typewriter" = per-character stepped reveal with no interpolation).

mdskills/hyperframes/references/transcript-guide.md

5.7 kB

# Transcript Guide

For the `transcribe` CLI invocation, the `.en`-translates-non-English rule, and whisper model selection, see the `hyperframes-media` skill. This file covers what to do with the resulting transcript when authoring captions: input formats, mandatory quality checks, cleaning code, external-API fallbacks.

## Supported Input Formats

The CLI auto-detects and normalizes these formats:

| --------------------- | --------- | --------------------------------------------------------------------------- | ----------------- |

| OpenAI Whisper API | `.json` | `openai.audio.transcriptions.create({ timestamp_granularities: ["word"] })` | Yes |

**Word-level timestamps produce better captions.** SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.

## Transcript Quality Check (Mandatory)

After every transcription, **read the transcript and check for quality issues before proceeding.** Bad transcripts produce nonsensical captions. Never skip this step.

### What to look for

| Signal | Example | Cause |

| ---------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |

| Music note tokens (`♪`, `�`) | `{ "text": "♪" }` or `{ "text": "�" }` | Whisper detected music, not speech |

| Garbled / nonsense words | "Do a chin", "Get so gay", "huh" | Model misheard lyrics or background noise |

| Long gaps with no words | 20+ seconds of only `♪` tokens | Instrumental section — expected, but high ratio means speech is being missed |

| Repeated filler | Many "huh", "uh", "oh" entries | Model is hallucinating on music |

| Very short word spans | Words with `end - start < 0.05` | Unreliable timestamp alignment |

### Automatic retry rules

**If more than 20% of entries are `♪`/`�` tokens, or the transcript contains obvious nonsense words, the transcription failed.** Do not proceed with the bad transcript. Instead:

1. **Retry with `medium.en`** if the original used `small.en` or smaller:

```bash

npx hyperframes transcribe audio.mp3 --model medium.en

```

2. **If `medium.en` also fails** (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:

- Providing lyrics manually as an SRT/VTT file

- Using an external API (OpenAI or Groq Whisper — see below)

3. **Always clean the transcript** before building captions — filter out `♪`/`�` tokens and entries where `text` is a single non-word character. Only real words should reach the caption composition.

### Cleaning a transcript

After transcription (even with a good model), strip non-word entries:

```js

var raw = JSON.parse(transcriptJson);

var words = raw.filter(function (w) {

if (!w.text || w.text.trim().length === 0) return false;

if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;

if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;

return true;

});

```

### When to use which model (decision tree)

1. **Is this speech over silence/light background?** → `small.en` is fine

2. **Is this speech over music, or music with vocals?** → Start with `medium.en`

3. **Is this a produced music track (vocals + full instrumentation)?** → Start with `medium.en`, expect to need manual lyrics or an external API

4. **Is this multilingual?** → Use `medium` or `large-v3` (no `.en` suffix)

## Using External Transcription APIs

For the best accuracy, use an external API and import the result:

**OpenAI Whisper API** (recommended for quality):

```bash

# Generate with word timestamps, then import

curl https://api.openai.com/v1/audio/transcriptions \

-H "Authorization: Bearer $OPENAI_API_KEY" \

-F file=@audio.mp3 -F model=whisper-1 \

-F response_format=verbose_json \

-F "timestamp_granularities[]=word" \

-o transcript-openai.json

npx hyperframes transcribe transcript-openai.json

```

**Groq Whisper API** (fast, free tier available):

```bash

curl https://api.groq.com/openai/v1/audio/transcriptions \

-H "Authorization: Bearer $GROQ_API_KEY" \

-F file=@audio.mp3 -F model=whisper-large-v3 \

-F response_format=verbose_json \

-F "timestamp_granularities[]=word" \

-o transcript-groq.json

npx hyperframes transcribe transcript-groq.json

```

## If No Transcript Exists

1. Check the project root for `transcript.json`, `.srt`, or `.vtt` files

2. If none found, run transcription — pick the starting model based on the content type:

- Speech/voiceover → `small.en`

- Music with vocals → `medium.en`

```bash

npx hyperframes transcribe <audio-or-video-file> --model medium.en

```

3. **Read the transcript and run the quality check** (see above). If it fails, retry with a larger model or suggest manual lyrics.

mdskills/hyperframes/references/transitions.md

13 kB

# Scene Transitions

A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.

## Animation Rules for Multi-Scene Compositions

These are non-negotiable for every multi-scene composition:

1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.

2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.

3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.

4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.

## Energy → Transition Character

The energy of a beat tells you what motion character the transition should have — not which specific transition to use. The motion character is a quality you derive from the brand and content, then find a transition that has that quality.

**Soft/organic character:** transitions that breathe, dissolve, or drift. Nothing sharp, mechanical, or percussive. Duration 0.5–0.8s, smooth easing curves.

**Directional/purposeful character:** transitions that move content decisively. Clear direction, readable momentum. Duration 0.3–0.5s, clean deceleration.

**Percussive/instant character:** transitions that hit like a cut. Immediate, almost hard-cut energy. Duration 0.15–0.3s, aggressive or near-instant easing.

These are calibration ranges, not recipes. A brand that treats its "high energy" section with restraint might use 0.4s for a moment that another brand transitions in 0.2s — both are correct for their brand. Pick ONE character that defines the video's primary transitions, then use 1–2 contrasting moments as intentional accents. See the **Mood → Motion Quality** section below to find transitions with the right character for a given mood.

## Mood → Motion Quality

Think about what the transition _communicates_, not what it looks like. The question is: **what motion quality serves this mood?** Then find transitions that have that quality in the catalog (`transitions/catalog.md`).

| Mood | Motion quality that fits | Why |

| ------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |

| **Warm / inviting** | Soft edges, dissolving, color-temperature washes — nothing sharp, mechanical, or percussive | Warmth reads as continuity and flow; hard cuts or compression feel cold |

| **Cold / clinical** | Mechanical transformation — compression, slicing, gridding, precision | The content appears to be processed or structured, reinforcing a systematic quality |

| **Editorial / magazine** | Clean directional movement — like turning a page | Feels like content is being browsed or curated, not revealed |

| **Tech / futuristic** | Data-like fragmentation, digital displacement, scan artifacts | Transition feels computational rather than physical |

| **Tense / edgy** | Instability, distortion, displacement — something slightly wrong about the image | Introduces friction where smooth transitions would release tension |

| **Playful / fun** | Overshoot, expansion, rotation — motion with personality and bounce | Transitions that feel like objects rather than effects |

| **Dramatic / cinematic** | Scale, weight, light extremes — the cut is an event, not a bridge | Every shader and every hard cut carries narrative gravity |

| **Premium / luxury** | Restraint — transitions that are barely visible, or invisible | Luxury communicates through what it withholds |

| **Retro / analog** | Organic imperfection — light bleed, scan lines, color wash | Physical film artifacts; imperfection as authenticity |

Use this table to derive what **quality** the transition should have, then look at the specific options in `transitions/catalog.md` to find one that has that quality for this brand. The transitions listed in the catalog are all available; none are reserved for a specific mood.

## Narrative Position

Each position in the video has a different job to do. What transition you pick for each should come from the brand's motion character and the storyboard's intent — not from a rule about "climax = boldest."

- **Opening** — establishes the motion language for the entire video. Make a deliberate choice; whatever you pick here sets the viewer's expectation for everything that follows.

- **Between related points** — should be almost invisible. The content is continuing; the transition shouldn't draw attention to itself. Consistency matters more than distinctiveness here.

- **Topic change** — needs enough contrast from your primary that it signals "something different is starting." The contrast is in motion character, not just duration.

- **Climax / hero reveal** — this is the moment the video has been building to. The transition should feel earned by what came before. "Use your boldest transition here" is a default, not a rule — the climax of a restrained editorial piece might be a hard cut.

- **Wind-down** — returns to a motion character that allows the viewer to exhale. Matches the opening in tone, not necessarily in technique.

- **Outro** — no new energy. Slowest and simplest in the video. Closure.

## Blur and Motion Intensity

Blur and duration should express the energy of the content, not match a lookup table. The ranges below are calibration references — starting points to adjust from based on what the brand and storyboard call for.

Higher-energy transitions: shorter duration, less blur, no hold at peak. The motion is immediate.

Lower-energy transitions: longer duration, more blur, longer hold at peak. The motion has weight.

Calibration ranges (not prescriptions):

- Soft/organic: blur 20–30px, duration 0.8–1.2s, hold 0.3–0.5s

- Directional/purposeful: blur 8–15px, duration 0.4–0.6s, hold 0.1–0.2s

- Percussive/instant: blur 3–6px, duration 0.2–0.3s, no hold

A brand that uses these as a formula will produce transitions that feel the same across every video. A brand-derived choice asks: what blur and duration expresses the weight this transition should have?

## Presets

| Preset | Duration | Easing |

| ---------- | -------- | ----------------- |

| `snappy` | 0.2s | `power4.inOut` |

| `smooth` | 0.4s | `power2.inOut` |

| `gentle` | 0.6s | `sine.inOut` |

| `dramatic` | 0.5s | `power3.in` → out |

| `instant` | 0.15s | `expo.inOut` |

| `luxe` | 0.7s | `power1.inOut` |

## Implementation

Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.

| Category | CSS | Shader (WebGL) |

| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |

| Push/slide | Push slide, vertical push, elastic push, squeeze | Whip pan |

| Scale/zoom | Zoom through, zoom out, gravity drop, 3D flip | Cinematic zoom, gravitational lens |

| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris |

| Dissolve | Crossfade, blur crossfade, focus pull, color dip | Cross-warp morph, domain warp |

| Cover | Staggered blocks, horizontal blinds, vertical blinds | — |

| Light | Light leak, overexposure burn, film burn | Light leak (shader), thermal distortion |

| Distortion | Glitch, chromatic aberration, ripple, VHS tape | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |

| Pattern | Grid dissolve, morph circle | — |

## Transitions That Don't Work in CSS

Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.

## CSS vs Shader

CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.

**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.

**Mixing is supported.** You can have some transitions use WebGL shaders and others use a CSS crossfade in the same composition. Omit the `shader` field on any `TransitionConfig` entry to get a smooth opacity crossfade instead of a WebGL effect:

```js

var tl = HyperShader.init({

bgColor: "#000",

accentColor: "#6366f1",

scenes: ["s1", "s2", "s3", "s4"],

transitions: [

{ time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader

{ time: 8.5, duration: 0.8 }, // no shader → CSS crossfade

{ time: 13.0, shader: "domain-warp", duration: 0.6 }, // WebGL shader

});

```

HyperShader manages all scene visibility regardless of transition type. Let it create the timeline (don't pass `timeline:` into `init()`) and add your beat animations to the returned `tl` after the call.

## Shader-Compatible CSS Rules

Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:

1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.

2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.

3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.

4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.

5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.

6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.

These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.

## Visual Pattern Warning

Avoid transitions that create visible repeating geometric patterns — grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.

mdskills/hyperframes/references/transitions/catalog.md

6.1 kB

# Transition Catalog

Hard rules, scene template, and routing to implementation code. Read the reference file for the transition type you need — don't load all of them.

## Hard Rules (CSS)

These cause real bugs if violated.

**Scene visibility:** Scene 1 visible by default (no `opacity: 0`). Scenes 2+ have `opacity: 0` on the CONTAINER div. GSAP reveals them. No visibility shim (`timedEls`).

**Fonts:** Just write the `font-family` you want — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No need for `<link>` tags or `@import`. Works in all contexts including sandboxed iframes.

**Element structure:** No `class="clip"` on scene divs in standalone compositions. Only the root div gets `data-composition-id`/`data-start`/`data-duration`.

**Overlay elements:** Staggered blocks = full-screen 1920x1080, NOT thin strips. Glitch RGB overlays = normal blending at 35% opacity, NOT `mix-blend-mode: multiply` (invisible on dark backgrounds). Light leak overlays = larger than the frame (2400px+), never a visible shape. Overexposure = use `filter: brightness()` on the scene, not just a white overlay.

**VHS tape:** Clone actual scene content with `cloneNode(true)`, NOT colored bars. Each strip: wider than frame (2020px at left:-50px). Red+blue chromatic copies at z-index above main strip. Seeded PRNG for deterministic random offsets.

**Z-index:** Gravity drop, zoom out, diagonal split need outgoing scene ON TOP (`zIndex: 10`) so it exits while revealing the new scene behind (`zIndex: 1`).

**Page burn:** Content burns with the page — no falling debris. Hide scene1 via `tl.set` at burn end, NEVER `onComplete` (not reversible). `onUpdate` must restore `clipPath: "none"` when `wp <= 0` for rewind support. Incoming scene fades from black at 90% through burn.

**Clock wipe:** 9-point polygon with intermediate edge positions. Step through 4 quadrants with separate tweens.

**Grid dissolve:** Cycle 5 palette colors per cell, not monochrome.

**Blinds count by energy:** Calm: 4h/6v. Medium: 6-8h/8v. High: 12-16h/16v.

**Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).

## Shader Transitions

Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".

## Scene Template

```html

<!DOCTYPE html>

<head>

<style>

body {

margin: 0;

width: 1920px;

height: 1080px;

overflow: hidden;

background: #000;

font-family: "YOUR FONT", sans-serif; /* compiler embeds supported fonts automatically */

}

.scene {

position: absolute;

top: 0;

left: 0;

width: 1920px;

height: 1080px;

overflow: hidden;

}

#scene1 {

z-index: 1;

background: #color;

}

#scene2 {

z-index: 2;

background: #color;

opacity: 0;

}

</style>

</head>

<body>

<div

id="root"

data-composition-id="main"

data-width="1920"

data-height="1080"

data-start="0"

data-duration="TOTAL"

</div>

window.__timelines = window.__timelines || {};

var tl = gsap.timeline({ paused: true });

// Transition code here

window.__timelines["main"] = tl;

</script>

</body>

</html>

```

Every transition follows: position new scene → animate outgoing → swap → animate incoming → clean up overlays.

## CSS Transitions

All code examples use `old` for the outgoing scene-inner selector and `new` for the incoming, with `T` as the transition start time. Read the reference file for the type you need.

| Type | Transitions | Reference |

| -------------- | ---------------------------------------------------- | ------------------------------------------ |

| Push | Push slide, vertical push, elastic push, squeeze | [css-push.md](./css-push.md) |

| Radial / Shape | Circle iris, diamond iris, diagonal split | [css-radial.md](./css-radial.md) |

| 3D | 3D card flip | [css-3d.md](./css-3d.md) |

| Scale / Zoom | Zoom through, zoom out | [css-scale.md](./css-scale.md) |

| Dissolve | Crossfade, blur crossfade, focus pull, color dip | [css-dissolve.md](./css-dissolve.md) |

| Cover | Staggered blocks, horizontal blinds, vertical blinds | [css-cover.md](./css-cover.md) |

| Light | Light leak, overexposure burn, film burn | [css-light.md](./css-light.md) |

| Distortion | Glitch, chromatic aberration, ripple, VHS tape | [css-distortion.md](./css-distortion.md) |

| Mechanical | Shutter, clock wipe | [css-mechanical.md](./css-mechanical.md) |

| Grid | Grid dissolve | [css-grid.md](./css-grid.md) |

| Other | Gravity drop, morph circle | [css-other.md](./css-other.md) |

| Blur | Blur through, directional blur | [css-blur.md](./css-blur.md) |

| Destruction | Page burn | [css-destruction.md](./css-destruction.md) |

## Shader Transitions

WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.

mdskills/hyperframes/references/transitions/css-destruction.md

4.4 kB

## Destruction

### Page Burn

The outgoing scene literally burns away from a corner. A fire front expands with noise-based irregular edges, a canvas draws the scorched char line at the burn boundary, and individual text characters/elements chip off and fall with gravity as the fire reaches them. The incoming scene reveals behind the burn.

This transition has three systems working together:

1. **Fire geometry** — a radial front expanding from a corner (e.g., bottom-right) with noise-based irregularity for organic edges

2. **Scene clipping** — the outgoing scene uses an SVG clip-path (with `fill-rule: evenodd`) that cuts a hole matching the fire front. As the fire expands, more of the scene is clipped away. All content (text, images, lines) burns with the page — no separate debris.

3. **Scorched edge** — a `<canvas>` overlay draws a radial gradient fringe at the fire boundary to simulate charring

**When to use:** Dramatic reveals, edgy/destructive mood, gaming, cyberpunk. This is the most dramatic transition in the catalog — reserve it for hero moments.

**Requirements:**

- A `<canvas>` element for the burn edge overlay

- A noise function for organic fire edge geometry

- SVG clip-path with evenodd fill-rule for the inverted clip

**Fire geometry (deterministic noise):**

```js

function noise(x) {

var ix = Math.floor(x),

fx = x - ix;

var a = Math.sin(ix * 127.1 + 311.7) * 43758.5453;

var b = Math.sin((ix + 1) * 127.1 + 311.7) * 43758.5453;

var t = fx * fx * (3 - 2 * fx);

return a - Math.floor(a) + (b - Math.floor(b) - (a - Math.floor(a))) * t;

}

function fireRadiusAtAngle(angle, progress) {

var base = progress * maxRadius;

return (

base +

noise(angle * 3 + progress * 4) * 50 +

noise(angle * 8 + progress * 9) * 20 +

noise(angle * 15 + progress * 15) * 8

);

}

```

**Incoming scene timing:** The incoming scene should NOT be visible during the burn. As the fire consumes the outgoing scene, **black shows through the holes** — this is the dramatic part. The viewer watches content being destroyed against blackness.

At ~90% through the burn, the incoming scene fades in SLOWLY from black — the background first, then content staggered. Use long, gentle fades (`power1.out`, 0.8-1.2s durations) so it feels like the new scene materializes from darkness, not a hard swap.

```js

// Scene 2 stays at opacity: 0 during the burn — black behind the fire

tl.set("#s2-title", { opacity: 0 }, T);

tl.set("#s2-subtitle", { opacity: 0 }, T);

// At 90% through, scene bg fades in slowly from black

var contentReveal = T + BURN_DURATION * 0.9;

tl.to("#scene2", { opacity: 1, duration: 1.2, ease: "power1.out" }, contentReveal);

// Content fades in staggered on top, even slower

tl.to("#s2-title", { opacity: 1, duration: 1.0, ease: "power1.out" }, contentReveal + 0.5);

tl.to("#s2-subtitle", { opacity: 1, duration: 0.8, ease: "power1.out" }, contentReveal + 0.7);

```

**Content burns with the page — no falling debris.** The clip-path on scene1 IS the effect — as the fire shape expands, everything behind the fire edge (text, images, lines) disappears naturally. Don't clone elements, don't create falling debris. The content is part of the page being consumed. The scorched canvas edge provides the visual char line at the burn boundary.

**Hide scene1 via `tl.set` at burn end — NEVER in `onComplete`.** Using `onComplete` to hide scene1 is not reversible when scrubbing. Instead, use a `tl.set` at the exact burn end time:

```js

tl.to(

burnState,

{

progress: 1,

duration: BURN_DURATION,

ease: "none",

onUpdate: function () {

var wp = burnState.progress;

var scene1 = document.getElementById("scene1");

if (wp <= 0) {

scene1.style.clipPath = "none"; // fully visible when rewound

} else if (wp < 1) {

scene1.style.clipPath = buildClipPath(wp);

}

drawEdge(wp);

// NO onComplete — use tl.set instead

);

// Hide scene1 at exact burn end — reversible via timeline

tl.set("#scene1", { opacity: 0 }, T + BURN_DURATION);

tl.set("#scene1", { clipPath: "none" }, T + BURN_DURATION);

```

The `onUpdate` handles clip-path and canvas edge per-frame. The `tl.set` handles the final hide — and GSAP automatically reverses it when scrubbing backward, restoring scene1 to `opacity: 1`.

The `onUpdate` callback is the key — it runs every frame to advance the clip-path and canvas edge in sync with the timeline.

mdskills/hyperframes/references/transitions/css-dissolve.md

2.4 kB

## Dissolve

### Crossfade

Simple opacity swap. The baseline.

```js

tl.to(old, { opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);

tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.inOut" }, T);

```

### Blur Crossfade

Dissolve with blur + scale shift. **Scale blur amount by energy** — see SKILL.md "Blur Intensity by Energy" section. The examples below show the medium (default) version. For calm compositions, increase to 20-30px with a 0.3-0.5s hold at peak blur. For high-energy, decrease to 3-6px with no hold.

**Medium (default):**

```js

tl.to(old, { filter: "blur(10px)", scale: 1.03, opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);

tl.fromTo(new,

{ filter: "blur(10px)", scale: 0.97, opacity: 0 },

{ filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.5, ease: "power2.inOut" }, T + 0.1);

```

**Calm (wellness, luxury) — heavy blur, holds at abstract color:**

```js

tl.to(old, { filter: "blur(25px)", scale: 1.05, duration: 0.6, ease: "power1.in" }, T);

tl.to(old, { opacity: 0, duration: 0.4, ease: "power1.in" }, T + 0.4);

tl.fromTo(new,

{ filter: "blur(25px)", scale: 0.95, opacity: 0 },

{ filter: "blur(25px)", scale: 0.95, opacity: 1, duration: 0.3, ease: "power1.inOut" }, T + 0.5);

tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.6, ease: "power1.out" }, T + 0.8);

```

### Focus Pull

Outgoing slowly blurs while incoming fades in sharp. Depth-of-field feel. **Scale blur amount and hold duration by energy.**

**Medium:**

```js

tl.to(old, { filter: "blur(15px)", duration: 0.5, ease: "power1.in" }, T);

tl.to(old, { opacity: 0, duration: 0.3, ease: "power2.in" }, T + 0.25);

tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, T + 0.25);

```

**Calm — slow rack focus with long hold at peak defocus:**

```js

tl.to(old, { filter: "blur(30px)", duration: 0.8, ease: "power1.in" }, T);

tl.to(old, { opacity: 0, duration: 0.5, ease: "power1.in" }, T + 0.6);

tl.fromTo(new, { opacity: 0, filter: "blur(20px)" },

{ opacity: 1, filter: "blur(20px)", duration: 0.3, ease: "power1.inOut" }, T + 0.7);

tl.to(new, { filter: "blur(0px)", duration: 0.6, ease: "power1.out" }, T + 1.0);

```

### Color Dip

Fade to solid color, hold, fade up new scene.

```js

tl.to(old, { opacity: 0, duration: 0.2, ease: "power2.in" }, T);

// Background color shows through

tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.2, ease: "power2.out" }, T + 0.25);

```

mdskills/hyperframes/references/transitions/css-light.md

2.3 kB

## Light

### Light Leak

Multiple warm-colored overlays wash across frame. Needs: a flat warm tint layer + 2-3 bright radial gradient divs, all larger than the frame so edges are never visible.

```js

// Warm tint washes over entire frame

tl.to("#leak-warm", { opacity: 0.4, duration: 0.3, ease: "power1.in" }, T);

// Bright leak elements drift in

tl.to("#leak-1", { opacity: 0.9, x: 300, duration: 0.5, ease: "sine.inOut" }, T + 0.05);

tl.to("#leak-2", { opacity: 0.8, x: 200, duration: 0.6, ease: "sine.inOut" }, T + 0.1);

// Peak warmth then swap

tl.to("#leak-warm", { opacity: 0.6, duration: 0.15, ease: "power2.in" }, T + 0.35);

tl.set(old, { opacity: 0 }, T + 0.45);

tl.set(new, { opacity: 1 }, T + 0.45);

// Leak fades

tl.to("#leak-warm", { opacity: 0, duration: 0.4, ease: "power2.out" }, T + 0.5);

tl.to("#leak-1", { opacity: 0, x: 600, duration: 0.35, ease: "power1.out" }, T + 0.5);

```

### Overexposure Burn

Scene progressively blows out to white using CSS `filter: brightness()`, then white overlay fades in. Swap at peak white. White recedes to reveal new scene.

```js

tl.to(old, { filter: "brightness(1.5)", scale: 1.03, duration: 0.2, ease: "power1.in" }, T);

tl.to(old, { filter: "brightness(3)", scale: 1.06, duration: 0.2, ease: "power2.in" }, T + 0.2);

tl.to("#flash-overlay", { opacity: 0.5, duration: 0.25, ease: "power1.in" }, T + 0.15);

tl.to("#flash-overlay", { opacity: 1, duration: 0.15, ease: "power2.in" }, T + 0.4);

tl.set(old, { opacity: 0, filter: "brightness(1)", scale: 1 }, T + 0.55);

tl.set(new, { opacity: 1 }, T + 0.55);

tl.to("#flash-overlay", { opacity: 0, duration: 0.35, ease: "power2.out" }, T + 0.55);

```

### Film Burn

Staggered warm overlays (amber, orange, red) bleed from one edge. Each overlay is a large radial gradient div at high z-index.

```js

tl.to("#burn-a", { opacity: 1, x: -300, duration: 0.4, ease: "power1.in" }, T);

tl.to("#burn-b", { opacity: 1, x: -500, duration: 0.5, ease: "power1.in" }, T + 0.05);

tl.to("#burn-c", { opacity: 1, x: -200, duration: 0.45, ease: "power1.in" }, T + 0.1);

tl.set(old, { opacity: 0 }, T + 0.35);

tl.set(new, { opacity: 1 }, T + 0.35);

tl.to("#burn-a", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.45);

tl.to("#burn-b", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.5);

tl.to("#burn-c", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.55);

```

mdskills/hyperframes/references/typography.md

9.1 kB

# Typography

The compiler embeds supported fonts — just write `font-family` in CSS.

## Banned

Training-data defaults that every LLM reaches for. These produce monoculture across compositions.

Inter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata, Syne

**Syne in particular** is the most overused "distinctive" display font. It is an instant AI design tell.

## Guardrails

You know these rules but you violate them. Stop.

- **Don't pair two sans-serifs.** You do this constantly — one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.

- **One expressive font per scene.** You pick two interesting fonts trying to make it "better." One performs, one recedes.

- **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.

- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.

## What You Don't Do Without Being Told

- **Tension should mean something.** Don't pattern-match pairings. Ask WHY these two fonts disagree. The pairing should embody the content's contradiction — mechanical vs human, public vs private, institutional vs personal. If you can't articulate the tension, it's arbitrary.

- **Register switching.** Assign different fonts to different communicative modes — one voice for statements, another for data, another for attribution. Not hierarchy on a page. Voices in a conversation.

- **Tension can live inside a single font.** A font that looks familiar but is secretly strange creates tension with the viewer's expectations, not with another font.

- **One variable changed = dramatic contrast.** Same letterforms, monospaced vs proportional. Same family at different optical sizes. Changing only rhythm while everything else stays constant.

- **Double personality works.** Two expressive fonts can coexist if they share an attitude (both irreverent, both precise) even when their forms are completely different.

- **Time is hierarchy.** The first element to appear is the most important. In video, sequence replaces position.

- **Motion is typography.** How a word enters carries as much meaning as the font. A 0.1s slam vs a 2s fade — same font, completely different message.

- **Fixed reading time.** 3 seconds on screen = must be readable in 2. Fewer words, larger type.

- **Tracking tighter than web.** -0.03em to -0.05em on display sizes. Video encoding compresses letter detail.

## Finding Fonts

Don't default to what you know. If the content is luxury, a grotesque sans might create more tension than the expected Didone serif. Decide the register first, then search.

Save this script to `/tmp/fontquery.py` and run with `curl -s 'https://fonts.google.com/metadata/fonts' > /tmp/gfonts.json && python3 /tmp/fontquery.py /tmp/gfonts.json`:

```python

import json, sys, random

from collections import OrderedDict

random.seed() # true random each run

with open(sys.argv[1]) as f:

data = json.load(f)

fonts = data.get("familyMetadataList", [])

ban = {"Inter","Roboto","Open Sans","Noto Sans","Lato","Poppins","Source Sans 3",

"PT Sans","Nunito","Outfit","Sora","Playfair Display","Cormorant Garamond",

"Bodoni Moda","EB Garamond","Cinzel","Prata","Arimo","Source Sans Pro","Syne"}

skip_pfx = ("Roboto","Noto ","Google Sans","Bpmf","Playwrite","Anek","BIZ ",

"Nanum","Shippori","Sawarabi","Zen ","Kaisei","Kiwi ","Yuji ","Radio ")

def ok(f):

if f["family"] in ban: return False

if any(f["family"].startswith(b) for b in skip_pfx): return False

if "latin" not in (f.get("subsets") or []): return False

return True

seen = set()

R = OrderedDict()

# Trending Sans — recent (2022+), popular (<300)

R["Trending Sans"] = []

for f in fonts:

if not ok(f) or f["family"] in seen: continue

if f.get("category") in ("Sans Serif","Display") and f.get("dateAdded","") >= "2022-01-01" and f.get("popularity",9999) < 300:

R["Trending Sans"].append(f); seen.add(f["family"])

# Trending Serif — recent (2018+), popular (<600)

R["Trending Serif"] = []

for f in fonts:

if not ok(f) or f["family"] in seen: continue

if f.get("category") == "Serif" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:

R["Trending Serif"].append(f); seen.add(f["family"])

# Monospace — recent (2018+), popular (<600)

R["Monospace"] = []

for f in fonts:

if not ok(f) or f["family"] in seen: continue

if f.get("category") == "Monospace" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:

R["Monospace"].append(f); seen.add(f["family"])

# Impact & Condensed — heavy display fonts with 800+ weight

R["Impact & Condensed"] = []

for f in fonts:

if not ok(f) or f["family"] in seen: continue

has_heavy = any(k in list(f.get("fonts",{}).keys()) for k in ("800","900"))

is_display = f.get("category") in ("Sans Serif","Display")

if has_heavy and is_display and f.get("popularity",9999) < 400:

R["Impact & Condensed"].append(f); seen.add(f["family"])

# Script & Handwriting — popular (<300)

R["Script & Handwriting"] = []

for f in fonts:

if not ok(f) or f["family"] in seen: continue

if f.get("category") == "Handwriting" and f.get("popularity",9999) < 300:

R["Script & Handwriting"].append(f); seen.add(f["family"])

# Randomize the top 5 in each category so the LLM doesn't always pick the same first result

for cat in R:

R[cat].sort(key=lambda x: x.get("popularity",9999))

top5 = R[cat][:5]

rest = R[cat][5:]

random.shuffle(top5)

R[cat] = top5 + rest

limits = {"Trending Sans":15,"Trending Serif":12,"Monospace":8,

"Impact & Condensed":12,"Script & Handwriting":10}

for cat in R:

items = R[cat][:limits.get(cat,10)]

if not items: continue

print(f"--- {cat} ({len(items)}) ---")

for ff in items:

var = "VAR" if ff.get("axes") else " "

print(f' {ff.get("popularity"):4d} | {var} | {ff["family"]}')

print()

```

Five categories: trending sans, trending serif, monospace, impact/condensed, script/handwriting. All dynamically filtered from Google Fonts metadata — no hardcoded font names. Cross classification boundaries when pairing.

## Selection Thinking

Don't pick fonts by category reflex (editorial → serif, tech → mono, modern → geometric sans). That's pattern matching, not design.

1. **Name the register.** What voice is the content speaking in? Institutional authority? Personal confession? Technical precision? Casual irreverence? The register narrows the field more than the category.

2. **Think physically.** Imagine the font as a physical object the brand could ship — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label inside a coat, a children's book printed on cheap newsprint, a tax form. Whichever physical object fits the register is pointing at the right _kind_ of typeface.

3. **Reject your first instinct.** The first font that feels right is usually your training-data default for that register. If you picked it last time too, find something else.

4. **Cross-check the assumption.** An editorial brief does NOT need a serif. A technical brief does NOT need a sans. A children's product does NOT need a rounded display font. The most distinctive choice often contradicts the category expectation.

## Similar-Font Pairing

Never pair two fonts that are similar but not identical — two geometric sans-serifs, two transitional serifs, two humanist sans. They create visual friction without clear hierarchy. The viewer senses something is "off" but can't articulate it. Either use one font at two weights, or pair fonts that contrast on multiple axes: serif + sans, condensed + wide, geometric + humanist.

## Dark Backgrounds

Light text on dark backgrounds creates two optical illusions you need to compensate for:

- **Increased apparent weight.** Light-on-dark reads heavier than dark-on-light at the same `font-weight`. Use 350 instead of 400 for body text. Headlines are less affected because size compensates.

- **Tighter apparent spacing.** Light halos around letterforms reduce perceived gaps. Increase `line-height` by 0.05-0.1 beyond your light-background value. For display sizes, add 0.01em `letter-spacing` to counteract.

## OpenType Features for Data

Most fonts ship with OpenType features that are off by default. Turn them on for data compositions:

```css

/* Tabular numbers — digits align vertically in columns */

.stat-value,

.timer,

.data-column {

font-variant-numeric: tabular-nums;

}

/* Diagonal fractions — renders 1/2 as ½ */

.recipe-amount,

.ratio {

font-variant-numeric: diagonal-fractions;

}

/* Small caps for abbreviations — less visual shouting */

.abbreviation,

.unit {

font-variant-caps: all-small-caps;

}

/* Disable ligatures in code — fi, fl, ffi should stay separate */

code,

.code {

font-variant-ligatures: none;

}

```

`tabular-nums` is essential any time numbers are stacked vertically — stat callouts, timers, scoreboards, data tables. Without it, digits have proportional widths and columns don't align.

mdskills/hyperframes/references/video-composition.md

3.6 kB

# Video Composition

Video frames are not web pages. These rules apply to every composition regardless of brand, style, or design.md.

## design.md Is Brand, Not Layout

design.md defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity.

**Strict from design.md:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette.

**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours.

## Density

A beat with 3 elements looks empty. A beat with 8-10 feels alive.

Every scene needs:

- **Background texture** — radial glow, oversized ghost type, color panel, grain, grid. Never solid flat color.

- **Midground content** — the actual message. Cards, stats, code blocks, images.

- **Foreground accents** — dividers, labels, data bars, registration marks, monospace metadata. The details that make it feel produced, not generated.

Aim for 8-10 visual elements per scene. Two of those should be decorative elements the user didn't ask for — you add them because empty frames look broken.

## Color Presence

Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye.

- Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements.

- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic.

- Tint neutrals toward the brand hue. Dead gray reads as undesigned.

## Scale

Web sizes are invisible on video. Everything scales up.

| Element | Web | Video |

| ------------------ | ------- | -------- |

| Headlines | 32-48px | 64-120px |

| Body text | 14-16px | 28-42px |

| Labels | 12px | 18-24px |

| Decorative opacity | 3-8% | 12-25% |

| Borders | 1px | 2-4px |

| Padding | 16-32px | 60-140px |

If you're writing a font-size under 24px in a video composition, justify it. If you're writing decorative opacity under 10%, it's invisible.

## Motion Intensity

Subtle reads as static at 30fps. Err toward more movement than feels safe.

- Every decorative element should have ambient motion: breathe, drift, pulse, orbit. Static decoratives feel dead.

- Vary motion per scene — don't repeat the same ambient pattern.

- Scene entrances should use 3+ different eases and directions. If every element enters from `y: 30, opacity: 0`, the scene has no choreography.

## Frame Composition

- **Two focal points minimum.** The eye needs somewhere to travel.

- **Fill the frame.** Hero text: 60-80% of frame width.

- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web layout pattern.

- **Split frames.** Data panel left, content right. Top bar with metadata, full-width below. Zone-based layouts over centered stacks.

- **Structural elements.** Rules, dividers, border panels. They create visual paths and animate well (`scaleX: 0` → `1`).

mjsskills/hyperframes/scripts/animation-map.mjs

19 kB

#!/usr/bin/env node

// animation-map.mjs — HyperFrames animation map for agents

// Reads every GSAP timeline registered in window.__timelines, enumerates

// tweens, samples bboxes at N points per tween, computes flags and

// human-readable summaries. Outputs a single animation-map.json.

// Usage:

// node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \

// [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N]

import { mkdir, writeFile } from "node:fs/promises";

import { resolve, join } from "node:path";

import { hyperframesPackageSpec, importPackagesOrBootstrap } from "./package-loader.mjs";

const {

createFileServer,

createCaptureSession,

initializeSession,

closeCaptureSession,

getCompositionDuration,

} = (

await importPackagesOrBootstrap(["@hyperframes/producer"], {

npmPackages: [hyperframesPackageSpec("@hyperframes/producer")],

})

)["@hyperframes/producer"];

// ─── CLI ─────────────────────────────────────────────────────────────────────

const args = parseArgs(process.argv.slice(2));

if (!args.composition) die("missing <composition-dir>");

const FRAMES = Number(args.frames ?? 6);

const OUT_DIR = resolve(args.out ?? ".hyperframes/anim-map");

const MIN_DUR = Number(args["min-duration"] ?? 0.15);

const WIDTH = Number(args.width ?? 1920);

const HEIGHT = Number(args.height ?? 1080);

const FPS = Number(args.fps ?? 30);

const COMP_DIR = resolve(args.composition);

await mkdir(OUT_DIR, { recursive: true });

// ─── Main ────────────────────────────────────────────────────────────────────

const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });

const session = await createCaptureSession(

server.url,

OUT_DIR,

{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },

null,

);

await initializeSession(session);

try {

const duration = await getCompositionDuration(session);

const tweens = await enumerateTweens(session);

const kept = tweens.filter((tw) => tw.end - tw.start >= MIN_DUR);

const report = {

composition: COMP_DIR,

duration,

totalTweens: tweens.length,

mappedTweens: kept.length,

skippedMicroTweens: tweens.length - kept.length,

tweens: [],

};

for (let i = 0; i < kept.length; i++) {

const tw = kept[i];

const times = Array.from(

{ length: FRAMES },

(_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3),

);

const bboxes = [];

for (const t of times) {

await seekTo(session, t);

const bbox = await measureTarget(session, tw.selectorHint);

bboxes.push({ t, ...bbox });

}

const animProps = tw.props.filter(

(p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p),

);

const flags = computeFlags(tw, bboxes, { width: WIDTH, height: HEIGHT });

const summary = describeTween(tw, animProps, bboxes, flags);

report.tweens.push({

index: i + 1,

selector: tw.selectorHint,

targets: tw.targetCount,

props: animProps,

start: +tw.start.toFixed(3),

end: +tw.end.toFixed(3),

duration: +(tw.end - tw.start).toFixed(3),

ease: tw.ease,

bboxes,

flags,

summary,

});

}

markCollisions(report.tweens);

for (const tw of report.tweens) {

if (tw.flags.includes("collision") && !tw.summary.includes("collision")) {

tw.summary += " Overlaps another animated element.";

}

// ── Composition-level analysis ──

report.choreography = buildTimeline(report.tweens, duration);

report.density = computeDensity(report.tweens, duration);

report.staggers = detectStaggers(report.tweens);

report.elements = buildElementLifecycles(report.tweens);

report.deadZones = findDeadZones(report.density, duration);

report.snapshots = await captureSnapshots(session, report.tweens, duration);

await writeFile(join(OUT_DIR, "animation-map.json"), JSON.stringify(report, null, 2));

printSummary(report);

} finally {

await closeCaptureSession(session).catch(() => {});

server.close();

}

// ─── Seek helper ────────────────────────────────────────────────────────────

async function seekTo(session, t) {

await session.page.evaluate((time) => {

if (window.__hf && typeof window.__hf.seek === "function") {

window.__hf.seek(time);

return;

}

const tls = window.__timelines;

if (tls) {

for (const tl of Object.values(tls)) {

if (typeof tl.seek === "function") tl.seek(time);

}

}, t);

await new Promise((r) => setTimeout(r, 100));

}

// ─── Timeline introspection ──────────────────────────────────────────────────

async function enumerateTweens(session) {

return await session.page.evaluate(() => {

const results = [];

const registry = window.__timelines || {};

const selectorOf = (el) => {

if (!el || !(el instanceof Element)) return null;

if (el.id) return `#${el.id}`;

const cls = [...el.classList].slice(0, 2).join(".");

return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();

};

const walk = (node, parentOffset = 0) => {

if (!node) return;

if (typeof node.getChildren === "function") {

const offset = parentOffset + (node.startTime?.() ?? 0);

for (const child of node.getChildren(true, true, true)) {

walk(child, offset);

}

return;

}

const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element);

if (!targets.length) return;

const vars = node.vars ?? {};

const props = Object.keys(vars).filter(

(k) =>

"duration",

"ease",

"delay",

"repeat",

"yoyo",

"onStart",

"onUpdate",

"onComplete",

"stagger",

].includes(k),

);

const start = parentOffset + (node.startTime?.() ?? 0);

const end = start + (node.duration?.() ?? 0);

results.push({

selectorHint: selectorOf(targets[0]) ?? "(unknown)",

targetCount: targets.length,

props,

start,

end,

ease: typeof vars.ease === "string" ? vars.ease : (vars.ease?.toString?.() ?? "none"),

});

};

for (const tl of Object.values(registry)) walk(tl, 0);

results.sort((a, b) => a.start - b.start);

return results;

});

}

async function measureTarget(session, selector) {

return await session.page.evaluate((sel) => {

const el = document.querySelector(sel);

if (!el) return { x: 0, y: 0, w: 0, h: 0, missing: true };

const r = el.getBoundingClientRect();

const cs = getComputedStyle(el);

return {

x: Math.round(r.x),

y: Math.round(r.y),

w: Math.round(r.width),

h: Math.round(r.height),

opacity: parseFloat(cs.opacity),

visible: cs.visibility !== "hidden" && cs.display !== "none",

};

}, selector);

}

// ─── Tween description (the key output for agents) ──────────────────────────

function describeTween(tw, props, bboxes, flags) {

const dur = (tw.end - tw.start).toFixed(2);

const parts = [];

parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);

// Movement

const first = bboxes[0];

const last = bboxes[bboxes.length - 1];

if (first && last) {

const dx = last.x - first.x;

const dy = last.y - first.y;

if (Math.abs(dx) > 3 || Math.abs(dy) > 3) {

const dirs = [];

if (Math.abs(dy) > 3) dirs.push(dy < 0 ? `${Math.abs(dy)}px up` : `${Math.abs(dy)}px down`);

if (Math.abs(dx) > 3)

dirs.push(dx < 0 ? `${Math.abs(dx)}px left` : `${Math.abs(dx)}px right`);

parts.push(`moves ${dirs.join(" and ")}`);

}

// Opacity

if (first && last && first.opacity !== undefined && last.opacity !== undefined) {

const o1 = first.opacity;

const o2 = last.opacity;

if (Math.abs(o2 - o1) > 0.1) {

if (o1 < 0.1 && o2 > 0.5) parts.push("fades in");

else if (o1 > 0.5 && o2 < 0.1) parts.push("fades out");

else parts.push(`opacity ${o1.toFixed(1)}→${o2.toFixed(1)}`);

}

// Scale (from props)

if (props.includes("scale") || props.includes("scaleX") || props.includes("scaleY")) {

parts.push("scales");

}

// Size changes

if (first && last) {

const dw = last.w - first.w;

const dh = last.h - first.h;

if (Math.abs(dw) > 5) parts.push(`width ${first.w}→${last.w}px`);

if (Math.abs(dh) > 5) parts.push(`height ${first.h}→${last.h}px`);

}

// Visibility

if (first && last && first.visible !== last.visible) {

parts.push(last.visible ? "becomes visible" : "becomes hidden");

}

// Final position

if (last && !last.missing) {

parts.push(`ends at (${last.x}, ${last.y}) ${last.w}×${last.h}px`);

}

// Flags

if (flags.length > 0) {

parts.push(`FLAGS: ${flags.join(", ")}`);

}

return parts.join(". ") + ".";

}

// ─── Flag computation ───────────────────────────────────────────────────────

function computeFlags(tw, bboxes, { width, height }) {

const flags = [];

const dur = tw.end - tw.start;

if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");

const anyOffscreen = bboxes.some(

(b) =>

b.x + b.w <= 0 ||

b.y + b.h <= 0 ||

b.x >= width ||

b.y >= height ||

b.x < -b.w * 0.5 ||

b.y < -b.h * 0.5 ||

b.x + b.w > width + b.w * 0.5 ||

b.y + b.h > height + b.h * 0.5,

);

if (anyOffscreen) flags.push("offscreen");

if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) {

flags.push("invisible");

}

if (dur < 0.2 && tw.props.some((p) => ["y", "x", "opacity", "scale"].includes(p))) {

flags.push("paced-fast");

}

if (dur > 2.0) flags.push("paced-slow");

return flags;

}

function markCollisions(tweens) {

for (let i = 0; i < tweens.length; i++) {

for (let j = i + 1; j < tweens.length; j++) {

const a = tweens[i];

const b = tweens[j];

if (a.end <= b.start || b.end <= a.start) continue;

for (const ba of a.bboxes) {

const bb = b.bboxes.find((x) => Math.abs(x.t - ba.t) < 0.05);

if (!bb) continue;

const overlap = rectOverlapArea(ba, bb);

const aArea = ba.w * ba.h;

if (aArea > 0 && overlap / aArea > 0.3) {

if (!a.flags.includes("collision")) a.flags.push("collision");

if (!b.flags.includes("collision")) b.flags.push("collision");

break;

}

function rectOverlapArea(a, b) {

const x1 = Math.max(a.x, b.x);

const y1 = Math.max(a.y, b.y);

const x2 = Math.min(a.x + a.w, b.x + b.w);

const y2 = Math.min(a.y + a.h, b.y + b.h);

return Math.max(0, x2 - x1) * Math.max(0, y2 - y1);

}

// ─── Composition-level analysis ─────────────────────────────────────────────

function buildTimeline(tweens, duration) {

const cols = 60;

const lines = [];

const secPerCol = duration / cols;

lines.push("Timeline (" + duration.toFixed(1) + "s, each char ≈ " + secPerCol.toFixed(2) + "s):");

lines.push(" " + "0s" + " ".repeat(cols - 8) + duration.toFixed(0) + "s");

lines.push(" " + "┼" + "─".repeat(cols - 1) + "┤");

for (const tw of tweens) {

const startCol = Math.floor(tw.start / secPerCol);

const endCol = Math.min(cols, Math.ceil(tw.end / secPerCol));

const bar =

" ".repeat(startCol) +

"█".repeat(Math.max(1, endCol - startCol)) +

" ".repeat(Math.max(0, cols - endCol));

const label = tw.selector + " " + tw.props.join("+");

lines.push(" " + bar + " " + label);

}

return lines.join("\n");

}

function computeDensity(tweens, duration) {

const buckets = [];

for (let t = 0; t < duration; t += 0.5) {

const active = tweens.filter((tw) => tw.start <= t + 0.5 && tw.end >= t);

buckets.push({ t: +t.toFixed(1), activeTweens: active.length });

}

return buckets;

}

function findDeadZones(density, duration) {

const zones = [];

let zoneStart = null;

for (const d of density) {

if (d.activeTweens === 0) {

if (zoneStart === null) zoneStart = d.t;

} else {

if (zoneStart !== null) {

const zoneEnd = d.t;

if (zoneEnd - zoneStart >= 1.0) {

zones.push({

start: zoneStart,

end: zoneEnd,

duration: +(zoneEnd - zoneStart).toFixed(1),

note:

"No animation for " +

(zoneEnd - zoneStart).toFixed(1) +

"s. Intentional hold or missing entrance?",

});

}

zoneStart = null;

}

if (zoneStart !== null && duration - zoneStart >= 1.0) {

zones.push({

start: zoneStart,

end: +duration.toFixed(1),

duration: +(duration - zoneStart).toFixed(1),

note:

"No animation for " +

(duration - zoneStart).toFixed(1) +

"s at end. Final hold or missing outro?",

});

}

return zones;

}

function detectStaggers(tweens) {

const groups = [];

const used = new Set();

for (let i = 0; i < tweens.length; i++) {

if (used.has(i)) continue;

const tw = tweens[i];

const group = [tw];

used.add(i);

for (let j = i + 1; j < tweens.length; j++) {

if (used.has(j)) continue;

const other = tweens[j];

const sameProps = tw.props.join(",") === other.props.join(",");

const sameDuration = Math.abs(tw.duration - other.duration) < 0.05;

const closeInTime = other.start - tw.start < tw.duration * 4;

if (sameProps && sameDuration && closeInTime) {

group.push(other);

used.add(j);

}

if (group.length >= 3) {

const intervals = [];

for (let k = 1; k < group.length; k++) {

intervals.push(+(group[k].start - group[k - 1].start).toFixed(3));

}

const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;

const maxDrift = Math.max(...intervals.map((iv) => Math.abs(iv - avgInterval)));

const consistent = maxDrift < avgInterval * 0.3;

groups.push({

elements: group.map((g) => g.selector),

props: tw.props,

intervals,

avgInterval: +avgInterval.toFixed(3),

consistent,

note: consistent

? group.length +

" elements stagger at " +

(avgInterval * 1000).toFixed(0) +

"ms intervals"

: group.length +

" elements stagger with uneven intervals (" +

intervals.map((iv) => (iv * 1000).toFixed(0) + "ms").join(", ") +

")",

});

}

return groups;

}

function buildElementLifecycles(tweens) {

const elements = {};

for (const tw of tweens) {

const sel = tw.selector;

if (!elements[sel]) {

elements[sel] = { firstTween: tw.start, lastTween: tw.end, tweenCount: 0, props: new Set() };

}

elements[sel].firstTween = Math.min(elements[sel].firstTween, tw.start);

elements[sel].lastTween = Math.max(elements[sel].lastTween, tw.end);

elements[sel].tweenCount++;

tw.props.forEach((p) => elements[sel].props.add(p));

}

const result = {};

for (const [sel, data] of Object.entries(elements)) {

const lastBbox = findLastBbox(tweens, sel);

result[sel] = {

firstAppears: +data.firstTween.toFixed(3),

lastAnimates: +data.lastTween.toFixed(3),

tweenCount: data.tweenCount,

props: [...data.props],

endsVisible: lastBbox ? lastBbox.opacity > 0.1 && lastBbox.visible : null,

finalPosition: lastBbox

? { x: lastBbox.x, y: lastBbox.y, w: lastBbox.w, h: lastBbox.h }

: null,

};

}

return result;

}

function findLastBbox(tweens, selector) {

for (let i = tweens.length - 1; i >= 0; i--) {

if (tweens[i].selector === selector && tweens[i].bboxes?.length > 0) {

return tweens[i].bboxes[tweens[i].bboxes.length - 1];

}

return null;

}

async function captureSnapshots(session, tweens, duration) {

const times = [0, duration * 0.25, duration * 0.5, duration * 0.75, duration - 0.1];

const snapshots = [];

for (const t of times) {

await seekTo(session, t);

const visible = await session.page.evaluate(() => {

const out = [];

const els = document.querySelectorAll("[id]");

for (const el of els) {

const cs = getComputedStyle(el);

if (cs.display === "none") continue;

const opacity = parseFloat(cs.opacity);

if (opacity < 0.01) continue;

const rect = el.getBoundingClientRect();

if (rect.width < 1 || rect.height < 1) continue;

out.push({

id: el.id,

x: Math.round(rect.x),

y: Math.round(rect.y),

w: Math.round(rect.width),

h: Math.round(rect.height),

opacity: +opacity.toFixed(2),

});

}

return out;

});

const activeTweens = tweens

.filter((tw) => tw.start <= t && tw.end >= t)

.map((tw) => tw.selector);

snapshots.push({

t: +t.toFixed(2),

visibleElements: visible.length,

animatingNow: activeTweens,

elements: visible,

});

}

return snapshots;

}

// ─── Output ─────────────────────────────────────────────────────────────────

function printSummary(report) {

console.log(

`\nAnimation map: ${report.mappedTweens}/${report.totalTweens} tweens (skipped ${report.skippedMicroTweens} micro-tweens)`,

);

const flagCounts = {};

for (const tw of report.tweens) {

for (const f of tw.flags) flagCounts[f] = (flagCounts[f] ?? 0) + 1;

}

if (Object.keys(flagCounts).length > 0) {

for (const [f, n] of Object.entries(flagCounts)) console.log(` ${f}: ${n}`);

}

if (report.staggers?.length > 0) {

console.log(` staggers: ${report.staggers.map((s) => s.note).join("; ")}`);

}

if (report.deadZones?.length > 0) {

console.log(

` dead zones: ${report.deadZones.map((z) => z.start + "-" + z.end + "s").join(", ")}`,

);

}

console.log(report.choreography);

}

function parseArgs(argv) {

const out = {};

let positional = 0;

for (let i = 0; i < argv.length; i++) {

const a = argv[i];

if (a.startsWith("--")) {

const k = a.slice(2);

const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];

out[k] = v;

} else if (positional === 0) {

out.composition = a;

positional++;

}

return out;

}

function die(msg) {

console.error(`animation-map: ${msg}`);

process.exit(2);

}

mjsskills/hyperframes/scripts/contrast-report.mjs

12 kB

#!/usr/bin/env node

// contrast-report.mjs — HyperFrames contrast audit

// Reads a composition, seeks to N sample timestamps, walks the DOM for text

// elements, measures the WCAG 2.1 contrast ratio between each element's

// declared foreground color and the pixels behind it, and emits:

// - contrast-report.json (machine-readable, one entry per text element × sample)

// - contrast-overlay.png (sprite grid; magenta=fail AA, yellow=pass AA only, green=AAA)

// Usage:

// node skills/hyperframes/scripts/contrast-report.mjs <composition-dir> \

// [--samples N] [--out <dir>] [--width W] [--height H] [--fps N]

// The composition directory must contain an index.html. Raw authoring HTML

// works — the producer's file server auto-injects the runtime at serve time.

// Exits 1 if any text element fails WCAG AA.

import { mkdir, writeFile } from "node:fs/promises";

import { resolve } from "node:path";

import { hyperframesPackageSpec, importPackagesOrBootstrap } from "./package-loader.mjs";

// Use the producer's file server — it auto-injects the HyperFrames runtime

// and render-seek bridge, so raw authoring HTML works without a build step.

const packages = await importPackagesOrBootstrap(["@hyperframes/producer", "sharp"], {

npmPackages: [hyperframesPackageSpec("@hyperframes/producer"), "sharp@0.34.5"],

});

const sharp = packages.sharp.default;

const {

createFileServer,

createCaptureSession,

initializeSession,

closeCaptureSession,

captureFrameToBuffer,

getCompositionDuration,

} = packages["@hyperframes/producer"];

const args = parseArgs(process.argv.slice(2));

if (!args.composition) die("missing <composition-dir>");

const SAMPLES = Number(args.samples ?? 10);

const OUT_DIR = resolve(args.out ?? ".hyperframes/contrast");

const WIDTH = Number(args.width ?? 1920);

const HEIGHT = Number(args.height ?? 1080);

const FPS = Number(args.fps ?? 30);

const COMP_DIR = resolve(args.composition);

await mkdir(OUT_DIR, { recursive: true });

const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });

const session = await createCaptureSession(

server.url,

OUT_DIR,

{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },

null,

);

await initializeSession(session);

try {

const duration = await getCompositionDuration(session);

const times = Array.from(

{ length: SAMPLES },

(_, i) => +(((i + 0.5) / SAMPLES) * duration).toFixed(3),

);

const allEntries = [];

const overlayFrames = [];

for (let i = 0; i < times.length; i++) {

const t = times[i];

const { buffer: pngBuf } = await captureFrameToBuffer(session, i, t);

const elements = await probeTextElements(session, t);

const annotated = await annotateFrame(pngBuf, elements);

overlayFrames.push({ t, png: annotated });

for (const el of elements) allEntries.push({ time: t, ...el });

}

const report = {

composition: COMP_DIR,

width: WIDTH,

height: HEIGHT,

duration,

samples: times,

entries: allEntries,

summary: summarize(allEntries),

};

await writeFile(resolve(OUT_DIR, "contrast-report.json"), JSON.stringify(report, null, 2));

await writeOverlaySprite(overlayFrames, resolve(OUT_DIR, "contrast-overlay.png"));

printSummary(report);

process.exitCode = report.summary.failAA > 0 ? 1 : 0;

} finally {

await closeCaptureSession(session).catch(() => {});

server.close();

}

// ─── DOM probe (runs in the page) ────────────────────────────────────────────

async function probeTextElements(session, _t) {

// `session.page` is the Puppeteer Page owned by the capture session.

// We pass a pure function to `evaluate`: it walks the DOM and returns

// enough info for us to compute a ratio in Node using the frame buffer.

return await session.page.evaluate(() => {

/** @type {Array<{selector: string, text: string, fg: [number,number,number,number], fontSize: number, fontWeight: number, bbox: {x:number,y:number,w:number,h:number}}>} */

const out = [];

const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);

const parseColor = (c) => {

const m = c.match(/rgba?$([^)]+)$/);

if (!m) return [0, 0, 0, 1];

const parts = m[1].split(",").map((s) => parseFloat(s.trim()));

return [parts[0], parts[1], parts[2], parts[3] ?? 1];

};

const selectorOf = (el) => {

if (el.id) return `#${el.id}`;

const cls = [...el.classList].slice(0, 2).join(".");

return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();

};

let el;

while ((el = walker.nextNode())) {

// must have direct text

const direct = [...el.childNodes].some(

(n) => n.nodeType === 3 && n.textContent.trim().length,

);

if (!direct) continue;

const cs = getComputedStyle(el);

if (cs.visibility === "hidden" || cs.display === "none") continue;

if (parseFloat(cs.opacity) <= 0.01) continue;

const rect = el.getBoundingClientRect();

if (rect.width < 8 || rect.height < 8) continue;

out.push({

selector: selectorOf(el),

text: el.textContent.trim().slice(0, 60),

fg: parseColor(cs.color),

fontSize: parseFloat(cs.fontSize),

fontWeight: Number(cs.fontWeight) || 400,

bbox: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },

});

}

return out;

});

}

// ─── Pixel sampling + WCAG math ──────────────────────────────────────────────

async function annotateFrame(pngBuf, elements) {

const img = sharp(pngBuf);

const meta = await img.metadata();

const { width, height } = meta;

const raw = await img.ensureAlpha().raw().toBuffer();

const channels = 4;

const measured = [];

for (const el of elements) {

if (isBBoxOutsideFrame(el.bbox, width, height)) continue;

const bg = sampleRingMedian(raw, width, height, channels, el.bbox);

if (!bg) continue;

const fg = compositeOver(el.fg, bg); // flatten any alpha against measured bg

const ratio = wcagRatio(fg, bg);

const large = isLargeText(el.fontSize, el.fontWeight);

el.bg = bg;

el.ratio = +ratio.toFixed(2);

el.wcagAA = large ? ratio >= 3 : ratio >= 4.5;

el.wcagAALarge = ratio >= 3;

el.wcagAAA = large ? ratio >= 4.5 : ratio >= 7;

measured.push(el);

}

elements.length = 0;

elements.push(...measured);

// Draw boxes + ratio labels as an SVG overlay (sharp composite).

const svg = buildOverlaySVG(measured, width, height);

return await sharp(pngBuf)

.composite([{ input: Buffer.from(svg), top: 0, left: 0 }])

.png()

.toBuffer();

}

function sampleRingMedian(raw, width, height, channels, bbox) {

// 4-px ring immediately outside the element bbox. Median of each channel.

const r = [],

g = [],

b = [];

const x0 = Math.max(0, Math.floor(bbox.x) - 4);

const x1 = Math.min(width - 1, Math.ceil(bbox.x + bbox.w) + 4);

const y0 = Math.max(0, Math.floor(bbox.y) - 4);

const y1 = Math.min(height - 1, Math.ceil(bbox.y + bbox.h) + 4);

const pushPixel = (x, y) => {

if (x < 0 || x >= width || y < 0 || y >= height) return;

const i = (y * width + x) * channels;

r.push(raw[i]);

g.push(raw[i + 1]);

b.push(raw[i + 2]);

};

for (let x = x0; x <= x1; x++) {

pushPixel(x, y0);

pushPixel(x, y1);

}

for (let y = y0; y <= y1; y++) {

pushPixel(x0, y);

pushPixel(x1, y);

}

if (r.length === 0) return null;

return [median(r), median(g), median(b), 1];

}

function isBBoxOutsideFrame(bbox, width, height) {

return bbox.x + bbox.w <= 0 || bbox.y + bbox.h <= 0 || bbox.x >= width || bbox.y >= height;

}

function median(arr) {

const s = [...arr].sort((a, b) => a - b);

return s[Math.floor(s.length / 2)];

}

function compositeOver([fr, fg, fb, fa], [br, bg, bb]) {

return [

Math.round(fr * fa + br * (1 - fa)),

Math.round(fg * fa + bg * (1 - fa)),

Math.round(fb * fa + bb * (1 - fa)),

];

}

function relLum([r, g, b]) {

const ch = (v) => {

const s = v / 255;

return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;

};

return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);

}

function wcagRatio(a, b) {

const la = relLum(a);

const lb = relLum(b);

const [L1, L2] = la > lb ? [la, lb] : [lb, la];

return (L1 + 0.05) / (L2 + 0.05);

}

function isLargeText(fontSize, fontWeight) {

return fontSize >= 24 || (fontSize >= 19 && fontWeight >= 700);

}

// ─── Overlay rendering ───────────────────────────────────────────────────────

function buildOverlaySVG(elements, w, h) {

const rects = elements

.map((el) => {

const color = !el.wcagAA ? "#ff00aa" : !el.wcagAAA ? "#ffcc00" : "#00e08a";

const { x, y, w: bw, h: bh } = el.bbox;

return `

<rect x="${x}" y="${y}" width="${bw}" height="${bh}"

fill="none" stroke="${color}" stroke-width="3"/>

${el.ratio.toFixed(1)}:1

</text>`;

})

.join("");

return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">${rects}</svg>`;

}

async function writeOverlaySprite(frames, outPath) {

if (!frames.length) return;

const cols = Math.min(frames.length, 5);

const rows = Math.ceil(frames.length / cols);

const { width, height } = await sharp(frames[0].png).metadata();

const scale = 0.25;

const cellW = Math.round(width * scale);

const cellH = Math.round(height * scale);

const cells = await Promise.all(

frames.map(async (f) => ({

input: await sharp(f.png).resize(cellW, cellH).png().toBuffer(),

time: f.t,

})),

);

const composites = cells.map((c, i) => ({

input: c.input,

top: Math.floor(i / cols) * cellH,

left: (i % cols) * cellW,

}));

await sharp({

create: {

width: cols * cellW,

height: rows * cellH,

channels: 3,

background: { r: 16, g: 16, b: 20 },

})

.composite(composites)

.png()

.toFile(outPath);

}

// ─── Summary ────────────────────────────────────────────────────────────────

function summarize(entries) {

const total = entries.length;

const failAA = entries.filter((e) => !e.wcagAA).length;

const passAAonly = entries.filter((e) => e.wcagAA && !e.wcagAAA).length;

const passAAA = entries.filter((e) => e.wcagAAA).length;

return { total, failAA, passAAonly, passAAA };

}

function printSummary({ summary, entries }) {

const { total, failAA, passAAonly, passAAA } = summary;

console.log(`\nContrast report: ${total} text-element samples`);

console.log(` fail WCAG AA: ${failAA}`);

console.log(` pass AA, not AAA: ${passAAonly}`);

console.log(` pass AAA: ${passAAA}`);

if (failAA) {

console.log("\nFailures:");

for (const e of entries.filter((x) => !x.wcagAA)) {

console.log(` t=${e.time}s ${e.selector.padEnd(24)} ${e.ratio.toFixed(2)}:1 "${e.text}"`);

}

// ─── Utilities ──────────────────────────────────────────────────────────────

function parseArgs(argv) {

const out = {};

let positional = 0;

for (let i = 0; i < argv.length; i++) {

const a = argv[i];

if (a.startsWith("--")) {

const k = a.slice(2);

const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];

out[k] = v;

} else if (positional === 0) {

out.composition = a;

positional++;

}

return out;

}

function die(msg) {

console.error(`contrast-report: ${msg}`);

process.exit(2);

}

mjsskills/hyperframes/scripts/package-loader.mjs

8.1 kB

import { spawnSync } from "node:child_process";

import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";

import { createRequire } from "node:module";

import { tmpdir } from "node:os";

import { basename, delimiter, dirname, join, parse, resolve } from "node:path";

import { createInterface } from "node:readline/promises";

import { fileURLToPath, pathToFileURL } from "node:url";

const HERE = dirname(fileURLToPath(import.meta.url));

const BOOTSTRAP_ENV = "HYPERFRAMES_SKILL_DEPS_BOOTSTRAPPED";

const BOOTSTRAP_CONFIRM_ENV = "HYPERFRAMES_SKILL_BOOTSTRAP_DEPS";

const NODE_MODULES_ENV = "HYPERFRAMES_SKILL_NODE_MODULES";

export async function importPackagesOrBootstrap(packageNames, options = {}) {

const entries = new Map();

const missing = [];

for (const packageName of packageNames) {

const entry = resolvePackageEntry(packageName);

if (entry) entries.set(packageName, entry);

else missing.push(packageName);

}

if (missing.length > 0 && !process.env[BOOTSTRAP_ENV]) {

const npmPackages = options.npmPackages ?? missing;

assertPinnedPackageSpecs(npmPackages);

await confirmBootstrap(npmPackages);

bootstrapWithNpmInstall(npmPackages);

}

if (missing.length > 0) {

throw new Error(

[

`Could not resolve required package(s): ${missing.join(", ")}`,

"Install them in this project, for example:",

` npm install --save-dev ${packageNames.map(shellQuote).join(" ")}`,

].join("\n"),

);

}

const modules = {};

for (const [packageName, entry] of entries) {

modules[packageName] = await import(pathToFileURL(entry).href);

}

return modules;

}

export function hyperframesPackageSpec(packageName) {

const version = readBundledHyperframesVersion();

if (!version) {

throw new Error(

[

`Could not determine the bundled HyperFrames version for ${packageName}.`,

"Install the package yourself or pass a pinned options.npmPackages entry.",

].join("\n"),

);

}

return `${packageName}@${version}`;

}

function resolvePackageEntry(packageName) {

const bases = [process.cwd(), HERE, ...envNodeModulesDirs(), ...nodeModulesDirsFromPath()];

const seen = new Set();

for (const base of bases) {

const normalized = resolve(base);

if (seen.has(normalized)) continue;

seen.add(normalized);

try {

return createRequire(join(normalized, "__hyperframes_skill_loader__.cjs")).resolve(

packageName,

);

} catch {

const packageDir = findPackageDir(normalized, packageName);

const packageEntry = packageDir ? readPackageEntry(packageDir) : null;

if (packageEntry) return packageEntry;

}

return null;

}

function readBundledHyperframesVersion() {

for (const ancestor of ancestors(HERE)) {

const directVersion = readPackageVersion(join(ancestor, "package.json"));

if (directVersion) return directVersion;

const monorepoCliVersion = readPackageVersion(

join(ancestor, "packages", "cli", "package.json"),

);

if (monorepoCliVersion) return monorepoCliVersion;

}

return null;

}

function readPackageVersion(packageJsonPath) {

try {

const manifest = JSON.parse(readFileSync(packageJsonPath, "utf8"));

if (manifest.name === "hyperframes" || manifest.name === "@hyperframes/cli") {

return typeof manifest.version === "string" ? manifest.version : null;

}

} catch {

// Keep searching ancestor package manifests.

}

return null;

}

function envNodeModulesDirs() {

return (process.env[NODE_MODULES_ENV] ?? "").split(delimiter).filter(Boolean);

}

function nodeModulesDirsFromPath() {

const dirs = [];

for (const entry of (process.env.PATH ?? "").split(delimiter)) {

if (!entry.endsWith(`${join("node_modules", ".bin")}`)) continue;

dirs.push(dirname(entry));

}

return dirs;

}

function findPackageDir(base, packageName) {

const packageSegments = packageName.split("/");

const roots =

basename(base) === "node_modules"

? [base]

: ancestors(base).map((ancestor) => join(ancestor, "node_modules"));

for (const root of roots) {

const packageDir = join(root, ...packageSegments);

if (existsSync(join(packageDir, "package.json"))) return packageDir;

}

return null;

}

function readPackageEntry(packageDir) {

try {

const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));

const entry = exportEntry(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";

const entryPath = join(packageDir, entry);

return existsSync(entryPath) ? entryPath : null;

} catch {

return null;

}

function exportEntry(exports) {

const root =

typeof exports === "object" && exports !== null ? (exports["."] ?? exports) : exports;

if (typeof root === "string") return root;

if (typeof root !== "object" || root === null) return null;

if (typeof root.import === "string") return root.import;

if (typeof root.default === "string") return root.default;

if (typeof root.node === "string") return root.node;

if (typeof root.node === "object" && root.node !== null) {

return root.node.import ?? root.node.default ?? null;

}

return null;

}

function assertPinnedPackageSpecs(packageSpecs) {

const unpinned = packageSpecs.filter((spec) => !hasVersionSpec(spec));

if (unpinned.length === 0) return;

throw new Error(

[

`Refusing to bootstrap unpinned package spec(s): ${unpinned.join(", ")}`,

"Pass pinned npm package specs, for example:",

` ${packageSpecs.map((spec) => (hasVersionSpec(spec) ? spec : `${spec}@<version>`)).join(" ")}`,

].join("\n"),

);

}

function hasVersionSpec(packageSpec) {

if (packageSpec.startsWith("@")) {

const slash = packageSpec.indexOf("/");

return slash !== -1 && packageSpec.indexOf("@", slash + 1) !== -1;

}

return packageSpec.includes("@");

}

async function confirmBootstrap(packageSpecs) {

if (process.env[BOOTSTRAP_CONFIRM_ENV] === "1") return;

const installLine = `npm install --ignore-scripts --no-save ${packageSpecs.map(shellQuote).join(" ")}`;

if (!process.stdin.isTTY) {

throw new Error(

[

"Required helper package(s) are missing.",

"To allow a one-time temporary dependency bootstrap for this run, set:",

` ${BOOTSTRAP_CONFIRM_ENV}=1`,

"The bootstrap command will be:",

` ${installLine}`,

].join("\n"),

);

}

const rl = createInterface({ input: process.stdin, output: process.stderr });

try {

const answer = await rl.question(

[

"HyperFrames helper package(s) are missing.",

`Run a temporary install with lifecycle scripts disabled?`,

` ${installLine}`,

"Proceed? [y/N] ",

].join("\n"),

);

if (!/^(y|yes)$/i.test(answer.trim())) {

throw new Error("Dependency bootstrap cancelled.");

}

} finally {

rl.close();

}

function ancestors(start) {

const dirs = [];

let current = resolve(start);

const root = parse(current).root;

while (current && current !== root) {

dirs.push(current);

current = dirname(current);

}

dirs.push(root);

return dirs;

}

function bootstrapWithNpmInstall(packageNames) {

const installRoot = mkdtempSync(join(tmpdir(), "hyperframes-skill-deps-"));

const installResult = spawnSync(

process.platform === "win32" ? "npm.cmd" : "npm",

[

"install",

"--silent",

"--no-audit",

"--no-fund",

"--ignore-scripts",

"--no-save",

"--prefix",

installRoot,

...packageNames,

{ stdio: "inherit" },

);

if (installResult.error) throw installResult.error;

if (installResult.status !== 0) {

rmSync(installRoot, { recursive: true, force: true });

process.exit(installResult.status ?? 1);

}

const args = [...process.argv.slice(1)];

const result = spawnSync(process.execPath, args, {

stdio: "inherit",

env: {

...process.env,

[BOOTSTRAP_ENV]: "1",

[NODE_MODULES_ENV]: join(installRoot, "node_modules"),

});

rmSync(installRoot, { recursive: true, force: true });

if (result.error) throw result.error;

process.exit(result.status ?? 1);

}

function shellQuote(value) {

if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;

return `'${value.replace(/'/g, "'\\''")}'`;

}

mdskills/hyperframes/SKILL.md

30 kB

---

description: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

---

# HyperFrames

HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.

## Approach

### Discovery (exploratory requests only)

For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors:

- **Audience** — who watches this? Developers? Executives? General consumers?

- **Platform** — where does it play? Social (15s), website hero, product demo, internal?

- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed?

- **Variations** — does the user want options, or a single best shot?

For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery.

For exploratory requests, consider offering 2-3 variations that differ meaningfully — not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this — it's a tool available when appropriate.

### Step 1: Design system

If `design.md` or `DESIGN.md` exists in the project, read it first (check both casings — they're different files on Linux). It's the source of truth for brand colors, fonts, and constraints. Use its exact values — don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables — just extract the values).

If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "design.md specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]."

If no `design.md` exists, offer the user a choice:

1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match.

2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](references/design-picker.md) for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation.

3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md).

**design.md defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity.

### Step 2: Prompt expansion

Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way.

Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format.

### Step 3: Plan

Before writing HTML, think at a high level:

1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.

2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).

3. **Rhythm** — declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read [references/beat-direction.md](references/beat-direction.md) for rhythm templates.

4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.

5. **Layout** — build the end-state first. See "Layout Before Animation" below.

6. **Animate** — then add motion using the rules below.

**Build what was asked.** A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them — don't add them.

For small edits (fix a color, adjust timing, add one element), skip straight to the rules.

<HARD-GATE>

Before writing ANY composition HTML — verify you have a visual identity from Step 1. If you're reaching for `#333`, `#3b82f6`, or `Roboto`, you skipped it.

</HARD-GATE>

## Layout Before Animation

Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.

**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion.

### The process

1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build.

2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.

3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there. (In sub-compositions loaded via `data-composition-src`, prefer `gsap.fromTo()` — see load-bearing GSAP rules in [references/motion-principles.md](references/motion-principles.md).)

4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position.

### Example

```css

/* scene-content fills the scene, padding positions content */

.scene-content {

display: flex;

flex-direction: column;

justify-content: center;

width: 100%;

height: 100%;

padding: 120px 160px;

gap: 24px;

box-sizing: border-box;

}

.title {

font-size: 120px;

}

.subtitle {

font-size: 42px;

}

/* Container fills any scene size (1920x1080, 1080x1920, etc).

Padding positions content. Flex + gap handles spacing. */

```

**WRONG — hardcoded dimensions and absolute positioning:**

```css

.scene-content {

position: absolute;

top: 200px;

left: 160px;

width: 1920px;

height: 1080px;

display: flex; /* ... */

}

```

```js

// Step 3: Animate INTO those positions

tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);

tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);

tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Step 4: Animate OUT from those positions

tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);

tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);

tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

```

### When elements share space across time

If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.

### What counts as intentional overlap

Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.

## Data Attributes

### All Clips

| Attribute | Required | Values |

| ------------------ | --------------------------------- | ------------------------------------------------------ |

| `id` | Yes | Unique identifier |

| `data-start` | Yes | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) |

| `data-duration` | Required for img/div/compositions | Seconds. Video/audio defaults to media duration. |

| `data-track-index` | Yes | Integer. Same-track clips cannot overlap. |

| `data-media-start` | No | Trim offset into source (seconds) |

| `data-volume` | No | 0-1 (default 1) |

`data-track-index` does **not** affect visual layering — use CSS `z-index`.

### Composition Clips

| Attribute | Required | Values |

| ---------------------------- | -------- | ----------------------------------------------------------------- |

| `data-composition-id` | Yes | Unique composition ID |

| `data-start` | Yes | Start time (root composition: use `"0"`) |

| `data-duration` | Yes | Takes precedence over GSAP timeline duration |

| `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) |

| `data-composition-src` | No | Path to external HTML file |

| `data-variable-values` | No | JSON object of per-instance variable overrides on a sub-comp host |

On the root `<html>` element:

| Attribute | Required | Values |

| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |

| `data-composition-variables` | No | JSON array of declared variables (id/type/label/default) — drives Studio editing UI and provides defaults for `getVariables()` |

## Composition Structure

Sub-compositions loaded via `data-composition-src` use a `<template>` wrapper. **Standalone compositions (the main index.html) do NOT use `<template>`** — they put the `data-composition-id` div directly in `<body>`. Using `<template>` on a standalone file hides all content from the browser and breaks rendering.

Sub-composition structure:

```html

<style>

[data-composition-id="my-comp"] {

/* scoped styles */

}

</style>

window.__timelines = window.__timelines || {};

const tl = gsap.timeline({ paused: true });

// tweens...

window.__timelines["my-comp"] = tl;

</script>

</div>

</template>

```

Load in root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`

## Variables (Parametrized Compositions)

Render the same composition with different content — title, theme color, prices, captions — without editing the source HTML.

**Three-step pattern:**

1. **Declare** variables on the composition's `<html>` root with `data-composition-variables`. Each entry needs `id`, `type` (one of `string`, `number`, `color`, `boolean`, `enum`), `label`, and `default`. Enum entries also need `options: [{value, label}, ...]`.

2. **Read** the resolved values inside the composition's script with `window.__hyperframes.getVariables()`. Returns the merged result of declared defaults + per-instance overrides + CLI overrides.

3. **Override** at render time with `npx hyperframes render --variables '{...}'` (top-level) or with `data-variable-values='{...}'` on the host element (per-instance for sub-comps).

```html

<!doctype html>

<html

data-composition-variables='[

{"id":"title","type":"string","label":"Title","default":"Hello"},

{"id":"theme","type":"enum","label":"Theme","default":"light","options":[

{"value":"light","label":"Light"},

{"value":"dark","label":"Dark"}

]}

<body>

const { title, theme } = window.__hyperframes.getVariables();

document.getElementById("hero").textContent = title;

document.body.dataset.theme = theme;

</script>

</div>

</body>

</html>

```

```bash

# Dev preview uses declared defaults

npx hyperframes preview

# Render with overrides

npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

# Or from a JSON file

npx hyperframes render --variables-file ./vars.json

```

**Sub-composition per-instance values:** the same `getVariables()` works inside sub-comps loaded via `data-composition-src`. Each host element passes its own values:

```html

<div

data-composition-id="card-pro"

data-composition-src="compositions/card.html"

data-variable-values='{"title":"Pro","price":"$29"}'

></div>

<div

data-composition-id="card-enterprise"

data-composition-src="compositions/card.html"

data-variable-values='{"title":"Enterprise","price":"Custom"}'

></div>

```

The runtime layers each host's `data-variable-values` over the sub-comp's declared defaults on a per-instance basis, so the same source can be embedded multiple times with different content.

**Rules of thumb:**

- Always provide a sensible `default` for every declared variable. Dev preview uses defaults — without them, the composition won't render correctly until `--variables` is provided.

- Read variables once at the top of the script (`const { title } = ...`), not inside frame loops or event handlers — `getVariables()` allocates a fresh object per call.

- Use `--strict-variables` in CI to fail fast on undeclared keys or type mismatches.

- Variable types are validated at render time. `string`, `number`, `boolean`, and `color` (hex string) check `typeof`; `enum` checks the value is in the declared `options`.

## Video and Audio

Video must be `muted playsinline`. Audio is always a separate `<audio>` element:

```html

<video

id="el-v"

data-start="0"

data-duration="30"

data-track-index="0"

src="video.mp4"

muted

playsinline

></video>

<audio

id="el-a"

data-start="0"

data-duration="30"

data-track-index="2"

src="video.mp4"

data-volume="1"

></audio>

```

## Timeline Contract

- All timelines start `{ paused: true }` — the player controls playback

- Register every timeline: `window.__timelines["<composition-id>"] = tl`

- Framework auto-nests sub-timelines — do NOT manually add them

- Duration comes from `data-duration`, not from GSAP timeline length

- Never create empty tweens to set duration

## Rules (Non-Negotiable)

**Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).

**GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`.

**Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously.

**No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`.

**Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately — no need to wait for font loading.

**Never do:**

1. Forget `window.__timelines` registration

2. Use video for audio — always muted video + separate `<audio>`

3. Nest video inside a timed div — use a non-timed wrapper

4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`)

5. Animate video element dimensions — animate a wrapper div

6. Call play/pause/seek on media — framework owns playback

7. Create a top-level container without `data-composition-id`

8. Use `repeat: -1` on any timeline or tween — always finite repeats

9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`)

10. Use `gsap.set()` on clip elements from later scenes — they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead.

11. Use `<br>` in content text — forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `<br>` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px).

## Scene Transitions (Non-Negotiable)

Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.

1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions.

2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.

3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.

4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed.

**WRONG — exit animation before transition:**

```js

// BANNED — this empties the scene before the transition can use it

tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);

tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);

// transition fires on empty frame

```

**RIGHT — entrance only, transition handles exit:**

```js

// Scene 1 entrance animations

tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);

tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);

// NO exit tweens — transition at 7.2s handles the scene change

// Scene 2 entrance animations

tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

```

## Animation Guardrails

- Offset first animation 0.1-0.3s (not t=0)

- Vary eases across entrance tweens — use at least 3 different eases per scene

- Don't repeat an entrance pattern within a scene

- Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow)

- 60px+ headlines, 20px+ body, 16px+ data labels for rendered video

- `font-variant-numeric: tabular-nums` on number columns

If no `design.md` exists, follow [house-style.md](./house-style.md) for aesthetic defaults.

## Typography and Assets

- **Built-in fonts:** Write the `font-family` you want in CSS — the compiler embeds supported fonts automatically.

- **Custom fonts:** If design.md names a font that isn't built-in, the user must provide `.woff2` files in a `fonts/` directory. If missing, warn before writing HTML. When files exist, add `@font-face` declarations pointing to the local files.

- Add `crossorigin="anonymous"` to external media

- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`

- All files live at the project root alongside `index.html`; sub-compositions use `../`

## Editing Existing Compositions

- **Read actual files, don't guess.** When editing, extending, or creating companion compositions, read the existing source. Don't reconstruct hex codes from memory. Don't guess GSAP easing patterns. The composition IS the spec — extract exact values from it.

- Match existing fonts, colors, animation patterns from what you read

- Only change what was requested

- Preserve timing of unrelated clips

## Output Checklist

**Fast (run immediately, block on results):**

- [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass

- [ ] Design adherence verified if design.md exists

**Slow (run in parallel while presenting the preview to the user):**

- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked

- [ ] Contrast warnings addressed (see Quality Checks below)

- [ ] Animation choreography verified (see Quality Checks below)

## Quality Checks

### Visual Inspect

`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`:

```bash

npx hyperframes inspect

npx hyperframes inspect --json

```

Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy.

Use `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.

`hyperframes layout` is the compatibility alias for the same check.

### Contrast

`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:

```

⚠ WCAG AA contrast warnings (3):

· .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

```

If warnings appear:

- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)

- On light backgrounds: darken it

- Stay within the palette family — don't invent a new color, adjust the existing one

- Re-run `hyperframes validate` until clean

Use `--no-contrast` to skip if iterating rapidly and you'll check later.

### Design Adherence

If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check:

1. **Colors** — every hex value in the composition appears in design.md's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors.

2. **Typography** — font families and weights match design.md's type spec. No substitutions.

3. **Corners** — border-radius values match the declared corner style, if specified.

4. **Spacing** — padding and gap values fall within the declared density range, if specified.

5. **Depth** — shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows).

6. **Avoidance rules** — if design.md has a section listing things to avoid (commonly "What NOT to Do", "Don'ts", "Anti-patterns", or "Do's and Don'ts"), verify none are present.

Report violations as a checklist. Fix each one before serving.

If no `design.md` exists (house-style-only path), verify:

1. **Palette consistency** — the same bg, fg, and accent colors are used across all scenes. No per-scene color invention.

2. **No lazy defaults** — check the composition against house-style.md's "Lazy Defaults to Question" list. If any appear, they must be a deliberate choice for the content, not a default.

### Animation Map

After authoring animations, run the animation map to verify choreography:

```bash

node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \

--out <composition-dir>/.hyperframes/anim-map

```

Outputs a single `animation-map.json` with:

- **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"`

- **ASCII timeline**: Gantt chart of all tweens across the composition duration

- **Stagger detection**: reports actual intervals (`"3 elements stagger at 120ms"`)

- **Dead zones**: periods over 1s with no animation — intentional hold or missing entrance?

- **Element lifecycles**: first/last animation time, final visibility

- **Scene snapshots**: visible element state at 5 key timestamps

- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)

Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.

Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.

---

## References (loaded on demand)

- **[references/captions.md](references/captions.md)** — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.

- **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.

- **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.

- **[references/video-composition.md](references/video-composition.md)** — Video-medium rules: density, color presence, scale, frame composition, design.md as brand not layout. **Always read** — these override web instincts.

- **[references/beat-direction.md](references/beat-direction.md)** — Beat planning: concept, mood, choreography verbs, rhythm templates, transition decisions, depth layers. **Always read for multi-scene compositions.**

- **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.

- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles, image motion treatment, load-bearing GSAP rules. **Always read** — every composition has motion.

- **[references/techniques.md](references/techniques.md)** — 13 primitive animation techniques with code patterns: SVG drawing, Canvas 2D, CSS 3D, kinetic type, Lottie, video compositing, typing, variable fonts, MotionPath, velocity transitions, audio-reactive, clip-path reveals, WebGL shaders. Adapt the patterns — don't copy-paste. (For pre-built UI templates — terminal chrome, device mockups, moodboard layouts — see `registry/blocks/`.)

- **[references/html-in-canvas-patterns.md](references/html-in-canvas-patterns.md)** — HTML-in-Canvas patterns: live DOM as GPU texture via `drawElementImage` + `layoutsubtree`. Shared boilerplate + ~6 effect recipes (iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor). Use for 1–3 hero beats per video.

- **[references/narration.md](references/narration.md)** — Pacing, tone, script structure, number pronunciation, opening line patterns. Read when the composition includes voiceover or TTS.

- **[references/design-picker.md](references/design-picker.md)** — Create a design.md via visual picker. Read when no design.md exists and the user wants to create one.

- **[visual-styles.md](visual-styles.md)** — 8 named visual styles with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md.

- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified.

- **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.

- **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.

- **[references/transcript-guide.md](references/transcript-guide.md)** — Caption-side transcript handling: input formats, mandatory quality check, cleaning JS, OpenAI/Groq API fallback, "if no transcript exists" flow. (For the `transcribe` CLI invocation, model selection rules, and the `.en` gotcha, see the `hyperframes-media` skill.)

- **[references/dynamic-techniques.md](references/dynamic-techniques.md)** — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).

- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. **Always read for multi-scene compositions** — scenes without transitions feel like jump cuts.

- [transitions/catalog.md](references/transitions/catalog.md) — Hard rules, scene template, and routing to per-type implementation code.

- Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) — read package source, not skill files.

GSAP patterns and effects are in the `/gsap` skill.

htmlskills/hyperframes/templates/design-picker.html

43 kB

<!doctype html>

<head>

<title>Design your visual direction</title>

<style>

* {

margin: 0;

padding: 0;

box-sizing: border-box;

}

body {

font-family:

system-ui,

-apple-system,

sans-serif;

background: #0e0e0e;

color: #eee;

height: 100vh;

overflow: hidden;

display: flex;

flex-direction: column;

font-size: 13px;

line-height: 1.4;

-webkit-font-smoothing: antialiased;

}

/* ── Phase bar ── */

.phase-bar {

display: flex;

border-bottom: 1px solid #1a1a1a;

padding: 0 20px;

flex-shrink: 0;

background: #111;

}

.phase-tab {

padding: 12px 16px;

font-size: 12px;

font-weight: 600;

color: #555;

cursor: pointer;

border-bottom: 2px solid transparent;

transition: all 0.15s;

letter-spacing: 0.02em;

}

.phase-tab.active {

color: #fff;

border-bottom-color: #fff;

}

.phase-tab.disabled {

opacity: 0.25;

pointer-events: none;

}

/* ── Phases ── */

.phase {

display: none;

flex: 1;

overflow: hidden;

}

.phase.active {

display: flex;

}

/* ── Phase 1: Mood boards ── */

.mood-grid {

display: grid;

grid-template-columns: repeat(auto-fill, minmax(380px, 1fr));

gap: 16px;

padding: 20px;

overflow-y: auto;

flex: 1;

align-content: start;

}

.mood-card {

border: 1px solid #1e1e1e;

border-radius: 12px;

overflow: hidden;

cursor: pointer;

transition:

border-color 0.15s,

transform 0.15s,

box-shadow 0.15s;

background: #141414;

display: flex;

flex-direction: column;

}

.mood-card:hover {

border-color: #333;

transform: translateY(-1px);

box-shadow: 0 4px 24px rgba(0, 0, 0, 0.3);

}

.mood-card.selected {

border-color: #fff;

}

.mood-preview {

height: 500px;

overflow: hidden;

position: relative;

background: #0a0a0a;

}

.mood-preview > div {

transform-origin: top left;

}

.mood-info {

padding: 14px 16px;

}

.mood-name {

font-size: 14px;

font-weight: 600;

margin-bottom: 3px;

}

.mood-desc {

font-size: 11px;

color: #666;

line-height: 1.4;

display: -webkit-box;

-webkit-line-clamp: 2;

-webkit-box-orient: vertical;

overflow: hidden;

}

.mood-tokens {

display: flex;

gap: 4px;

margin-top: 8px;

flex-wrap: wrap;

}

.mood-token {

font-size: 9px;

color: #555;

background: #1a1a1a;

padding: 2px 7px;

border-radius: 3px;

letter-spacing: 0.02em;

}

.mood-header {

padding: 20px 20px 0;

flex-shrink: 0;

}

.mood-header h2 {

font-size: 16px;

font-weight: 600;

margin-bottom: 2px;

}

.mood-header p {

font-size: 12px;

color: #555;

}

.mood-next {

padding: 12px 20px;

flex-shrink: 0;

display: flex;

justify-content: flex-end;

}

.mood-next-btn {

background: #fff;

color: #000;

border: none;

padding: 10px 24px;

border-radius: 8px;

font-size: 13px;

font-weight: 600;

cursor: pointer;

opacity: 0;

transform: translateY(8px);

transition: all 0.2s;

}

.mood-next-btn.visible {

opacity: 1;

transform: translateY(0);

}

.mood-next-btn:hover {

background: #ddd;

}

/* ── Phase 2: Fine-tune ── */

.panel-left {

width: 400px;

min-width: 400px;

height: 100%;

overflow-y: auto;

border-right: 1px solid #1a1a1a;

padding: 0 0 100px;

background: #111;

}

.panel-right {

flex: 1;

height: 100%;

overflow-y: auto;

overflow-x: hidden;

background: #0e0e0e;

}

.panel-right * {

max-width: 100%;

box-sizing: border-box;

}

/* ── Section cards (Neuform-inspired) ── */

.section-card {

border-bottom: 1px solid #1a1a1a;

}

.section-header {

display: flex;

align-items: center;

gap: 8px;

padding: 14px 16px 6px;

}

.section-icon {

width: 22px;

height: 22px;

border-radius: 5px;

background: rgba(255, 255, 255, 0.04);

display: flex;

align-items: center;

justify-content: center;

color: #555;

font-size: 11px;

flex-shrink: 0;

}

.section-title {

font-size: 11px;

font-weight: 600;

color: #fff;

letter-spacing: 0.01em;

}

.section-meta {

font-size: 10px;

color: #444;

margin-left: auto;

}

.section-body {

padding: 6px 16px 16px;

}

/* ── Option cards ── */

.opt {

border: 1px solid #1e1e1e;

border-radius: 10px;

margin-bottom: 6px;

cursor: pointer;

transition: border-color 0.12s;

overflow: hidden;

background: #141414;

position: relative;

}

.opt:hover {

border-color: #333;

}

.opt.selected {

border-color: #fff;

}

.opt-inner {

padding: 12px 14px;

}

.opt-name {

font-size: 12px;

font-weight: 600;

margin-bottom: 2px;

}

.opt-desc {

font-size: 10px;

color: #666;

line-height: 1.4;

}

.opt-tag {

font-size: 9px;

color: #444;

margin-top: 4px;

text-transform: uppercase;

letter-spacing: 0.04em;

}

.opt-rec {

position: absolute;

top: 8px;

right: 10px;

font-size: 8px;

font-weight: 700;

color: #4ade80;

background: rgba(74, 222, 128, 0.08);

padding: 2px 6px;

border-radius: 3px;

text-transform: uppercase;

letter-spacing: 0.04em;

}

/* ── Palette option ── */

.pal-strip {

display: flex;

height: 28px;

border-radius: 6px;

overflow: hidden;

margin-bottom: 8px;

}

.pal-strip > div {

flex: 1;

}

.pal-ramp {

display: flex;

gap: 2px;

margin-top: 4px;

}

.pal-ramp-swatch {

width: 100%;

height: 6px;

border-radius: 2px;

}

/* ── Type option (specimen) ── */

.type-specimen {

padding: 14px;

border-bottom: 1px solid #1a1a1a;

}

.type-headline {

line-height: 1.1;

letter-spacing: -0.02em;

margin-bottom: 6px;

}

.type-body {

line-height: 1.5;

color: #666;

font-size: 11px;

}

.type-meta {

padding: 10px 14px;

display: flex;

justify-content: space-between;

align-items: center;

}

.type-families {

font-size: 9px;

color: #444;

letter-spacing: 0.02em;

}

.type-letters {

font-size: 9px;

color: #333;

letter-spacing: 0.08em;

overflow: hidden;

white-space: nowrap;

text-overflow: ellipsis;

max-width: 200px;

}

/* ── Chip options ── */

.chips {

display: flex;

gap: 6px;

flex-wrap: wrap;

}

.chip {

border: 1px solid #1e1e1e;

border-radius: 8px;

padding: 8px 12px;

cursor: pointer;

transition: border-color 0.12s;

display: flex;

align-items: center;

gap: 8px;

background: #141414;

}

.chip:hover {

border-color: #333;

}

.chip.selected {

border-color: #fff;

}

.chip-label {

font-size: 11px;

font-weight: 500;

}

.chip-sub {

font-size: 9px;

color: #555;

}

.chip-preview {

flex-shrink: 0;

}

.theme-chip {

flex: 1;

min-width: 90px;

flex-direction: column;

align-items: center;

padding: 10px 12px;

text-align: center;

}

.theme-swatch {

width: 100%;

height: 28px;

border-radius: 4px;

margin-bottom: 4px;

border: 1px solid rgba(255, 255, 255, 0.06);

}

.corner-box {

width: 22px;

height: 22px;

border: 2px solid #666;

}

.density-bars {

display: flex;

flex-direction: column;

width: 24px;

}

.density-bar {

background: #666;

height: 3px;

border-radius: 1px;

}

.depth-square {

width: 22px;

height: 22px;

background: #2a2a2a;

border-radius: 3px;

}

/* ── Easing option ── */

.ease-opt {

border: 1px solid #1e1e1e;

border-radius: 10px;

margin-bottom: 6px;

cursor: pointer;

transition: border-color 0.12s;

overflow: hidden;

background: #141414;

padding: 10px 14px;

}

.ease-opt:hover {

border-color: #333;

}

.ease-opt.selected {

border-color: #fff;

}

.ease-track {

position: relative;

height: 8px;

background: #1a1a1a;

border-radius: 4px;

margin-bottom: 8px;

overflow: visible;

}

.ease-dot {

position: absolute;

top: 50%;

transform: translateY(-50%);

left: 0;

width: 12px;

height: 12px;

border-radius: 50%;

background: #fff;

}

.ease-label {

display: flex;

justify-content: space-between;

align-items: center;

}

.ease-name {

font-size: 11px;

font-weight: 600;

}

.ease-value {

font-size: 9px;

color: #444;

font-family: "SF Mono", Consolas, monospace;

letter-spacing: 0.02em;

}

.preview-empty {

display: flex;

align-items: center;

justify-content: center;

height: 100%;

color: #2a2a2a;

font-size: 13px;

}

/* ── FAB + Overlay ── */

.fab {

position: fixed;

bottom: 20px;

right: 32px;

transform: translateY(60px);

opacity: 0;

background: #fff;

color: #000;

border: none;

padding: 12px 24px;

border-radius: 10px;

font-size: 13px;

font-weight: 600;

cursor: pointer;

box-shadow: 0 4px 24px rgba(0, 0, 0, 0.5);

transition:

transform 0.25s ease,

opacity 0.25s ease;

z-index: 100;

}

.fab.visible {

transform: translateY(0);

opacity: 1;

}

.fab:hover {

background: #ddd;

}

.md-overlay {

position: fixed;

inset: 0;

background: rgba(0, 0, 0, 0.85);

backdrop-filter: blur(8px);

z-index: 200;

display: none;

align-items: center;

justify-content: center;

}

.md-overlay.visible {

display: flex;

}

.md-card {

background: #161616;

border: 1px solid #2a2a2a;

border-radius: 14px;

max-width: 600px;

width: 90%;

max-height: 80vh;

display: flex;

flex-direction: column;

}

.md-header {

padding: 16px 20px;

border-bottom: 1px solid #1e1e1e;

display: flex;

justify-content: space-between;

align-items: center;

}

.md-title {

font-size: 14px;

font-weight: 600;

}

.md-actions {

display: flex;

gap: 6px;

}

.copy-btn {

background: #fff;

color: #000;

border: none;

padding: 7px 16px;

border-radius: 6px;

font-size: 12px;

font-weight: 600;

cursor: pointer;

}

.copy-btn:hover {

background: #ddd;

}

.close-btn {

background: transparent;

color: #666;

border: 1px solid #2a2a2a;

padding: 7px 14px;

border-radius: 6px;

font-size: 12px;

cursor: pointer;

}

.close-btn:hover {

color: #fff;

border-color: #444;

}

.md-body {

padding: 20px;

overflow-y: auto;

flex: 1;

}

.md-editor {

font-family: "SF Mono", Consolas, monospace;

font-size: 12px;

line-height: 1.6;

color: #aaa;

background: transparent;

border: none;

width: 100%;

min-height: 360px;

resize: vertical;

outline: none;

white-space: pre-wrap;

}

/* ── Phase 1 palette bar ── */

.pal-bar {

display: flex;

gap: 8px;

padding: 12px 20px 0;

flex-shrink: 0;

flex-wrap: wrap;

align-items: center;

}

.pal-bar-label {

font-size: 10px;

color: #444;

letter-spacing: 0.03em;

text-transform: uppercase;

margin-right: 4px;

}

.pal-bar-chip {

display: flex;

align-items: center;

gap: 6px;

padding: 5px 10px;

border: 1px solid #1e1e1e;

border-radius: 6px;

cursor: pointer;

transition: border-color 0.12s;

background: #141414;

}

.pal-bar-chip:hover {

border-color: #333;

}

.pal-bar-chip.active {

border-color: #fff;

}

.pal-bar-chip-swatches {

display: flex;

gap: 2px;

}

.pal-bar-chip-swatch {

width: 14px;

height: 14px;

border-radius: 3px;

}

.pal-bar-chip-name {

font-size: 10px;

font-weight: 500;

color: #888;

}

</style>

</head>

<body>

<div class="phase-tab active" id="tab-mood" onclick="showPhase('mood')">1. Direction</div>

</div>

<h2 id="mood-title">Pick a direction</h2>

Each option is a complete visual identity. Pick one, then fine-tune.

</p>

</div>

<div class="pal-bar" id="pal-bar"><span class="pal-bar-label">Palette</span></div>

Customize this direction →

</button>

</div>

<div class="section-title">Theme</div>

</div>

</div>

<div class="section-title">Structure</div>

</div>

</div>

<div class="section-title">Color</div>

</div>

</div>

<div class="section-title">Typography</div>

</div>

</div>

<div class="section-title">Corners</div>

</div>

</div>

<div class="section-title">Density</div>

</div>

</div>

<div class="section-title">Depth</div>

</div>

</div>

<div class="section-title">Motion</div>

<div class="section-meta">entry easing</div>

</div>

</div>

<div class="preview-empty">Pick a structure to preview</div>

</div>

<button class="fab" id="fab" onclick="showOutput()">Create design.md</button>

design.md

</div>

<button

class="close-btn"

onclick="document.getElementById('md-overlay').classList.remove('visible')"

</button>

</div>

</div>

var ARCHITECTURES = __ARCHITECTURES_JSON__;

var PALETTES = __PALETTES_JSON__;

var TYPEPAIRS = __TYPEPAIRS_JSON__;

var MOODBOARDS = __MOODBOARDS_JSON__;

var PROMPT = __PROMPT_JSON__;

var picks = {

theme: null,

arch: null,

palette: null,

type: null,

corners: null,

density: null,

depth: null,

easing: null,

};

var EASINGS = [

{ name: "Confident", value: "power3.out", desc: "Fast start, smooth deceleration" },

{ name: "Snappy", value: "expo.out", desc: "Very fast start, crisp stop" },

{ name: "Gentle", value: "sine.inOut", desc: "Soft acceleration and deceleration" },

{ name: "Bouncy", value: "back.out(1.4)", desc: "Overshoots then settles" },

{ name: "Elastic", value: "elastic.out(1, 0.5)", desc: "Springs past target and wobbles" },

{ name: "Sharp", value: "power4.out", desc: "Aggressive start, hard stop" },

];

var THEMES = [

{ name: "Dark", id: "dark", bg: "#0e0e0e", fg: "#eee", desc: "Light on dark" },

{ name: "Light", id: "light", bg: "#f5f3ef", fg: "#1a1a1a", desc: "Dark on light" },

{ name: "Palette", id: "palette", bg: null, fg: null, desc: "Use palette colors" },

];

var CORNERS = [

{ name: "Sharp", value: "0px" },

{ name: "Slight", value: "4px" },

{ name: "Rounded", value: "12px" },

];

var DENSITIES = [

{ name: "Tight", padding: "8-12px", gap: "8-12px", desc: "Compact" },

{ name: "Normal", padding: "16-24px", gap: "16-20px", desc: "Balanced" },

{ name: "Generous", padding: "32-48px", gap: "28-40px", desc: "Spacious" },

];

var DEPTHS = [

{ name: "Flat", desc: "No shadows" },

{ name: "Subtle", desc: "Faint shadows" },

{ name: "Layered", desc: "Glows + depth" },

];

// Load fonts

var fams = [];

TYPEPAIRS.forEach(function (tp) {

fams.push(tp.headline.family.replace(/ /g, "+") + ":wght@" + tp.headline.weight);

fams.push(tp.body.family.replace(/ /g, "+") + ":wght@" + tp.body.weight);

});

var lnk = document.createElement("link");

lnk.rel = "stylesheet";

lnk.href =

"https://fonts.googleapis.com/css2?family=" + fams.join("&family=") + "&display=swap";

document.head.appendChild(lnk);

function al(hex, o) {

if (!hex || typeof hex !== "string" || hex[0] !== "#") return "rgba(128,128,128," + o + ")";

if (hex.length === 4) hex = "#" + hex[1] + hex[1] + hex[2] + hex[2] + hex[3] + hex[3];

var r = parseInt(hex.slice(1, 3), 16),

g = parseInt(hex.slice(3, 5), 16),

b = parseInt(hex.slice(5, 7), 16);

if (isNaN(r)) r = 128;

if (isNaN(g)) g = 128;

if (isNaN(b)) b = 128;

return "rgba(" + r + "," + g + "," + b + "," + o + ")";

}

// Prompt-aware UI

if (PROMPT && PROMPT.title)

document.getElementById("mood-title").textContent = "Pick a direction for: " + PROMPT.title;

// ── Phase 1: Mood boards + Palette bar ──

var moodGrid = document.getElementById("mood-grid");

var selectedMood = null;

var overridePalette = null;

// Build palette bar

var palBar = document.getElementById("pal-bar");

PALETTES.forEach(function (p, i) {

var chip = document.createElement("div");

chip.className = "pal-bar-chip" + (i === 0 ? "" : "");

chip.innerHTML =

'<div class="pal-bar-chip-swatches"><div class="pal-bar-chip-swatch" style="background:' +

p.background +

';border:1px solid rgba(255,255,255,0.08);"></div><div class="pal-bar-chip-swatch" style="background:' +

p.accent +

';"></div><div class="pal-bar-chip-swatch" style="background:' +

p.foreground +

';border:1px solid rgba(255,255,255,0.08);"></div></div><span class="pal-bar-chip-name">' +

p.name +

"</span>";

chip.onclick = function () {

palBar.querySelectorAll(".pal-bar-chip").forEach(function (c) {

c.classList.remove("active");

});

if (overridePalette === i) {

overridePalette = null;

} else {

chip.classList.add("active");

overridePalette = i;

}

renderMoodBoards();

};

palBar.appendChild(chip);

});

function renderMoodBoards() {

var prevSelected = selectedMood;

moodGrid.innerHTML = "";

MOODBOARDS.forEach(function (mb, i) {

var card = document.createElement("div");

card.className = "mood-card" + (i === prevSelected ? " selected" : "");

var tp = TYPEPAIRS[mb.type_index || 0],

arch = ARCHITECTURES[mb.arch_index || 0];

var pal =

overridePalette !== null ? PALETTES[overridePalette] : PALETTES[mb.palette_index || 0];

var thId = mb.theme || "dark",

th =

THEMES.find(function (t) {

return t.id === thId;

}) || THEMES[0];

var bg = thId === "palette" ? pal.background : th.bg,

fg = thId === "palette" ? pal.foreground : th.fg;

var tokens = {

"{{bg}}": bg,

"{{fg}}": fg,

"{{ac}}": pal.accent,

"{{mt}}": pal.muted || pal.mid || al(fg, 0.4),

"{{hf}}": tp.headline.family,

"{{hw}}": tp.headline.weight,

"{{bf}}": tp.body.family,

"{{bw}}": tp.body.weight,

"{{cr}}": mb.corners || "4px",

"{{pad}}": mb.padding || "20px",

"{{gap}}": mb.gap || "16px",

"{{shadow}}": mb.shadow || "none",

"{{sf}}": al(fg, 0.06),

"{{g}}": al(fg, 0.06),

"{{fg3}}": al(fg, 0.03),

"{{fg6}}": al(fg, 0.06),

"{{fg8}}": al(fg, 0.08),

"{{fg15}}": al(fg, 0.15),

"{{ac3}}": al(pal.accent, 0.03),

"{{ac5}}": al(pal.accent, 0.05),

"{{ac25}}": al(pal.accent, 0.25),

"{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline",

"{{prompt_sub}}": (PROMPT && PROMPT.subline) || "A subline for your product.",

};

var preview = arch.preview_html || "";

Object.keys(tokens).forEach(function (k) {

preview = preview.split(k).join(tokens[k]);

});

var tagHtml = [tp.headline.family, pal.name, CORNERS[mb.corners_index || 1].name]

.map(function (t) {

return '<span class="mood-token">' + t + "</span>";

})

.join("");

card.innerHTML =

'<div class="mood-preview"><div style="transform:scale(0.38);transform-origin:top left;width:263.16%;min-height:263.16%;">' +

preview +

'</div></div><div class="mood-info"><div class="mood-name">' +

mb.name +

'</div><div class="mood-desc">' +

mb.description +

'</div><div class="mood-tokens">' +

tagHtml +

"</div></div>";

card.onclick = function () {

moodGrid.querySelectorAll(".mood-card").forEach(function (c) {

c.classList.remove("selected");

});

card.classList.add("selected");

selectedMood = i;

document.getElementById("mood-next-btn").classList.add("visible");

};

moodGrid.appendChild(card);

});

}

renderMoodBoards();

var currentPhase = "mood";

function showPhase(name) {

currentPhase = name;

document.querySelectorAll(".phase").forEach(function (p) {

p.classList.remove("active");

});

document.querySelectorAll(".phase-tab").forEach(function (t) {

t.classList.remove("active");

});

document.getElementById("phase-" + name).classList.add("active");

document.getElementById("tab-" + name).classList.add("active");

if (name === "mood") document.getElementById("fab").classList.remove("visible");

else checkReady();

}

function goToTune() {

if (selectedMood === null) return;

var mb = MOODBOARDS[selectedMood];

var thIdx = THEMES.findIndex(function (t) {

return t.id === (mb.theme || "dark");

});

if (thIdx >= 0) chipSel("theme", thIdx, document.getElementById("theme-options"));

if (mb.arch_index != null)

sel("arch", mb.arch_index, document.getElementById("arch-options"));

var palIdx = overridePalette !== null ? overridePalette : mb.palette_index;

if (palIdx != null) sel("palette", palIdx, document.getElementById("pal-options"));

if (mb.type_index != null)

sel("type", mb.type_index, document.getElementById("type-options"));

if (mb.corners_index != null)

chipSel("corners", mb.corners_index, document.getElementById("corner-options"));

if (mb.density_index != null)

chipSel("density", mb.density_index, document.getElementById("density-options"));

if (mb.depth_index != null)

chipSel("depth", mb.depth_index, document.getElementById("depth-options"));

var eIdx = mb.easing_index != null ? mb.easing_index : 0;

var eOpts = document.getElementById("ease-options");

eOpts.querySelectorAll(".ease-opt").forEach(function (c) {

c.classList.remove("selected");

});

eOpts.children[eIdx].classList.add("selected");

picks.easing = eIdx;

document.getElementById("tab-tune").classList.remove("disabled");

showPhase("tune");

}

// ── Phase 2: Build options ──

// Architecture cards

var archOpts = document.getElementById("arch-options");

ARCHITECTURES.forEach(function (a, i) {

var el = document.createElement("div");

el.className = "opt";

el.innerHTML =

'<div class="opt-inner"><div class="opt-name">' +

a.name +

'</div><div class="opt-desc">' +

a.description +

'</div><div class="opt-tag">' +

a.tag +

"</div></div>";

el.onclick = function () {

sel("arch", i, archOpts);

};

archOpts.appendChild(el);

});

// Palette cards with ramp

var palOpts = document.getElementById("pal-options");

PALETTES.forEach(function (p, i) {

var el = document.createElement("div");

el.className = "opt";

el.innerHTML =

'<div class="opt-inner"><div class="pal-strip"><div style="background:' +

p.background +

';"></div><div style="background:' +

(p.muted || p.mid || "#888") +

';"></div><div style="background:' +

p.accent +

';"></div><div style="background:' +

p.foreground +

';"></div></div><div class="opt-name">' +

p.name +

'</div><div class="opt-desc">' +

p.description +

"</div></div>";

el.onclick = function () {

sel("palette", i, palOpts);

};

palOpts.appendChild(el);

});

// Typography cards with specimen

var typeOpts = document.getElementById("type-options");

TYPEPAIRS.forEach(function (tp, i) {

var letters = "AaBbCcDdEeFfGgHh";

var el = document.createElement("div");

el.className = "opt";

el.innerHTML =

'<div class="type-specimen"><div class="type-headline" style="font-family:\'' +

tp.headline.family +

"',sans-serif;font-weight:" +

tp.headline.weight +

';font-size:24px;">' +

tp.preview +

'</div><div class="type-body" style="font-family:\'' +

tp.body.family +

"',monospace;font-weight:" +

tp.body.weight +

';">' +

tp.body_preview +

'</div></div><div class="type-meta"><div class="type-families">' +

tp.headline.family +

" " +

tp.headline.weight +

" · " +

tp.body.family +

" " +

tp.body.weight +

'</div><div class="type-letters" style="font-family:\'' +

tp.headline.family +

"',sans-serif;font-weight:" +

tp.headline.weight +

';">' +

letters +

"</div></div>";

el.onclick = function () {

sel("type", i, typeOpts);

};

typeOpts.appendChild(el);

});

// Theme chips

var themeOpts = document.getElementById("theme-options");

THEMES.forEach(function (th, i) {

var el = document.createElement("div");

el.className = "chip theme-chip";

el.innerHTML =

'<div class="theme-swatch" style="background:' +

th.bg +

';"></div><div class="chip-label">' +

th.name +

'</div><div class="chip-sub">' +

th.desc +

"</div>";

el.onclick = function () {

chipSel("theme", i, themeOpts);

};

themeOpts.appendChild(el);

});

// Corner chips

var cornerOpts = document.getElementById("corner-options");

CORNERS.forEach(function (c, i) {

var el = document.createElement("div");

el.className = "chip";

el.innerHTML =

'<div class="chip-preview"><div class="corner-box" style="border-radius:' +

c.value +

';"></div></div><div><div class="chip-label">' +

c.name +

'</div><div class="chip-sub">' +

c.value +

"</div></div>";

el.onclick = function () {

chipSel("corners", i, cornerOpts);

};

cornerOpts.appendChild(el);

});

// Density chips

var densityOpts = document.getElementById("density-options");

DENSITIES.forEach(function (d, i) {

var gaps = [2, 4, 7][i];

var el = document.createElement("div");

el.className = "chip";

el.innerHTML =

'<div class="chip-preview"><div class="density-bars" style="gap:' +

gaps +

'px;"><div class="density-bar"></div><div class="density-bar"></div><div class="density-bar"></div></div></div><div><div class="chip-label">' +

d.name +

'</div><div class="chip-sub">' +

d.desc +

"</div></div>";

el.onclick = function () {

chipSel("density", i, densityOpts);

};

densityOpts.appendChild(el);

});

// Depth chips

var depthOpts = document.getElementById("depth-options");

DEPTHS.forEach(function (d, i) {

var shadow = [

"none",

"0 2px 8px rgba(255,255,255,0.04)",

"0 0 16px rgba(255,255,255,0.06)",

][i];

var el = document.createElement("div");

el.className = "chip";

el.innerHTML =

'<div class="chip-preview"><div class="depth-square" style="box-shadow:' +

shadow +

';"></div></div><div><div class="chip-label">' +

d.name +

'</div><div class="chip-sub">' +

d.desc +

"</div></div>";

el.onclick = function () {

chipSel("depth", i, depthOpts);

};

depthOpts.appendChild(el);

});

// Easing options with GSAP animation

var easeOpts = document.getElementById("ease-options");

EASINGS.forEach(function (e, i) {

var el = document.createElement("div");

el.className = "ease-opt";

var dotId = "ease-dot-" + i;

el.innerHTML =

'<div class="ease-track"><div class="ease-dot" id="' +

dotId +

'"></div></div>' +

'<div class="ease-label"><div class="ease-name">' +

e.name +

'</div><div class="ease-value">' +

e.value +

"</div></div>";

el.onclick = function () {

easeOpts.querySelectorAll(".ease-opt").forEach(function (c) {

c.classList.remove("selected");

});

el.classList.add("selected");

picks.easing = i;

checkReady();

};

easeOpts.appendChild(el);

// Animate the dot with GSAP

gsap.to("#" + dotId, {

left: "calc(100% - 12px)",

duration: 1.2,

ease: e.value,

repeat: -1,

repeatDelay: 0.8,

yoyo: true,

});

function chipSel(key, idx, container) {

container.querySelectorAll(".chip").forEach(function (c) {

c.classList.remove("selected");

});

container.children[idx].classList.add("selected");

picks[key] = idx;

checkReady();

renderPreview();

}

function sel(key, idx, container) {

container.querySelectorAll(".opt").forEach(function (c) {

c.classList.remove("selected");

});

container.children[idx].classList.add("selected");

picks[key] = idx;

checkReady();

renderPreview();

}

function checkReady() {

var ready =

picks.theme !== null &&

picks.arch !== null &&

picks.palette !== null &&

picks.type !== null &&

picks.corners !== null &&

picks.density !== null &&

picks.depth !== null &&

picks.easing !== null;

document

.getElementById("fab")

.classList.toggle("visible", ready && currentPhase === "tune");

document.getElementById("md-overlay").classList.remove("visible");

}

function renderPreview() {

var pv = document.getElementById("preview");

if (picks.arch === null) {

pv.innerHTML = '<div class="preview-empty">Pick a structure to preview</div>';

return;

}

var a = ARCHITECTURES[picks.arch];

var th = picks.theme !== null ? THEMES[picks.theme] : THEMES[0];

var p =

picks.palette !== null ? PALETTES[picks.palette] : { accent: "#888", muted: "#555" };

var t =

picks.type !== null

? TYPEPAIRS[picks.type]

: {

headline: { family: "system-ui", weight: 600 },

body: { family: "system-ui", weight: 400 },

};

var cr = picks.corners !== null ? CORNERS[picks.corners].value : "0px";

var dn = picks.density !== null ? picks.density : 1;

var dp = picks.depth !== null ? picks.depth : 0;

var bg, fg;

if (th.id === "palette" && p.background) {

bg = p.background;

fg = p.foreground;

} else {

bg = th.bg;

fg = th.fg;

}

var ac = p.accent,

mt = p.muted || al(fg, 0.4);

var pad = [12, 20, 36][dn] + "px",

gap = [8, 16, 28][dn] + "px";

var isDark = bg && bg[0] === "#" ? parseInt(bg.slice(1, 3), 16) < 80 : true;

var shCol = isDark ? ac : fg;

var shadow = [

"none",

"0 2px 16px " + al(shCol, isDark ? 0.15 : 0.1),

"0 4px 32px " + al(shCol, isDark ? 0.3 : 0.18),

][dp];

var tokens = {

"{{bg}}": bg,

"{{fg}}": fg,

"{{ac}}": ac,

"{{mt}}": mt,

"{{sf}}": al(fg, 0.06),

"{{hf}}": t.headline.family,

"{{hw}}": t.headline.weight,

"{{bf}}": t.body.family,

"{{bw}}": t.body.weight,

"{{cr}}": cr,

"{{pad}}": pad,

"{{gap}}": gap,

"{{shadow}}": shadow,

"{{g}}": al(fg, 0.06),

"{{fg3}}": al(fg, 0.03),

"{{fg6}}": al(fg, 0.06),

"{{fg8}}": al(fg, 0.08),

"{{fg15}}": al(fg, 0.15),

"{{ac3}}": al(ac, 0.03),

"{{ac5}}": al(ac, 0.05),

"{{ac25}}": al(ac, 0.25),

"{{prompt_headline}}": (PROMPT && PROMPT.headline) || "Your Headline",

"{{prompt_sub}}": (PROMPT && PROMPT.subline) || "Subline.",

};

var h =

a.preview_html ||

'<div style="background:' +

bg +

";padding:40px;min-height:100%;display:flex;align-items:center;justify-content:center;color:" +

mt +

';font-size:14px;">No preview</div>';

Object.keys(tokens).forEach(function (k) {

h = h.split(k).join(tokens[k]);

});

pv.innerHTML = h;

}

// ── Output ──

function showOutput() {

if (

picks.theme === null ||

picks.arch === null ||

picks.palette === null ||

picks.type === null ||

picks.corners === null ||

picks.density === null ||

picks.depth === null

)

return;

var a = ARCHITECTURES[picks.arch],

p = PALETTES[picks.palette],

t = TYPEPAIRS[picks.type];

var th = THEMES[picks.theme],

cr = CORNERS[picks.corners],

dn = DENSITIES[picks.density],

dp = DEPTHS[picks.depth];

var bg = th.id === "palette" && p.background ? p.background : th.bg;

var fg = th.id === "palette" && p.foreground ? p.foreground : th.fg;

var ac = p.accent,

mt = p.muted || p.mid || "#888";

var padVal = { Tight: "8px", Normal: "16px", Generous: "32px" }[dn.name] || "16px";

var gapVal = { Tight: "8px", Normal: "16px", Generous: "28px" }[dn.name] || "16px";

var md = "---\n";

md += "name: " + ((PROMPT && PROMPT.title) || "Untitled") + "\n";

md +=

'colors:\n primary: "' +

bg +

'"\n on-primary: "' +

fg +

'"\n accent: "' +

ac +

'"\n muted: "' +

mt +

'"\n';

md +=

"typography:\n headline:\n fontFamily: " +

t.headline.family +

"\n fontSize: 3.5rem\n fontWeight: " +

t.headline.weight +

"\n letterSpacing: -0.03em\n";

md +=

" body:\n fontFamily: " +

t.body.family +

"\n fontSize: 1rem\n fontWeight: " +

t.body.weight +

"\n lineHeight: 1.5\n";

md += "rounded:\n md: " + cr.value + "\n";

md += "spacing:\n md: " + padVal + "\n lg: " + gapVal + "\n";

md += "---\n\n";

md += "## Overview\n\n" + a.mood + ". " + a.description + ". " + p.description + ".\n\n";

md +=

"## Colors\n\n- **Primary** (`" +

bg +

"`) — Canvas background\n- **On-Primary** (`" +

fg +

"`) — Text and content\n- **Accent** (`" +

ac +

"`) — CTAs, highlights\n- **Muted** (`" +

mt +

"`) — Secondary text\n\n";

md +=

"## Typography\n\n- **Headline** — " +

t.headline.family +

" at weight " +

t.headline.weight +

"\n- **Body** — " +

t.body.family +

" at weight " +

t.body.weight +

"\n\n";

md +=

"## Layout\n\n- Structure: " +

a.name +

" — " +

a.tag +

"\n- Density: " +

dn.name +

" (" +

dn.desc +

")\n- Corners: " +

cr.name +

" (" +

cr.value +

")\n\n";

md += "## Elevation\n\n" + dp.name + " — " + dp.desc + ".\n\n";

var easeObj = picks.easing !== null ? EASINGS[picks.easing] : null;

if (easeObj) {

md +=

"## Motion\n\n- **Entry easing:** `" +

easeObj.value +

"` — " +

easeObj.desc +

"\n- **Energy:** " +

easeObj.name +

"\n\n";

}

if (a.components) md += "## Components\n\n" + a.components + "\n\n";

md += "## Do's and Don'ts\n\n";

if (a.dos) {

md += a.dos + "\n";

} else {

md +=

"### Do's\n- Use accent color sparingly for maximum impact\n- Maintain consistent " +

cr.name.toLowerCase() +

" corners\n\n### Don'ts\n- Do not mix multiple accent colors\n- Do not use weights outside the headline/body pair\n";

}

document.getElementById("md-output").value = md;

document.getElementById("md-overlay").classList.add("visible");

}

document.getElementById("copy-btn").addEventListener("click", function () {

navigator.clipboard.writeText(document.getElementById("md-output").value).then(function () {

document.getElementById("copy-btn").textContent = "Copied!";

setTimeout(function () {

document.getElementById("copy-btn").textContent = "Copy";

}, 2000);

});

</script>

</body>

</html>

mdskills/hyperframes/visual-styles.md

11 kB

# Visual Style Library

Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition and expressed as a DESIGN.md-compatible token block. Use them as starters — copy the YAML into your project's `design.md` front matter, then customize.

**How to pick:** Match mood first, content second. Ask: _"What should the viewer FEEL?"_

**How to use:** Copy the style's YAML token block into `design.md` front matter. Add `## Overview`, `## Colors`, `## Typography`, `## Elevation`, `## Components`, `## Do's and Don'ts` prose sections to complete the file.

## Quick Reference

| --------------- | --------------------- | ---------------------------------- | --------------------------------- |

---

## 1. Swiss Pulse — Josef Müller-Brockmann

**Mood:** Clinical, precise | **Best for:** SaaS dashboards, developer tools, APIs, metrics

```yaml

colors:

primary: "#1a1a1a"

on-primary: "#ffffff"

accent: "#0066FF"

typography:

headline:

fontFamily: Helvetica Neue

fontSize: 5rem

fontWeight: 700

label:

fontFamily: Inter

fontSize: 0.875rem

fontWeight: 400

stat:

fontFamily: Helvetica Neue

fontSize: 7rem

fontWeight: 700

rounded:

none: 0px

sm: 2px

spacing:

sm: 8px

md: 16px

lg: 32px

motion:

energy: high

easing:

entry: "expo.out"

exit: "power4.in"

ambient: "none"

duration:

entrance: 0.4

hold: 1.5

transition: 0.6

atmosphere:

- grid-lines

- registration-marks

transition: cinematic-zoom

```

Grid-locked compositions. Every element snaps to an invisible 12-column grid. Numbers dominate the frame at 80–120px. Animated counters count up from 0. Hard cuts, no decorative transitions. Nothing floats.

---

## 2. Velvet Standard — Massimo Vignelli

**Mood:** Premium, timeless | **Best for:** Luxury products, enterprise software, keynotes, investor decks

```yaml

colors:

primary: "#0a0a0a"

on-primary: "#ffffff"

accent: "#1a237e"

typography:

headline:

fontFamily: Inter

fontSize: 3rem

fontWeight: 300

letterSpacing: 0.15em

textTransform: uppercase

body:

fontFamily: Inter

fontSize: 1rem

fontWeight: 300

lineHeight: 1.6

rounded:

sm: 0px

md: 2px

spacing:

sm: 16px

md: 32px

lg: 64px

motion:

energy: calm

easing:

entry: "sine.inOut"

exit: "power1.in"

ambient: "sine.inOut"

duration:

entrance: 1.2

hold: 3.0

transition: 1.5

atmosphere:

- subtle-grain

- hairline-rules

transition: cross-warp-morph

```

Generous negative space. Symmetrical, centered, architectural precision. Thin sans-serif, ALL CAPS, wide letter-spacing. Sequential reveals with long holds. Nothing snaps — everything glides with intention. Luxury takes its time.

---

## 3. Deconstructed — Neville Brody

**Mood:** Industrial, raw | **Best for:** Tech news, developer launches, security products, punk-energy reveals

```yaml

colors:

primary: "#1a1a1a"

on-primary: "#f0f0f0"

accent: "#D4501E"

typography:

headline:

fontFamily: Space Grotesk

fontSize: 4rem

fontWeight: 700

label:

fontFamily: Space Mono

fontSize: 0.75rem

fontWeight: 700

textTransform: uppercase

rounded:

none: 0px

spacing:

sm: 4px

md: 12px

lg: 24px

motion:

energy: high

easing:

entry: "back.out(2.5)"

exit: "steps(8)"

ambient: "elastic.out(1.2, 0.4)"

duration:

entrance: 0.3

hold: 1.0

transition: 0.5

atmosphere:

- scan-lines

- glitch-artifacts

- grain-overlay

transition: glitch

```

Type at angles, overlapping edges, escaping frames. Bold industrial weight. Gritty textures: scan-line effects, glitch artifacts baked into design. Text SLAMS and SHATTERS. Letters scramble then snap to final position. Intentional irregularity — nothing should feel polished.

---

## 4. Maximalist Type — Paula Scher

**Mood:** Loud, kinetic | **Best for:** Big product launches, milestone announcements, high-energy hype videos

```yaml

colors:

primary: "#0a0a0a"

on-primary: "#ffffff"

accent-red: "#E63946"

accent-yellow: "#FFD60A"

typography:

headline:

fontFamily: Anton

fontSize: 8rem

fontWeight: 400

textTransform: uppercase

subhead:

fontFamily: Space Grotesk

fontSize: 3rem

fontWeight: 700

rounded:

none: 0px

spacing:

sm: 0px

md: 8px

motion:

energy: high

easing:

entry: "expo.out"

exit: "back.out(1.8)"

ambient: "power3.out"

duration:

entrance: 0.3

hold: 0.8

transition: 0.4

atmosphere:

- type-layers

- color-blocks

transition: ridged-burn

```

Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame. Bold saturated colors — maximum contrast. Everything kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes. No static moments. Fast arrivals, hard stops.

---

## 5. Data Drift — Refik Anadol

**Mood:** Futuristic, immersive | **Best for:** AI products, ML platforms, data companies, speculative tech

```yaml

colors:

primary: "#0a0a0a"

on-primary: "#e0e0e0"

accent-purple: "#7c3aed"

accent-cyan: "#06b6d4"

typography:

headline:

fontFamily: Inter

fontSize: 2.5rem

fontWeight: 200

letterSpacing: 0.05em

body:

fontFamily: Inter

fontSize: 0.875rem

fontWeight: 300

rounded:

sm: 4px

md: 12px

full: 9999px

spacing:

sm: 16px

md: 32px

lg: 64px

motion:

energy: moderate

easing:

entry: "sine.inOut"

exit: "power2.out"

ambient: "sine.inOut"

duration:

entrance: 1.0

hold: 2.5

transition: 1.5

atmosphere:

- particle-field

- light-traces

- radial-glow

transition: gravitational-lens

```

Thin futuristic sans-serif — floating, weightless, minimal. Fluid morphing compositions. Extreme scale shifts (micro → macro). Particles coalesce into numbers. Light traces data paths through the frame. Smooth, continuous, organic. Nothing hard.

---

## 6. Soft Signal — Stefan Sagmeister

**Mood:** Intimate, warm | **Best for:** Wellness brands, personal stories, lifestyle products, human-centered apps

```yaml

colors:

primary: "#FFF8EC"

on-primary: "#2a2a2a"

accent-amber: "#F5A623"

accent-rose: "#C4A3A3"

accent-sage: "#8FAF8C"

typography:

headline:

fontFamily: Playfair Display

fontSize: 3rem

fontWeight: 400

fontStyle: italic

body:

fontFamily: Inter

fontSize: 1rem

fontWeight: 300

lineHeight: 1.7

rounded:

sm: 8px

md: 16px

lg: 24px

full: 9999px

spacing:

sm: 12px

md: 24px

lg: 48px

motion:

energy: calm

easing:

entry: "sine.inOut"

exit: "power1.inOut"

ambient: "sine.inOut"

duration:

entrance: 1.0

hold: 3.0

transition: 1.5

atmosphere:

- soft-gradient

- warm-grain

transition: thermal-distortion

```

Handwritten-style or humanist serif fonts. Personal, lowercase, delicate. Close-up framing: single element fills the frame. Slow drifts and floats, never snaps. Soft organic motion. Nothing should feel hurried or polished. Intimate, never corporate.

---

## 7. Folk Frequency — Eduardo Terrazas

**Mood:** Cultural, vivid | **Best for:** Consumer apps, food platforms, community products, festive launches

```yaml

colors:

primary: "#ffffff"

on-primary: "#1a1a1a"

accent-pink: "#FF1493"

accent-blue: "#0047AB"

accent-yellow: "#FFE000"

accent-green: "#009B77"

typography:

headline:

fontFamily: Fredoka One

fontSize: 4rem

fontWeight: 400

body:

fontFamily: Nunito

fontSize: 1rem

fontWeight: 600

rounded:

sm: 8px

md: 16px

lg: 32px

full: 9999px

spacing:

sm: 8px

md: 16px

lg: 32px

motion:

energy: high

easing:

entry: "back.out(1.6)"

exit: "elastic.out(1, 0.5)"

ambient: "sine.inOut"

duration:

entrance: 0.5

hold: 1.5

transition: 0.8

atmosphere:

- pattern-tiles

- confetti-burst

- color-blocks

transition: swirl-vortex

```

Bold warm rounded type. Pattern and repetition — folk art rhythm and density. Layered compositions with rich visual texture. Every frame feels handcrafted. Colorful motion: elements bounce, pop, spin into place with joy. Overshoots feel intentional. Celebratory energy.

---

## 8. Shadow Cut — Hans Hillmann

**Mood:** Dark, cinematic | **Best for:** Security products, dramatic reveals, investigative content, intense launches

```yaml

colors:

primary: "#0a0a0a"

on-primary: "#f0f0f0"

surface: "#3a3a3a"

accent: "#C1121F"

typography:

headline:

fontFamily: Oswald

fontSize: 4rem

fontWeight: 700

textTransform: uppercase

body:

fontFamily: Inter

fontSize: 0.875rem

fontWeight: 400

rounded:

none: 0px

sm: 2px

spacing:

sm: 8px

md: 16px

lg: 48px

motion:

energy: moderate

easing:

entry: "power3.out"

exit: "power4.in"

ambient: "sine.inOut"

duration:

entrance: 0.8

hold: 2.5

transition: 1.2

atmosphere:

- deep-shadow

- vignette

- grain-overlay

transition: domain-warp

```

Near-monochrome: deep blacks, cold greys, stark white + one blood accent. Sharp angular text like film noir title cards. Heavy contrast, no softness. Elements emerge from darkness — reveal is the narrative. Slow creeping push-ins, dramatic scale reveals. The pause before the hit matters. Domain Warp dissolves reality before the next scene.

---

## Mood → Style Guide

| If the content feels... | Use... |

| ---------------------------------- | --------------- |

| Data-driven, analytical, technical | Swiss Pulse |

| Premium, enterprise, luxury | Velvet Standard |

| Raw, punk, aggressive, rebellious | Deconstructed |

| Hype, loud, high-energy launch | Maximalist Type |

| AI, ML, speculative, futuristic | Data Drift |

| Human, warm, personal, wellness | Soft Signal |

| Cultural, fun, consumer, festive | Folk Frequency |

| Dark, dramatic, intense, cinematic | Shadow Cut |

---

## Creating Custom Styles

These 8 styles are starters — not constraints. Create your own:

1. **Name it** after a designer, art movement, or cultural reference

2. **Write YAML tokens** — `colors` (2–5 tokens), `typography` (2–3 scales), `rounded`, `spacing`, `motion` (energy + easing + duration + atmosphere + transition)

3. **Add prose** — one paragraph describing the feel, what to do, what to avoid

4. **Token references** — use `{colors.accent}`, `{typography.headline}` in component definitions

The pattern: **YAML tokens (what) → prose rationale (why) → components (how they combine).**

mdskills/lottie/SKILL.md

3.3 kB

---

description: Lottie and dotLottie adapter patterns for HyperFrames. Use when embedding lottie-web JSON animations, .lottie files, @lottiefiles/dotlottie-web players, registering instances on window.__hfLottie, or making After Effects exports deterministic in HyperFrames.

---

# Lottie for HyperFrames

HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie` runtime adapter. Lottie is a strong fit because the animation timeline is already encoded in the asset; HyperFrames only needs a player object it can seek.

## Contract

- Load assets from local project files, usually under `assets/`.

- Set `autoplay: false`.

- Prefer `loop: false` unless the user explicitly wants a loop.

- Register every returned animation or player on `window.__hfLottie`.

- Keep the Lottie container dimensions stable with CSS.

The adapter seeks `lottie-web` with `goToAndStop(timeMs, false)` and dotLottie with frame or percentage APIs depending on player shape.

## lottie-web Pattern

```html

const anim = lottie.loadAnimation({

container: document.getElementById("logo-lottie"),

renderer: "svg",

loop: false,

autoplay: false,

path: "assets/logo-reveal.json",

});

window.__hfLottie = window.__hfLottie || [];

window.__hfLottie.push(anim);

</script>

```

```css

.lottie-layer {

width: 100%;

height: 100%;

}

```

## dotLottie Pattern

```html

const player = new DotLottie({

canvas: document.getElementById("product-lottie"),

src: "assets/product-flow.lottie",

autoplay: false,

loop: false,

});

window.__hfLottie = window.__hfLottie || [];

window.__hfLottie.push(player);

</script>

```

```css

.lottie-canvas {

width: 100%;

height: 100%;

display: block;

}

```

## Multiple Animations

Push each player into the same registry:

```js

window.__hfLottie = window.__hfLottie || [];

window.__hfLottie.push(backgroundAnim);

window.__hfLottie.push(iconAnim);

window.__hfLottie.push(confettiAnim);

```

HyperFrames seeks them all to the same composition time.

## Good Uses

- After Effects exports that are already known to render correctly in lottie-web.

- Logo reveals, icon loops, decorative accents, and product UI motion.

- Translating Remotion Lottie usage into plain HyperFrames HTML.

## Avoid

- Relying on remote `path` URLs at render time.

- Starting playback with `play()`.

- Assuming unsupported After Effects effects will survive export. Test the JSON or `.lottie` file in a browser first.

- Loading a player asynchronously and registering it after HyperFrames validation has already inspected the page.

## Validation

After editing a Lottie composition:

```bash

npx hyperframes lint

npx hyperframes validate

```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/lottie.ts`.

- lottie-web by Airbnb: https://github.com/airbnb/lottie-web

- lottie-web `loadAnimation` options: https://github.com/airbnb/lottie-web/wiki/loadAnimation-options

- dotLottie web player methods by LottieFiles: https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/methods

shskills/remotion-to-hyperframes/assets/test-corpus/run.sh

8.2 kB

#!/usr/bin/env bash

# run.sh — corpus orchestrator. Runs every tier and prints a pass/fail summary.

# Tiers 1-3: render Remotion baseline + HF translation, run SSIM diff,

# assert mean >= ssim_threshold from each fixture's expected.json.

# Tier 4: runs cases/validate.sh which lints each case and asserts against

# expected.json.

# Usage:

# ./run.sh run all tiers

# ./run.sh tier-1-title-card run a single tier

# Requirements:

# - ffmpeg, ffprobe, python3 on PATH

# - node 22 (for the HF CLI)

# - npm (for Remotion installs)

# - HF CLI built at packages/cli/dist/cli.js (run `bun run --filter @hyperframes/cli build`

# in the repo root if missing)

# Output:

# <fixture>/diff/summary.json per-fixture SSIM summary

# <fixture>/strip/strip.png per-fixture comparison strip (only on fail)

# ./run-report.json aggregate report

set -euo pipefail

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

SKILL_DIR="$(cd "$THIS_DIR/../.." && pwd)"

REPO_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"

LINT="$SKILL_DIR/scripts/lint_source.py"

DIFF="$SKILL_DIR/scripts/render_diff.sh"

STRIP="$SKILL_DIR/scripts/frame_strip.sh"

HF_CLI="$REPO_ROOT/packages/cli/dist/cli.js"

REPORT="$THIS_DIR/run-report.json"

# Per-fixture results land here as one JSON file each, then the aggregator

# globs them. This is safer than building JSON via bash string concatenation

# (a fixture name containing a quote would break the previous approach).

RESULTS_DIR="$(mktemp -d)"

trap 'rm -rf "$RESULTS_DIR"' EXIT

# T4 is lint-only — no ffmpeg or HF CLI needed. Defer the render-tier

# toolchain checks until run_render_tier() actually runs, so

# `./run.sh tier-4-escape-hatch` works on a clean checkout.

require_render_tier_tools() {

if [[ ! -f "$HF_CLI" ]]; then

echo "error: HF CLI not built at $HF_CLI" >&2

echo " Run 'bun run --filter @hyperframes/cli build' in $REPO_ROOT" >&2

return 2

if ! command -v ffmpeg >/dev/null 2>&1; then

echo "error: ffmpeg not on PATH" >&2

return 2

return 0

}

# Write one fixture's result as a JSON file. Values are passed via argv so

# bash string interpolation can't corrupt the JSON or inject Python source.

write_result() {

local fixture_name="$1"

local status="$2"

shift 2

python3 - "$RESULTS_DIR/$fixture_name.json" "$fixture_name" "$status" "$@" <<'PY'

import json

import sys

out_path, fixture_name, status, *kvs = sys.argv[1:]

result = {"fixture": fixture_name, "status": status}

for i in range(0, len(kvs), 2):

k, v = kvs[i], kvs[i + 1]

try:

result[k] = float(v) if "." in v or v.lstrip("-").isdigit() else v

except ValueError:

result[k] = v

with open(out_path, "w") as f:

json.dump(result, f)

}

# Read a top-level scalar value from a JSON file. Falls back to $3 if the

# key is missing (used to default composition_id for older fixtures).

read_json_value() {

local file="$1"

local key="$2"

local default="${3:-}"

python3 - "$file" "$key" "$default" <<'PY'

import json

import sys

path, key, default = sys.argv[1], sys.argv[2], sys.argv[3]

with open(path) as f:

data = json.load(f)

val = data.get(key, default)

print(val if val is not None else "")

}

run_render_tier() {

local fixture_dir="$1"

local fixture_name

fixture_name=$(basename "$fixture_dir")

local expected="$fixture_dir/expected.json"

if ! require_render_tier_tools; then

echo " ⚠ $fixture_name: render toolchain unavailable, skipping"

write_result "$fixture_name" "skipped" reason "render toolchain unavailable"

return 0

local threshold composition_id

threshold=$(read_json_value "$expected" "ssim_threshold")

composition_id=$(read_json_value "$expected" "composition_id" "Composition")

echo " ▶ $fixture_name (threshold $threshold, composition $composition_id)"

if [[ -x "$fixture_dir/setup.sh" ]]; then

"$fixture_dir/setup.sh" >/dev/null

if ! python3 "$LINT" "$fixture_dir/remotion-src/src/" >/dev/null; then

echo " ✗ lint failed (blockers in Remotion source)"

write_result "$fixture_name" "fail" stage "lint"

return 0

if [[ ! -d "$fixture_dir/remotion-src/node_modules" ]]; then

echo " ⏳ npm install (first run)"

(cd "$fixture_dir/remotion-src" && npm install --silent --no-progress >/dev/null 2>&1)

echo " ⏳ render Remotion baseline"

if ! (cd "$fixture_dir/remotion-src" && \

npx --no-install remotion render "$composition_id" out/baseline.mp4 >/dev/null 2>&1); then

echo " ✗ Remotion render failed"

write_result "$fixture_name" "fail" stage "remotion-render"

return 0

echo " ⏳ render HF translation"

if ! (cd "$fixture_dir" && \

node "$HF_CLI" render hf-src/ --output hf.mp4 --quiet >/dev/null 2>&1); then

echo " ✗ HF render failed"

write_result "$fixture_name" "fail" stage "hf-render"

return 0

if R2HF_SSIM_THRESHOLD="$threshold" "$DIFF" \

"$fixture_dir/remotion-src/out/baseline.mp4" \

"$fixture_dir/hf.mp4" \

"$fixture_dir/diff" >/dev/null; then

local mean

mean=$(read_json_value "$fixture_dir/diff/summary.json" "mean")

echo " ✓ pass (mean SSIM $mean, threshold $threshold)"

write_result "$fixture_name" "pass" mean_ssim "$mean" threshold "$threshold"

else

local mean

mean=$(read_json_value "$fixture_dir/diff/summary.json" "mean")

echo " ✗ fail (mean SSIM $mean, threshold $threshold)"

"$STRIP" \

"$fixture_dir/remotion-src/out/baseline.mp4" \

"$fixture_dir/hf.mp4" \

"$fixture_dir/strip" 8 >/dev/null

write_result "$fixture_name" "fail" stage "ssim" mean_ssim "$mean" threshold "$threshold"

}

run_lint_tier() {

local fixture_dir="$1"

local fixture_name

fixture_name=$(basename "$fixture_dir")

echo " ▶ $fixture_name (lint-only)"

if "$fixture_dir/validate.sh" >/dev/null 2>&1; then

echo " ✓ pass (8/8 cases)"

write_result "$fixture_name" "pass" mode "lint"

else

echo " ✗ fail (some cases mismatched expected.json)"

write_result "$fixture_name" "fail" mode "lint"

}

echo "remotion-to-hyperframes corpus run"

echo "=================================="

for tier in tier-1-title-card tier-2-multi-scene tier-3-data-driven; do

if [[ -n "${1:-}" && "$1" != "$tier" ]]; then

continue

if [[ -d "$THIS_DIR/$tier" ]]; then

run_render_tier "$THIS_DIR/$tier"

done

if [[ -z "${1:-}" || "$1" == "tier-4-escape-hatch" ]]; then

if [[ -d "$THIS_DIR/tier-4-escape-hatch" ]]; then

run_lint_tier "$THIS_DIR/tier-4-escape-hatch"

# Aggregate the per-fixture JSON files into one report.

# Skipped fixtures are *not* a pass — they mean a tier didn't run because

# tooling or fixtures were unavailable. The orchestrator exits non-zero on

# any skip so a clean checkout that lacks the HF CLI doesn't accidentally

# report "passed 1/4" (T4 alone) and look like the corpus is healthy.

# Single-tier mode (`./run.sh tier-N`) only writes a result file for the

# selected tier; tiers that weren't run aren't counted as skips.

python3 - "$RESULTS_DIR" "$REPORT" <<'PY'

import json

import sys

from pathlib import Path

results_dir, out_path = Path(sys.argv[1]), Path(sys.argv[2])

results = sorted(

(json.loads(p.read_text()) for p in results_dir.glob("*.json")),

key=lambda r: r["fixture"],

)

total = len(results)

passed = sum(1 for r in results if r["status"] == "pass")

failed = sum(1 for r in results if r["status"] == "fail")

skipped = sum(1 for r in results if r["status"] == "skipped")

report = {

"total": total,

"passed": passed,

"failed": failed,

"skipped": skipped,

"results": results,

}

out_path.write_text(json.dumps(report, indent=2))

print()

print("=" * 50)

print(f" passed {passed}/{total}, failed {failed}, skipped {skipped}")

print(f" report → {out_path}")

if skipped > 0:

skipped_fixtures = [r["fixture"] for r in results if r["status"] == "skipped"]

skipped_reasons = sorted({r.get("reason", "unknown") for r in results if r["status"] == "skipped"})

print()

print(f" ⚠ {skipped} skipped: {', '.join(skipped_fixtures)}")

for reason in skipped_reasons:

print(f" reason: {reason}")

print(" Skipped fixtures count as failures for the aggregate.")

print("=" * 50)

sys.exit(0 if failed == 0 and skipped == 0 else 1)

mdskills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/README.md

2.2 kB

# Tier 1 — title-card-fade

## What it tests

The simplest non-trivial Remotion → HyperFrames translation. A single text

element fades in over the first 0.5 s, holds for 2.0 s, and fades out over

the last 0.5 s. No audio, no media, no custom components.

If a translation can't pass T1, it's broken on table-stakes basics:

`AbsoluteFill`, `useCurrentFrame`, `interpolate` with multi-segment input,

and the timing offset between Remotion's frame-based driver and HF's

paused-GSAP driver.

## Translation walk-through

| Remotion | HyperFrames |

| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |

| `<AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>` | `<body style="background: #0a0a0a">` + a positioned root div |

| `useCurrentFrame()` | dropped — HF seeks the timeline |

| `interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0])` at fps=30 | `gsap.timeline({ paused: true })` with three `.to()` calls at offsets 0s/0.5s/2.5s, each `ease: "none"` |

| `<div style={{ opacity }}>HELLO</div>` | static markup; opacity is animated by the timeline |

The Remotion→HF time conversion is `time = frame / fps`. So

`[0, 15, 75, 90]` at 30 fps becomes `[0, 0.5, 2.5, 3.0]` seconds.

## How to render and evaluate

```bash

# Render Remotion baseline

cd remotion-src && npm install && npm run render

# Renders to remotion-src/out/baseline.mp4

# Render HyperFrames translation

cd ../hf-src && npx hyperframes render --output ../hf.mp4

# Compare with the eval harness (from skill scripts/)

../../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

```

`expected.json` documents the SSIM threshold (0.95) for this fixture; the

calibrated mean against Remotion @ 4.0 with PNG/BT.709 output is 0.974.

jsonskills/remotion-to-hyperframes/assets/test-corpus/tier-2-multi-scene/expected.json

2.0 kB

{

"tier": 2,

"name": "title-image-outro",

"composition_id": "MultiScene",

"description": "Three-scene composition exercising Sequence, spring, interpolate, Audio, Img, and staticFile. Title scene uses Remotion's spring (translated to GSAP back.out as an approximation). Image scene scales an Img (from staticFile) with linear interpolate. Outro scene fades text in linearly. A silent WAV plays throughout at volume 0.5.",

"duration_seconds": 6,

"fps": 30,

"width": 1280,

"height": 720,

"ssim_threshold": 0.95,

"validation": {

"measured_mean_ssim": 0.985,

"measured_min_ssim": 0.963,

"measured_p05_ssim": 0.966,

"measured_p95_ssim": 0.999,

"measured_at": "2026-04-27",

"measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.4.15-alpha.1",

"notes": "Spring → back.out(1.4) translation came out cleaner than expected; mean 0.985 leaves substantial headroom over 0.95."

"translation_notes": [

"spring({damping:12, stiffness:100, mass:1}) → back.out(1.4) over 0.7s. Spring overshoot+settle and back.out's overshoot+settle have similar shape; budget ~0.02 SSIM for the late-tail curvature mismatch (validated lower than predicted in spec; original notes overestimated drift).",

"<Sequence from durationInFrames> → wrapping div with data-start/data-duration in seconds and explicit gsap.set(opacity, 0/1) at scene boundaries to crossfade in/out cleanly",

"<Audio src volume> → <audio data-start data-duration data-volume>",

"<Img src={staticFile('x')}> → <img src='assets/x'>; setup.sh copies the asset into both fixture trees",

"interpolate with default linear easing → ease:'none' in GSAP",

"Fonts again rely on system Helvetica/Arial; ~0.015 SSIM cost from AA differences"

"rationale": "Threshold 0.95 sits ~0.015 below measured p05 (0.966). T2 actually validated cleaner than T1 because the lower title fontWeight (140px vs T1's 160px) shows less of the system-font fallback divergence."

}

htmlskills/remotion-to-hyperframes/assets/test-corpus/tier-2-multi-scene/hf-src/index.html

3.7 kB

<!doctype html>

<head>

<title>tier-2-multi-scene</title>

<style>

html,

body {

margin: 0;

padding: 0;

width: 1280px;

height: 720px;

overflow: hidden;

background: #0a0a0a;

font-family: Helvetica, Arial, sans-serif;

}

.scene {

position: absolute;

inset: 0;

display: flex;

align-items: center;

justify-content: center;

opacity: 0;

}

.title {

font-size: 140px;

font-weight: 800;

color: #ffffff;

letter-spacing: 0.05em;

transform: scale(0);

}

.square {

width: 200px;

height: 200px;

opacity: 0;

transform: scale(0.8);

}

.outro {

font-size: 100px;

font-weight: 600;

color: #ffffff;

}

</style>

</head>

<body>

<div

id="stage"

data-composition-id="tier-2-multi-scene"

data-start="0"

data-width="1280"

data-height="720"

data-duration="6"

data-fps="30"

<div class="title">Welcome</div>

</div>

</div>

<div class="outro">Goodbye</div>

</div>

<audio

id="bg-music"

data-start="0"

data-duration="6"

data-track-index="1"

data-volume="0.5"

src="assets/music.wav"

></audio>

// Translation of Remotion's 3-Sequence MultiScene at fps=30, total 6s.

// Scene 1 (0-2s): TitleScene — spring scale on "Welcome".

// Remotion: spring({frame, fps, config: {damping:12, stiffness:100, mass:1}})

// GSAP equivalent: back.out(1.4) over ~0.7s. Spring → ease translation

// is approximate; expect minor differences in the tail of the curve.

// Scene 2 (2-4s): ImageScene — opacity 0→1 over 0-0.5s + scale 0.8→1.0 over 0-2.0s.

// Both Remotion interpolates use linear (default), match with ease:"none".

// Scene 3 (4-6s): OutroScene — opacity 0→1 over 4-5s, linear.

const tl = gsap.timeline({ paused: true });

// Scene 1 setup: opacity flick on so scene becomes visible at start

const scene1 = document.querySelector("#scene-1");

const title = scene1.querySelector(".title");

tl.set(scene1, { opacity: 1 }, 0);

tl.to(title, { scale: 1, duration: 0.7, ease: "back.out(1.4)" }, 0);

tl.set(scene1, { opacity: 0 }, 2);

// Scene 2

const scene2 = document.querySelector("#scene-2");

const square = scene2.querySelector(".square");

tl.set(scene2, { opacity: 1 }, 2);

tl.to(square, { opacity: 1, duration: 0.5, ease: "none" }, 2);

tl.to(square, { scale: 1.0, duration: 2.0, ease: "none" }, 2);

tl.set(scene2, { opacity: 0 }, 4);

// Scene 3

const scene3 = document.querySelector("#scene-3");

const outro = scene3.querySelector(".outro");

tl.set(scene3, { opacity: 1 }, 4);

tl.fromTo(outro, { opacity: 0 }, { opacity: 1, duration: 1.0, ease: "none" }, 4);

window.__timelines = window.__timelines || {};

window.__timelines["tier-2-multi-scene"] = tl;

</script>

</div>

</body>

</html>

mdskills/remotion-to-hyperframes/assets/test-corpus/tier-2-multi-scene/README.md

3.1 kB

# Tier 2 — title-image-outro

## What it tests

Three-scene composition. Each scene exercises a different Remotion idiom:

1. **Scene 1 (0–2 s)** — TitleScene with `spring({damping:12, stiffness:100, mass:1})`

driving a `transform: scale()` on text. Tests the lossy `spring → GSAP ease` translation.

2. **Scene 2 (2–4 s)** — ImageScene that fades in a `staticFile`-loaded image and

linearly scales it from 0.8 → 1.0. Tests asset paths + linear `interpolate`.

3. **Scene 3 (4–6 s)** — OutroScene with a 1-s linear fade-in. Sanity check after

the harder scenes.

A silent 6-second WAV plays throughout at `volume={0.5}`. Tests `<Audio>` translation.

If a translation passes T2, the skill correctly handles `<Sequence>` boundaries,

`<Audio>` / `<Img>` / `staticFile`, and the Remotion `spring → GSAP ease` heuristic.

## Translation walk-through

| Remotion | HyperFrames |

| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |

| `<Sequence from={0} durationInFrames={60}>` | `<div data-start="0" data-duration="2" data-track-index="0">` |

| `spring({frame, fps, config: {damping:12, stiffness:100, mass:1}})` | `gsap.to(target, { scale: 1, duration: 0.7, ease: "back.out(1.4)" })` |

| `<Audio src={staticFile("music.wav")} volume={0.5} />` | `<audio src="assets/music.wav" data-start="0" data-duration="6" data-volume="0.5" data-track-index="1">` |

| `<Img src={staticFile("square.png")} />` | `<img src="assets/square.png">` (with setup.sh copying into both trees) |

| `interpolate(frame, [0, 15], [0, 1])` at 30 fps | `gsap.to(target, { opacity: 1, duration: 0.5, ease: "none" })` |

The scene crossfading is a HyperFrames idiom, not a Remotion one: at scene boundaries

we `gsap.set(scene, { opacity: 0 })` so the previous scene disappears at the

right time. Remotion does this implicitly by virtue of `<Sequence>`'s durationInFrames.

## How to render and evaluate

```bash

# 1. Generate the binary assets (PNG + WAV) via ffmpeg

./setup.sh

# 2. Render Remotion baseline

cd remotion-src && npm install && npm run render

# 3. Render HyperFrames translation

cd ../hf-src && npx hyperframes render --output ../hf.mp4

# 4. Compare

../../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

```

## Why threshold 0.95?

Same threshold as T1 (`expected.json` codifies it for the orchestrator). Spring → `back.out(1.4)`

came in cleaner than predicted during calibration — the validated mean is 0.985 against the

0.95 gate. If the translation breaks anything else (spring overshoot wrong, stagger off,

asset path drift), mean SSIM will fall well below 0.95 — that's the failure signal.

tsxskills/remotion-to-hyperframes/assets/test-corpus/tier-2-multi-scene/remotion-src/src/MultiScene.tsx

2.3 kB

import {

AbsoluteFill,

Audio,

Img,

Sequence,

interpolate,

spring,

staticFile,

useCurrentFrame,

useVideoConfig,

} from "remotion";

const TitleScene = () => {

const frame = useCurrentFrame();

const { fps } = useVideoConfig();

const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100, mass: 1 } });

return (

<AbsoluteFill

style={{

backgroundColor: "#0a0a0a",

justifyContent: "center",

alignItems: "center",

fontFamily: "Helvetica, Arial, sans-serif",

}}

<div

style={{

fontSize: 140,

fontWeight: 800,

color: "#ffffff",

transform: `scale(${scale})`,

letterSpacing: "0.05em",

}}

Welcome

</div>

</AbsoluteFill>

);

};

const ImageScene = () => {

const frame = useCurrentFrame();

const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });

const scale = interpolate(frame, [0, 60], [0.8, 1.0], { extrapolateRight: "clamp" });

return (

<AbsoluteFill

style={{

backgroundColor: "#0a0a0a",

justifyContent: "center",

alignItems: "center",

}}

<Img

src={staticFile("square.png")}

style={{

width: 200,

height: 200,

opacity,

transform: `scale(${scale})`,

}}

</AbsoluteFill>

);

};

const OutroScene = () => {

const frame = useCurrentFrame();

const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });

return (

<AbsoluteFill

style={{

backgroundColor: "#0a0a0a",

justifyContent: "center",

alignItems: "center",

fontFamily: "Helvetica, Arial, sans-serif",

}}

<div

style={{

fontSize: 100,

fontWeight: 600,

color: "#ffffff",

opacity,

}}

Goodbye

</div>

</AbsoluteFill>

);

};

export const MultiScene = () => (

</Sequence>

</Sequence>

</Sequence>

</AbsoluteFill>

);

jsonskills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/expected.json

3.4 kB

{

"tier": 3,

"name": "stargazed-data-driven",

"composition_id": "Stargazed",

"description": "Data-driven 10-second composition with three scenes, custom React subcomponents reused across scenes, a Zod schema with defaultProps, and a count-up number animation. Translates the realistic shape of a production Remotion composition into HF — without using the runtime adapter from PR #214.",

"duration_seconds": 10,

"fps": 30,

"width": 1280,

"height": 720,

"ssim_threshold": 0.9,

"validation": {

"measured_mean_ssim": 0.953,

"measured_min_ssim": 0.927,

"measured_p05_ssim": 0.938,

"measured_p95_ssim": 0.977,

"measured_at": "2026-04-27",

"measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.4.15-alpha.1",

"notes": "Count-up timing in StatsScene shows a few-frame offset between Remotion's manual 1-(1-t)^3 and GSAP's power3.out — both formulas are identical, so the offset comes from sub-frame timing of when the seek + onUpdate fire. Final values converge correctly. Visible only as transient digit mismatches mid-animation; no SSIM impact above the noise floor."

"remotion_apis_exercised": [

"Composition with z.object schema and typed defaultProps",

"Sequence (3 nested with computed offsets)",

"AbsoluteFill",

"useCurrentFrame, useVideoConfig",

"interpolate (single-segment, multi-segment, with extrapolation)",

"spring (two configs: damping:12 and damping:14)",

"Custom React subcomponents reused with different props (StatCard ×3)",

"Custom React utility component (AnimatedNumber for count-up)",

"Custom React utility component (UnderlinedText)",

"Per-instance delay via prop (delayInFrames)"

"translation_notes": [

"Zod schema + defaultProps → data-* attributes on the root #stage div. The skill emits one data attribute per scalar prop; nested arrays (stats[]) get materialized as repeated HTML markup with per-instance data attributes (data-stat-index, data-stat-value, --card-color).",

"Custom React subcomponents inline as repeated HTML divs. The component prop interface becomes the repeated markup template. This is lossy for components with internal state — fine here because StatCard, AnimatedNumber, UnderlinedText all derive from props alone.",

"AnimatedNumber's frame-driven count-up → a GSAP tween on a { v: 0 } counter object with onUpdate rewriting textContent. GSAP's power3.out is cubic easeOut, matching the Remotion 1-(1-t)^3 manual ease.",

"Two different springs in this composition: damping:12 → back.out(1.4) (snappy), damping:14 → back.out(1.2) (calmer). The 1.4 vs 1.2 overshoot ratio approximates the damping difference.",

"Per-instance stagger via delayInFrames prop translates to a GSAP timeline offset of (i * 0.4)s.",

"Threshold 0.90 reflects: spring → back.out approximation (×2 different configs), the count-up easing curve match (very close but not identical due to sub-frame seek timing), font/AA differences on body text. SSIM well below 0.90 indicates a structural mismatch, not approximation drift."

"rationale": "Threshold 0.90 sits ~0.04 below measured p05 (0.938). The wider gap vs T1/T2 reflects T3's bigger approximation budget (2 spring instances + count-up timing + font fallback on multiple text sizes). Mean SSIM below 0.90 = structural mismatch (wrong durations, wrong stagger, missing prop wiring), not approximation drift."

}

htmlskills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/hf-src/index.html

8.9 kB

<!doctype html>

<head>

<title>tier-3-data-driven</title>

<style>

html,

body {

margin: 0;

padding: 0;

width: 1280px;

height: 720px;

overflow: hidden;

background: #0a0a0a;

font-family: Helvetica, Arial, sans-serif;

color: #ffffff;

}

.scene {

position: absolute;

inset: 0;

display: flex;

align-items: center;

justify-content: center;

opacity: 0;

}

/* Scene 1 — Title */

.scene-1 {

flex-direction: column;

}

.scene-1 .title {

font-size: 160px;

font-weight: 900;

letter-spacing: 0.05em;

transform: scale(0);

}

.scene-1 .subtitle {

font-size: 36px;

font-weight: 400;

color: #9ca3af;

margin-top: 24px;

opacity: 0;

}

/* Scene 2 — Stats */

.scene-2 {

gap: 48px;

}

.stat-card {

width: 280px;

height: 220px;

background: #1a1a1a;

border-radius: 16px;

border: 2px solid var(--card-color);

display: flex;

flex-direction: column;

justify-content: center;

align-items: center;

opacity: 0;

transform: scale(0);

}

.stat-card .number {

font-size: 72px;

font-weight: 800;

color: var(--card-color);

line-height: 1;

}

.stat-card .label {

font-size: 24px;

font-weight: 500;

color: #9ca3af;

margin-top: 16px;

text-transform: uppercase;

letter-spacing: 0.1em;

}

/* Scene 3 — Outro */

.scene-3 .outro-wrap {

position: relative;

display: inline-block;

opacity: 0;

}

.scene-3 .outro-text {

font-size: 80px;

font-weight: 600;

}

.scene-3 .outro-underline {

position: absolute;

left: 0;

bottom: -8px;

width: 100%;

height: 6px;

background: #fbbf24;

border-radius: 3px;

transform: scaleX(0);

transform-origin: left center;

}

</style>

</head>

<body>

<div

id="stage"

data-composition-id="tier-3-data-driven"

data-start="0"

data-width="1280"

data-height="720"

data-duration="10"

data-fps="30"

data-title="STARGAZED"

data-subtitle="by HeyGen"

data-outro="thanks for watching"

<div

id="scene-1"

class="scene scene-1 clip"

data-start="0"

data-duration="3"

data-track-index="0"

<div class="title">STARGAZED</div>

<div class="subtitle">by HeyGen</div>

</div>

<div

id="scene-2"

class="scene scene-2 clip"

data-start="3"

data-duration="4"

data-track-index="0"

<div

class="stat-card"

data-stat-index="0"

data-stat-value="1247"

style="--card-color: #fbbf24"

<div class="label">Stars</div>

</div>

<div

class="stat-card"

data-stat-index="1"

data-stat-value="312"

style="--card-color: #60a5fa"

<div class="label">Forks</div>

</div>

<div

class="stat-card"

data-stat-index="2"

data-stat-value="48"

style="--card-color: #f87171"

<div class="label">Issues</div>

</div>

<div

id="scene-3"

class="scene scene-3 clip"

data-start="7"

data-duration="3"

data-track-index="0"

<div class="outro-text">thanks for watching</div>

</div>

// ────────────────────────────────────────────────────────────────────

// Translation of Stargazed.tsx

// Remotion structure:

// <Composition schema={zod} defaultProps={...} fps=30 dur=300>

// <Sequence 0..90> <TitleScene title subtitle />

// <Sequence 90..210> <StatsScene stats />

// <Sequence 210..300><OutroScene text />

// HF structure:

// - root #stage carries data-* with the same props (title, subtitle, outro)

// - 3 scene divs with data-start/data-duration in seconds (frames/fps)

// - Custom React subcomponents inline as repeated HTML; their per-instance

// props become data-* attributes on the markup

// - Animation lives in a single paused GSAP timeline keyed by composition seconds

// Frame → time:

// Sequence(0,90) → 0s..3s (title)

// Sequence(90,210) → 3s..7s (stats; 4s window)

// Sequence(210,300) → 7s..10s (outro)

// Stagger(i*12) → i*0.4s (12 frames at 30fps)

const tl = gsap.timeline({ paused: true });

// ─── Scene 1: Title ─────────────────────────────────────────────────

const scene1 = document.querySelector("#scene-1");

const title = scene1.querySelector(".title");

const subtitle = scene1.querySelector(".subtitle");

tl.set(scene1, { opacity: 1 }, 0);

// spring({damping:12, stiffness:100, mass:1}) → back.out(1.4) ~0.7s

tl.to(title, { scale: 1, duration: 0.7, ease: "back.out(1.4)" }, 0);

// interpolate(frame, [20,40], [0,1]) at fps=30 → 0.667s..1.333s linear

tl.fromTo(subtitle, { opacity: 0 }, { opacity: 1, duration: 0.667, ease: "none" }, 0.667);

tl.set(scene1, { opacity: 0 }, 3);

// ─── Scene 2: Stats ─────────────────────────────────────────────────

const scene2 = document.querySelector("#scene-2");

const cards = scene2.querySelectorAll(".stat-card");

tl.set(scene2, { opacity: 1 }, 3);

cards.forEach((card, i) => {

const stagger = i * 0.4; // i * 12 frames at 30 fps

const start = 3 + stagger;

const value = Number(card.dataset.statValue);

const numberEl = card.querySelector(".number");

// StatCard entrance:

// spring({damping:14, stiffness:90, mass:1}) → back.out(1.2) ~0.7s

// interpolate(local, [0,12], [0,1]) → 0s..0.4s linear opacity

tl.to(card, { scale: 1, duration: 0.7, ease: "back.out(1.2)" }, start);

tl.to(card, { opacity: 1, duration: 0.4, ease: "none" }, start);

// AnimatedNumber: count from 0 → value with easeOutCubic over 45 frames (1.5s).

// GSAP equivalent: a tween on a counter object with onUpdate rewriting textContent.

// power3.out is GSAP's name for cubic easeOut.

const counter = { v: 0 };

tl.to(

counter,

{

v: value,

duration: 1.5,

ease: "power3.out",

onUpdate: () => {

numberEl.textContent = Math.round(counter.v).toLocaleString();

start,

);

});

tl.set(scene2, { opacity: 0 }, 7);

// ─── Scene 3: Outro ─────────────────────────────────────────────────

const scene3 = document.querySelector("#scene-3");

const outroWrap = scene3.querySelector(".outro-wrap");

const underline = scene3.querySelector(".outro-underline");

tl.set(scene3, { opacity: 1 }, 7);

// interpolate(frame, [0,12], [0,1]) → 0s..0.4s linear opacity

tl.to(outroWrap, { opacity: 1, duration: 0.4, ease: "none" }, 7);

// interpolate(frame, [10,40], [0,1]) for underline → starts at 7+0.333s, dur 1s

tl.to(underline, { scaleX: 1, duration: 1.0, ease: "none" }, 7.333);

window.__timelines = window.__timelines || {};

window.__timelines["tier-3-data-driven"] = tl;

</script>

</div>

</body>

</html>

mdskills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/README.md

4.9 kB

# Tier 3 — stargazed-data-driven

## What it tests

A purpose-built data-driven fixture that exercises the realistic shape of a

production Remotion composition without using the runtime adapter from

PR #214. If a translation passes T3, the skill correctly handles:

- A `<Composition>` with a `z.object` schema and typed `defaultProps`

- Custom React subcomponents reused with different props across scenes

- A nested data structure (`stats[]`) materialized as repeated HTML with

per-instance attributes

- A frame-driven count-up animation (`AnimatedNumber` → GSAP `onUpdate`)

- Two different `spring` configs translated to two different `back.out` overshoots

- Per-instance delays via component props (`delayInFrames` → GSAP timeline offsets)

## Composition shape

```

Stargazed (10 s @ 30 fps, 1280×720)

├── Sequence 0–3 s TitleScene

│ ├── title ← spring scale

│ └── subtitle ← linear fade

├── Sequence 3–7 s StatsScene

│ ├── StatCard "Stars" 1247 #fbbf24 (delay 0 frames)

│ ├── StatCard "Forks" 312 #60a5fa (delay 12 frames)

│ └── StatCard "Issues" 48 #f87171 (delay 24 frames)

└── Sequence 7–10 s OutroScene

└── UnderlinedText "thanks for watching" ← scale-in underline

```

Each `StatCard` is a custom subcomponent that internally uses `AnimatedNumber`

to count from 0 to the target. `AnimatedNumber` itself derives the displayed

value from `useCurrentFrame()` + a manual `1 - (1 - t)^3` ease.

## The lossy parts (and why threshold = 0.90)

1. **`spring → back.out(N)`**: two different spring configs in this composition.

- `{ damping: 12, stiffness: 100, mass: 1 }` (title) → `back.out(1.4)`

- `{ damping: 14, stiffness: 90, mass: 1 }` (stat card) → `back.out(1.2)`

Overshoot ratio (1.4 vs 1.2) approximates the damping difference. The

late-tail curve of GSAP's back ease and Remotion's spring don't match

exactly — costs ~0.03 mean SSIM per spring instance.

2. **Count-up easing**: `AnimatedNumber` uses `1 - (1 - t)^3` (cubic ease-out)

manually computed in the component. GSAP's `power3.out` is the same curve

shape — should match closely. The displayed integer is rounded each frame

in both renderers; minor mismatches occur when the rounded value flips

between two numbers on a sub-frame timing difference.

3. **Font rendering**: same caveat as T1/T2. System Helvetica/Arial fallback

produces minor anti-aliasing differences between renderers. Affects the

stat card numbers (large weight 800) most.

A mean SSIM below 0.90 in T3 indicates a _structural_ mismatch (wrong scene

durations, wrong stagger timing, missing prop wiring), not approximation

drift. That's the failure signal we care about. The calibrated mean against

Remotion @ 4.0 with PNG/BT.709 output is 0.953.

## Translation walk-through (skill cheat sheet)

| Remotion | HyperFrames |

| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |

| `<Composition schema={z.object({...})} defaultProps={...} />` | data-\* attributes on root `#stage` div |

| nested array prop (`stats[]`) | repeated HTML markup with per-instance `data-*` attrs |

| custom React subcomponent | inline repeated HTML using the component's prop interface as the template |

| `<AnimatedNumber from={0} to={value} dur={45} />` (cubic ease-out count-up) | tween on `{ v: 0 }` object with `onUpdate` rewriting `textContent`, ease `power3.out` |

| `spring({damping:12, stiffness:100})` | `back.out(1.4)` over ~0.7 s |

| `spring({damping:14, stiffness:90})` | `back.out(1.2)` over ~0.7 s |

| `delayInFrames={i * 12}` (per-instance) | GSAP timeline offset `(i * 0.4)` s |

| `useVideoConfig()` to get `fps` | dropped — composition fps is in `data-fps` on `#stage` |

## How to render and evaluate

```bash

# Render Remotion baseline (no setup.sh — no binary assets in this fixture)

cd remotion-src && npm install && npm run render

# Render HyperFrames translation

cd ../hf-src && npx hyperframes render --output ../hf.mp4

# Compare

../../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

```

jsonskills/remotion-to-hyperframes/assets/test-corpus/tier-4-escape-hatch/expected.json

2.7 kB

{

"tier": 4,

"name": "escape-hatch",

"description": "Lint-only fixture set. Each case demonstrates a Remotion pattern the skill cannot or should not translate cleanly. The skill is graded on whether lint_source.py emits the right finding for each case — there are no renders to compare. T4 passes when every case triggers its expected rule and no others.",

"cases": [

{

"file": "01-use-state.tsx",

"expected": {

"blockers": [

{

"rule": "r2hf/use-state",

"min_count": 1

}

"warnings": [],

"skill_action": "refuse_translation_recommend_interop"

}

{

"file": "02-use-effect-deps.tsx",

"expected": {

"blockers": [

{

"rule": "r2hf/use-effect-deps",

"min_count": 1

}

"warnings": [],

"skill_action": "refuse_translation_recommend_interop"

}

{

"file": "03-async-metadata.tsx",

"expected": {

"blockers": [

{

"rule": "r2hf/async-metadata",

"min_count": 1

}

"warnings": [],

"skill_action": "refuse_translation_recommend_interop"

}

{

"file": "04-third-party-react.tsx",

"expected": {

"blockers": [

{

"rule": "r2hf/third-party-react-ui",

"min_count": 1

}

"warnings": [],

"skill_action": "refuse_translation_recommend_interop"

}

{

"file": "05-lambda-config.tsx",

"expected": {

"blockers": [],

"warnings": [

{

"rule": "r2hf/lambda-import",

"min_count": 1

}

"skill_action": "drop_lambda_code_translate_remainder_if_clean"

}

{

"file": "06-warnings-only.tsx",

"expected": {

"blockers": [],

"warnings": [

{

"rule": "r2hf/delay-render",

"min_count": 1

{

"rule": "r2hf/use-callback",

"min_count": 1

{

"rule": "r2hf/use-memo",

"min_count": 1

}

"skill_action": "translate_after_dropping_wrappers"

}

{

"file": "07-custom-hook.tsx",

"expected": {

"blockers": [],

"warnings": [

{

"rule": "r2hf/custom-hook",

"min_count": 1

}

"skill_action": "inline_hook_body_if_pure"

}

{

"file": "08-mixed.tsx",

"expected": {

"blockers": [

{

"rule": "r2hf/use-state",

"min_count": 1

{

"rule": "r2hf/use-effect-deps",

"min_count": 1

{

"rule": "r2hf/third-party-react-ui",

"min_count": 1

}

"warnings": [

{

"rule": "r2hf/use-callback",

"min_count": 1

}

"skill_action": "refuse_translation_recommend_interop"

}

"totals": {

"expected_blocker_cases": 5,

"expected_warning_only_cases": 3,

"expected_total_blocker_findings_min": 7,

"expected_total_warning_findings_min": 6

}

mdskills/remotion-to-hyperframes/assets/test-corpus/tier-4-escape-hatch/README.md

2.8 kB

# Tier 4 — escape-hatch

## What it tests

T4 is the **lint-only** tier. There are no renders to diff — the skill is

graded on whether it correctly _refuses_ to translate each case (and

recommends the runtime interop pattern from PR #214 instead) or, where

appropriate, translates after dropping warning-level decorations.

Each `cases/*.tsx` file is a minimal Remotion composition that

demonstrates one specific pattern. The skill should:

1. Run `scripts/lint_source.py` over the source.

2. Compare the JSON output to `expected.json` for that case.

3. Take the documented `skill_action`:

- `refuse_translation_recommend_interop` — print the rationale + link to

the PR #214 interop guide; do not produce HF output.

- `drop_lambda_code_translate_remainder_if_clean` — drop the

`@remotion/lambda` code with a note; translate the rest only if no

other blockers are present.

- `translate_after_dropping_wrappers` — translate normally; drop

`useCallback` / `useMemo` / `delayRender` wrappers.

- `inline_hook_body_if_pure` — inline the custom hook's body if it's a

pure derivation of `useCurrentFrame`; otherwise bow out.

## Cases

| --- | -------------------------- | ----------------------------------- | ----------------------------------------------- |

## Validation

```bash

./validate.sh

```

The script runs `lint_source.py` against each case and asserts:

- Each expected blocker rule fires with severity `blocker`.

- Each expected warning rule fires with severity `warning` (or stronger).

- `lint_source.py`'s exit code is 1 when blockers are expected, 0 otherwise.

T4 passes when every case matches its expected output. No renders involved.

shskills/remotion-to-hyperframes/assets/test-corpus/tier-4-escape-hatch/validate.sh

3.5 kB

#!/usr/bin/env bash

# validate.sh — assert lint_source.py output matches expected.json for every T4 case.

# T4 has no renders to diff. The skill is graded on whether it correctly

# refuses to translate each case (or drops only the lambda config in case 5,

# or warns appropriately in cases 6 and 7).

# Usage:

# ./validate.sh

# Exit 0 on pass.

set -euo pipefail

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

SCRIPTS_DIR="$(cd "$THIS_DIR/../../../scripts" && pwd)"

EXPECTED="$THIS_DIR/expected.json"

if [[ ! -f "$SCRIPTS_DIR/lint_source.py" ]]; then

echo "error: lint_source.py not found at $SCRIPTS_DIR/lint_source.py" >&2

exit 2

if [[ ! -f "$EXPECTED" ]]; then

echo "error: expected.json not found at $EXPECTED" >&2

exit 2

# Drive lint_file() in-process so the per-case overhead is one Python startup,

# not N (8 cases × ~80 ms forking python3 was the dominant cost).

SCRIPTS_DIR="$SCRIPTS_DIR" \

THIS_DIR="$THIS_DIR" \

EXPECTED="$EXPECTED" \

python3 <<'PY'

import json

import os

import sys

from collections import Counter

from pathlib import Path

scripts_dir = Path(os.environ["SCRIPTS_DIR"])

this_dir = Path(os.environ["THIS_DIR"])

expected_path = Path(os.environ["EXPECTED"])

cases_dir = this_dir / "cases"

sys.path.insert(0, str(scripts_dir))

from lint_source import BLOCKER, WARNING, lint_file # noqa: E402

expected = json.loads(expected_path.read_text())

fails: list[str] = []

passes: list[str] = []

for case in expected["cases"]:

file_name = case["file"]

fixture = cases_dir / file_name

if not fixture.exists():

fails.append(f"{file_name}: fixture missing at {fixture}")

continue

findings = lint_file(fixture)

rule_counts: Counter[str] = Counter()

severity_by_rule: dict[str, str] = {}

for f in findings:

rule_counts[f.rule] += 1

severity_by_rule[f.rule] = f.severity

case_failed = False

def assert_rule(expected_entry, expected_severity_floor, kind):

global case_failed

rule = expected_entry["rule"]

min_count = expected_entry["min_count"]

actual = rule_counts[rule]

actual_severity = severity_by_rule.get(rule)

if actual < min_count:

fails.append(f"{file_name}: expected >={min_count} {kind} findings of rule {rule}, got {actual}")

case_failed = True

elif actual_severity not in expected_severity_floor:

fails.append(

f"{file_name}: rule {rule} found but severity={actual_severity!r} (expected {kind})"

)

case_failed = True

for entry in case["expected"]["blockers"]:

assert_rule(entry, {BLOCKER}, "blocker")

for entry in case["expected"]["warnings"]:

assert_rule(entry, {WARNING, BLOCKER}, "warning")

# Implied lint exit code: 1 when blockers are expected, 0 otherwise.

has_blockers = any(f.severity == BLOCKER for f in findings)

expected_has_blockers = bool(case["expected"]["blockers"])

if has_blockers != expected_has_blockers:

fails.append(

f"{file_name}: implied lint exit {1 if has_blockers else 0}, "

f"expected {1 if expected_has_blockers else 0} (blockers expected: {expected_has_blockers})"

)

case_failed = True

if not case_failed:

passes.append(file_name)

print(f"Passed: {len(passes)}")

for name in passes:

print(f" ✓ {name}")

if fails:

print(f"Failed: {len(fails)}")

for msg in fails:

print(f" ✗ {msg}")

sys.exit(1)

sys.exit(0)

mdskills/remotion-to-hyperframes/references/api-map.md

12 kB

# Remotion → HyperFrames API Map

Authoritative translation table. Load this reference when starting a translation

to know the high-level mapping; load the per-topic references for fragile

details (timing, transitions, etc.).

## Reading this table

- **`drop`** = remove from output entirely. The HF runtime handles it.

- **`see references/X.md`** = the mapping is non-trivial; read the linked file.

- **`refuse + interop`** = the skill bows out and recommends the runtime adapter

pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214).

## Composition root

| Remotion | HyperFrames |

| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |

| `<Composition id durationInFrames fps width height>` | root `<div id="stage" data-composition-id data-start="0" data-duration="<dur/fps>" data-fps data-width data-height>` |

| `defaultProps={...}` | `data-*` attributes on `#stage` (one per scalar prop). Nested objects/arrays — see [parameters.md](parameters.md) |

| `schema={z.object(...)}` | not represented in HTML; the schema lives in the agent's translation step only |

| `calculateMetadata` (sync) | resolve at translation time, write concrete values into `data-*` |

| `calculateMetadata` (async) | **refuse + interop** — see [escape-hatch.md](escape-hatch.md) |

| `registerRoot(RemotionRoot)` | drop |

| `<AbsoluteFill style>` | `<div style="position:absolute;inset:0;{style}">` |

## Sequencing

See [sequencing.md](sequencing.md) for nesting and stagger details.

| Remotion | HyperFrames |

| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |

| `<Sequence from={F} durationInFrames={D}>` | `<div data-start="<F/fps>" data-duration="<D/fps>" data-track-index="N">` |

| `<Series>` + `<Series.Sequence>` | siblings with sequential `data-start` values |

| `<Loop durationInFrames={D}>` | not a primitive — emit a custom GSAP `repeat: -1` loop with manual offset math |

| `<Freeze frame={F}>` | drop the wrapper; HF doesn't have running animation outside the seek-driven timeline so freeze is a no-op |

## Timing

See [timing.md](timing.md) — this is the highest-leverage section.

| Remotion | HyperFrames |

| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |

| `useCurrentFrame()` | drop — HF seeks the timeline. The math derived from `frame` becomes an animatable property of a paused GSAP tween. |

| `useVideoConfig()` for `fps` / `durationInFrames` | drop — read from `data-fps` / `data-duration` on `#stage` |

| `interpolate(frame, [a,b], [x,y])` (linear) | `gsap.fromTo(t, {p:x}, {p:y, duration:(b-a)/fps, ease:"none"})` at offset `a/fps` |

| `interpolate(frame, [a,b,c,d], [x,y,y,z])` (multi-segment) | three `gsap.to` calls at offsets `a/fps`, `b/fps`, `c/fps` |

| `interpolate(..., {easing: Easing.bezier})` | GSAP `CustomEase.create("c", "M0,0 C${a},${b} ${c},${d} 1,1")` |

| `spring({frame, fps, config: {damping, stiffness, mass}})` | GSAP `back.out(N)` — see [timing.md](timing.md) for damping → overshoot table |

| `interpolateColors(frame, range, colors)` | `gsap.to({...}, { backgroundColor, color, duration, ease })` — GSAP handles color tweens natively |

| `Easing.in / .out / .inOut(power)` | GSAP `power<N>.in` / `power<N>.out` / `power<N>.inOut` |

## Media

See [media.md](media.md) for trim, volume ramps, and decoder notes.

| Remotion | HyperFrames |

| -------------------------------------- | --------------------------------------------------------------------------- |

| `<Audio src volume>` | `<audio data-start data-duration data-track-index data-volume src>` |

| `<Audio playbackRate startFrom endAt>` | `data-playback-rate`, `data-trim-start`, `data-trim-end` |

| `<Video src>` | `<video muted playsinline data-start data-duration data-track-index src>` |

| `<OffthreadVideo>` | `<video>` — HF doesn't need the off-thread variant (uses headless Chrome) |

| `<Img src>` | `<img>` |

| `<IFrame src>` | `<iframe>` — HF auto-falls back to screenshot mode for nested iframes |

| `staticFile("x.png")` | `"assets/x.png"` — copy the file into `hf-src/assets/` next to `index.html` |

| `delayRender()` / `continueRender()` | drop — HF waits on asset readiness via the Frame Adapter pattern |

## Transitions

See [transitions.md](transitions.md).

| Remotion | HyperFrames |

| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |

| `<TransitionSeries>` + `<TransitionSeries.Transition presentation={fade()} />` | manual `gsap.to(scene, {opacity: 0/1, duration})` crossfade at the boundary |

| `slide()`, `wipe()`, `clockWipe()`, `fade()` | HF [shader-transitions](https://hyperframes.heygen.com/catalog/blocks) package presets — pick the closest |

| `linearTiming({durationInFrames})` | duration in seconds (`/fps`) |

| `springTiming({config})` | duration in seconds, ease `back.out` — see [timing.md](timing.md) |

## Lottie

See [lottie.md](lottie.md).

| Remotion | HyperFrames |

| ------------------------------- | --------------------------------------------------------------------------------------------------------- |

| `<Lottie animationData={data}>` | `<div id="lottie-N">` + `<script>lottie.loadAnimation(...).then(a => window.__hfLottie.push(a))</script>` |

| `loop` / `playbackRate` props | translate to `loop` / lottie playback options; HF adapter seeks via `goToAndStop` |

| `@remotion/lottie` runtime | `lottie-web` from CDN — drop the React wrapper |

## Fonts

See [fonts.md](fonts.md).

| Remotion | HyperFrames |

| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |

| `loadFont()` from `@remotion/google-fonts/<Family>` | `@font-face` rule referencing the Google Fonts CSS, OR `<link>` to Google Fonts in `<head>` |

| Local font via `@font-face` | same — paste the rule into `<style>` |

| System font fallback | document the font-fallback divergence cost (see [eval.md](eval.md)) |

## Parameters

See [parameters.md](parameters.md).

| Remotion | HyperFrames |

| ----------------------------- | --------------------------------------------------------------------------------------------- |

| `z.object({foo: z.string()})` | `data-foo` on `#stage` (the schema is implicit in HTML structure) |

| nested array prop (`stats[]`) | repeated HTML markup with per-instance `data-*` attrs |

| Zod default values | bake defaults into the HTML directly |

| Zod runtime validation | not represented; if validation matters, validate in the translation step before emitting HTML |

## React patterns

| Remotion | HyperFrames |

| -------------------------------------------------- | ---------------------------------------------------------------- |

| Custom React subcomponent (pure, prop-driven) | inline as repeated HTML using the prop interface as the template |

| `useState` driving animation | **refuse + interop** |

| `useReducer` driving animation | **refuse + interop** |

| `useEffect(fn, [deps])` (non-empty deps) | **refuse + interop** |

| `useEffect(fn, [])` (mount-once side effect) | drop the effect; use `queueMicrotask` if startup work is needed |

| `useCallback`, `useMemo` | drop the wrappers — decorative |

| Custom hook (pure derivation of `useCurrentFrame`) | inline the body |

| Custom hook with state/effects | refuse + interop |

## Distributed rendering

`@remotion/lambda` and `@remotion/cloudrun` are deployment configuration —

orthogonal to the rendered composition itself. The skill emits these as

**warnings** (not blockers) and drops them in step 3 (Generate) with a note

in `TRANSLATION_NOTES.md`. HF is single-machine today; document the gap.

| Remotion | HyperFrames |

| -------------------------- | ------------------------------------------------------ |

| `@remotion/lambda` import | drop the import (warning `r2hf/lambda-import`) |

| `renderMediaOnLambda(...)` | drop the call; note in `TRANSLATION_NOTES.md` |

| `@remotion/cloudrun` | drop the import + call; note in `TRANSLATION_NOTES.md` |

## When to bow out entirely

If any blocker pattern is present, recommend the runtime interop pattern from

[PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead of

attempting translation. See [escape-hatch.md](escape-hatch.md).

The blockers are documented in [`scripts/lint_source.py`](../scripts/lint_source.py)

and tested by [tier-4-escape-hatch](../assets/test-corpus/tier-4-escape-hatch/).

mdskills/remotion-to-hyperframes/references/escape-hatch.md

5.3 kB

# When to bow out: the runtime interop pattern

Some Remotion compositions can't be translated cleanly. The skill should

recognize them upfront and recommend the **runtime interop pattern** from

[PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead of

producing broken HTML.

## When to recommend interop

Run `scripts/lint_source.py` first. If it returns any blocker, recommend

interop. The blockers are:

| Rule | What it catches |

| --------------------------- | -------------------------------------------------------------- |

| `r2hf/use-state` | useState driving animation |

| `r2hf/use-reducer` | useReducer driving animation |

| `r2hf/use-effect-deps` | useEffect/useLayoutEffect with non-empty deps (side effects) |

| `r2hf/async-metadata` | calculateMetadata returns a Promise |

| `r2hf/third-party-react-ui` | Imports from MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI |

Each of these breaks the seek-driven, deterministic-frame model that HF

relies on. Translating them produces silently-wrong output.

## What the interop pattern actually does

Per [PR #214](https://github.com/heygen-com/hyperframes/pull/214), the

runtime adapter:

1. Bundles the user's Remotion code with React + `@remotion/player` via esbuild.

2. Mounts a Remotion `<Player>` inside an HF composition's HTML.

3. Pauses the player on mount.

4. Registers the player on `window.__hfRemotion` with `seekTo(frame)`,

`pause()`, `durationInFrames`, `fps`.

5. HF's render loop seeks the player frame-by-frame via `seekTo(frame)`.

Result: Remotion's React tree renders at HF's deterministic frame ticks.

Custom hooks, useState, useEffect, MUI components — all work because

Remotion's React reconciler is doing the rendering.

## The recommendation message

When the skill detects a blocker, output something like:

> The Remotion source uses `useState` (and others), which can't be

> translated to HF's seek-driven HTML model. The recommended path is the

> **runtime interop pattern**: bundle your Remotion code with `@remotion/player`

> and let HF drive it frame-by-frame.

> See https://github.com/heygen-com/hyperframes/pull/214 for the full

> implementation. Quick summary:

> 1. Bundle `entry.tsx` with esbuild: `npx esbuild entry.tsx --bundle --outfile=dist/bundle.js --format=iife --jsx=automatic`

> 2. Mount the Player and register on `window.__hfRemotion`:

> ```tsx

> const playerRef = useRef<PlayerRef>(null);

> useEffect(() => {

> playerRef.current?.pause();

> window.__hfRemotion = window.__hfRemotion || [];

> window.__hfRemotion.push({

> seekTo: (f) => playerRef.current?.seekTo(f),

> pause: () => playerRef.current?.pause(),

> durationInFrames,

> fps,

> });

> }, []);

> ```

> 3. Reference the bundle from your HF `index.html` and render normally:

> `<script src="dist/bundle.js"></script>`

## The lint output already includes recommendations

`lint_source.py` emits a `recommendation` field per finding. Surface those

verbatim — they're tuned per blocker rule:

```json

{

"rule": "r2hf/use-state",

"message": "useState detected — Remotion compositions that drive animation via React state are not deterministic frame-capture targets in HyperFrames",

"recommendation": "Use the runtime interop pattern from PR #214 instead of attempting a translation"

}

```

## When NOT to bow out: warnings only

Some patterns produce warnings, not blockers — translate after dropping

the wrappers:

| Rule | Action |

| ------------------------- | ------------------------------------------------------------------- |

| `r2hf/lambda-import` | drop the `@remotion/lambda` config; HF runs single-machine, log gap |

| `r2hf/delay-render` | drop the call; HF handles asset readiness |

| `r2hf/use-callback` | drop the wrapper, inline the function |

| `r2hf/use-memo` | drop the wrapper, compute inline |

| `r2hf/custom-hook` (pure) | inline the hook body if it's a derivation of `useCurrentFrame` |

| `r2hf/static-file` | replace `staticFile("x")` with `"assets/x"` |

| `r2hf/interpolate-colors` | translate to GSAP color tween (see [timing.md](timing.md)) |

These are documented in T4 cases 05–07.

`r2hf/lambda-import` is a warning — not a blocker — because Lambda

configuration is orthogonal to the rendered composition. Translating an

otherwise-clean Remotion comp shouldn't fail just because the author also

configured AWS Lambda for distributed rendering. The skill drops the

`@remotion/lambda` imports and `renderMediaOnLambda(...)` calls in step 3

(Generate) and writes a `TRANSLATION_NOTES.md` entry so the user knows to

set up HF rendering separately.

## When the source has BOTH blockers AND warnings

Bow out. The presence of a single blocker means the skill shouldn't

attempt translation — even if the rest of the composition is clean.

The user should use interop for the whole thing OR refactor the

blocker patterns out of their Remotion source first.

mdskills/remotion-to-hyperframes/references/eval.md

5.5 kB

# Eval: how to validate a translation end-to-end

Every translation should be measured. The skill ships three scripts and

a tiered test corpus that, together, gate translation quality.

## The three scripts

| Script | Input | Output |

| ------------------------ | --------------------------- | ------------------------------------------------------------------- |

| `scripts/lint_source.py` | Remotion source dir or file | JSON findings + exit code (0 clean, 1 has blockers) |

| `scripts/render_diff.sh` | two MP4 paths | per-frame SSIM + JSON summary (`mean`, `min`, `p05`, `p95`, `pass`) |

| `scripts/frame_strip.sh` | two MP4 paths | side-by-side comparison strip PNG for visual debugging |

Run them in this order: **lint → render → diff → (if fail) strip**.

## Per-fixture flow

```bash

# 1. Lint the source — blockers mean stop

python3 ../../scripts/lint_source.py ./remotion-src/src/

# 2. Generate any binary assets (T2+T3 only)

[ -f setup.sh ] && ./setup.sh

# 3. Render Remotion baseline

cd remotion-src && npm install && npm run render

# -> remotion-src/out/baseline.mp4

# 4. Render HF translation

cd .. && node ../../../packages/cli/dist/cli.js render hf-src/ --output hf.mp4

# -> hf.mp4

# 5. SSIM diff

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

# -> diff/summary.json

# 6. If diff fails, generate frame strip for visual inspection

../../scripts/frame_strip.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./strip 8

# -> strip/strip.png

```

## Reading `diff/summary.json`

```json

{

"frame_count": 90,

"mean": 0.974,

"min": 0.972,

"max": 0.999,

"p05": 0.972,

"p95": 0.983,

"threshold": 0.95,

"pass": true

}

```

| Field | What it tells you |

| ------------- | --------------------------------------------------------------------------- |

| `mean` | average SSIM across all frames; the headline number |

| `min` | worst frame; below threshold means at least one frame is structurally wrong |

| `p05` / `p95` | 5th / 95th percentile — most frames sit between these |

| `threshold` | from `R2HF_SSIM_THRESHOLD` env var (default 0.85) |

| `pass` | whether `mean >= threshold` |

## Validated tier thresholds

Calibrated against actual Remotion + HF renders:

| ---- | ------------------------------------------- | ----- | --------- | ------ |

| T1 | single-element fade-in | 0.974 | 0.95 | +0.022 |

| T2 | multi-scene + spring + audio + image | 0.985 | 0.95 | +0.016 |

| T3 | data-driven, custom subcomponents, count-up | 0.953 | 0.90 | +0.038 |

Each fixture's `expected.json` carries:

- `ssim_threshold` — the gate for `pass`

- `validation` — the actual measured numbers from the calibration run

- `translation_notes` — what's lossy and why

## Critical: encoder config

Both Remotion and HF must output the same pixel format for SSIM to be

meaningful. Remotion's default JPEG output writes `yuvj420p` (full-range);

HF outputs `yuv420p` (limited-range). The mismatch costs ~0.05 SSIM.

Every fixture's `remotion.config.ts` sets:

```ts

Config.setVideoImageFormat("png");

Config.setColorSpace("bt709");

```

If the user's source doesn't have these, add them in the translation

step — otherwise the diff measures encoder differences, not translation

fidelity.

## What the noise floor looks like

The dominant non-translation noise is **system font fallback divergence**.

Remotion's bundled Chromium and HF's `chrome-headless-shell` interpret

`font-weight: 800` differently when there's no real font installed:

- Remotion HELLO at 160px: medium-weight stroke

- HF HELLO at 160px: heavy-weight stroke

This costs ~0.025 mean SSIM. Visible in T1's frame strip.

[fonts.md](fonts.md) covers how to mitigate (use Inter, load explicit

Google Fonts).

## Threshold rule of thumb

Set the threshold ~0.02 below measured `p05`:

- Real translation regressions drop mean by 0.05+ — caught.

- Encoder/font drift between CI runs is bounded at ~0.01 — not caught.

If a calibration run's measured mean is far above your initial threshold

guess, _don't_ tighten the threshold to fit. Leave headroom — fixtures

re-rendered on different hardware will drift.

## When the diff fails

1. **Look at `frame_strip.sh` output first.** A side-by-side strip at 6–10

evenly-spaced timestamps shows whether the failure is structural

(wrong scene durations, missing element) or cosmetic (different font

weight, slight timing skew).

2. **Check `diff/ssim.log`.** Per-frame SSIM tells you _which_ frames

failed. Cluster of bad frames in the middle of a scene = animation

problem; bad frames at scene boundaries = sequencing problem.

3. **Re-read the relevant reference.** [timing.md](timing.md) for

spring/easing issues, [sequencing.md](sequencing.md) for scene

boundary issues, [media.md](media.md) for asset loading issues.

## CI integration

The fixtures are not yet wired into CI (`packages/producer/tests/` runs

inside Docker; the skill corpus needs the same). PR 7 of the stack adds

the orchestrator that runs all four tiers and emits an aggregated pass

report. For now, evaluate by hand per fixture.

mdskills/remotion-to-hyperframes/references/fonts.md

3.2 kB

# Font translation

Fonts are the dominant non-translation noise floor. Same `font-weight: 800`

renders perceptibly bolder on HF's `chrome-headless-shell` than on

Remotion's bundled Chromium when there's no real font installed. Validation

showed this costs ~0.025 mean SSIM at the noise floor.

## Pattern: `@remotion/google-fonts/<Family>`

```tsx

import { loadFont } from "@remotion/google-fonts/Inter";

loadFont("normal", { weights: ["400", "800"] });

```

Translate to a `<link>` tag in `<head>`:

```html

<head>

<link

href="https://fonts.googleapis.com/css2?family=Inter:wght@400;800&display=swap"

rel="stylesheet"

<style>

body {

font-family: Inter, sans-serif;

}

</style>

</head>

```

Pull the family name and weights from the import path and `loadFont`

arguments. HF's compiler inlines the Google Fonts CSS at render time, so

you don't pay a network round-trip per render.

## Pattern: local fonts via `@font-face`

```tsx

import { Font } from "remotion";

Font.loadFont("/MyFont.woff2", "MyFont");

```

Translate to a `@font-face` rule:

```html

<style>

@font-face {

font-family: "MyFont";

src: url("assets/MyFont.woff2") format("woff2");

font-weight: 400;

font-style: normal;

}

</style>

```

Copy the font file into `hf-src/assets/` next to the HTML.

## Pattern: system font fallback (no font load)

```tsx

```

Same string in HF — but be aware: on Linux without a real Helvetica

installed (typical CI environment), Remotion and HF fall back to

_different_ sans-serif system fonts because they bundle different

Chromium versions. This is the noise floor: ~0.025 mean SSIM cost,

visible as different stroke widths at large font weights (800+).

If matching the Remotion render exactly matters for a specific

fixture, load the same font explicitly — don't rely on system

fallback.

## When in doubt: use Inter

Inter renders identically across Chromium versions and is free.

Translate any "system sans-serif" Remotion comp to Inter when you

need to minimize font drift in the validation harness.

## Font loading and `delayRender`

Remotion uses `delayRender()` to defer the first frame until fonts

load. HF's compiler inlines Google Fonts at compile time and waits

on `@font-face` readiness via the Frame Adapter pattern — the

`delayRender` call drops in translation. See [media.md](media.md).

## Multi-weight loading

When Remotion loads multiple weights:

```tsx

loadFont("normal", { weights: ["400", "500", "700", "800"] });

```

Inline all weights in the Google Fonts URL:

```

?family=Inter:wght@400;500;700;800&display=swap

```

Translation rule: enumerate every distinct `font-weight` value

that appears in the composition's CSS (`font-weight: 800` →

weight 800 must be loaded). If the Remotion source loads weights

that aren't actually used, drop them.

## Font subsetting

Remotion's `loadFont` doesn't subset; HF's compiler doesn't either

(yet). Don't try to optimize this in translation — it's lossless to

keep the same weight set as the Remotion source.

mdskills/remotion-to-hyperframes/references/limitations.md

4.7 kB

# Translation limitations

What the skill explicitly cannot translate, separated from the

blocker-list (which is enforced by `lint_source.py`). These are

_known_ gaps — surface them to the user as translation notes

when translating the surrounding composition.

## React patterns the skill refuses

See [escape-hatch.md](escape-hatch.md). Any of these triggers

a bow-out:

- `useState`, `useReducer` driving animation

- `useEffect` / `useLayoutEffect` with non-empty deps (side effects)

- async `calculateMetadata`

- Third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI)

`@remotion/lambda` is no longer in this list — it's a warning, not a

blocker, because Lambda config is orthogonal to composition rendering.

The skill drops the imports and `renderMediaOnLambda(...)` calls and

writes a `TRANSLATION_NOTES.md` entry. See

[escape-hatch.md](escape-hatch.md).

## Patterns that work with caveats

### Volume ramps on `<Audio>`

Remotion accepts a function for `volume`:

```tsx

<Audio src={...} volume={(f) => interpolate(f, [0, 30], [0, 1])} />

```

HF supports static `data-volume` only. Translation: bake the ramp into

the audio file at translation time using `ffmpeg afade`, OR drop the

ramp with a note. The dropped-ramp path produces audibly different

output but visually-identical video, so SSIM passes — just flag it.

### `<Loop>` with stateful children

```tsx

</Loop>

```

Loop with `repeat: -1` works for _visual_ repetition. If the looped

child has cross-iteration state (a counter, a randomness seed), HF

won't reproduce it identically per iteration. Bow out unless the

child is fully deterministic per-iteration.

### Remotion's `<Img>` with crossOrigin

```tsx

```

HF's renderer doesn't enforce CORS the same way Remotion does. Most

public images work; private images served with auth headers won't.

If the source uses `crossOrigin="use-credentials"`, the asset needs

to be downloaded and inlined at translation time.

### Custom `presentation` in `<TransitionSeries>`

```tsx

const customPresentation: PresentationComponent = ({ children, presentationProgress }) => {

return <div style={{ filter: `blur(${(1 - presentationProgress) * 20}px)` }}>{children}</div>;

};

```

Pure presentations (transform/filter/opacity computed from progress)

translate to GSAP tweens cleanly. Presentations that read

`useCurrentFrame()` internally or have stateful children don't —

bow out.

### Code-split components (`React.lazy`)

```tsx

const HeavyChart = React.lazy(() => import("./HeavyChart"));

```

`React.lazy` is async and doesn't fit the deterministic-render model.

Translate to a regular import; the resulting HF composition will

just include all the code upfront.

## Patterns that always work

- `<AbsoluteFill>` and `<Sequence>` (any nesting)

- `useCurrentFrame()` derivations: `interpolate`, `spring`, `Easing`,

`interpolateColors`, manual math

- `<Audio>`, `<Video>`, `<Img>`, `<IFrame>` with simple props

- `staticFile()` references

- Custom React subcomponents that are pure functions of props

- Custom hooks that are pure derivations of `useCurrentFrame`

- `@remotion/lottie` (translates to HF's Lottie adapter)

- `@remotion/google-fonts/<Family>` (translates to `<link>` or `@font-face`)

- Sync `calculateMetadata` (resolved at translation time)

- `<TransitionSeries>` with built-in presentations (`fade`, `slide`,

`wipe`, `clockWipe`, `flip`, `iris`)

## What the skill never tries to translate

These are out-of-scope by design:

- **HDR rendering** — HF supports HDR but Remotion doesn't, so there's

nothing to translate from.

- **Variable frame rate** — both tools assume constant fps.

- **Multi-composition `<Composition>` lists** — translate one at a

time. The skill prompts the user to choose which composition.

- **Remotion Studio props panel** — visual prop editing in HF Studio

needs different infrastructure; out of scope.

## Reporting gaps to the user

When translation produces _something_ but the something has gaps, write

a `TRANSLATION_NOTES.md` next to the output:

```markdown

# Translation notes

The following Remotion patterns were translated with caveats:

- `<Audio volume={(f) => ...}>` (line 15): volume ramp dropped — added

static `data-volume="0.5"`. To preserve the ramp, run

`ffmpeg -i music.wav -af "afade=t=in:st=0:d=1" music.faded.wav` and

swap the source file.

- `<HeavyChart>` (line 30): translated as inline HTML. The original

React.lazy boundary was dropped — bundle size unchanged because HF

serves a single HTML file.

If any of these caveats matter, consider the runtime interop pattern

instead.

```

This file is also generated by the skill alongside the HF output, not

held in the corpus.

mdskills/remotion-to-hyperframes/references/lottie.md

4.1 kB

# Lottie translation: @remotion/lottie → HF lottie adapter

Lottie animations are a clean translation case — HF has a built-in

[Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)

that supports both `lottie-web` and `@lottiefiles/dotlottie-web`. The

adapter auto-discovers animations registered on `window.__hfLottie`

and seeks them per-frame via `goToAndStop`.

## Pattern

```tsx

import { Lottie } from "@remotion/lottie";

import animationData from "./hello.json";

export const MyComp = () => (

</AbsoluteFill>

);

```

Translates to:

```html

const anim = lottie.loadAnimation({

container: document.getElementById("lottie-anim"),

renderer: "svg",

loop: false,

autoplay: false,

path: "assets/hello.json",

});

window.__hfLottie = window.__hfLottie || [];

window.__hfLottie.push(anim);

</script>

</div>

```

Key differences from a typical Lottie embed:

- `autoplay: false` — HF drives playback by seeking

- `loop: false` typically (unless Remotion's `loop={true}`)

- `window.__hfLottie.push(anim)` is what hooks the animation into HF's

per-frame seek

## Asset handling

Remotion bundles the animation JSON via webpack import. HF needs the JSON

on disk under `assets/` and references it via path:

1. Copy `hello.json` from the Remotion project into `hf-src/assets/`.

2. Reference as `path: "assets/hello.json"` in `loadAnimation`.

For dotlottie (binary) format, swap in `@lottiefiles/dotlottie-web`:

```html

const player = new DotLottie({

canvas: document.getElementById("anim"),

src: "assets/hello.lottie",

autoplay: false,

});

window.__hfLottie = window.__hfLottie || [];

window.__hfLottie.push(player);

</script>

```

The HF adapter handles both player APIs (it duck-types `goToAndStop`

vs `setCurrentRawFrameValue` / `seek`).

## Multiple Lottie animations

Multiple `<Lottie>` instances in one composition work — push each one

onto `window.__hfLottie` and the adapter will seek all of them in sync:

```js

window.__hfLottie.push(anim1);

window.__hfLottie.push(anim2);

window.__hfLottie.push(anim3);

```

## Lottie source isn't actually translation-blocking

Lottie animations encode their own deterministic timeline. They're the

_easiest_ part of a Remotion composition to translate because the

animation logic is already self-contained — neither Remotion nor HF

"animate" them, both just seek them. Translation cost is near-zero.

## After Effects → Lottie limitations

Lottie supports a subset of After Effects features. Expressions, most

Effects (drop shadow, color overlay), all blend modes beyond Normal/Add/

Multiply, luma mattes, and most 3D parameters are not supported. If the

Remotion composition uses a Lottie file that depends on these, the

animation will break in BOTH Remotion and HF — this isn't a translation

problem, it's a Lottie limitation. See

[airbnb/lottie/after-effects.md](https://github.com/airbnb/lottie/blob/master/after-effects.md)

for the full supported feature list.

## Loop behavior

Remotion's `loop={true}` plays the animation continuously. Translate to

the lottie-web `loop: true` setting AND rely on the adapter's natural

seek behavior (it'll seek modulo the animation's duration). For

non-default playback rates, set `playbackRate` in `loadAnimation` and HF

will respect it during seek.

## Performance note

Per the [Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)

docs: lottie-web's `goToAndStop(time, isFrame=false)` takes time in ms;

the adapter passes `time * 1000` for precision. This is more accurate

than passing frame numbers (especially for animations whose internal

fps doesn't match the HF render fps).

mdskills/remotion-to-hyperframes/references/media.md

3.8 kB

# Media translation: Audio, Video, Img, IFrame, staticFile

## Asset paths

Remotion's `staticFile("x.png")` resolves to the project's `public/` directory.

HF uses relative paths from the composition's `index.html`, conventionally

`assets/`:

```tsx

```

```html

```

When translating, copy the asset from `remotion-src/public/x` to

`hf-src/assets/x`. Multiple files can be batched with a setup script;

see T2's `setup.sh` for an example pattern.

## `<Audio>`

```tsx

```

```html

<audio

data-start="0"

data-duration="6"

data-track-index="2"

data-volume="0.5"

src="assets/music.wav"

></audio>

```

`data-start` and `data-duration` are required — the runtime needs them to

schedule the audio. Default to the composition's full duration if Remotion

didn't specify trim.

### Volume ramps

```tsx

<Audio src={staticFile("music.wav")} volume={(f) => interpolate(f, [0, 30], [0, 1])} />

```

HF supports static `data-volume` only for now. Volume ramps need to be

applied to the audio file at translation time (with ffmpeg `afade`) or the

ramp is dropped with a translation note.

### Trim / playbackRate

```tsx

```

```html

<audio

data-start="0"

data-duration="<resolved from trim>"

data-trim-start="2"

data-trim-end="6"

data-playback-rate="1.5"

src="assets/music.wav"

></audio>

```

`startFrom` / `endAt` are frame indexes; convert to seconds.

## `<Video>` and `<OffthreadVideo>`

```tsx

```

```html

<video

muted

playsinline

data-start="0"

data-duration="5"

data-track-index="0"

src="assets/intro.mp4"

></video>

```

`<OffthreadVideo>` is a Remotion-specific optimization for headless

rendering. HF runs in headless Chrome already, so the off-thread variant

collapses to a regular `<video>`.

`muted` and `playsinline` are required for the runtime to autoplay

(browser policy). Always emit them.

## `<Img>`

```tsx

```

```html

```

Width/height get rounded to integer px. If the original style has

animated dimensions, the GSAP tween animates them — see [timing.md](timing.md).

## `<IFrame>`

```tsx

```

```html

```

When HF detects a nested iframe in a composition, it auto-falls back to

**screenshot mode** rather than the deterministic BeginFrame mode. This

costs render performance but produces visibly-correct output. See

[hyperframes-vs-remotion.mdx](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/hyperframes-vs-remotion.mdx)

for details.

## `delayRender()` / `continueRender()`

```tsx

const handle = delayRender();

useEffect(() => {

loadAsset().then(() => continueRender(handle));

}, []);

```

Drop. HF waits on asset readiness via the [Frame Adapter pattern](https://hyperframes.heygen.com/concepts/frame-adapters)

— images, videos, fonts, and Lottie animations all signal load

completion natively. There's nothing to do at the application level.

## When the asset isn't a file

If Remotion's media source is a Buffer, dataURL, or URL.createObjectURL,

the asset doesn't exist on disk and can't be copied via setup.sh. Two

options:

1. Materialize the asset at translation time — write the buffer to a file

in `hf-src/assets/`.

2. Embed as a data URL directly in the HTML (`src="data:image/png;base64,..."`)

for small assets (< 100 KB).

For audio/video Buffers, option 1 is preferred — base64-encoded media

bloats the HTML and slows the renderer.

mdskills/remotion-to-hyperframes/references/parameters.md

4.5 kB

# Parameter translation: Zod schemas, defaultProps, calculateMetadata

How a typed Remotion `<Composition schema={...} defaultProps={...} />`

turns into a parameterized HF composition.

## Sync calculateMetadata (translatable)

```tsx

<Composition

id="MyVideo"

component={MyVideo}

schema={z.object({ title: z.string(), duration: z.number() })}

defaultProps={{ title: "Hello", duration: 90 }}

calculateMetadata={({ props }) => ({

durationInFrames: props.duration,

fps: 30,

})}

```

When `calculateMetadata` is synchronous and only uses `props`, **resolve

it at translation time** — call it with `defaultProps` (or whatever the

caller specifies) and write the concrete result into the HTML:

```html

<div

id="stage"

data-composition-id="MyVideo"

data-start="0"

data-duration="3"

data-fps="30"

data-title="Hello"

></div>

```

The `data-title` attribute carries the value through. Code that originally

read `props.title` reads `document.getElementById("stage").dataset.title`

in HF.

## Async calculateMetadata (NOT translatable)

```tsx

<Composition

calculateMetadata={async ({ props }) => {

const res = await fetch(...);

return { durationInFrames: res.duration };

}}

```

**Refuse + interop**. HF needs composition metadata up-front to seed the

HTML. Resolving network calls at translation time defeats the purpose

of having dynamic metadata. See [escape-hatch.md](escape-hatch.md).

The lint rule `r2hf/async-metadata` catches this. T4 case 03 tests it.

## Default props

```tsx

defaultProps={{

title: "Hello",

subtitle: "World",

}}

```

Translate to `data-*` attributes on the root `#stage` div:

```html

```

Convention: `propName` → `data-prop-name` (kebab-case). Inside the GSAP

script, read via `document.getElementById("stage").dataset.propName`.

## Nested object / array props

```tsx

defaultProps={{

stats: [

{ label: "Stars", value: 1247, color: "#fbbf24" },

{ label: "Forks", value: 312, color: "#60a5fa" },

}}

```

Don't try to encode the array as a JSON `data-` attribute — HF's runtime

doesn't parse those. Materialize the array as **repeated HTML markup**:

```html

<div class="label">Stars</div>

</div>

<div class="label">Forks</div>

</div>

```

The component template (`StatCard.tsx`) becomes the markup template;

each instance gets its scalar props rendered as `data-*` and CSS

custom properties.

Validated in T3 — three StatCards reused with different props,

mean SSIM 0.953.

## Numeric props that need typed parsing

`document.getElementById("stage").dataset.count` is a string. Convert at

read time:

```js

const count = Number(stage.dataset.count);

```

Or inline values directly into the GSAP script when the data is known

at translation time and doesn't need to vary per render.

## Boolean props

```tsx

defaultProps={{ darkMode: true }}

```

Two conventions:

- `data-dark-mode="true"` — read as string, compare `=== "true"`

- `data-dark-mode` (presence/absence) — `<div data-dark-mode>` for true, omit for false

Pick one and be consistent. The presence/absence form is HTML-idiomatic

and pairs well with CSS attribute selectors:

```css

[data-dark-mode] .scene {

background: #000;

}

```

## Zod runtime validation

Remotion's `schema` validates props at composition load. HF doesn't have

an equivalent — by the time the HTML is in the renderer, the schema is

already gone.

Validate at translation time instead. If the user passes invalid data,

fail with a translation error before emitting HTML. This matches Zod's

"fail loud" intent without requiring the runtime dependency.

## When the composition uses props for computed prop derivation

```tsx

const Composition: React.FC<Props> = ({ stats }) => {

const total = stats.reduce((acc, s) => acc + s.value, 0);

return <div>{total}</div>;

};

```

Compute the derived value at translation time and bake it into the HTML

or a `data-` attribute. Don't try to express the computation in JS in the

HF composition — that adds runtime overhead and makes the HTML stateful

in ways that complicate human editing.

If the derivation is non-trivial (involves the array itself, not just

scalars), materialize it as static text in the HTML.

mdskills/remotion-to-hyperframes/references/sequencing.md

5.0 kB

# Sequencing translation: Sequence, Series, Composition root

How Remotion's nested `Sequence` tree maps to HF's flat `data-start` /

`data-duration` markup with a single paused GSAP timeline.

## The core idea

Remotion's `<Sequence from={F} durationInFrames={D}>` is a coordinate

transform: it shifts `useCurrentFrame()` by `F` and clips the child

component to the window `[F, F+D]`. HF doesn't have a per-element

"current frame" — there's a single composition seek time and the

runtime hides/shows elements based on their `data-start` / `data-duration`.

Result: the nested tree flattens into a list of siblings on the same

parent, each with their own time window.

## `<Composition>` → root `#stage`

```tsx

<Composition

id="MyVideo"

component={MyVideo}

durationInFrames={300}

fps={30}

width={1280}

height={720}

```

```html

<div

id="stage"

data-composition-id="MyVideo"

data-start="0"

data-duration="10"

data-fps="30"

data-width="1280"

data-height="720"

</div>

```

`data-start="0"` is required on `#stage` (the runtime needs it to anchor

playback; missing it triggers a lint warning).

## `<AbsoluteFill>` → positioned div

```tsx

<AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>...children...</AbsoluteFill>

```

```html

<div style="position:absolute;inset:0;background-color:#0a0a0a;">...children...</div>

```

`AbsoluteFill` is just a styled div in Remotion. Translate to a div with

`position:absolute; inset:0` and copy through any other style props.

## `<Sequence>` → time-windowed div

```tsx

</Sequence>

```

```html

</div>

```

Convert frames to seconds: `from/fps`, `durationInFrames/fps`. Pick a

`data-track-index` per parallel rendering layer (background = 0,

overlays = 1, audio = 2, etc.). Sequential scenes can share an index.

## Nested `<Sequence>` flattens

Remotion adds offsets when sequences nest:

```tsx

</Sequence>

```

The inner sequence's effective window is `[60+30, 60+30+60] = [90, 150]`.

Translate by computing the sum and emitting one HF div with the resolved

window:

```html

</div>

```

## `<Series>` → siblings with sequential offsets

```tsx

<Series.Sequence durationInFrames={60}>

<A />

</Series.Sequence>

<Series.Sequence durationInFrames={120}>

<B />

</Series.Sequence>

<Series.Sequence durationInFrames={90}>

<C />

</Series.Sequence>

</Series>

```

Each `Sequence.Sequence` lives in the next time slot. Emit siblings

with `data-start` accumulating:

```html

```

## Crossfading scene boundaries

Remotion `<Sequence>` shows/hides at hard boundaries by default. HF does

the same — but if your composition needs a smooth fade between scenes,

you have to drive opacity explicitly with GSAP at the boundary:

```js

const tl = gsap.timeline({ paused: true });

tl.set(scene1, { opacity: 1 }, 0);

tl.set(scene1, { opacity: 0 }, 2); // hard cut at 2s

tl.set(scene2, { opacity: 1 }, 2);

```

For a 0.5 s crossfade:

```js

tl.to(scene1, { opacity: 0, duration: 0.5 }, 1.5);

tl.to(scene2, { opacity: 1, duration: 0.5 }, 1.5);

```

For Remotion `<TransitionSeries>` translations see [transitions.md](transitions.md).

## `<Loop>`

```tsx

</Loop>

```

HF doesn't have a `<Loop>` primitive. Translate to a GSAP timeline with

`repeat: -1`:

```js

const spinTl = gsap.timeline({ paused: true, repeat: -1, repeatRefresh: false });

spinTl.to(spinner, { rotate: 360, duration: 1.0, ease: "none" });

// Embed in the main composition timeline at the right offset:

mainTl.add(spinTl, 3);

```

This is fragile — Remotion's `<Loop>` resets internal state every iteration,

which GSAP repeat does too, but if the looped child has its own animation,

you need to be careful that GSAP's `repeatRefresh` is on or off as needed.

For most simple "spin forever" cases this is fine.

## `<Freeze>`

```tsx

</Freeze>

```

Drop the wrapper. `<Freeze>` pins `useCurrentFrame()` at a constant for

the children — but in HF, the children's animation is already driven by

explicit GSAP tweens, so freeze translates to "don't tween this element".

## Multiple parallel tracks

When you have a background video + overlay text + audio playing

simultaneously, use distinct `data-track-index` values:

```html

<div data-track-index="0">background video</div>

<div data-track-index="1">overlay text</div>

```

The runtime picks track ordering from the index. See [media.md](media.md)

for media-specific track conventions.

mdskills/remotion-to-hyperframes/references/timing.md

6.1 kB

# Timing translation: interpolate, spring, easing

The single highest-leverage reference. Easings and timings are what readers

notice; getting them wrong costs more SSIM than any other translation choice.

Empirically validated against tiers T1–T3.

## Conversion: frames → seconds

HF's timeline is in seconds. Remotion is frame-based. Always:

```

time_seconds = frame / fps

```

So at fps=30:

- frame 15 → 0.5 s

- frame 30 → 1.0 s

- frame 90 → 3.0 s

Do this conversion once when translating, not at runtime.

## interpolate — linear

```tsx

const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });

```

Translates to:

```js

gsap.to(target, { opacity: 1, duration: 1.0, ease: "none" }, 0);

// fromTo if the property starts at 0 and CSS doesn't already set it

gsap.fromTo(target, { opacity: 0 }, { opacity: 1, duration: 1.0, ease: "none" }, 0);

```

`ease: "none"` matches Remotion's default linear interpolation. CSS sets the

`from` value if your initial state is in CSS; otherwise use `fromTo`.

`extrapolateLeft`/`extrapolateRight` defaults to `"extend"` in Remotion but

`"clamp"` is what the agent will see most often. GSAP doesn't extend — values

hold at the start and end of the tween. So for `clamp`, GSAP matches; for

`extend`, you'd need to extend the input range manually before emitting.

## interpolate — multi-segment

```tsx

const opacity = interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0]);

```

Three keyframed tweens at offsets `[0]/fps`, `[1]/fps`, `[2]/fps`:

```js

const tl = gsap.timeline({ paused: true });

tl.to(target, { opacity: 1, duration: 0.5, ease: "none" }, 0);

tl.to(target, { opacity: 1, duration: 2.0, ease: "none" }, 0.5);

tl.to(target, { opacity: 0, duration: 0.5, ease: "none" }, 2.5);

```

Validated in T1 — mean SSIM 0.974 against Remotion baseline.

## spring → GSAP back.out

Remotion's `spring()` is the most lossy translation. The mapping is approximate

but close enough that real-world compositions hold ≥ 0.92 SSIM (T2: 0.985, T3: 0.953).

| Remotion `spring` config | GSAP equivalent | Validated in |

| ------------------------------------------------- | ---------------------------------------------------- | -------------------------------- |

| `{damping: 12, stiffness: 100, mass: 1}` (snappy) | `back.out(1.4)` over ~0.7 s | T2, T3 (TitleScene) |

| `{damping: 14, stiffness: 90, mass: 1}` (calmer) | `back.out(1.2)` over ~0.7 s | T3 (StatCard) |

| `{damping: 8, stiffness: 200}` (very bouncy) | `back.out(2.0)` or `elastic.out(1, 0.5)` over ~0.6 s | not validated; budget ~0.05 SSIM |

| `{overshootClamping: true}` | `power3.out` over ~0.6 s (no overshoot) | not validated |

**Rule of thumb**: `back.out(N)` overshoot ratio ≈ `(stiffness / damping^2) * 1.4`. For

`damping:12, stiffness:100` that gives `1.4 * 100/144 = 0.97`, which is close to

the validated 1.4 (the formula is rough; tune by visual). Default duration is

~0.7 s for the typical config.

When the spring's `delay`/`from`/`to` are non-default, scale the duration

proportionally.

## interpolate with custom easing

```tsx

import { Easing } from "remotion";

interpolate(frame, [0, 30], [0, 1], { easing: Easing.out(Easing.cubic) });

```

| Remotion | GSAP |

| ---------------------------- | -------------------------------------------------------------------------------------- |

| `Easing.in(Easing.linear)` | `ease: "none"` |

| `Easing.out(Easing.cubic)` | `ease: "power3.out"` |

| `Easing.inOut(Easing.cubic)` | `ease: "power3.inOut"` |

| `Easing.out(Easing.poly(N))` | `ease: "power<N>.out"` (N=2 quad, 3 cubic, 4 quart, 5 quint) |

| `Easing.bezier(a,b,c,d)` | `CustomEase.create("c", "M0,0 C${a},${b} ${c},${d} 1,1")` (requires CustomEase plugin) |

| `Easing.elastic(bounciness)` | `ease: "elastic.out(${bounciness}, 0.3)"` |

| `Easing.bounce` | `ease: "bounce.out"` |

| `Easing.back(overshoot)` | `ease: "back.out(${overshoot * 1.7})"` (Remotion's overshoot scale differs) |

## interpolate driving non-numeric properties

```tsx

const color = interpolateColors(frame, [0, 30], ["#ff0000", "#0000ff"]);

```

GSAP does color tweens natively:

```js

gsap.to(target, { color: "#0000ff", duration: 1.0, ease: "none" }, 0);

```

Same for `backgroundColor`, `borderColor`. The `from` value is read from CSS

or the inline style.

## Custom count-up / number tweens

When Remotion uses a frame-driven number ramp (`Math.round(value * eased)`):

```tsx

const t = interpolate(frame, [0, 45], [0, 1]);

const eased = 1 - (1 - t) ** 3; // cubic ease-out

const value = Math.round(target * eased);

return <div>{value.toLocaleString()}</div>;

```

GSAP equivalent — tween a counter object, write `textContent` on update:

```js

const counter = { v: 0 };

tl.to(

counter,

{

v: target,

duration: 1.5,

ease: "power3.out",

onUpdate: () => {

el.textContent = Math.round(counter.v).toLocaleString();

);

```

`power3.out` matches `1 - (1-t)^3` exactly. Validated in T3 (mean SSIM 0.953).

Per-frame digit mismatches occur on sub-frame timing offsets but final values

converge — no SSIM impact above the noise floor.

## Stagger via per-instance prop

When custom subcomponents take a `delayInFrames` prop:

```tsx

```

Translate to GSAP timeline offsets:

```js

cards.forEach((card, i) => {

const start = base + i * (12 / fps); // i * 0.4s at fps=30

tl.to(card, { ... }, start);

});

```

Validated in T3 — three StatCards staggered at 0.0/0.4/0.8 s.

mdskills/remotion-to-hyperframes/references/transitions.md

4.4 kB

# Transitions translation: @remotion/transitions → HF crossfades / shader-transitions

The `@remotion/transitions` package is Remotion's library of pre-built

scene-to-scene transitions. HF has two paths to translate them:

1. **Manual GSAP crossfade** — for simple opacity/transform transitions. Free, no extra package.

2. **HF shader-transitions package** — for visually-rich transitions that match the @remotion/transitions presets.

## Pattern: `<TransitionSeries>` is `<Series>` with overlap

```tsx

<TransitionSeries.Sequence durationInFrames={60}>

</TransitionSeries.Sequence>

<TransitionSeries.Transition

presentation={fade()}

timing={linearTiming({ durationInFrames: 15 })}

<TransitionSeries.Sequence durationInFrames={60}>

</TransitionSeries.Sequence>

</TransitionSeries>

```

Translates to scenes that overlap by the transition duration:

- SceneA: [0, 60] = `data-start="0" data-duration="2"`

- SceneB: [60-15, 60-15+60] = `data-start="1.5" data-duration="2"` (the transition window overlaps the end of A and start of B)

Then drive the transition with GSAP:

```js

// Manual fade (presentation={fade()})

tl.to(sceneA, { opacity: 0, duration: 0.5, ease: "none" }, 1.5);

tl.fromTo(sceneB, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "none" }, 1.5);

```

## Presentation table

| Remotion `presentation` | HF translation |

| ---------------------------------- | ----------------------------------------------------------------------------------------- |

| `fade()` | manual `gsap.to(opacity)` crossfade |

| `slide({direction: "from-right"})` | `gsap.fromTo(translateX: "100%" → 0)` on incoming + `to(translateX: "-100%")` on outgoing |

| `wipe({direction: "from-left"})` | `gsap.fromTo(clip-path: inset(0 100% 0 0) → inset(0 0 0 0))` on incoming |

| `clockWipe()` | use HF's `sdf-iris` shader-transition (`npx hyperframes add sdf-iris`) |

| `flip()` | `gsap.to(rotateY)` 180° split between scenes |

| `cube()` | use HF's `cinematic-zoom` or build manually with `rotateY` + `transform-origin` |

| `iris()` | use HF's `sdf-iris` shader-transition |

| `none()` | no transition; hard cut at the boundary |

## Timing translations

```tsx

linearTiming({durationInFrames: 15}) → ease: "none"

linearTiming({durationInFrames: 15, easing: ...}) → ease per the easing table in timing.md

springTiming({config: {damping: 12}}) → ease: "back.out(1.4)" (~0.7 s)

```

Convert `durationInFrames` to seconds (`/fps`).

## When to use HF shader-transitions

For transitions Remotion presets that have visually-rich GLSL equivalents

(iris, ripple, zoom, glitch), use HF's [shader-transitions](https://hyperframes.heygen.com/catalog/blocks)

package. They produce richer output than manual GSAP transforms.

```bash

npx hyperframes add sdf-iris

```

Then in the composition:

```html

</div>

```

Each shader-transition has its own data attributes; see the catalog page

for the specific block.

## When the source uses a custom Presentation

Remotion supports custom `presentation` implementations:

```tsx

const customPresentation: PresentationComponent = ({

children,

presentationProgress,

presentationDirection,

}) => {

return (

<div

style={

{

/* compute transform from progress */

}

{children}

</div>

);

};

```

Translation: extract the math from the `style={...}` block and emit

equivalent GSAP tweens. Specifically the transform formula maps directly

to a `gsap.to(target, { transform: ... })` parameterized by `progress`.

If the custom presentation uses `useCurrentFrame()` internally to

animate something _outside_ the simple progress curve, treat the source

as untranslatable and bow out to the runtime interop pattern (see

[escape-hatch.md](escape-hatch.md)).

shskills/remotion-to-hyperframes/scripts/frame_strip.sh

3.6 kB

#!/usr/bin/env bash

# frame_strip.sh — produce a side-by-side comparison strip from two videos.

# Used to debug failing render_diff.sh runs visually: pick a sample timestamp

# range, extract frames from both videos, lay them out as a grid for review.

# Usage:

# frame_strip.sh <baseline.mp4> <translated.mp4> [output-dir] [samples]

# Defaults: output-dir=./strip-out, samples=8 (evenly spaced across duration).

# Output:

# strip.png — single PNG with `samples` rows, each row is

# (baseline frame | translated frame) at one timestamp

# timestamps.txt — the timestamps sampled

set -euo pipefail

if [[ $# -lt 2 || $# -gt 4 ]]; then

echo "usage: $0 <baseline.mp4> <translated.mp4> [output-dir] [samples]" >&2

exit 2

BASELINE="$1"

TRANSLATED="$2"

OUTDIR="${3:-./strip-out}"

SAMPLES="${4:-8}"

if ! command -v ffmpeg >/dev/null 2>&1 || ! command -v ffprobe >/dev/null 2>&1; then

echo "error: ffmpeg/ffprobe not on PATH" >&2

exit 2

mkdir -p "$OUTDIR"

# Build the strip in a single ffmpeg invocation. Two inputs (baseline and

# translated) are sampled at N evenly-spaced timestamps via the `select`

# filter, then assembled with hstack (per-row pairs) + vstack (rows).

# Earlier versions spawned 3 ffmpeg calls per timestamp + a final vstack;

# this is one call regardless of N.

python3 - "$BASELINE" "$TRANSLATED" "$OUTDIR" "$SAMPLES" <<'PY'

import json

import shutil

import subprocess

import sys

from pathlib import Path

baseline, translated, outdir, samples = sys.argv[1], sys.argv[2], Path(sys.argv[3]), int(sys.argv[4])

# Read fps + duration from the baseline so we can map timestamps to frame

# indexes for the `select` filter (frame-accurate, doesn't depend on

# keyframe alignment).

probe = subprocess.run(

["ffprobe", "-v", "error", "-select_streams", "v:0",

"-show_entries", "stream=r_frame_rate,nb_read_frames,duration",

"-show_entries", "format=duration",

"-of", "json", "-count_frames", baseline],

check=True, capture_output=True, text=True,

)

data = json.loads(probe.stdout)

stream = data["streams"][0]

num, den = stream["r_frame_rate"].split("/")

fps = float(num) / float(den)

nb_frames = int(stream.get("nb_read_frames") or 0)

if nb_frames <= 0:

duration = float(stream.get("duration") or data["format"]["duration"])

nb_frames = int(duration * fps)

# Even-spaced sample frames in the 5%-95% window (skip fade-in/out noise).

start = max(0, int(nb_frames * 0.05))

end = max(start, int(nb_frames * 0.95) - 1)

if samples == 1:

frames = [start]

else:

step = (end - start) / (samples - 1)

frames = [int(start + i * step) for i in range(samples)]

(outdir / "timestamps.txt").write_text(

"\n".join(f"{f / fps:.3f}" for f in frames) + "\n"

)

# select='eq(n,F1)+eq(n,F2)+...' picks exactly the listed frames from each

# input. We then hstack per-frame pairs and vstack the result.

select_expr = "+".join(f"eq(n,{f})" for f in frames)

n = len(frames)

filter_parts = [

f"[0:v]select='{select_expr}',setpts=N/FRAME_RATE/TB,split={n}"

+ "".join(f"[b{i}]" for i in range(n)),

f"[1:v]select='{select_expr}',setpts=N/FRAME_RATE/TB,split={n}"

+ "".join(f"[t{i}]" for i in range(n)),

]

for i in range(n):

filter_parts.append(f"[b{i}][t{i}]hstack=inputs=2[row{i}]")

filter_parts.append(

"".join(f"[row{i}]" for i in range(n)) + f"vstack=inputs={n}[out]"

)

filter_graph = ";".join(filter_parts)

cmd = [

"ffmpeg", "-y", "-hide_banner", "-loglevel", "error",

"-i", baseline, "-i", translated,

"-filter_complex", filter_graph,

"-map", "[out]", "-frames:v", "1",

str(outdir / "strip.png"),

]

subprocess.run(cmd, check=True)

print(f"wrote {outdir / 'strip.png'} ({n} samples)")

pyskills/remotion-to-hyperframes/scripts/lint_source.py

12 kB

#!/usr/bin/env python3

"""Lint a Remotion project for patterns that don't translate cleanly to HyperFrames.

The skill should run this *before* attempting a translation. If any blocker

findings come back, the recommendation is to use the runtime interop pattern

from PR #214 instead of producing broken HTML.

Usage:

lint_source.py <path-to-remotion-src> [--json]

Output (default human-readable, --json for machine-readable):

For each .ts/.tsx file, a list of findings with:

- severity: blocker | warning | info

- line, column

- rule id

- message

- recommendation

Blockers (skill should refuse to translate):

- r2hf/use-state React state machine drives animation

- r2hf/use-effect-deps useEffect/useLayoutEffect with non-empty deps (side effects)

- r2hf/use-reducer useReducer drives animation

- r2hf/async-metadata calculateMetadata returns a Promise

- r2hf/third-party-react-ui Imports a React UI library (shadcn, mui, antd, mantine, chakra)

Warnings (translate but flag — drop the construct, keep the rest):

- r2hf/lambda-import @remotion/lambda configuration — drop, HF is single-machine

- r2hf/delay-render delayRender() — HF handles asset loading differently

- r2hf/use-callback useCallback — usually decorative, drop

- r2hf/use-memo useMemo — usually decorative, drop

- r2hf/custom-hook Custom hook (use*) defined locally; may need manual rewrite

Info (translate and document):

- r2hf/static-file staticFile("x") — convert to relative path

- r2hf/interpolate-colors interpolateColors — translate to GSAP color tween

"""

from __future__ import annotations

import argparse

import json

import re

import sys

from collections.abc import Iterable

from dataclasses import dataclass, asdict

from pathlib import Path

from typing import Callable

BLOCKER = "blocker"

WARNING = "warning"

INFO = "info"

THIRD_PARTY_UI_PACKAGES = {

"@mui/material",

"@mui/icons-material",

"@chakra-ui/react",

"@mantine/core",

"antd",

"@shadcn/ui",

"@radix-ui",

"@nextui-org/react",

}

@dataclass

class Finding:

file: str

line: int

column: int

severity: str

rule: str

message: str

recommendation: str

@dataclass

class Rule:

"""A lint rule: a matcher that yields hits, plus the metadata each hit gets.

A matcher is a function `src -> Iterable[(offset, override_message)]`. If

`override_message` is None, the rule's default `message` is used; matchers

that need to embed the matched text (custom-hook name, third-party package

name) return the customized message instead.

"""

rule_id: str

severity: str

matcher: Callable[[str], Iterable[tuple[int, str | None]]]

message: str

recommendation: str

def _regex_matcher(pattern: re.Pattern[str]) -> Callable[[str], Iterable[tuple[int, str | None]]]:

def _match(src: str) -> Iterable[tuple[int, str | None]]:

for m in pattern.finditer(src):

yield m.start(), None

return _match

def _use_effect_with_deps(src: str) -> Iterable[tuple[int, str | None]]:

# Find use(Layout)?Effect(, walk to its matching ), and check if the call

# ends with `, [<non-empty>])`. Empty `[]` is mount-only, allowed.

for m in re.finditer(r"\buse(?:Layout)?Effect\s*\(", src):

end = _find_matching_paren(src, m.end() - 1)

if end is None:

continue

call = src[m.start() : end + 1]

m2 = re.search(r",\s*\[([^\]]*)\]\s*$", call[:-1])

if m2 and m2.group(1).strip():

yield m.start(), None

_CUSTOM_HOOK_DECL = re.compile(

r"^\s*(?:export\s+(?:default\s+)?)?(?:function|const|let|var)\s+(use[A-Z]\w+)\b",

re.MULTILINE,

)

_REMOTION_BUILTIN_HOOKS = {"useCurrentFrame", "useVideoConfig"}

def _custom_hook(src: str) -> Iterable[tuple[int, str | None]]:

for m in _CUSTOM_HOOK_DECL.finditer(src):

name = m.group(1)

if name in _REMOTION_BUILTIN_HOOKS:

continue

yield m.start(), f"Custom hook `{name}` defined locally — may need manual rewrite"

_IMPORT_FROM = re.compile(r"from\s+['\"]([^'\"]+)['\"]")

def _third_party_react_ui(src: str) -> Iterable[tuple[int, str | None]]:

for m in _IMPORT_FROM.finditer(src):

pkg = m.group(1)

if any(pkg.startswith(p) for p in THIRD_PARTY_UI_PACKAGES):

yield m.start(), f"Imports `{pkg}` — third-party React UI library has no HF equivalent"

RULES: list[Rule] = [

Rule(

"r2hf/use-state",

BLOCKER,

_regex_matcher(re.compile(r"\buseState\s*[(<]")),

"useState detected — Remotion compositions that drive animation via React state are not deterministic frame-capture targets in HyperFrames",

"Use the runtime interop pattern from PR #214 instead of attempting a translation",

Rule(

"r2hf/use-reducer",

BLOCKER,

_regex_matcher(re.compile(r"\buseReducer\s*[(<]")),

"useReducer detected — same issue as useState",

"Use the runtime interop pattern from PR #214",

Rule(

"r2hf/use-effect-deps",

BLOCKER,

_use_effect_with_deps,

"useEffect/useLayoutEffect with non-empty deps — side effects don't translate to HF's seek-driven model",

"Move the side-effect work into a build step, or use the runtime interop pattern",

Rule(

"r2hf/async-metadata",

BLOCKER,

_regex_matcher(

re.compile(

r"calculateMetadata[^=]*=\s*async\b|async\s+calculateMetadata\b|calculateMetadata\s*:\s*async"

)

"calculateMetadata returns a Promise — HF needs composition metadata up front",

"Resolve metadata at build time and pass concrete values, or use runtime interop",

Rule(

"r2hf/third-party-react-ui",

BLOCKER,

_third_party_react_ui,

"Imports a third-party React UI library — no HF equivalent",

"Use runtime interop, or rewrite the affected components as HTML+CSS",

# Lambda is a warning, not a blocker: it's deployment config, orthogonal

# to the rendered composition. The skill drops the import and translates

# the rest. See references/escape-hatch.md.

Rule(

"r2hf/lambda-import",

WARNING,

_regex_matcher(re.compile(r"from\s+['\"]@remotion/lambda['\"]")),

"@remotion/lambda is Remotion-specific distributed rendering — no HF equivalent today",

"Drop the Lambda config; HF runs single-machine. Document the gap in TRANSLATION_NOTES.md.",

Rule(

"r2hf/delay-render",

WARNING,

_regex_matcher(re.compile(r"\bdelayRender\s*\(")),

"delayRender() — HF waits on asset readiness via the Frame Adapter pattern",

"Drop the call; HF handles this transparently",

Rule(

"r2hf/use-callback",

WARNING,

_regex_matcher(re.compile(r"\buseCallback\s*\(")),

"useCallback — typically decorative for render performance, no HF equivalent needed",

"Drop the wrapper, inline the function",

Rule(

"r2hf/use-memo",

WARNING,

_regex_matcher(re.compile(r"\buseMemo\s*\(")),

"useMemo — typically decorative, no HF equivalent needed",

"Drop the wrapper, compute inline",

Rule(

"r2hf/custom-hook",

WARNING,

_custom_hook,

"Custom hook defined locally — may need manual rewrite",

"Inline the hook body if pure; bow out to runtime interop if it uses useState/useEffect",

Rule(

"r2hf/static-file",

INFO,

_regex_matcher(re.compile(r"\bstaticFile\s*\(")),

"staticFile() reference — convert to a relative path in the HF composition",

"Replace `staticFile(\"x.png\")` with `\"x.png\"` and copy the asset alongside the HTML",

Rule(

"r2hf/interpolate-colors",

INFO,

_regex_matcher(re.compile(r"\binterpolateColors\s*\(")),

"interpolateColors() — translate to a GSAP color tween",

"See references/timing.md for the GSAP equivalent",

]

def _find_matching_paren(src: str, open_idx: int) -> int | None:

"""Given the index of an open `(`, return the index of its matching `)`.

Skips parens that appear inside `'...'`, `"..."`, or `` `...` `` string

literals. Returns None if no matching close paren is found.

This is good enough for hand-written Remotion source. It does not handle

template-literal interpolations `${...}` recursively or comments — both

are uncommon in Remotion code we expect to lint and would only matter

if the unbalanced paren landed inside such a region.

"""

if open_idx >= len(src) or src[open_idx] != "(":

return None

depth = 0

i = open_idx

in_str: str | None = None

while i < len(src):

c = src[i]

if in_str is not None:

if c == "\\":

i += 2

continue

if c == in_str:

in_str = None

i += 1

continue

if c in ("'", '"', "`"):

in_str = c

i += 1

continue

if c == "(":

depth += 1

elif c == ")":

depth -= 1

if depth == 0:

return i

i += 1

return None

def lint_file(path: Path) -> list[Finding]:

src = path.read_text()

findings: list[Finding] = []

def loc(offset: int) -> tuple[int, int]:

line = src.count("\n", 0, offset) + 1

col = offset - (src.rfind("\n", 0, offset) + 1) + 1

return line, col

for rule in RULES:

for offset, override_message in rule.matcher(src):

line, col = loc(offset)

findings.append(

Finding(

str(path),

line,

col,

rule.severity,

rule.rule_id,

override_message or rule.message,

rule.recommendation,

)

findings.sort(key=lambda f: (f.file, f.line, f.column))

return findings

def main() -> int:

ap = argparse.ArgumentParser()

ap.add_argument("path", type=Path, help="Directory or file to lint")

ap.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable output")

args = ap.parse_args()

if not args.path.exists():

print(f"error: {args.path} does not exist", file=sys.stderr)

return 2

files: list[Path]

if args.path.is_file():

files = [args.path]

else:

files = sorted(

for p in args.path.rglob("*")

if p.is_file()

and p.suffix in {".ts", ".tsx", ".jsx", ".js"}

and "node_modules" not in p.parts

)

all_findings: list[Finding] = []

for f in files:

all_findings.extend(lint_file(f))

blockers = sum(1 for f in all_findings if f.severity == BLOCKER)

warnings = sum(1 for f in all_findings if f.severity == WARNING)

infos = sum(1 for f in all_findings if f.severity == INFO)

if args.json:

json.dump(

{

"files_scanned": len(files),

"blockers": blockers,

"warnings": warnings,

"infos": infos,

"findings": [asdict(f) for f in all_findings],

sys.stdout,

indent=2,

)

sys.stdout.write("\n")

else:

for f in all_findings:

print(f"{f.file}:{f.line}:{f.column} [{f.severity}] {f.rule}: {f.message}")

print(f" -> {f.recommendation}")

print()

print(f"{len(files)} files scanned · {blockers} blocker · {warnings} warning · {infos} info")

if blockers:

print("RECOMMENDATION: do not attempt translation. Use the runtime interop pattern from PR #214.")

return 1 if blockers else 0

if __name__ == "__main__":

sys.exit(main())

shskills/remotion-to-hyperframes/scripts/render_diff.sh

3.0 kB

#!/usr/bin/env bash

# render_diff.sh — compute per-frame SSIM between two video files.

# The eval primitive for the remotion-to-hyperframes skill: given a Remotion

# render and a HyperFrames render of the same composition, report whether the

# translation is visually equivalent.

# Usage:

# render_diff.sh <baseline.mp4> <translated.mp4> [output-dir]

# Output (in output-dir, defaults to ./diff-out):

# ssim.log — per-frame SSIM lines from ffmpeg

# summary.json — { mean, min, p05, p95, frame_count, pass, threshold }

# Exit codes:

# 0 — pass (mean SSIM >= threshold)

# 1 — fail (mean SSIM < threshold)

# 2 — usage / setup error

# Threshold defaults to 0.85 (loose; tier-specific thresholds are applied by

# the orchestrator). Override with R2HF_SSIM_THRESHOLD=0.95 in the environment.

set -euo pipefail

THRESHOLD="${R2HF_SSIM_THRESHOLD:-0.85}"

if [[ $# -lt 2 || $# -gt 3 ]]; then

echo "usage: $0 <baseline.mp4> <translated.mp4> [output-dir]" >&2

exit 2

BASELINE="$1"

TRANSLATED="$2"

OUTDIR="${3:-./diff-out}"

if [[ ! -f "$BASELINE" ]]; then

echo "error: baseline not found: $BASELINE" >&2

exit 2

if [[ ! -f "$TRANSLATED" ]]; then

echo "error: translated not found: $TRANSLATED" >&2

exit 2

if ! command -v ffmpeg >/dev/null 2>&1; then

echo "error: ffmpeg not on PATH" >&2

exit 2

mkdir -p "$OUTDIR"

SSIM_LOG="$OUTDIR/ssim.log"

SUMMARY="$OUTDIR/summary.json"

# ffmpeg's ssim filter writes one line per frame to stats_file and a single

# Mean SSIM line to stderr. We capture both — per-frame for distribution

# stats, and the mean for the headline number.

ffmpeg -hide_banner -nostats -loglevel info \

-i "$BASELINE" -i "$TRANSLATED" \

-lavfi "[0:v]scale=iw:ih[ref];[1:v]scale=iw:ih[main];[main][ref]ssim=stats_file=$SSIM_LOG" \

-f null - 2>"$OUTDIR/ffmpeg.stderr"

# Parse: each line in ssim.log looks like

# n:1 Y:0.987655 U:0.992345 V:0.991234 All:0.989012 (19.512345)

# We want the All:N column.

python3 - "$SSIM_LOG" "$SUMMARY" "$THRESHOLD" <<'PY'

import json, math, re, sys

from pathlib import Path

log_path = Path(sys.argv[1])

out_path = Path(sys.argv[2])

threshold = float(sys.argv[3])

values = []

pattern = re.compile(r"All:([\d.]+)")

for line in log_path.read_text().splitlines():

m = pattern.search(line)

if m:

try:

values.append(float(m.group(1)))

except ValueError:

pass

if not values:

print(f"error: no SSIM samples parsed from {log_path}", file=sys.stderr)

sys.exit(2)

values.sort()

n = len(values)

mean = sum(values) / n

p_idx = lambda p: min(n - 1, max(0, int(math.floor(p * n))))

summary = {

"frame_count": n,

"mean": round(mean, 6),

"min": round(values[0], 6),

"max": round(values[-1], 6),

"p05": round(values[p_idx(0.05)], 6),

"p95": round(values[p_idx(0.95)], 6),

"threshold": threshold,

"pass": bool(mean >= threshold),

}

out_path.write_text(json.dumps(summary, indent=2) + "\n")

print(json.dumps(summary, indent=2))

sys.exit(0 if summary["pass"] else 1)

shskills/remotion-to-hyperframes/scripts/tests/smoke.sh

3.5 kB

#!/usr/bin/env bash

# smoke.sh — exercise the eval harness scripts against synthetic inputs.

# Generates two synthetic videos with ffmpeg's testsrc filter, runs render_diff

# and frame_strip against them, and runs lint_source against fixture .tsx files.

# Asserts the harness produces sensible output without depending on a real

# Remotion or HyperFrames render pipeline being installed.

# Usage: ./smoke.sh

# Exit 0 on pass.

set -euo pipefail

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

SCRIPTS_DIR="$(cd "$THIS_DIR/.." && pwd)"

WORK="$(mktemp -d)"

trap 'rm -rf "$WORK"' EXIT

echo "==> smoke: render_diff.sh against identical inputs"

# Generate the same test pattern twice. Identical inputs → SSIM should be ~1.0.

ffmpeg -y -hide_banner -loglevel error \

-f lavfi -i "testsrc=duration=2:size=320x240:rate=30" \

-pix_fmt yuv420p "$WORK/baseline.mp4"

cp "$WORK/baseline.mp4" "$WORK/translated.mp4"

R2HF_SSIM_THRESHOLD=0.99 "$SCRIPTS_DIR/render_diff.sh" \

"$WORK/baseline.mp4" "$WORK/translated.mp4" "$WORK/diff" >/dev/null

MEAN=$(python3 -c "import json,sys; print(json.load(open('$WORK/diff/summary.json'))['mean'])")

PASS=$(python3 -c "import json,sys; print(json.load(open('$WORK/diff/summary.json'))['pass'])")

if [[ "$PASS" != "True" ]]; then

echo "FAIL: identical inputs failed pass check (mean=$MEAN)"

exit 1

echo " identical inputs → mean SSIM=$MEAN (pass=True)"

echo "==> smoke: render_diff.sh against different inputs"

# Different test pattern → SSIM should be lower. With a high threshold it should fail.

ffmpeg -y -hide_banner -loglevel error \

-f lavfi -i "testsrc2=duration=2:size=320x240:rate=30" \

-pix_fmt yuv420p "$WORK/different.mp4"

set +e

R2HF_SSIM_THRESHOLD=0.99 "$SCRIPTS_DIR/render_diff.sh" \

"$WORK/baseline.mp4" "$WORK/different.mp4" "$WORK/diff2" >/dev/null

RC=$?

set -e

if [[ "$RC" -eq 0 ]]; then

echo "FAIL: different inputs unexpectedly passed at threshold 0.99"

exit 1

DIFF_MEAN=$(python3 -c "import json; print(json.load(open('$WORK/diff2/summary.json'))['mean'])")

echo " different inputs → mean SSIM=$DIFF_MEAN (correctly failed at 0.99)"

echo "==> smoke: frame_strip.sh produces a strip"

"$SCRIPTS_DIR/frame_strip.sh" "$WORK/baseline.mp4" "$WORK/different.mp4" "$WORK/strip" 4 >/dev/null

if [[ ! -f "$WORK/strip/strip.png" ]]; then

echo "FAIL: frame_strip.sh did not produce strip.png"

exit 1

echo " strip.png written ($(stat -c%s "$WORK/strip/strip.png" 2>/dev/null || stat -f%z "$WORK/strip/strip.png") bytes)"

echo "==> smoke: lint_source.py on clean fixture (expect exit 0)"

set +e

python3 "$SCRIPTS_DIR/lint_source.py" "$THIS_DIR/fixtures/clean.tsx" --json >"$WORK/clean.json"

RC=$?

set -e

BLOCKERS=$(python3 -c "import json; print(json.load(open('$WORK/clean.json'))['blockers'])")

if [[ "$RC" -ne 0 || "$BLOCKERS" -ne 0 ]]; then

echo "FAIL: clean fixture reported $BLOCKERS blockers (rc=$RC)"

exit 1

INFOS=$(python3 -c "import json; print(json.load(open('$WORK/clean.json'))['infos'])")

echo " clean.tsx → 0 blockers, $INFOS info findings"

echo "==> smoke: lint_source.py on blocker fixture (expect exit 1)"

set +e

python3 "$SCRIPTS_DIR/lint_source.py" "$THIS_DIR/fixtures/blocker.tsx" --json >"$WORK/blocker.json"

RC=$?

set -e

BLOCKERS=$(python3 -c "import json; print(json.load(open('$WORK/blocker.json'))['blockers'])")

if [[ "$RC" -eq 0 || "$BLOCKERS" -lt 3 ]]; then

echo "FAIL: blocker fixture reported $BLOCKERS blockers, expected >=3 (rc=$RC)"

cat "$WORK/blocker.json"

exit 1

echo " blocker.tsx → $BLOCKERS blockers detected (correctly refused)"

echo

echo "✅ smoke tests passed"

mdskills/remotion-to-hyperframes/SKILL.md

8.7 kB

---

description: Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

---

# Remotion to HyperFrames

## Overview

Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model and recommending the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead.

The skill ships with a **tiered test corpus** (T1–T4, 4 fixtures total) that grades translations against measured SSIM thresholds. Don't translate without running the eval — a translation that "looks right" but renders 0.05 SSIM lower than the validated baseline is silently wrong.

## When to use

**Use this skill ONLY when the user explicitly asks to migrate from Remotion.** Example trigger phrases:

- "port my Remotion project to HyperFrames"

- "convert this Remotion code to HyperFrames"

- "migrate from Remotion"

- "translate this Remotion comp"

- "rewrite this as HyperFrames HTML"

**Do NOT use this skill when:**

- (a) The user is authoring a **new** HyperFrames composition, even if they have or are A/B-testing a similar Remotion video.

- (b) The user mentions Remotion in passing without asking for migration.

- (c) The user shares Remotion code as reference material rather than asking for a translation.

- (d) The user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build.

When in doubt, default to authoring a native HyperFrames composition with the `hyperframes` skill instead.

## Workflow

### Step 1: Lint the source

Run [`scripts/lint_source.py`](scripts/lint_source.py) over the Remotion source directory. The lint detects patterns that can't translate cleanly:

- **Blockers** (refuse + recommend interop): `useState`, `useReducer`, `useEffect`/`useLayoutEffect` with non-empty deps, async `calculateMetadata`, third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).

- **Warnings** (translate after dropping the construct): `@remotion/lambda` config, `delayRender`, `useCallback`, `useMemo`, custom hooks.

- **Info** (translate with note): `staticFile`, `interpolateColors`.

If any blocker fires, **stop**. Read [`references/escape-hatch.md`](references/escape-hatch.md) and surface the recommendation message. Warnings don't stop translation — drop the offending construct in step 3 and note the gap in `TRANSLATION_NOTES.md`. `@remotion/lambda` config is the canonical warning case: the skill drops the import + `renderMediaOnLambda(...)` calls but translates the rest of the composition.

### Step 2: Plan the translation

Read [`references/api-map.md`](references/api-map.md) — the index of every Remotion API and its HF equivalent or per-topic reference. Identify which topic references you'll need based on what the source uses:

| Source contains | Load reference |

| ------------------------------------------------------------------------- | --------------------------------------------- |

| `Composition`, `defaultProps`, `schema`, `calculateMetadata` | [`parameters.md`](references/parameters.md) |

| `Sequence`, `Series`, `Loop`, `AbsoluteFill`, `Freeze` | [`sequencing.md`](references/sequencing.md) |

| `useCurrentFrame`, `interpolate`, `spring`, `Easing`, `interpolateColors` | [`timing.md`](references/timing.md) |

| `Audio`, `Video`, `Img`, `IFrame`, `staticFile`, `delayRender` | [`media.md`](references/media.md) |

| `TransitionSeries`, `@remotion/transitions` | [`transitions.md`](references/transitions.md) |

| `@remotion/lottie` | [`lottie.md`](references/lottie.md) |

| `@remotion/google-fonts/<Family>`, `Font.loadFont`, `@font-face` | [`fonts.md`](references/fonts.md) |

Don't load all of them — load only what the specific source needs.

### Step 3: Generate the HF composition

Emit `index.html` with:

- Root `<div id="stage">` carrying the composition's `data-composition-id`, `data-start="0"`, `data-duration` (in seconds), `data-fps`, `data-width`, `data-height`, plus one `data-*` per scalar prop.

- A flat list of scene divs with `data-start` / `data-duration` / `data-track-index`.

- Inline `<style>` for layout; CSS sets the `from` state of every animated property.

- A single `<script>` tag at the bottom containing one paused `gsap.timeline({paused: true})`. Every Remotion `useCurrentFrame()` derivation becomes a tween on this timeline at the right offset.

- `window.__timelines["<composition-id>"] = tl;` registers the timeline with HF's runtime.

Custom React subcomponents inline as repeated HTML using the prop interface as the template (see [`parameters.md`](references/parameters.md) for the per-instance `data-*` pattern).

### Step 4: Validate

Run the eval harness — [`references/eval.md`](references/eval.md) for the full guide. Quick path:

```bash

# Render Remotion baseline (after npm install in the fixture)

cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# Render HF translation

cd ../hf-src && npx hyperframes render --output ../hf.mp4

# SSIM diff

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

```

Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.

**Critical**: both renders must use matching pixel format. Set `Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")` in the Remotion source's `remotion.config.ts` — otherwise the diff measures encoder differences (~0.05 SSIM hit), not translation fidelity.

### Step 5: Document gaps

Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a `TRANSLATION_NOTES.md` written next to the HF output. See [`references/limitations.md`](references/limitations.md) for the format.

## What this skill explicitly does NOT do

- **Translate React state machines.** Compositions that drive animation via `useState` + `useEffect` are not deterministic frame-capture targets in HyperFrames' seek-driven model. Recommend the runtime interop pattern.

- **Run Remotion's render pipeline alongside HyperFrames.** That's the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) — a separate solution for compositions that fail this skill's lint.

(`@remotion/lambda` is _not_ a blocker — Lambda config is deployment, not animation. The skill drops it as a warning and translates the rest. See [`references/escape-hatch.md`](references/escape-hatch.md).)

## How to grade your own translation

Run the test corpus orchestrator:

```bash

./assets/test-corpus/run.sh

```

It runs T1, T2, T3 (render + diff) and T4 (lint validation), prints a per-tier pass/fail table, and emits an aggregate JSON report. Use this to verify the skill is working end-to-end on a clean checkout — and as a regression check after editing any reference.

Validated baseline (as of 2026-04-27):

| ---- | ------------------------------------------- | --------- | --------- |

| T1 | single-element fade-in | 0.974 | 0.95 |

| T2 | multi-scene + spring + audio + image | 0.985 | 0.95 |

| T3 | data-driven, custom subcomponents, count-up | 0.953 | 0.90 |

| T4 | escape-hatch (8 lint cases) | 8/8 pass | n/a |

mdskills/tailwind/SKILL.md

6.1 kB

---

description: Tailwind CSS v4.2 browser-runtime patterns for HyperFrames compositions. Use when scaffolding or editing projects created with `hyperframes init --tailwind`, writing Tailwind utility classes in composition HTML, adding CSS-first Tailwind v4 theme tokens, debugging v3 vs v4 syntax, or deciding when to compile Tailwind to CSS instead of using the browser runtime.

---

# Tailwind CSS for HyperFrames

HyperFrames `init --tailwind` uses the Tailwind browser runtime pinned to `@tailwindcss/browser@4.2.4`. Treat that as Tailwind v4, not v3.

This skill is for composition HTML generated by the CLI. It is not for `packages/studio`, which still uses Tailwind v3 internally with `tailwind.config.js`, PostCSS, and `@tailwind` directives.

## When To Use

- The user asks for Tailwind in a HyperFrames composition.

- A project was created with `hyperframes init --tailwind`.

- You see `window.__tailwindReady` in `index.html`.

- You need utility classes, CSS-first theme tokens, custom utilities, or v3-to-v4 migration guidance.

- The render has missing styles and the project is relying on the browser runtime.

## Version Contract

- Pinned runtime: `@tailwindcss/browser@4.2.4`.

- Browser runtime script is injected by the CLI. Do not replace it with `cdn.tailwindcss.com`.

- HyperFrames waits for `window.__tailwindReady` before frame capture starts.

- The readiness shim must stay deterministic: no render-loop polling APIs, no clock-based retries, no runtime network fetches beyond the pinned Tailwind runtime script.

- For offline, locked-down, or production-stable renders, compile Tailwind to CSS and include the stylesheet directly instead of relying on the browser runtime.

## v4 Rules

Tailwind v4 is CSS-first:

```html

@theme {

--color-brand: oklch(0.68 0.2 252);

--font-display: "Inter", sans-serif;

}

@utility headline-balance {

text-wrap: balance;

letter-spacing: 0;

}

</style>

```

Avoid v3 setup patterns in browser-runtime compositions:

```css

/* Do not use these in Tailwind v4 browser-runtime compositions. */

@tailwind base;

@tailwind components;

@tailwind utilities;

```

Do not add a `tailwind.config.js` just to define colors, fonts, spacing, or utilities for a v4 browser-runtime composition. Use `@theme` and `@utility` in a `text/tailwindcss` style block.

If you truly need an existing JavaScript config for a compiled v4 build, load it explicitly from CSS with `@config`, then validate in the browser. Do not assume v4 auto-detects v3 config files.

## HyperFrames Composition Pattern

Keep Tailwind responsible for static layout and visual style. Keep motion timing in GSAP or another seekable adapter.

```html

<section

class="clip absolute inset-0 grid place-items-center bg-zinc-950 text-white"

data-start="0"

data-duration="5"

data-track-index="1"

Render-ready Tailwind

</p>

Utility classes, deterministic frames.

</h1>

</div>

</section>

```

For repeated items, prefer class lists plus CSS custom properties over generating class names dynamically:

```html

```

## Dynamic Class Safety

Tailwind's browser runtime scans the current document and generates CSS for class names it can see. Do not build render-critical class names only at seek time:

```js

// Risky: Tailwind may not see every generated class before capture.

element.className = `bg-${color}-500`;

```

Use complete class names in HTML, data attributes, or explicit CSS instead:

```html

```

If a generated class is unavoidable, make sure the full class token appears in a `text/tailwindcss` block before validation.

## Video-Specific Guardrails

- Use stable dimensions: `w-[...]`, `h-[...]`, `aspect-video`, `grid`, `flex`, and fixed padding for video layouts.

- Prefer transforms and opacity for animated properties.

- Keep Tailwind transitions out of render-critical timing unless a seekable runtime owns the state.

- Avoid hover, focus, scroll, viewport, or pointer variants for content that must render deterministically.

- Use explicit border colors. Tailwind v4 changed the default border behavior from v3, so `border border-white/20` is safer than bare `border`.

- Use v4 utility names: `shadow-xs`, `rounded-xs`, `outline-hidden`, `shrink-*`, and `grow-*` where those replacements apply.

- Be careful with modern CSS utilities if the output needs older browser support. Tailwind v4 targets modern browsers.

## Validation

After editing a Tailwind-enabled composition:

```bash

npx hyperframes lint

npx hyperframes validate

npx hyperframes inspect

```

For a render proof:

```bash

npx hyperframes render . --workers 1 --quality draft --output tailwind-proof.mp4

```

The validation path should show no missing-style flashes on frame 0. If styles appear in preview but not render, check that `window.__tailwindReady` exists and resolves before capture.

## Quick Debug Checklist

1. Confirm the project was scaffolded with `hyperframes init --tailwind`.

2. Confirm the script points to `@tailwindcss/browser@4.2.4`.

3. Confirm `window.__tailwindReady` is present.

4. Replace v3 `@tailwind` directives with v4 browser-runtime CSS.

5. Move custom tokens from `tailwind.config.js` to `@theme`.

6. Replace dynamically assembled classes with complete static tokens.

7. Run `npx hyperframes validate` and render a short proof.

## Credits And References

- Tailwind CSS official v4 installation, upgrade, and compatibility docs: https://tailwindcss.com/docs

- Tailwind CSS v4 release notes: https://tailwindcss.com/blog/tailwindcss-v4

- Community Tailwind skills were reviewed for v4 gotchas and skill shape, but this skill keeps the durable contract in-repo and HyperFrames-specific.

mdskills/three/SKILL.md

3.5 kB

---

description: Three.js and WebGL adapter patterns for HyperFrames. Use when creating deterministic Three.js scenes, WebGL canvas layers, AnimationMixer timelines, camera motion, shader-driven visuals, or canvas renders that respond to HyperFrames hf-seek events.

---

# Three.js for HyperFrames

HyperFrames supports Three.js through its `three` runtime adapter. The adapter does not own your scene. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact frame.

## Contract

- Create the scene, camera, renderer, materials, and assets synchronously when possible.

- Render from HyperFrames time, not wall-clock time.

- Listen for the `hf-seek` event and render exactly that time.

- Load models, textures, and HDRIs before render-critical seeking. Do not fetch them at seek time.

- Avoid `requestAnimationFrame` or `renderer.setAnimationLoop` as the source of truth for render-critical motion.

The adapter sets `window.__hfThreeTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.

## Basic Pattern

```html

import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm";

const canvas = document.getElementById("three-layer");

const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });

// Match these to your composition's frame size.

renderer.setSize(1920, 1080, false);

renderer.setPixelRatio(1);

const scene = new THREE.Scene();

const camera = new THREE.PerspectiveCamera(35, 1920 / 1080, 0.1, 100);

camera.position.set(0, 0, 6);

const mesh = new THREE.Mesh(

new THREE.IcosahedronGeometry(1.4, 4),

new THREE.MeshStandardMaterial({ color: 0x64d2ff, roughness: 0.38 }),

);

scene.add(mesh);

scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));

function renderAt(time) {

mesh.rotation.y = time * 0.7;

mesh.rotation.x = Math.sin(time * 0.6) * 0.16;

renderer.render(scene, camera);

}

window.addEventListener("hf-seek", (event) => {

renderAt(event.detail.time);

});

renderAt(window.__hfThreeTime || 0);

</script>

```

```css

#three-layer {

width: 100%;

height: 100%;

display: block;

}

```

## AnimationMixer Pattern

For GLTF or authored clip animation, seek the mixer directly:

```js

function renderAt(time) {

mixer.setTime(time);

renderer.render(scene, camera);

}

```

If several mixers exist, seek all of them from the same `time`.

## Good Uses

- Deterministic 3D objects, product spins, particles with seeded data, and shader plates.

- Camera moves derived from `time`.

- GLTF animation clips when assets are local and loaded before validation completes.

## Avoid

- Using `Date.now()`, `performance.now()`, or clock deltas to update scene state.

- Leaving render-critical work inside a free-running animation loop.

- Loading remote models or textures at render time.

- Device-pixel-ratio dependent output. Pin renderer size and pixel ratio for video renders.

- Post-processing passes that depend on previous frame history unless you can reconstruct state from time.

## Validation

After editing a Three.js composition:

```bash

npx hyperframes lint

npx hyperframes validate

```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/three.ts`.

- Three.js `WebGLRenderer` docs: https://threejs.org/docs/pages/WebGLRenderer.html

- Three.js `AnimationMixer.setTime()` docs: https://threejs.org/docs/pages/AnimationMixer.html

mdskills/typegpu/SKILL.md

6.5 kB

---

description: TypeGPU and raw WebGPU adapter patterns for HyperFrames. Use when creating GPU-rendered compositions with TypeGPU, raw WebGPU, WGSL fragment shaders, compute pipelines, liquid glass effects, particle systems, or any canvas layer driven by navigator.gpu that responds to HyperFrames hf-seek events.

---

# TypeGPU / WebGPU for HyperFrames

HyperFrames supports TypeGPU and raw WebGPU through its `typegpu` runtime adapter. The adapter does not own your pipeline. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact GPU frame.

## Contract

- Initialize WebGPU asynchronously (`await navigator.gpu.requestAdapter()`), but register all GSAP tweens **synchronously** — before any `await`. The HyperFrames player reads the timeline immediately at page load.

- Render from HyperFrames time, not `performance.now()`.

- Listen for the `hf-seek` event and re-render at exactly that time.

- Guard against environments where WebGPU is unavailable — the adapter does not check for you.

- For video renders, call `await device.queue.onSubmittedWorkDone()` after submitting GPU work to ensure the canvas is flushed before the frame is captured.

The adapter sets `window.__hfTypegpuTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.

## Basic Pattern

```html

(async () => {

if (!navigator.gpu) return;

const adapter = await navigator.gpu.requestAdapter();

if (!adapter) return;

const device = await adapter.requestDevice();

const canvas = document.getElementById("gpu-layer");

canvas.width = 1920;

canvas.height = 1080;

const ctx = canvas.getContext("webgpu");

const fmt = navigator.gpu.getPreferredCanvasFormat();

ctx.configure({ device, format: fmt, alphaMode: "opaque" });

// Build your pipeline, buffers, bind groups...

const timeUniform = new Float32Array([0]);

const timeBuf = device.createBuffer({

size: 16,

usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,

});

function render(t) {

timeUniform[0] = t;

device.queue.writeBuffer(timeBuf, 0, timeUniform);

const enc = device.createCommandEncoder();

const pass = enc.beginRenderPass({

colorAttachments: [

{

view: ctx.getCurrentTexture().createView(),

loadOp: "clear",

clearValue: { r: 0, g: 0, b: 0, a: 1 },

storeOp: "store",

});

pass.setPipeline(pipeline);

pass.setBindGroup(0, bindGroup);

pass.draw(3);

pass.end();

device.queue.submit([enc.finish()]);

}

render(0);

window.addEventListener("hf-seek", (e) => render(e.detail.time));

})();

</script>

```

## Timeline Registration

GSAP tweens that drive text, captions, or HTML elements must be registered **synchronously** — before any `await`:

```js

const tl = gsap.timeline({ paused: true });

// Caption tweens: synchronous, added before WebGPU init

gsap.set(".cap", { opacity: 0 });

tl.to("#cap-1", { opacity: 1, duration: 0.3 }, 1.0);

tl.to("#cap-1", { opacity: 0, duration: 0.2 }, 3.5);

window.__timelines["my-comp"] = tl;

// GPU-dependent tweens can go inside the async IIFE

(async () => {

// ... WebGPU init ...

const proxy = { value: 0 };

tl.to(proxy, { value: 1, duration: 2, onUpdate: render }, 0.5);

})();

```

## Video-Backed Effects (Liquid Glass, Distortion)

To use a `<video>` as the GPU input texture:

```js

const videoEl = document.getElementById("aroll");

// Wait for video metadata before creating the texture

await new Promise((r) => {

if (videoEl.readyState >= 1) r();

else videoEl.addEventListener("loadedmetadata", r, { once: true });

});

// Create texture at the video's NATIVE resolution

const vw = videoEl.videoWidth,

vh = videoEl.videoHeight;

const bgTex = device.createTexture({

size: [vw, vh],

format: "rgba8unorm",

usage:

GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,

});

function render(t) {

try {

device.queue.copyExternalImageToTexture({ source: videoEl }, { texture: bgTex }, [vw, vh]);

} catch (_) {

/* frame not decoded yet */

}

// ... draw ...

}

```

**Render-mode caveat:** headless Chrome may fail `copyExternalImageToTexture` for video elements. For production renders, pre-extract key frames via FFmpeg as PNGs and load them as image textures instead.

## Frosted Blur via Downsample Pass

A single-pass Gaussian kernel is too weak for glass-like frosted blur. Use a two-pass approach:

1. **Pass 1 — Downsample:** render the full-res texture to a small texture (1/6 resolution). Bilinear filtering during the downsample naturally averages pixels.

2. **Pass 2 — Glass composite:** sample the small texture for the frosted interior (bilinear upscale = heavy smooth blur) and the full-res texture for sharp areas and chromatic refraction.

This matches TypeGPU's `textureSampleBias` mip-level approach without generating mipmaps.

## Transparent vs Opaque Canvas

- **`alphaMode: 'opaque'`** — the GPU canvas renders the full frame (video + effect). Use when the GPU pipeline handles all visual content.

- **`alphaMode: 'premultiplied'`** — the GPU canvas is transparent where alpha = 0, letting HTML elements below show through. Use for overlays (particles, path animations) on top of a regular `<video>` element.

## WGSL Full-Screen Triangle

The standard vertex shader for full-screen effects (no vertex buffer needed):

```wgsl

struct Vo { @builtin(position) pos: vec4f, @location(0) uv: vec2f }

@vertex fn vs(@builtin(vertex_index) vi: u32) -> Vo {

let ps = array<vec2f, 3>(vec2f(-1., -1.), vec2f(3., -1.), vec2f(-1., 3.));

let ts = array<vec2f, 3>(vec2f(0., 1.), vec2f(2., 1.), vec2f(0., -1.));

return Vo(vec4f(ps[vi], 0., 1.), ts[vi]);

}

```

Draw with `pass.draw(3)` — one triangle that covers the viewport.

## Rounded-Rect SDF (Liquid Glass Pill)

```wgsl

fn sdf_box(p: vec2f, half_size: vec2f, corner_radius: f32) -> f32 {

let d = abs(p) - half_size + vec2f(corner_radius);

return length(max(d, vec2f(0.))) + min(max(d.x, d.y), 0.) - corner_radius;

}

```

Use this to define inside/ring/outside zones for glass effects. Negative values are inside the shape.

## Deterministic Rendering

- No `Math.random()` — use a seeded PRNG.

- No `requestAnimationFrame` for the render loop — render only in response to `hf-seek`.

- No `performance.now()` for animation time — read `window.__hfTypegpuTime` or `e.detail.time`.

- After GPU submit, call `await device.queue.onSubmittedWorkDone()` for render-mode frame capture.

mdskills/waapi/SKILL.md

3.1 kB

---

description: Web Animations API adapter patterns for HyperFrames. Use when authoring element.animate() motion, Animation currentTime seeking, document.getAnimations(), KeyframeEffect timing, fill modes, or native browser animations that must render deterministically in HyperFrames.

---

# Web Animations API for HyperFrames

HyperFrames can seek Web Animations API animations through its `waapi` runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.

## Contract

- Create animations synchronously during composition initialization.

- Use `element.animate(...)` with finite `duration` and `iterations`.

- Use `fill: "both"` so seeked states persist.

- Pause animations after creation or let the adapter pause them on first seek.

- Avoid callbacks and promises for render-critical state.

The adapter calls `document.getAnimations()`, sets each animation's `currentTime` to HyperFrames time in milliseconds, then pauses it.

## Basic Pattern

```html

const orb = document.getElementById("orb");

const animation = orb.animate(

[

{ transform: "translate3d(-160px, 0, 0) scale(0.8)", opacity: 0 },

{ transform: "translate3d(0, 0, 0) scale(1)", opacity: 1, offset: 0.35 },

{ transform: "translate3d(120px, 0, 0) scale(1.08)", opacity: 1 },

{

duration: 3000,

delay: 2000,

easing: "cubic-bezier(0.2, 0, 0, 1)",

fill: "both",

iterations: 1,

);

animation.pause();

</script>

```

## Stagger Pattern

```js

document.querySelectorAll(".token").forEach((token, index) => {

const animation = token.animate(

[

{ transform: "translateY(24px)", opacity: 0 },

{ transform: "translateY(0)", opacity: 1 },

{

duration: 620,

delay: index * 80,

easing: "cubic-bezier(0.2, 0, 0, 1)",

fill: "both",

iterations: 1,

);

animation.pause();

});

```

## Good Uses

- Lightweight DOM motion where CSS keyframes are too rigid and GSAP is unnecessary.

- Generated animations from structured data.

- Simple timelines that can be represented as keyframes, delays, and offsets.

## Avoid

- Infinite `iterations`.

- Depending on `animation.finished` to mutate render-critical DOM.

- Running separate clocks with `requestAnimationFrame`, timers, or `performance.now()`.

- Animating layout properties when transforms and opacity can express the motion.

- Assuming clip-local start time is automatic. WAAPI adapter seeks document-level animation time; model clip offsets with `delay` or create the animation on an element whose visibility is controlled by HyperFrames timing.

## Validation

After editing a WAAPI composition:

```bash

npx hyperframes lint

npx hyperframes validate

```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/waapi.ts`.

- MDN Web Animations API guide: https://developer.mozilla.org/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API

- MDN `Animation.currentTime`: https://developer.mozilla.org/en-US/docs/Web/API/Animation/currentTime

jsonskills/website-to-hyperframes/assets/sfx/manifest.json

4.2 kB

{

"chime": {

"file": "chime.mp3",

"duration": 2.5,

"description": "This is a soft, melodic chime sound effect perfect for signaling a gentle transition or a lighthearted moment in a video."

"click-soft": {

"file": "click-soft.mp3",

"duration": 0.37,

"description": "This is a smooth, medium-energy swoosh sound effect, perfect for transitioning between two scenes or highlighting a sleek reveal."

"click": {

"file": "click.mp3",

"duration": 0.37,

"description": "This is a sharp, medium-energy digital \"whoosh\" effect that works perfectly for a quick transition between video clips."

"error": {

"file": "error.mp3",

"duration": 1.62,

"description": "This is a sharp, medium-energy digital glitch sound that serves as an effective, abrupt transition for a video cut or error screen."

"glitch-1": {

"file": "glitch-1.mp3",

"duration": 2.64,

"description": "This is a high-energy, distorted digital impact sound effect that works perfectly for a sudden reveal or a punchy transition in a fast-paced edit."

"glitch-2": {

"file": "glitch-2.mp3",

"duration": 3.5,

"description": "This is a harsh, distorted digital glitch effect with high energy that serves as a jarring transition or a chaotic digital reveal."

"glitch-3": {

"file": "glitch-3.mp3",

"duration": 3.1,

"description": "This is a low-energy, subtle electronic click sound effect that works well as a minimal audio transition or a UI element for a subtle selection reveal."

"impact-bass-1": {

"file": "impact-bass-1.mp3",

"duration": 2.12,

"description": "This is a medium-energy, sharp electronic chime that works perfectly as an accent for a quick transition or a brief, high-tech visual reveal."

"impact-bass-2": {

"file": "impact-bass-2.mp3",

"duration": 2.59,

"description": "This sound effect is a shimmering, ethereal synth riser with a medium energy level, perfect for creating anticipation before a magical transition or reveal."

"key-press": {

"file": "key-press.mp3",

"duration": 0.4,

"description": "This is a medium-energy, distorted digital impact sound effect that works well for a sudden glitch transition or a glitchy text reveal."

"notification": {

"file": "notification.mp3",

"duration": 2.46,

"description": "This is a medium-energy, whimsical digital transition sound effect that fits perfectly with a playful visual reveal or a cute UI interaction."

"ping": {

"file": "ping.mp3",

"duration": 1.32,

"description": "This is a medium-energy, sharp electronic impact sound that works perfectly for punchy transitions or highlighting key on-screen reveals."

"pop": {

"file": "pop.mp3",

"duration": 0.72,

"description": "This is a medium-energy, metallic clinking sound that works perfectly as an accent or a subtle impact for a precise visual reveal or UI element."

"riser": {

"file": "riser.mp3",

"duration": 10.03,

"description": "This is a high-energy cinematic air whoosh transition that builds tension before suddenly cutting, making it perfect for a dramatic scene change or a quick reveal."

"sparkle": {

"file": "sparkle.mp3",

"duration": 1.8,

"description": "This is a bright, high-energy \"whoosh\" transition sound with a fast, ascending pitch that is perfect for a rapid scene change or a quick reveal."

"typing": {

"file": "typing.mp3",

"duration": 1.5,

"description": "This is a hard, high-pitched \"ding\" sound that works well as an accent for a reveal or a quick transition."

"whoosh-cinematic": {

"file": "whoosh-cinematic.mp3",

"duration": 5.54,

"description": "This is a medium-energy, cinematic whoosh effect, ideal for smooth scene transitions or emphasizing a quick reveal."

"whoosh-short": {

"file": "whoosh-short.mp3",

"duration": 0.57,

"description": "This is a medium-energy, organic wooden texture sound effect that works well as a subtle transition or a background accent."

"whoosh": {

"file": "whoosh.mp3",

"duration": 0.57,

"description": "This is a hard, metallic impact sound effect that works well for a sudden reveal or a punchy transition."

}

mdskills/website-to-hyperframes/references/beat-builder-guide.md

20 kB

# Beat Builder Guide

You are building ONE beat of a multi-beat video composition. This file tells you what to read, how to build, how to verify, and how to report back.

## Step 1: Read and understand

**Required (every beat):**

1. **Load the `hyperframes` skill** — composition rules, data attributes, timeline contract, deterministic rendering. Read the whole skill.

2. **[capabilities.md](capabilities.md)** — full inventory of HyperFrames capabilities (24 sections). Read the Table of Contents first, then deep-dive sections your beat needs.

3. **The beat spec** the main agent gave you — concept, choreography, assets, brand values, timing.

**Read based on what your beat needs (pick relevant ones):**

| Resource | What it covers | Read when |

| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |

| [techniques.md](../../hyperframes/references/techniques.md) | 13 primitive animation techniques: SVG path drawing, Canvas 2D, CSS 3D, kinetic type, variable fonts, MotionPath, etc. | Beat uses any of these techniques |

| [text-effects.md](../../hyperframes/references/text-effects.md) | 24 named text animations from `pixel-point/animate-text` (separate skill — load via `/animate-text` for specs) | Beat has text animation |

| [html-in-canvas-patterns.md](../../hyperframes/references/html-in-canvas-patterns.md) | HTML-in-Canvas: iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor | Beat uses device mockups or WebGL effects on HTML |

| [transitions.md](../../hyperframes/references/transitions.md) | Shader transition API, HyperShader.init() pattern, all 14 WebGL shaders | Beat has shader transitions |

| [transitions/](../../hyperframes/references/transitions/) | 14 CSS transition category files: push, scale, dissolve, blur, 3D flip, light leak, distortion, grid, mechanical, destruction | Beat uses CSS transitions |

| [css-patterns.md](../../hyperframes/references/css-patterns.md) | Text markers: highlight sweeps, hand-drawn circles, burst lines, scribble, sketchout | Beat uses text emphasis/markers |

| [audio-reactive.md](../../hyperframes/references/audio-reactive.md) | Bass→scale, mid→shape, treble→glow mappings | Beat reacts to music/audio |

| [captions.md](../../hyperframes/references/captions.md) | Per-word karaoke, tone-adaptive styling, positioning | Beat includes captions |

| [typography.md](../../hyperframes/references/typography.md) | Font hierarchy, variable fonts, responsive type scaling | Beat has complex typography |

| [motion-principles.md](../../hyperframes/references/motion-principles.md) | Velocity matching, easing philosophy, motion continuity | Beat needs polished motion design |

| [dynamic-techniques.md](../../hyperframes/references/dynamic-techniques.md) | Counter animations, data-driven visuals, dynamic content | Beat has counters or data visualization |

| [video-composition.md](../../hyperframes/references/video-composition.md) | Frame composition, color presence, scale, density rules | General composition quality |

**Other skills you can load if needed:**

- `/gsap` or `/gsap-core`, `/gsap-timeline`, `/gsap-plugins` — deeper GSAP reference

- `/animate-text` — curated text animation catalog with exact JSON specs

- `/hyperframes-registry` — if you need to install and wire registry blocks

- `/hyperframes-contrast` — audit color contrast (WCAG)

- `/lottie`, `/three`, `/waapi`, `/animejs`, `/css-animations` — if beat uses these engines

**Always open the captured assets folder before designing the beat:**

- `capture/assets/svgs/` — brand logos, icons, decorative marks. SVGs are infinitely scalable and stroke-animatable (path drawing, dash offset). A logo SVG drawing itself onto frame can carry an entire beat.

- `capture/assets/` — hero illustrations, screenshots, product art, gradients, photography. These are first-class beat subjects, not background decoration. A breathing hero illustration with a single line of kinetic type is a complete shot.

- VIEW every image before placing text on it. Check safe zones, contrast, actual content, where the focal point sits.

**If your beat spec names a captured asset, USE it.** Don't substitute a CSS recreation. The user captured these from the real brand site precisely so the video carries the brand's actual visual identity.

## Step 2: Build the composition

Save to the path the main agent specified (usually `compositions/beat-N-name.html`).

```html

<style>

* {

margin: 0;

padding: 0;

box-sizing: border-box;

}

/* your styles */

</style>

<div

id="beat-N-name"

data-composition-id="beat-N-name"

data-width="1920"

data-height="1080"

style="width:1920px; height:1080px; position:relative; overflow:hidden; background:#YOUR_BG;"

</div>

(function () {

var BEAT = 5.5; // MUST match data-duration on the host div in index.html

window.__timelines = window.__timelines || {};

var tl = gsap.timeline({ paused: true });

// your GSAP animations

window.__timelines["beat-N-name"] = tl;

})();

</script>

</template>

```

**Critical:** `data-composition-id`, `data-width`, `data-height` on the root div MUST match the host div in index.html.

## Step 3: Lint

```bash

npx hyperframes lint .

```

Fix ALL errors. Zero errors required.

## Step 4: Snapshot and verify

```bash

npx hyperframes snapshot . --frames 3

```

**READ the contact sheet** (`snapshots/contact-sheet.jpg`). For each frame:

- Is content visible? (not black, blank, or loading)

- Is text readable, properly positioned, correct font/color?

- Are assets at the right size and position?

- Does the animation state match the beat spec at this timestamp?

**If anything is wrong:** fix, re-snapshot, re-check. You are done ONLY when every frame matches the spec.

## Step 5: Report back honestly

After lint passes, snapshots are taken, and you've fixed every issue you saw — report back to the main agent with concrete observations. Not "0 errors, looks good." That phrasing is what got prior videos shipped with mismatched brand colors, missing logos, and headlines too small to read.

**The main agent will OPEN your composition file and read it top-to-bottom** to cross-check against DESIGN.md and STORYBOARD.md — does the brand bg/accent hex actually appear in your CSS, are the captured assets the storyboard called for actually referenced, is the headline ≥80px, does the GSAP timeline cover the full beat duration. You cannot pass that check by claiming things you didn't do; the file is on disk, the truth is in the file.

So in your report, name the hex codes you used, the captured asset paths you placed, the headline `font-size`, and the GSAP timeline's last `tl.fromTo(...)` timestamp. Brief, concrete, true. If anything diverges from DESIGN.md or the storyboard, say so explicitly — the main agent can decide whether to accept the divergence or send you back to fix it. Surprises caught at this hand-off cost minutes; surprises caught at Step 6 cost iterations.

### FLAG protocol — required phrasing for non-blocking issues

When you find any of these, surface them as **FLAGS** in your report, not as conditional suggestions:

- Visual states that briefly look broken (empty containers, hanging elements, gap moments)

- Spec ambiguities you had to resolve by guessing

- Linter bugs you worked around

- Tween values you changed from the spec because they wouldn't fit

**Forbidden phrasing:** "if the X feels too long, you could...", "consider tweaking Y", "might want to..."

**Required phrasing — concrete, actionable, with line numbers:**

```

FLAG: at beat-local t=1.2s the doc card is visible but its inner content is still

opacity 0 — a 0.4s empty-panel window.

RECOMMENDED FIX: pull title typewriter from 1.6s → 1.4s

in compositions/beat-5-name.html line 234.

```

The main agent MUST EITHER apply each FLAG's fix OR write a one-sentence rejection with reason. Silently dropping a FLAG is a verification failure that gets caught at Step 6 (or worse, in the user's preview).

### Spec ambiguity — escalate, don't paper over

If STORYBOARD.md gives you a transition or transformation but doesn't establish the **start** state, do NOT guess. Examples of ambiguity worth flagging:

- "Row 1 transitions from Huly Blue to Huly Orange at 3.5s" — but Row 1's initial color isn't specified

- "Headline grows" — but the start size isn't specified

- "Cards slide in" — but the off-screen position isn't specified

- "Subhead appears after the headline" — but exact timing offset isn't specified

**Required action:** FLAG the ambiguity in your report verbatim:

```

FLAG: STORYBOARD.md beat 3 says "Row 1 transitions blue → orange at 3.5s" but

Row 1's initial color is not specified anywhere. I interpreted Row 1 starts

blue and tweened to orange. CONFIRM or correct.

```

The main agent then confirms or corrects before Step 6 advances. Picking an interpretation silently means the build looks "fine" while diverging from intent — and the user only notices in motion.

### Sub-agent diagnoses are unverified claims, not facts

When a sub-agent reports "this is a linter false positive" / "this is a known bug" / "this attribute doesn't work as documented" — those are HYPOTHESES, not findings. Sub-agents diagnose from one symptom; they don't have repo-wide context.

Before propagating any sub-agent diagnosis (e.g., applying the same "workaround" to another beat, or telling the user "this is a known bug"), do ONE of:

1. **Verify by reading the source.** Open the file the sub-agent claims is buggy. Confirm the bug exists. Example: "I read `packages/core/src/lint/utils.ts:42` and confirmed the regex matches `url(\"data:image/svg+xml...\")` incorrectly. The workaround is to base64-encode the URI."

2. **Disclose the unverified claim.** Don't suppress it — surface it. Example: "Sub-agent for beat 2 diagnosed `root_missing_composition_id` as a linter false positive on inline SVG data URIs. I applied the same workaround to beat 4 WITHOUT verifying the underlying claim. Worth filing as a regression against `packages/core/src/lint/utils.ts` to confirm."

**Forbidden:** silently adopting the workaround pattern and presenting "lint passes" as evidence. If the workaround came from an unverified diagnosis, "lint passes because the diagnosis was correct AND I worked around it" and "lint passes because the diagnosis was wrong but the workaround happened to make the symptom disappear" are both possible. Without verification, you don't know which. The next session inherits the workaround AND the unverified diagnosis.

### When you accept a sub-agent's divergence from spec — UPDATE the spec

If a sub-agent reports "I diverged from STORYBOARD.md because..." AND you accept the divergence, you MUST update STORYBOARD.md to reflect the actual implementation. Otherwise the spec lies about the artifact.

Examples:

- Sub-agent: "Storyboard says 'HULY' uppercase but the actual logo asset is lowercase 'huly'. I used lowercase." Accept → edit STORYBOARD.md beat N to say "huly" lowercase. Note the change inline.

- Sub-agent: "Storyboard says cells at 56px but they read too small at 1920×1080. I used 96px." Accept → edit STORYBOARD.md beat N's cell size to 96px.

- Sub-agent: "Storyboard says SFX at t=4.7s but the visual moment lands at t=5.2s; I aligned SFX to the visual." Accept → edit STORYBOARD.md SFX line to t=5.2s.

**Forbidden:** accepting the divergence silently and leaving the storyboard with the wrong spec. The next session reading STORYBOARD.md will trust it as ground truth. The spec is a contract; if you break the contract, update the contract.

---

## Continuous motion — the most important rule

A beat is a SHOT in a film, not a webpage with entrance animations. Your GSAP timeline should have events spread across the ENTIRE beat duration — not just entrance tweens in the first 1-2 seconds followed by nothing. If an element is on screen, it should be doing something. After elements enter, add continuous hold motion: camera dolly, parallax layers moving at different speeds, secondary elements appearing mid-beat, real depth shifts.

## You are building a SHOT, not a webpage

The storyboard tells you the shot framing (close-up / medium / wide / etc.) and the camera move. Implement them. A beat is a moment, not a screenshot. The distinction is **what the camera is doing**, not whether the subject is a UI element or a logo — a tight push-in on a real product screenshot is a shot; a centered card on a parked camera is a webpage.

**Patterns that turn a shot back into a webpage:**

These are defaults to avoid, **not absolute prohibitions.** If the storyboard genuinely calls for "the kanban app interface" or "the browser chrome" as the subject of a specific beat (a product tour, a "this is how it works" demo, a stylized window mockup for the closer), then build it. The rule is: don't reach for these patterns by default when the storyboard didn't ask for them.

- ⚠ **macOS / browser window chrome reproduced in CSS** — traffic-light dots, URL bars, browser tabs. Fine when the storyboard makes the chrome the subject (e.g. "stylized macOS window framing the product UI" for a closer). NOT fine when it's a frame you added around a card "to make it look like an app."

- ⚠ **Full webpage layout** (sidebar + header + footer + main content area) — fine when the beat is genuinely a product tour shot. NOT fine when the beat was supposed to be about _the kanban moment_ and you defaulted to drawing the whole app around it.

- ❌ **Parked-camera composition** — centered card with 60–120px margins on all sides and no camera move. Almost always wrong. Either give it a real push-in / dolly / parallax, or reframe.

- ❌ **"Hold with breathing"** implemented as `y: ±1–2px` or `scale: 1.01` — invisible at 1920×1080+ scale. If continuous motion is required, use camera dolly (scale 1.0 → 1.05), parallax pan (x/y ±30–80px), or progressive reveals.

- ❌ **Hover-state simulations** — videos have no hover. If the brand uses hover effects, show the BEFORE and AFTER as discrete frames in the timeline.

- ❌ **Counter pulses + dot pulses + tiny scale wobbles** as the only motion during the hold — these are "I ran out of ideas" filler.

The test: if the storyboard says _"this beat is the product tour, viewer sees the app interface"_, building a CSS dashboard with chrome is correct. If the storyboard says _"this beat is the kanban moment, single card sliding home"_, drawing the full app around it is wrong. Read the beat spec carefully.

**Patterns that ARE shots (do these freely):**

- ✅ **Captured SVG logo drawing itself stroke-by-stroke** (DrawSVG / path dashoffset) — a complete opener or stinger.

- ✅ **Captured hero illustration with camera dolly** — push-in from 1.0 → 1.08 over 4s, focal element holds frame.

- ✅ **Captured product screenshot with parallax layers** — separate the foreground UI from background panels and move them at different speeds, or use HTML-in-Canvas for an iPhone/MacBook mockup.

- ✅ **Captured asset as the bed, kinetic type as the punchline** — the brand's hero image holds the frame while a one-line message arrives, splits, reflows.

- ✅ **Composed-from-divs UI moment** when the beat is specifically about that UI's interaction (a card sliding into a column, a search result resolving) — this is the legit case for CSS-only composition.

**Required motion magnitudes** (anything smaller is invisible at video scale):

| Motion type | Minimum magnitude |

| --------------- | ------------------------------------------- |

| Translate (y/x) | 30px (entrance) / 8px (drift during hold) |

| Scale | 0.05 change (1.0 → 1.05 or larger) |

| Opacity | full 0 → 1 or vice versa for reveals |

| Rotate | 4° minimum to read (Dutch angles, ticks) |

| Camera dolly | scale 1.0 → 1.06 minimum over beat duration |

**Required cinematography per beat** (the storyboard should give you these; if it doesn't, escalate):

- A **shot type** (close-up / medium / wide / over-the-shoulder / Dutch)

- A **camera move** (dolly in/out, push, parallax pan, orbit, rack focus)

- A **depth strategy** (what's foreground / midground / background)

- A **purpose** (what specific feeling or noticing the shot delivers)

If any are missing from the beat spec, the beat is under-defined. Don't fill the gap with "centered layout + breathing" — re-read the spec, and if it's genuinely missing, ask the main agent.

## Rules

- SCRIPT PLACEMENT: scripts inside `<template>`, never after `</template>`. Scripts outside see no DOM.

- GSAP FROM TRAP: never `gsap.from(el, {opacity:0})` with CSS `opacity:0`. It animates 0→0. Use `tl.fromTo()`.

- STYLE: avoid CSS `opacity:0` on GSAP-animated elements. Use GSAP fromTo for initial states.

- ASSET PATHS: project-root-relative. `capture/assets/file.png` ✅ `../capture/assets/file.png` ❌

- SVG VIA IMG: `<img src="logo.svg">` can't inherit CSS color. Inline SVG or `filter: brightness(0) invert(1)`.

- CSS CENTERING: no `transform: translate(-50%, -50%)` with GSAP transforms. Use flexbox or `xPercent/yPercent`.

- QUERYSELECTOR: `document.getElementById("id")` with null guards. No method calls without null check.

- CHARACTER SPANS: `display:inline-block` on spaces collapses them. Use ` ` or per-word spans.

- COUNTERS: no `onUpdate` for numeric counters — use discrete `tl.set(el, {textContent: "42"}, 2.5)` at timestamps. `onUpdate` and `tl.call()` ARE supported for canvas/WebGL rendering loops and character-by-character typing — see capabilities.md §10.

- TIMELINE: `window.__timelines["beat-N-name"] = tl` synchronously. Key = `data-composition-id`.

- DETERMINISTIC: no `Math.random()`, `Date.now()`, `requestAnimationFrame`, `repeat:-1`.

- Always `tl.fromTo()` not `tl.from()` for entrances.

- Never stack two transform tweens on same element at same time.

- FONTS: copy the `@font-face` block VERBATIM from DESIGN.md's Fonts section. Do NOT guess which `.woff2` file belongs to which family — capture filenames are content-hashed (`14d7ce3e41dcbb66-s.p.woff2`) and there is no visible mapping. If DESIGN.md doesn't include exact `src:` paths per family, STOP and ask the main agent to add them; never pair an arbitrary `.woff2` file with a family name from memory.

## Easing — pick per intent

Do NOT default to `power2.out` on everything.

| Intent | GSAP Ease | Use for |

| --------------- | --------------------- | ------------------------------------ |

| Snap (iOS feel) | `power4.out` | Hero text, UI elements |

| Whip overshoot | `back.out(1.7)` | Numbers, badges, impact |

| Soft land | `expo.out` | Per-word reveals, gentle entrances |

| Mechanical | `power1.out` | Terminal text, code typing |

| Bounce settle | `elastic.out(1, 0.5)` | Counters, CTA buttons |

| Dramatic | `expo.inOut` | Full-screen statements, hero reveals |

| Drift | `"none"` | Parallax, Ken Burns, camera drift |

Staggered items: `power4.out` with `stagger: 0.08` to `0.15`.

mdskills/website-to-hyperframes/references/capabilities.md

56 kB

# HyperFrames — Complete Capabilities Inventory

Everything possible in HyperFrames as of today's workspace, synthesized from direct source reads of all 7 packages, 16 skills, and the full registry.

> **How to read this file.** Scan the **Table of Contents** below first. **Do NOT read this file linearly** — it is a 700+ line inventory; reading top-to-bottom every session wastes context. When the storyboard or a specific beat needs a particular capability (HTML-in-Canvas, shader transitions, audio-reactive, dynamic counters, etc.), jump straight to that section.

You are NOT limited to what was captured from the website. You can create shaders from scratch, search for and download registry blocks, build Three.js scenes, write custom WebGL effects, use any web API — anything a browser can render.

For implementation patterns (working code), see `techniques.md`. This file is the WHAT; techniques.md is the HOW.

## Essential Rules

- **Deterministic:** No `Math.random()`, no `Date.now()`, no `requestAnimationFrame`, no `repeat: -1`. The render engine seeks to exact timestamps.

- **Timeline contract:** `window.__timelines["composition-id"] = tl` must be set synchronously. The timeline length defines the composition duration.

- **Sub-compositions:** External `.html` files loaded via `data-composition-src`. Auto-nested timelines, scoped CSS, scoped scripts.

- **Linter:** 60+ rules. Run `npx hyperframes lint` before render. Catches missing timelines, overlapping clips, broken paths, GSAP errors.

## Table of Contents

| # | Section | What it covers |

| --- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| 1 | **Composition fundamentals** | Data attributes, timeline contract, resolution presets (1080p, 4K, portrait, square, custom) |

| 2 | **Animation engines (6 adapters)** | GSAP + 15 plugins, Anime.js v4, CSS @keyframes, WAAPI, Lottie (lottie-web + dotlottie), Three.js (hf-seek event) |

| 3 | **Shader transitions (14 WebGL)** | domain-warp, ridged-burn, whip-pan, sdf-iris, ripple-waves, gravitational-lens, cinematic-zoom, chromatic-split, swirl-vortex, thermal-distortion, flash-through-white, cross-warp-morph, light-leak, glitch — plus custom GLSL |

| 4 | **CSS scene transitions (30+)** | Push/slide, scale/zoom, radial/clip, 3D flip, blur, dissolve, cover/blinds, light leak/burn, distortion/glitch, mechanical/shutter, grid dissolve, destruction/burn, VHS/gravity/morph — 6 timing presets |

| 5 | **Visual effects + textures** | Text markers (highlight, circle, burst, scribble, sketchout), grain/noise, light leaks, film burn, vignette, glow, paper texture, shimmer sweep |

| 6 | **Caption techniques** | Per-word karaoke, intensity tiers, 5 exit styles, 6 tone mappings, per-word styling triggers, 7 audio source formats, positioning helpers |

| 7 | **Audio-reactive animation** | Bass→scale, mid→shape, treble→glow; any GSAP property; band extraction script; banned patterns |

| 8 | **HTML-in-canvas** | Live DOM as GPU texture (drawElementImage), Three.js planes, WebGL shaders on HTML, 7 VFX blocks (iPhone/MacBook device, liquid, glass, magnetic, portal, shatter, text cursor) |

| 9 | **Three.js / WebGL custom scenes** | Full 3D: AnimationMixer, custom GLSL, post-processing, GLTF models, lights, cameras, materials — all deterministic via hf-seek |

| 10 | **SVG / canvas / variable fonts** | SVG path drawing, Canvas 2D procedural art, CSS 3D card, per-word type, variable font axes, character typing, velocity-matched cuts, MotionPath |

| 11 | **Media: video, audio, TTS** | Video compositing + frame injection, audio mixer (multi-track), Kokoro TTS (54 voices, 9 languages), Whisper/Groq/OpenAI transcription, background removal (u2net) |

| 12 | **Registry (51 blocks + 4 components + 8 examples)** | Social overlays (8), showcases (5), data viz (2), logo branding (1), 3D/VFX (7), shader transitions (14), transition galleries (13), components (grain, shimmer, pixelate, texture-mask), 8 starter examples |

| 13 | **CLI (25 commands)** | init, add, catalog, play, preview, publish, render (MP4/WebM/MOV/PNG, HDR, GPU, parallel), lint, validate, inspect, snapshot, capture, tts, transcribe, remove-background, doctor, and more |

| 14 | **Linter (60+ rules)** | Core, media, GSAP, captions, composition, adapters, textures, fonts — plus async URL checks |

| 15 | **Player web component** | `<hyperframes-player>` with seek/play/pause API, 11 events, media mirror, runtime auto-inject |

| 16 | **Engine + Producer** | MP4/WebM/MOV/PNG output, HDR (PQ/HLG), transparency (ProRes), GPU encoding (NVENC/VideoToolbox/VAAPI/QSV), parallel rendering, video frame injection |

| 17 | **Studio (in-browser NLE)** | Timeline editor, drag/resize clips, asset browser, render queue, lint modal, caption editor, element picker |

| 18 | **Determinism guarantees** | No Math.random, no Date.now, no RAF, no repeat:-1, no callbacks, synchronous construction |

| 19 | **Variables / parameterization** | Typed runtime variables (string, color, number, boolean, enum), CLI override, strict validation |

| 20 | **Sub-compositions** | External file or inline template, auto-nested timelines, scoped CSS, scoped scripts, variable inheritance |

| 21 | **Global runtime APIs** | 25+ window globals for timelines, player, variables, adapters, hooks |

| 22 | **Skills (16)** | hyperframes, cli, media, registry, contrast, animation-map, website-to-hyperframes, remotion, gsap, animejs, css-animations, waapi, lottie, three, tailwind, contribute-catalog |

| 23 | **References (15 docs)** | transitions, css-patterns, dynamic-techniques, motion-principles, typography, narration, captions, audio-reactive, transcript-guide, techniques, beat-direction, visual-styles, and more |

| 24 | **Documentation (27 pages)** | Guides + package docs covering rendering, HDR, html-in-canvas, performance, prompting, troubleshooting, etc. |

---

## 1. Composition fundamentals

### Data attributes recognized by the runtime

- **Root composition:** `data-composition-id`, `data-start`, `data-duration`, `data-width`, `data-height`, `data-composition-src` (external sub-comp), `data-composition-duration`, `data-composition-variables` (JSON), `data-variable-values` (override)

- **Every clip:** `id`, `data-start`, `data-duration`, `data-track-index`, `class="clip"`, optional `data-media-start`, `data-volume`, `data-playback-start`

- **Sub-composition host:** `data-composition-id`, `data-composition-src` OR inline `<template id="${compId}-template">`

### Timeline contract

- `gsap.timeline({ paused: true })` registered on `window.__timelines["<composition-id>"]`

- Master clock (TransportClock + WebAudioTransport) drives the timeline via `tl.totalTime(t, false)` or `tl.seek(t, false)`

- Framework auto-nests sub-comp timelines

- Duration sourced from `data-duration` on root, not from GSAP length

- Synchronous timeline construction required (no async/await/setTimeout)

- Looping handled by `<hyperframes-player>`, not GSAP `repeat: -1`

### Resolution presets

VALID_CANVAS_RESOLUTIONS: 1920×1080 default, 1080×1920 portrait, 1080×1080 square, 4K, 1440×2560, plus `normalizeResolutionFlag` for `--resolution` CLI flag.

---

## 2. Animation engines (6 deterministic frame adapters)

The runtime registers these adapters in order; each implements `discover()` / `seek({time})` / `pause` / `play?` / `revert`:

| ---------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |

| GSAP (createGsapAdapter) | The primary timeline + all tweens registered on `window.__timelines[<id>]` | CDN `https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js` | Plugins via standard GSAP register; HyperFrames does NOT patch THREE.Clock (uses `__hfThreeTime` instead) |

| Anime.js v4 (createAnimeJsAdapter) | Anime instances pushed to `window.__hfAnime` | CDN `animejs@4.0.2/lib/anime.iife.min.js` or ESM | Adapter multiplies composition seconds by 1000 for ms |

| Lottie (createLottieAdapter) | `window.__hfLottie` array; supports lottie-web + dotlottie-web | CDN `lottie.min.js` + `@lottiefiles/dotlottie-web` | `goToAndStop(time*1000)` or `setCurrentRawFrameValue` / `seek(%)` |

| Three.js (createThreeAdapter) | `window.__hfThreeTime` + dispatches `CustomEvent("hf-seek", {detail:{time}})` | ESM CDN `three@0.181.2/+esm` | Composition's render loop listens to `hf-seek`; pattern: `mixer.setTime(time)` |

### GSAP plugins (documented patterns)

- **TextPlugin** — text mutation in `tl.call` (skills/gsap/references/effects.md)

- **MotionPathPlugin** — curve-constrained tweens (skills/hyperframes/references/techniques.md)

- **CustomEase** — bezier eases imported from Remotion-style timing

- **ScrollTrigger / Flip / SplitText / Draggable / Inertia / Observer / ScrambleText / CustomWiggle / CustomBounce / ScrollSmoother / GSDevTools** — work natively if loaded and tweens are on the registered paused timeline, but no special HyperFrames adapter

- Producer injects ScrollTrigger CDN automatically when needed (packages/producer/src/services/htmlCompiler.ts)

---

## 3. Shader transitions — @hyperframes/shader-transitions

14 named WebGL fragment shaders. All share the same uniforms: `u_from`, `u_to`, `u_progress`, `u_resolution`, `u_accent`, `u_accent_dark`, `u_accent_bright`.

### The 14 shaders

| Name | Visual | Notes |

| ------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |

| domain-warp | Multi-octave FBM warps both scenes oppositely; organic dissolve edge with accent flash | Uses NQ noise bundle |

| ridged-burn | Ridged multifractal mask reveals B; accent → bright → white burn ramp; sparks | NQ |

| whip-pan | 10-sample horizontal motion blur + lateral crossfade | No noise |

| sdf-iris | Aspect-corrected circle SDF expansion + accent-tinted glow rings | — |

| ripple-waves | Radial standing-wave UV displacement + tinted crossfade | — |

| gravitational-lens | Pinch pull toward center + R/B chromatic separation | — |

| cinematic-zoom | 12 RGB-offset radial zoom blur samples (chromatic zoom streak) | — |

| chromatic-split | R/B radial channel shift outward / inward; G fixed | Distinct from CSS chromatic aberration |

| swirl-vortex | CCW swirl with FBM noise; reciprocal on incoming | NQ |

| thermal-distortion | Vertical sin + FBM horizontal displacement; warm haze | NQ |

| flash-through-white | Fade through white midpoint — a visible white flash between scenes | No accent. Use only when the brand specifically calls for a white-flash beat boundary; this is NOT a neutral "default" transition. |

| cross-warp-morph | FBM vector field displaces both scenes; third FBM biases irregular wipe | NQ |

| light-leak | Fixed off-frame leak with exponential falloff + accent warmth + ridge flare | Hard-coded leak anchor |

| glitch | Line displacement + RGB lateral split + scan modulation + posterization + flicker | Deterministic |

### Public API

```js

HyperShader.init({

bgColor: "#0b0f14",

accentColor: "#f59e42",

scenes: ["scene1", "scene2"],

transitions: [{ time: 3, shader: "sdf-iris", duration: 0.65, ease: "power2.inOut" }],

timeline: gsap.timeline({ paused: true }),

compositionId: "main",

previewCaptureFps: 30,

});

```

- Capability probe: `isHtmlInCanvasCaptureSupported()` (Chrome layoutSubtree/drawElementImage)

- Tuning: `?__hf_shader_capture_scale=` (0.25–1), `?__hf_shader_loading=` (internal|player|none)

- Cache: IndexedDB for PNG snapshots; max 2 textured transitions live at once

- Fallback (`applyFallbackTransition`): smoothstep opacity tween when capture / texImage2D fails

- Engine mode skips GL/capture when `window.__HF_VIRTUAL_TIME__` set (producer uses metadata)

You can also **write custom GLSL shaders from scratch** — any fragment shader works with the standard uniforms.

---

## 4. CSS scene transitions (30+ named patterns)

Documented in skills/hyperframes/references/transitions/ across 14 category files. All GSAP-driven, none mixable with shader transitions in same composition.

### By category

| Category | Patterns |

| -------------------------------- | ------------------------------------------------------------------------------------------------ |

| Push / slide (css-push.md) | Push slide, vertical push, elastic push, squeeze |

| Scale / zoom (css-scale.md) | Zoom through, zoom out, scale-up swap |

| Radial / clip (css-radial.md) | Circle iris, diamond iris, diagonal split |

| 3D (css-3d.md) | 3D card flip, hinge door |

| Blur (css-blur.md) | Crossfade, blur crossfade, focus pull |

| Dissolve (css-dissolve.md) | Color dip (gap-to-black), staggered color blocks (2-block, 5-block) |

| Cover (css-cover.md) | Horizontal blinds, vertical blinds (variable strip counts: 6 / 12 / 20) |

| Light (css-light.md) | Light leak overlays, overexposure burn, film burn |

| Distortion (css-distortion.md) | Glitch (CSS — RGB layer jitter), chromatic aberration, ripple |

| Mechanical (css-mechanical.md) | Shutter (two-half), clock wipe (9-point rotating wedge) |

| Grid (css-grid.md) | Grid dissolve (12 or 120 cells), grid pixelate wipe |

| Destruction (css-destruction.md) | Page burn (SVG clip-path + canvas char rim) |

| Other (css-other.md) | VHS tape (strip-based seeded jitter), gravity drop, morph circle, blur through, directional blur |

| Rejected | Star iris, tilt-shift, lens flare (don't use — non-CSS-realistic) |

### Timing presets

| Preset | duration | ease |

| -------- | -------- | ---------------------- |

| snappy | 0.2s | power4.inOut |

| smooth | 0.4s | power2.inOut |

| gentle | 0.6s | sine.inOut |

| dramatic | 0.5s | power3.in → power3.out |

| instant | 0.15s | expo.inOut |

| luxe | 0.7s | power1.inOut |

---

## 5. Visual effects + textures

### Marker/emphasis patterns (css-patterns.md)

| Mode | What it does | Implementation |

| --------- | --------------------------------- | ----------------------------------------- |

| highlight | Yellow bar wipes behind text | CSS bar + GSAP scaleX 0→1 |

| circle | Hand-drawn red ring around word | CSS border ellipse + back.out scale |

| burst | 12 radial spikes from word center | DOM line array, --len/--angle vars |

| scribble | Wavy underline drawn over time | SVG `<path>` quadratic + stroke-dash GSAP |

| sketchout | Cross-hatch x-out over text | Two 2px rotated lines |

### Grain / noise

- **grain-overlay** (registry component): SVG feTurbulence data-URL + CSS keyframe jitter, `steps(1)`, default opacity 0.15

- **Layered radial-gradient grain** (preferred pattern): no SVG, no canvas-taint, fast everywhere

### Light / film

- Light leak transitions (CSS + shader variants)

- Overexposure burn — `brightness()` ramp + flash overlay

- Film burn — multi-layer amber/orange/red radials

- Vignette — radial-gradient overlay

- Paper texture (in registry/examples/warm-grain/)

### Glow

- Caption text glow: textShadow radius keyed to treble bands (always on active words only, never parents)

- Radial glow backgrounds: CSS gradients / blurred blobs

---

## 6. Caption techniques

### Animation styles

- Baseline: per-word karaoke highlight (every energy level)

- Intensity tiers: accent + glow + 15% scale (high energy) → 3% scale (low energy)

- Exits by energy (dynamic-techniques.md): scatter, drop, collapse, fade+slide, fade

- Tone mappings (captions.md): scale-pop `back.out(1.7)`, fade+slide `power3.out`, typewriter, bounce, `elastic.out`, word-by-word

### Per-word styling triggers

- Brand/product names

- ALL CAPS

- Numbers / stats

- Emotional keywords

- CTAs

- Marker highlight modes (5 listed above)

### Audio sources for caption timing

| Source | Format | Granularity |

| ------------------------------------------ | -------- | ----------------- |

| hyperframes transcribe (local whisper.cpp) | JSON | Word-level |

| OpenAI verbose_json | JSON | Word-level |

| Groq verbose_json | JSON | Word-level |

| Manually authored | JSON | Word-level |

| SRT | text | Phrase-level only |

| VTT | text | Phrase-level only |

| hyperframes tts → transcribe chain | wav→json | Word-level |

### Positioning helpers

- Landscape: bottom 80–120px centered

- Portrait: ~600–700px from bottom

- `window.__hyperframes.fitTextFontSize(text, {maxWidth, fontFamily, fontWeight})` for dynamic sizing

---

## 7. Audio-reactive animation

### Data shape

```js

window.AUDIO_DATA = {

fps: 30,

totalFrames: 900,

frames: [{ bands: [0.42, 0.18, ...] }] // bands normalized 0–1 per band across track

};

```

Index 0 = bass, higher = treble. Bands range 0–1, normalized across full track length.

### Mappings documented

| Band | Property |

| --------------------- | ---------------------------- |

| Bass (bands[0–1]) | scale (pulse) |

| Mid (bands[4–8]) | borderRadius, width |

| Treble (bands[12–14]) | textShadow, boxShadow (glow) |

| Overall amplitude | opacity, y, backgroundColor |

Any GSAP-tweenable property is fair game — including clipPath, filter, SVG attrs, CSS variables.

### Extraction

```bash

python3 .../extract-audio-data.py audio.mp3 --fps 30 --bands 8

```

Pre-extracted only — no Web Audio at render time.

### Banned in audio-reactive

EQ bars, spectrum UI, generic waveforms, note clip-art, generic particles, rainbow cycling, white strobe on beats, abstract pulsing orbs.

---

## 8. HTML-in-canvas

Documented in skills/hyperframes/references/html-in-canvas-patterns.md (504 lines).

### Capability

- Chrome's experimental `layoutSubtree` + `drawElementImage` rasterizes live DOM into canvas

- Feature detection: `isHtmlInCanvasCaptureSupported()`

- Used by shader-transitions for scene textures

- Combined with Three.js: `CanvasTexture` + post-processing

### Available patterns

- HTML on a Three.js plane (displacement, distortion, liquid sim)

- HTML in shaders (texture sampling for VFX)

- Recursive HTML-in-canvas-in-shader-in-HTML

### Experimental VFX blocks using this

- `vfx-iphone-device` (GLTF iPhone + MacBook, HTML screens)

- `vfx-liquid-background` (liquid sim displaces HTML)

- `vfx-liquid-glass`

- `vfx-magnetic`

- `vfx-portal`

- `vfx-shatter`

- `vfx-text-cursor` (chromatic edges, canvas post)

---

## 9. Three.js / WebGL custom scenes

### Integration pattern

```js

window.addEventListener("hf-seek", (e) => {

const time = e.detail.time;

mixer.setTime(time);

shaderUniforms.u_time.value = time;

renderer.render(scene, camera);

});

```

- Load: `import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm"`

- Deterministic: every frame must derive from `time`, never `requestAnimationFrame` / `Date.now()`

- Includes: AnimationMixer, custom GLSL shaders, post-processing, GLTF models, lights, cameras, materials

---

## 10. SVG / canvas / variable fonts (other authored techniques)

(From skills/hyperframes/references/techniques.md)

| Technique | Mechanism |

| ------------------------ | ------------------------------------------------------------------------------------ |

| SVG path drawing | `strokeDasharray` + `getTotalLength()` + GSAP stroke offset |

| Canvas 2D procedural art | Seeded hash function + `tl.to` proxy `{time}` onUpdate |

| CSS 3D card | GSAP `rotationY` + `perspective: 900` |

| Per-word kinetic type | GSAP timings array, sliding decay |

| Variable font axes | Animate CSS vars → `font-variation-settings: "opsz" var(--opsz), "wght" var(--wght)` |

| Character typing | `tl.call` text mutation + `steps(1)` cursor blink |

| Velocity-matched cuts | Match outgoing blur/translate velocity to incoming for seamless beats |

| MotionPathPlugin | `gsap.registerPlugin(MotionPathPlugin)` + path string |

---

## 11. Media: video, audio, TTS

### Video compositing

- `<video muted playsinline data-start="..." data-duration="..." data-track-index="..." src="...">`

- HyperFrames extracts frames at render via videoFrameInjector (avoids unreliable headless `<video>` playback)

- Linter forbids `<video>` with audio at the same time — split into separate `<video muted>` + `<audio>`

- Video frame extraction uses FFmpeg

- HDR videos: PQ or HLG transfer detection + x265 with mastering metadata

### Audio mixer

- `<audio id="..." data-start="..." data-duration="..." data-volume="0.8" data-track-index="2" src="...">`

- Multiple tracks mixed with `amix normalize=0` + per-track adelay + volume

- Master audioGain from EngineConfig

- Output: AAC 192kbps

### TTS (Kokoro-82M, local)

- 54 bundled voices with prefixes: `a` American EN, `b` British EN, `e` Spanish, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Brazilian Portuguese, `z` Mandarin

- Default voice: `af_heart`

- Speed: 0.1–3.0 (default 1.0)

- Languages: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh (non-EN needs system espeak-ng)

- Output: WAV; no pitch/volume CLI flags

- No API key required

### Transcription

- Whisper.cpp models: tiny, base, small, medium, large-v3, small.en, medium.en (default small)

- Groq API: whisper-large-v3 with word granularities

- OpenAI API: whisper-1 verbose_json

- Imports: SRT, VTT, JSON formats

- Quality gates: music-token detection, garbage cleaning, retry with medium.en

### Background removal

- u2net ONNX models

- Devices: auto / cpu / coreml / cuda

- Quality presets: fast / balanced / best

- Outputs: transparent WebM, ProRes MOV, PNG sequence

- Optional dual output (foreground + extracted background)

---

## 12. Registry — 51 blocks + 4 components + 8 examples

### Blocks by category

**Social overlays (8):** instagram-follow, tiktok-follow, yt-lower-third, x-post, reddit-post, spotify-card, macos-notification, blue-sweater-intro-video

**Showcases (5):** app-showcase (3D phones), north-korea-locked-down (map + annotation), apple-money-count (counter + SFX), vpn-youtube-spot (app-store scroll), nyc-paris-flight (map + plane path)

**Data viz (2):** data-chart (animated bar+line, NYT-style), flowchart + flowchart-vertical (decision tree with SVG connectors, typing correction)

**Logo / branding (1):** logo-outro (build + glow + tagline + URL pill)

**3D / experimental VFX (8):** ui-3d-reveal, vfx-iphone-device (GLTF), vfx-liquid-background, vfx-liquid-glass, vfx-magnetic, vfx-portal, vfx-shatter, vfx-text-cursor

**Single shader transitions (14):** one block per named shader — domain-warp-dissolve, ridged-burn, whip-pan, sdf-iris, ripple-waves, gravitational-lens, cinematic-zoom, chromatic-radial-split, glitch, swirl-vortex, thermal-distortion, flash-through-white, cross-warp-morph, light-leak

**Transition galleries (13 showcase pieces):** transitions-3d, transitions-blur, transitions-cover, transitions-destruction, transitions-dissolve, transitions-distortion, transitions-grid, transitions-light, transitions-mechanical, transitions-other, transitions-push, transitions-radial, transitions-scale

### Components (4 reusable snippets)

- **grain-overlay** — SVG feTurbulence + CSS keyframes

- **shimmer-sweep** — Light sweep gradient mask on text

- **grid-pixelate-wipe** — Grid squares stagger fade scene wipe

- **texture-mask-text** — Luminance-masked letterforms with 66 mask PNGs (Masonry, Stone, Ground/Road, Wood, Metal, Organic/Soft texture categories)

### Examples (8 starter projects)

warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph

Install: `npx hyperframes add <name>` for blocks/components, `hyperframes init <dir> --example <name>` for examples.

---

## 13. CLI — 25 commands

| Command | Purpose |

| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

| init | Scaffold project from template/example (interactive or --non-interactive) |

| add | Install registry block / component |

| catalog | Browse registry blocks/components (--type, --tag, --json, --human-friendly picker) |

| play | Lightweight browser player (default port 3003) |

| preview | Studio dev server (port 3002; --force-new, --list, --kill-all) |

| publish | Zip + upload + return hyperframes.dev URL |

| render | Render to MP4 / WebM / MOV / PNG sequence — flags: --fps 24/30/60, --quality draft/standard/high, --workers, --docker, --hdr/--sdr, --crf, --video-bitrate, --gpu, --browser-gpu auto/software/hardware, --max-concurrent-renders 1-10, --variables JSON, --variables-file PATH, --strict-variables, --resolution preset |

| lint | Static lint (--json, --verbose) |

| validate | Bundle + headless Chrome + console + contrast (--contrast default true, --timeout 3000) |

| inspect / layout | Visual layout audit (overflow detection at N timestamps; --samples 9, --at, --tolerance 2, --max-issues 80) |

| info | Print project metadata |

| compositions | List compositions (root + sub-comps) |

| benchmark | 5 preset configs × N runs (--runs 3) |

| browser | Manage Chrome (ensure/path/clear) |

| remove-background | u2net + FFmpeg → transparent video |

| transcribe | whisper.cpp or import SRT/VTT/JSON |

| tts | Kokoro-82M (--voice, --speed, --lang, --list) |

| docs | Print bundled markdown topics (data-attributes, examples, rendering, gsap, troubleshooting, compositions) |

| doctor | Environment checklist (Node, CPU, memory, disk, FFmpeg, FFprobe, Chrome, Docker) |

| upgrade | npm update check + optional global install |

| skills | Run `npx skills add heygen-com/hyperframes --all` |

| telemetry | enable/disable/status |

| snapshot | PNG screenshots at timeline timestamps |

| capture | Capture URL → site assets + screenshots + design tokens (uses Puppeteer + optional Gemini vision) |

### Website capture (`hyperframes capture <url>`)

Detects these libraries on captured sites (for context labeling): GSAP / ScrollTrigger, Three.js, Lottie, Anime.js, PixiJS, Babylon.js, Rive, Matter.js, Lenis, Framer Motion, Tailwind CSS, WebGL (shader fingerprinting). Captured outputs feed the website-to-hyperframes skill workflow.

---

## 14. Linter — 60+ rules

Across 8 files in packages/core/src/lint/rules/:

| Rule file | Catches |

| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

| core | Missing composition-id, missing dimensions, missing timeline registry, registry mismatch, invalid script syntax, scoped-CSS issues, non-deterministic code |

| media | Duplicate media id, video missing muted, video nested in timed element, placeholder URLs, base64 prohibited, missing src/start/id, imperative play()/pause()/seek() |

| gsap | Overlapping tweens, exit missing hard kill, GSAP animating .clip element, unscoped selectors, CSS transform conflict, missing GSAP script, infinite repeat (repeat: -1), repeat ceil overshoot, scene layer visibility kill, audio-reactive single-tween-per-group |

| captions | Caption exit missing kill, text overflow risk, transcript not inline, parse error, container position, scale mismatch, textShadow on parent container |

| composition | File too large, dense tracks, missing class="clip", deprecated data-layer/data-end, split attribute selectors, external script deps, RAF in composition, invalid variable JSON |

| adapters | Missing Lottie script, missing Three script |

| textures | Drop-shadow on text, class missing base, text missing mask, unknown texture class |

| fonts | Google Fonts import (use @font-face), font-family without @font-face |

Plus async URL checks (`lintMediaUrls`, `lintScriptUrls` — HEAD probes).

`validateCompositionGsap` also forbids: `Math.random`, `Date.now`, `new Date`, `setTimeout`, `setInterval`, `requestAnimationFrame`, `repeat: -1`.

**Note:** `onUpdate` callbacks, `tl.call()`, and GSAP event callbacks (`onComplete`, `onStart`, etc.) are NOT banned by the linter — they are required for canvas/WebGL rendering and character-by-character typing patterns. The linter only catches the determinism violations listed above.

---

## 15. Player — `<hyperframes-player>` web component

### Attributes

`src`, `srcdoc`, `width`, `height`, `controls`, `muted`, `volume`, `poster`, `playback-rate`, `audio-src`, `shader-capture-scale`, `shader-loading` (internal|player|none), `loop`, `autoplay`, `speed-presets`

### Public API

`seek(t)` (synchronous when same-origin — uses `iframe.contentWindow.__player.seek` directly), `play()`, `pause()`, `currentTime`, `duration`, `paused`, `ready`, `playbackRate`, `iframeElement`

### Events

`ready`, `timeupdate`, `play`, `pause`, `ended`, `volumechange`, `ratechange`, `shadertransitionstate`, `playbackerror`, `error`, `audioownershipchange`

### Media mirror

Parent audio/video elements with `data-start` are proxied; `_mirrorParentMediaTime` corrects drift; `_audioOwner` promotes to parent if autoplay blocked.

### Runtime auto-inject

Loads `RUNTIME_CDN_URL` (`@hyperframes/core/dist/hyperframe.runtime.iife.js`) if missing `__hf`/`__player` but timelines exist.

---

## 16. Engine + Producer — rendering pipeline

### Output formats

mp4, webm, mov, png-sequence — with HDR (PQ / HLG / SDR / auto-detect), transparency (ProRes MOV / WebM / PNG), or standard 8-bit SDR

### Encoding controls

- `--fps`: 24 / 30 / 60

- `--quality`: draft / standard / high

- `--crf`: integer (mutually exclusive with `--video-bitrate`)

- `--video-bitrate`: e.g. `8M`

- `--gpu`: NVENC, VideoToolbox, VAAPI, QSV

- `--browser-gpu`: auto / software / hardware

- `--workers`: parallel render workers

- `--max-concurrent-renders`: 1–10 (sets `PRODUCER_MAX_CONCURRENT_RENDERS`)

- `--resolution`: preset (1080p, 4k, portrait, etc.)

- `--docker`: render inside Dockerfile.test image (reproducibility)

- `--hdr` / `--sdr`: force HDR or SDR pipeline

### Engine subsystems

- Frame capture: BeginFrame on Linux headless-shell (fast, no alpha) or `Page.captureScreenshot` (alpha + supersample)

- Video frame injector: pre-extracts video to images, swaps `<video>` for `<img>` during capture (LRU cache by path + byte budget)

- Audio mixer: FFmpeg-based; per-track delay, volume, master gain, AAC 192k output

- Chunk encoder: H.264 / H.265 / VP9 / ProRes presets with optional GPU

- Streaming encoder: `streamingEncodeMaxDurationSeconds` for long renders

- HDR compositing: `rgba16float` WebGPU readback (headed Chrome), PQ OETF helpers

- Layer compositor: groups DOM by z-order; splits HDR elements into separate layers

- Alpha blit: matrix3d affine extraction, `blitRgba8OverRgb48le`, `blitRgb48leAffine`

- Parallel coordinator: concurrency, coresPerWorker, minParallelFrames, largeRenderThreshold

- Browser pool: optional with timeout configs

### Producer-only

- `RenderConfig` with `hdrMode` (auto / force-hdr / force-sdr), `outputResolution` mapped to `deviceScaleFactor`

- File server injects `HF_EARLY_STUB`, `HF_BRIDGE_SCRIPT`, virtual-time so `window.__hf` bridges `window.__player.renderSeek`

- HDR-aware shader transition compositing via `window.__hf.transitions` metadata

---

## 17. Studio — in-browser NLE

Full editor in packages/studio/:

- **NLELayout**: NLE preview + timeline + controls

- **Timeline**: clip rendering, drag to move (`data-start`), resize (`data-duration`), `data-track-index` reassignment, asset drop, file drop

- **PlayerControls**: scrub, play, pause, frame step (`stepFrameTime`), `STUDIO_PREVIEW_FPS`

- **useTimelinePlayer**: resolves `__player` / `__timeline` / `__timelines`

- **LeftSidebar**: compositions list, asset browser

- **RenderQueue + useRenderQueue**: queue multiple renders

- **LintModal**: in-app lint output

- **MediaPreview + AudioWaveform**: waveform rendering

- **CaptionOverlay, CaptionTimeline, CaptionPropertyPanel**: caption editor

- **useCaptionSync**: word-level sync

- **useElementPicker**: click-to-inspect picker mode

- Built with Tailwind v3 (separate from Tailwind v4 browser runtime used by compositions).

---

## 18. Determinism guarantees

- No `Math.random()` (use seeded PRNGs; mulberry32 is the pattern in skills)

- No `Date.now()` / `new Date()`

- No `setTimeout` / `setInterval` in timeline construction

- No `requestAnimationFrame` (timeline-driven; engine seeks per frame)

- No `repeat: -1` (calculate exact repeats: `Math.ceil(duration / cycleDuration) - 1`)

- No `onComplete`/`onStart`/`onRepeat` callbacks (engine doesn't fire them). **Exception:** `onUpdate` and `tl.call()` ARE supported — they're required for canvas/WebGL rendering, character-by-character typing, and counter patterns. See §10 (Canvas 2D procedural art) for the documented pattern.

- No `gsap.set` on clips from later scenes (use `tl.set(selector, vars, position)`)

- Synchronous timeline construction (no async)

- Master clock can clamp at composition end

---

## 19. Variables / parameterization

Compositions support typed runtime variables:

```html

<html

data-composition-variables='[

{"name":"brand","type":"string","default":"Stripe"},

{"name":"primary","type":"color","default":"#635BFF"},

{"name":"duration","type":"number","default":15},

{"name":"darkMode","type":"boolean","default":false},

{"name":"layout","type":"enum","options":["hero","split","stacked"]}

></html>

```

Access via `window.__hyperframes.getVariables()`. Override at render time:

```bash

npx hyperframes render --variables '{"brand":"Linear","primary":"#5E6AD2"}'

npx hyperframes render --variables-file vars.json

npx hyperframes render --strict-variables # error if unused / mismatched

```

`validateVariables()` checks values against declarations at the CLI/tooling boundary.

---

## 20. Sub-compositions

Two loading mechanisms:

- **External file:** `data-composition-src="compositions/act-1.html"` — fetched at runtime

- **Inline template:** `<template id="<id>-template">` — extracted by `loadInlineTemplateCompositions`

Each sub-comp:

- Has its own `data-composition-id`

- Has its own `window.__timelines[<id>]`

- Auto-nested into the root timeline

- Scoped CSS via `scopeCssToComposition` (`[data-composition-id="<id>"]` selector)

- Wrapped scripts via `wrapScopedCompositionScript`

- Reads `data-variable-values` merged with own defaults into `window.__hfVariablesByComp[<id>]`

- External scripts load with `EXTERNAL_SCRIPT_LOAD_TIMEOUT_MS` timeout. Failed loads emit `external_composition_load_failed` / `external_composition_script_load_issue` diagnostics.

---

## 21. Global runtime APIs (`window.*`)

| Global | Purpose |

| ------------------------------------- | ----------------------------------------------------------------------- |

| `__hyperframes` | `{ fitTextFontSize, getVariables }` |

| `__timelines` | `{ [compositionId]: GsapTimeline }` |

| `__player` | Internal player bridge: seek, play, pause, renderSeek, etc. |

| `__clipManifest` | Computed clip array (for Studio) |

| `__playerReady` | Resolved when player ready |

| `__renderReady` | Resolved when ready for render capture |

| `__HF_PARITY_MODE` | Engine parity flag |

| `__HF_FPS` | Render FPS hint |

| `__HF_MAX_DURATION_SEC` | Engine clamp |

| `__HF_VIRTUAL_TIME__` | Set by engine in render mode (shader-transitions switches paths) |

| `__hfThreeTime` | Current time for Three.js adapter |

| `__HF_PICKER_API` | Element picker hook for Studio |

| `__hfAnime` | Array of Anime.js instances |

| `__hfLottie` | Array of Lottie animations |

| `__hfVariables` | Resolved root variables |

| `__hfVariablesByComp` | Per-composition variable map |

| `__hfRuntimeTeardown` | Cleanup function |

| `__tailwindReady` | Tailwind browser build ready (gates capture) |

| `__hf.transitions` | Shader transition metadata (read by producer for HDR-aware compositing) |

| `__beforeTimeline`, `__afterTimeline` | Optional user hooks |

| `__afterRender`, `__beforeRender` | Optional user hooks |

| `gsap`, `THREE`, `anime`, `lottie` | Library globals |

Control bridge actions: play, pause, seek, set-muted, set-playback-rate, enable-pick-mode, disable-pick-mode, set-volume, set-media-output-muted.

---

## 22. Skills available — 16

| Skill | Purpose |

| ------------------------- | ----------------------------------------------------------------------- |

| hyperframes | Core framework skill (composition authoring) |

| hyperframes-cli | All CLI commands as an agent skill |

| hyperframes-media | Media workflows (TTS, transcribe, captions integration) |

| hyperframes-registry | Installing blocks/components |

| hyperframes-contrast | WCAG audit (scripts/contrast-report.mjs) |

| hyperframes-animation-map | Per-tween bbox + flags report |

| website-to-hyperframes | Capture → DESIGN.md → brief → storyboard+script → VO → build → validate |

| remotion-to-hyperframes | Migration patterns + API map + CustomEase |

| gsap | GSAP API + plugins reference |

| animejs | Anime.js v4 patterns |

| css-animations | @keyframes patterns |

| waapi | Web Animations API |

| lottie | Lottie integration |

| three | Three.js + deterministic seek |

| tailwind | Tailwind browser runtime v4 |

| contribute-catalog | Adding blocks to registry |

---

## 23. References inventory (skills/hyperframes/references/)

16 reference docs covering:

- text-effects.md — 24 named text animation effects (per-character, per-word, per-line, whole) — vocabulary reference for the separate `pixel-point/animate-text` skill (load it via `npx skills add pixel-point/animate-text` or `/animate-text`). Specs live in that upstream skill, not in this repo.

- transitions.md + transitions/catalog.md + 14 category subfiles

- css-patterns.md (marker patterns)

- dynamic-techniques.md (caption animation)

- motion-principles.md (easing as emotion, choreography)

- typography.md (banned-font list, pairing rules, variable fonts)

- narration.md (script + VO pacing)

- captions.md (caption authoring contract)

- audio-reactive.md (band mappings + extraction)

- transcript-guide.md (whisper, Groq, OpenAI workflows)

- techniques.md (the big technique catalog — SVG, canvas 2D, 3D, kinetic, lottie, variable fonts, MotionPath, audio-reactive)

- beat-direction.md, design-picker.md, prompt-expansion.md, video-composition.md

- visual-styles.md (8 named visual styles: Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut — available via the `visual-style` skill)

---

## 24. Documentation pages (docs/)

27 mdx pages in docs/guides/ and docs/packages/:

**Guides:** 4k-rendering, claude-design, common-mistakes, deploy, gsap-animation, hdr, html-in-canvas, hyperframes-vs-remotion, open-design, performance, prompting, remove-background, rendering, timeline-editing, troubleshooting, video-editor-cheatsheet, website-to-video, etc.

**Packages:** cli.mdx, core.mdx, engine.mdx, player.mdx, producer.mdx, studio.mdx

mdskills/website-to-hyperframes/references/step-0-capture.md

4.0 kB

# Step 0: Capture

The capture pipeline downloads the site and extracts structured data for the rest of the workflow to read. Step 0 is a single command plus a sanity check. **All analysis (reading files, viewing contact sheets, deriving brand voice, picking assets) happens in Steps 1–3, not here.**

## Run the capture

No API keys required for the base capture. However, before running, ask the user:

> "For the best results, it is recommended to set a Gemini API key — it gives me AI-powered descriptions of every captured image, which helps me choose the right assets for each scene. It costs about $0.001 per image. You can skip this if you want, but the video quality will be better with it. To set it up: add `GEMINI_API_KEY=your-key` to a `.env` file in the project root. You can get a free key at ai.google.dev."

If the user provides the key or already has one set, proceed. If they skip it, proceed anyway — the capture works without it, but `asset-descriptions.md` will have DOM-context descriptions only (position, size, alt text) instead of AI vision descriptions.

Create a project directory for your video if it doesn't exist yet, then capture the website into a `capture/` subfolder within it:

```bash

npx hyperframes capture <URL> -o <project-dir>/capture

```

Example: `npx hyperframes capture https://stripe.com -o videos/stripe-launch/capture`

Keeping capture artifacts (`screenshots/`, `assets/`, `extracted/`, `AGENTS.md`, `CLAUDE.md`) in a dedicated `capture/` subfolder keeps them isolated from later build files (`SCRIPT.md`, `STORYBOARD.md`, `DESIGN.md`, `compositions/`, `index.html`, `narration.wav`, `transcript.json`, `renders/`, `snapshots/`), which all live at `<project-dir>/` root.

For exploratory captures that aren't becoming a video yet, `-o captures/<name>` at the repo root is fine — the isolation convention only matters when you're building a video on top of the capture.

## Confirm it succeeded

Wait for the capture to complete. Print one line summarizing what was captured:

> "Captured N screenshots, M assets, K SVGs, F fonts. Ready for Step 1."

If the command exited non-zero, the counts are all zero, or required directories (`extracted/`, `assets/`, `screenshots/`) are missing, surface the error and stop — don't advance to Step 1 with a broken capture.

## What lives in `capture/` (reference table — DO NOT read these here)

Each downstream step reads only what it needs. Don't pre-fetch everything in Step 0; that bloats context and produces summaries that get stale by the time they're used.

| Path | First read in |

| ----------------------------------------- | --------------------------------------------- |

| `capture/extracted/tokens.json` | Step 1 (DESIGN.md — colors / fonts) |

| `capture/extracted/design-styles.json` | Step 1 (DESIGN.md — typography / components) |

| `capture/extracted/fonts-manifest.json` | Step 1 (font identification) |

| `capture/extracted/asset-descriptions.md` | Step 2 (brief grounding) and Step 3 (assets) |

| `capture/extracted/visible-text.txt` | Step 2 (brief) and Step 3 (script) |

| `capture/assets/contact-sheet-*.jpg` | Step 3 (asset picking) |

| `capture/assets/svgs/contact-sheet-*.jpg` | Step 3 (SVG / logo picking) |

| `capture/screenshots/contact-sheet-*.jpg` | Step 3 (visual mood reference) |

| `capture/extracted/animations.json` | Step 3 / Step 5 (only if site has animations) |

| `capture/extracted/lottie-manifest.json` | Step 3 (only if site uses Lottie) |

| `capture/extracted/video-manifest.json` | Step 3 (only if site embeds video) |

| `capture/extracted/shaders.json` | Step 3 / Step 5 (only if site has WebGL) |

| `capture/assets/<individual files>` | Step 5 (only when placing a specific asset) |

## Gate

Capture exits 0. Asset / screenshot / font counts non-zero. Proceed to Step 1.

mdskills/website-to-hyperframes/references/step-1-design.md

20 kB

# Step 1: Write DESIGN.md (the brand-truth cheat sheet)

DESIGN.md is a **brand-truth cheat sheet** — colors and fonts you'll **weave into your composed builds**. It is NOT a layout spec, not a moodboard, not a 400-line design system audit.

DESIGN.md is the brand inflection sub-agents apply when building each beat: which color is "primary," which font is for headlines, what tone the brand carries — the load-bearing knobs they flip while building.

**Target length: 250–350 lines.** Step 5 sub-agents read DESIGN.md to brand each beat — the more precise the component CSS values you encode here, the more brand-faithful the result. Going under 200 lines tends to produce generic dark-cinematic output because sub-agents have no brand component DNA to work from; going over 350 means you're over-investing in prose.

**Fast-pacing exception:** For billboard-per-beat videos (short social ads where each beat is a single hero element on full-bleed background), a 50-line DESIGN.md with just colors + fonts + 3-5 do's/don'ts is enough. The Step 5 sub-agent prompt pastes brand values inline, so DESIGN.md depth only matters when the beats render full UIs.

**User preferences always override brand rules.** If the user says "make it bright even though the site is dark" or "use serif fonts even though the brand is sans" — follow the user. DESIGN.md describes the captured website. The video might deliberately break that.

**Read these now** — they're the inputs DESIGN.md is built from. Don't guess colors or sizes from screenshots:

- `capture/extracted/tokens.json` — top brand colors (HEX) and font families with weight ranges.

- `capture/extracted/design-styles.json` — computed CSS values from the live DOM: typography hierarchy (font-size, weight, line-height, letter-spacing per text role), button variants (background, padding, radius, shadow), card/container/nav styles, spacing scale, border-radius scale, box-shadow values with usage counts. **Primary data source for Sections 3–6 below.**

**Font availability check — do this before writing anything else.** Read `capture/extracted/fonts-manifest.json`. The capture pipeline reads the OpenType `name` table embedded in every downloaded font file, so even hash-renamed Next.js/Webpack fonts are identified by their real family name (Inter, JetBrains Mono, Geist Mono, etc.). No guessing required.

The manifest gives you two views:

- `families[]` — one entry per distinct family with the weights captured, whether it's a variable font, and the files belonging to it

- `files[]` — one entry per downloaded font with family, subfamily, weight, style, and any variation axes

**How to use it:**

- For each family you'll reference in DESIGN.md, name it by what's in `families[].family` (e.g. "Inter", not "f266e704 hashed font"). The hashed filenames are the `@font-face src` paths — they stay as-is on disk; only the display name comes from the manifest.

- If a family has `variable: true` and `variationAxes` includes `"wght"`, you can use any weight 100-900 via `font-variation-settings: 'wght' <value>` even if only one static weight appears in the captured files. Note this in DESIGN.md so sub-agents know they have the full weight range available.

- If the manifest's `unidentified[]` is non-empty, those files failed name-table extraction (rare — heavily subset fonts that strip metadata). Flag them as `unknown` in DESIGN.md and suggest a fallback rather than guessing.

- Commercial fonts hosted on brand CDNs (GT Walsheim, Söhne, Graphik, Canela) won't be in the manifest because they aren't downloaded. Detect this by checking what the site uses (from `design-styles.json`) against what's in the manifest — anything used but missing is a CDN-hosted font. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."

Sub-agents try to use the fonts you list. The manifest tells you exactly what's available — there's no excuse for claiming "Charlie Display 700" when no such file exists.

---

## The 5 sections to write

### `## 1. Visual Theme (one paragraph)`

3–5 sentences describing the brand's visual personality. Cover: dark-first or light-first, contrast strategy, dominant visual elements (gradients, illustrations, photography, UI mockups), overall mood, what makes it distinctive vs. generic.

This is the only prose section. Make it specific to _this_ brand — not template-filling. A sentence that could describe any well-designed website is not useful.

**Example:**

> Stripe's visual language is light-first and clean, with deep navy (`#061B31`) and pure white as the foundation. The accent stack — Stripe Purple (`#533AFD`) for CTAs, Vibrant Orange (`#FF6118`) for energetic emphasis — keeps interactive elements unmistakable. Type is sohne-var Light (300) for display, weight 400 for body; the brand achieves hierarchy through size and weight, never color shifts. The mood is confident financial-tech — premium without theatrical drama. Distinctive: gradient overlays at 135° between purple and orange appear as subtle washes over white backgrounds, never as bold focal elements.

---

### `## 2. Quick Reference`

A flat lookup of the values sub-agents grab while composing beats. Two sub-sections — keep them tight.

#### Colors

List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.

**For each text-on-surface combination the brand uses, compute the WCAG AA contrast ratio and flag failing pairings explicitly.** A real failure mode from prior runs: the brand's secondary-text color (`#68686A`) on its dark panel color (`#18191B`) = 3.16:1, which fails AA's 4.5:1 minimum. Sub-agents faithfully reproduced the brand's color choice and the result was unreadable. Encode the safe / unsafe pairings here so sub-agents pick text colors by surface context, not by "this is the brand's secondary text color." The `/hyperframes-contrast` skill audits ratios — run it before finalizing DESIGN.md.

**Example:**

```markdown

#### Colors

- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal

- On Pure White: 6.2:1 ✅ — On Deep Navy: 3.8:1 ⚠ AA-only-Large

- **Deep Navy** (`#061B31`): Primary text on light surfaces, also a dark surface tier

- As text on Pure White: 17.4:1 ✅ — As surface: see Slate-on-Navy pairings below

- **Pure White** (`#FFFFFF`): Page background, card surfaces

- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)

- **Slate Blue** (`#273951`): Secondary text on LIGHT surfaces

- On Pure White: 12.6:1 ✅ — On Light Gray: 11.8:1 ✅ — On Deep Navy: 1.4:1 ❌ DO NOT USE

- **Light Slate** (`#64748D`): Metadata, captions on light surfaces only

- On Pure White: 4.8:1 ✅ — On Light Gray: 4.5:1 ✅ — On Deep Navy: 3.0:1 ❌ — On Dark Panel: 2.9:1 ❌

- **For dark-surface metadata, use `#9A9A9E` instead: 6.4:1 on Deep Navy ✅, 6.1:1 on Dark Panel ✅**

- **Subtle Border** (`#D4DEE9`): Card borders, dividers (not text — borders don't need AA)

- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary text)

- **Error Red** (`#FF0022`): Validation errors. On Pure White: 4.5:1 ✅

- **Success Green** (`#4CD963`): Confirmation states. On Pure White: 1.7:1 ❌ — must be paired with a darker outline or use as accent on dark surfaces

```

**Where the brand's own palette fails WCAG**, document the substitute (like the `#9A9A9E` override above). Sub-agents pick the safe color by surface — and if the deviation matters to the brand identity, the user can revisit at Step 6.

#### Fonts

List font families with their role AND **the exact file path per family + weight** from `fonts-manifest.json`. Sub-agents will copy the `@font-face` block verbatim — if you only name the family without the path, sub-agents have to guess which `.woff2` file belongs to which family and get it wrong half the time (a real failure mode from prior runs: agents pointed `@font-face` for "ES Build Neutral" at the Inter `.woff2` files and the wordmark rendered in Inter).

**Example:**

````markdown

#### Fonts

- **Display:** `"ES Build Neutral"` — wordmarks, headlines

- 600: `capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2`

- 700: `capture/assets/fonts/e8b276476c0ac6fa-s.p.woff2`

- **Body:** `"Inter"` (variable 100–900, captured ✓) — body, labels, UI

- 400: `capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2`

- 600: `capture/assets/fonts/1b0b3615811be75b-s.p.woff2`

- **Mono:** `"JetBrains Mono"` — code, metadata

- 400: `capture/assets/fonts/c7d2e9f5a1b3c8d4-s.p.woff2`

- **Fallback stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`

**`@font-face` block to paste in every composition** (sub-agents copy this verbatim — do not invent file paths):

```css

@font-face {

font-family: "ES Build Neutral";

src: url("capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2") format("woff2");

font-weight: 600;

font-display: block;

}

@font-face {

font-family: "Inter";

src: url("capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2") format("woff2");

font-weight: 400;

font-display: block;

}

/* + any other family/weight combinations the storyboard's beats need */

```

````

The brand uses **size for hierarchy, weight for emphasis**. Display 1: 48px/600, Display 2: 32px/600, Body: 14px/400. (Adjust to the actual brand's hierarchy.)

````

The exact `@font-face` block lets sub-agents copy verbatim instead of constructing one from inference. If a beat needs a weight that isn't in the manifest, flag it explicitly here: e.g., "ES Build Neutral 900 NOT in capture; use ES Build Neutral 700 as substitute, or fall back to Inter 700."

That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read `design-styles.json` directly.

---

### `## 3. Component Stylings` (the build-step's spec sheet)

This is the section sub-agents consult most when building beats in Step 5. **Without exact per-component CSS, sub-agents fall back to generic "dark bg + glow + centered text" patterns regardless of brand** — which is why every video starts looking the same. Encode the brand's actual component DNA here.

Target **6-12 distinct components**. Document what the site actually uses; skip categories the brand doesn't have. For each component, name it descriptively ("Stripe Primary Button" not "Button 1") and provide exact CSS-level properties: background, text color, padding, border-radius, border, font size/weight, height, box-shadow, and any hover/active/disabled states.

#### Buttons (always required)

Cover every variant the site uses — typically Primary, Secondary/Ghost, and Icon. **Example:**

```markdown

#### Primary Button (Stripe Purple)

- **Background:** `#533AFD`

- **Text color:** `#FFFFFF`

- **Font:** sohne-var 16px / 400

- **Padding:** `15.5px 24px 16.5px 24px`

- **Border radius:** `4px`

- **Border:** none

- **Height:** `48px` (with padding)

- **Box shadow:** none

- **Hover:** background `#4329E8`, opacity `0.95`

- **Active:** background `#3720D4`, scale `0.98`

- **Disabled:** background `#C9C3F0`, cursor `not-allowed`

#### Secondary Button (outline)

- **Background:** `#FFFFFF`

- **Text color:** `#533AFD`

- **Border:** `1px solid #533AFD`

- **Padding / radius / font:** same as Primary

- **Hover:** background `#F3F0FF`, border `#4329E8`

#### Ghost Button (text-only link)

- **Background:** transparent

- **Text color:** `#533AFD`

- **Font:** sohne-var 14px / 400

- **Padding:** `12px 0`

- **Hover:** background `rgba(83, 58, 253, 0.08)`, optional underline

````

#### Cards & Containers (always required if the site uses any)

Document each distinct card type — Standard, Feature Highlight, Glass, Pricing, Testimonial — whatever this brand actually uses. **Example:**

```markdown

#### Standard Card

- **Background:** `#FFFFFF`

- **Border:** `1px solid #D4DEE9`

- **Border radius:** `5px`

- **Padding:** `32px`

- **Box shadow:** `0 1px 2px rgba(0, 0, 0, 0.04)` (default), `0 4px 12px rgba(0, 0, 0, 0.08)` (hover)

- **Hover:** border `#B8CCDB`

#### Feature Highlight Card (gradient backdrop)

- **Background:** linear-gradient(180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)

- **Border:** `1px solid #E5EDF5`

- **Padding:** `36px`

- **Box shadow:** none

```

#### Distinctive components (anything else the brand actually shows)

Logo marquees, testimonial carousels, pricing tables, gradient overlays, glassmorphism panels, bento grids, code blocks, terminal UIs, dashboard mockups — name and document anything visually distinctive. Sub-agents will reach for these specs when the storyboard calls for a beat featuring the X.

```markdown

#### Glass Container (frosted overlay)

- **Background:** `rgba(255, 255, 255, 0.9)`

- **Border:** `1px solid rgba(255, 255, 255, 0.2)`

- **Backdrop filter:** `blur(8px)`

- **Use:** floating chat widgets, modal overlays, hero callouts only — the only place transparent fills appear in the system

```

**The rule:** if a sub-agent in Step 5 has to invent CSS values for a component this brand actually uses, you under-documented this section. The values should be lookup-able, not guessable.

---

### `## 4. Spacing & Layout`

The brand's rhythm. Three sub-sections, kept tight.

#### Spacing scale

Identify the **base unit** (typically `4px` or `8px`) and the full scale with usage context. **Example:**

```markdown

**Base unit:** `4px`

| Token | Value | Used for |

| ----- | ------- | --------------------------------------------------------- |

| xs | `4px` | Inline icon gaps, tight badge padding |

| sm | `8px` | Button-group gaps, small component padding |

| md | `16px` | Card padding, form-field gaps, standard component spacing |

| lg | `32px` | Section vertical spacing, large card padding |

| xl | `60px` | Major section separation |

| 2xl | `100px` | Page-level rhythm, hero section padding |

Never use odd values (`13px`, `17px`) — the system only uses multiples of 4.

```

#### Border-radius scale

Every radius the site uses, with what uses it.

```markdown

- `0px`: Form labels, technical UI markers

- `4px`: Primary buttons, inputs, small badges

- `8px`: Standard cards, dropdowns

- `12px`: Feature cards, larger callouts

- `40px`: Icon buttons (square pill)

- `9999px`: Pill-shaped CTAs, status chips

```

#### Whitespace philosophy (one paragraph)

How does this brand use whitespace — generous and architectural? Tight and information-dense? Section gaps in the 60–100px range, or 20–40px? Document the brand's actual rhythm.

```markdown

Generous whitespace as confidence. Section gaps are always `60–100px`. Content never touches viewport edges — minimum `40px` horizontal padding on mobile, `80–160px` on desktop. The brand uses negative space as active design, not emptiness.

```

---

### `## 5. Iteration Guide` (the load-bearing section)

5–10 numbered rules that encode the most important brand decisions. Each rule is a **single actionable sentence stating what to do, with the specific values from this site.** These are the "if in doubt, do this" rules sub-agents consult while composing beats.

**The single most common failure mode is writing generic rules that could apply to any well-designed website.** A rule that doesn't name a specific value, a specific color, or a specific component this brand actually uses is doing nothing.

**Test for any rule you write:** can you swap this brand for a different brand and have the rule still make sense? If yes, it's too generic. If no, ship it.

#### ❌ Generic vs ✅ site-specific

| Generic (delete) | Site-specific (keep) |

| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| Use the primary brand color for CTAs. | All primary CTAs use Stripe Purple (`#533AFD`). Secondary actions use white background with `#533AFD` border + text. **There is no third button color anywhere in the system.** |

| Maintain visual hierarchy through color contrast. | Body text is `#000000` on white, `#FFFFFF` on dark. Metadata uses `#64748D` on white only — never on dark. The brand has no mid-gray text on dark backgrounds. |

| Use clear typographic hierarchy. | All type is sohne-var. H1 `48px`/300, H2 `32px`/300, body `14px`/400. **Never use weights above 400** — this brand has no bold variant. |

| Use consistent spacing. | Spacing is from a fixed scale: `4, 8, 12, 16, 20, 24, 32, 40, 60` px. Section gaps are always `60–100px`. Card padding is always `32px`. No exceptions. |

| Buttons should have rounded corners. | Buttons are `40px` tall minimum, `4px` radius, `15.5px 24px` padding. Pill-shape `9999px` radius is reserved for the floating chat trigger only. |

#### One worked example (Framer — 5 rules)

```markdown

### Iteration Guide

1. **All interactive elements use Framer Blue (`#0000EE`)** — links, primary buttons, active states, focus indicators. Secondary uses `#0099FF` for hover. **No other interactive color exists in the system.**

2. **Typography: GT Walsheim Medium for headings, Inter for body.** Hierarchy enforced through size only, never color. H2 `62px`, H5 `85px`, body `14px`, labels `12px`/500. Text defaults to `#000000` on white, `#FFFFFF` on dark.

3. **Spacing is base-4** — every margin / padding / gap is a multiple of `4px`. Section gaps `60–100px`. **Never use odd values like `13px` or `17px`** — the system has no place for them.

4. **Cards: white (`#FFFFFF`), `1px` border `#EFEFEF`, `8px` radius, `16–20px` padding, no shadow by default.** Dark-mode cards swap to `#1A1A1A` background with `#242424` border. Shadow only appears on hover.

5. **Glass containers** use `rgba(255,255,255,0.9)` background, `1px` border `rgba(255,255,255,0.2)`, optional `backdrop-filter: blur(8px)`. **These are the only place transparent fills appear** — everywhere else uses solid color.

```

If your draft has a rule like "all interactive elements require visible focus states for accessibility" — delete it. Not wrong, just not load-bearing for _this_ brand.

---

## Rules

- Use **exact values** from `capture/extracted/tokens.json`. Cross-reference with screenshots when needed.

- Name colors and components descriptively — "Stripe Purple" not "Accent 1."

- When you can't extract exact values, estimate from visual inspection and note it.

- No "Assets" section — `capture/extracted/asset-descriptions.md` is the asset index.

- No "Motion" section — the storyboard specifies motion per-beat.

- No separate "Components" section — Quick Reference is where components live.

- No "Depth & Elevation" tables — shadow language is implied by the brand's mood (heavy shadows for premium, no shadows for flat/clean); sub-agents pick appropriate values without a table.

---

## Quick User Check (before moving to Step 2)

30-second sanity check before Step 2:

> "Here's what I extracted as [Brand Name]'s visual identity:

> - **Colors:** [primary], [accent], [2-3 others with roles]

> - **Fonts:** [headline font], [body font]

> - **Tone:** [1 sentence on the brand feel]

> Does this match how you want the video to feel? Any corrections or overrides before I start the storyboard?"

If the user has corrections ("use the blue, not the gray" / "ignore the dark mode" / "we just rebranded, use [these values] instead") — update DESIGN.md now. One minute here saves thirty minutes of rebuilding.

---

## What makes a useful DESIGN.md

A sub-agent reading just your Quick Reference + Iteration Guide should be able to:

1. Pick the right color for any primary action, secondary action, body text, error state

2. Pick the right font/weight/size for any headline, body, metadata

3. Know which 2-3 rules they cannot break without losing the brand

That's the test. If they can answer those three questions from a 60–120 line doc, you've nailed it. If they need to read 400 lines of mood-board prose to find a color, you've buried the signal.

mdskills/website-to-hyperframes/references/step-2-brief.md

14 kB

# Step 2: Strategy & Messaging

**First, scan the Table of Contents in [capabilities.md](capabilities.md)** — the 24-row TOC tells you everything HyperFrames can do. You need this to tell users what's possible. Deep-dive specific sections only if a beat needs them.

You've captured the site and you now understand the brand — what the product does, who it's for, what voice it speaks in, what mood it lives in. Before any creative decisions, **align with the user on the story this video must tell.** Captured assets exist as a brand toolkit you'll reach for late in Step 3; they are not what the conversation in this step is about.

**Parse the user's prompt first.** Read what they already told you — video type, style, specific requests, duration. Only ask about things they DIDN'T specify. If they said "product demo, show me the kanban board and chat, moderate pace" — that's most of the brief already. Don't ask "what type of video?" when they literally said "product demo."

Skip questions the user already answered. Ask only what's missing. If the prompt is detailed enough to build from, confirm the direction in one message and move to Step 3. The goal is to fill gaps, not interrogate.

---

## What to Ask

Before asking the user anything, ground yourself in the brand: skim `DESIGN.md` (just written in Step 1) for colors / fonts / voice; read `capture/extracted/asset-descriptions.md` for what visual assets exist; skim `capture/extracted/visible-text.txt` for what the site says about itself. Don't summarize all of it back to the user — that's noise; they captured the site, they know what's there. Use it to draft a tight one-paragraph framing of the brand and proceed to the questions.

Engage the user with the questions below. Use your agent's question/answer UI if available (multi-choice with custom option). If not, ask conversationally.

### Question 1: What's this video for?

Present options based on what makes sense for the captured site:

**Example (Not a required options)**

- **Social ad** (15–20s) — Instagram, TikTok, LinkedIn. Fast, punchy, hook in first 2s.

- **Product demo** (30–60s) — Walk through key features. Narrated, professional.

- **Launch teaser** (15–25s) — Build hype for a new feature or product. Dramatic reveal.

- **Brand reel** (20–45s) — Showcase the brand identity. Visual-forward, minimal narration.

- **Feature announcement** (15–30s) — Highlight a specific feature or update.

- Or describe something else.

This determines duration, beat count, narration density, and overall energy.

### Question 2: What style/vibe?

Ask the user to describe what they want — or react to concrete framings that describe motion and energy, not aesthetic presets.

Do NOT present a labeled menu of styles with pre-filled descriptions ("Cinematic = dark + glow + Apple keynote energy"). Those descriptions become the brief even when they don't match the brand. "Cinematic" for a wellness brand should look completely different from "cinematic" for a security tool — but a label with a baked-in description collapses that distinction.

Instead, ask them approachable open-ended questions:

> "A few questions to get the direction right:

> - **Pace:** Should the video move slowly and let moments breathe, or be fast and punchy? Or somewhere in between?

> - **Mood:** What atmosphere matches how you want viewers to feel — dark and dramatic, clean and light, energetic and vibrant, or something else?

> - **Narration:** Should a voice guide viewers through the video, or let the visuals carry it?

> - **Anything specific?** Any moments, techniques, or references you're drawn to? Or say 'surprise me' and I'll work from what I found in the capture."

Their answers modify the brand-derived baseline you built in Step 1. When the user's words conflict with the brand, don't blindly override — let the brand and their direction converge. If the conflict is sharp (user says "dark cinematic" for a brand whose entire identity is white-and-pastel light), surface it and ask before resolving.

### Question 3: What's the ONE thing this video must communicate?

This is the strategy question. Every effective marketing video has a single core message — the one idea that has to land. Every beat serves that idea, or it doesn't belong. Get the user to articulate this BEFORE talking about visuals, assets, or specific scenes.

Frame it like this:

> "From your site, here's the brand frame I'm working from:

> - **What the product does:** [one sentence from the site summary — not features, the actual job]

> - **Audience:** [who it's for, derived from copy and visual tone]

> - **Brand voice:** [confident / playful / clinical / urgent / premium — what tone the brand speaks in]

> Before we plan visuals, two questions to anchor the story:

> 1. **What's the ONE thing this video must communicate?** If a viewer remembers only one sentence after watching, what should it be? (the value prop, a launch announcement, a specific feature claim, a brand feeling, a problem-solution pair, etc.)

> 2. **What's the narrative shape?** Possible arcs: _Problem → Solution_ (most demos), _Reveal_ (launches, teasers), _Demonstration_ (feature showcase, walkthroughs), _Vibe piece_ (brand reels — feeling over information), _Comparison_ (vs. competitor / before-after). Pick or describe your own.

> Either give me your own answers, or say 'surprise me' and I'll make the call based on the brand and what you said in Question 1 ([video type])."

Once those answers exist, **then** sketch the composed-beat directions — but ground each one in the message and arc, not in the asset list:

> "Given [the message] and [the arc], here's how I'd shape it:

> - [Compose-first sketch grounded in the answer to Q1, e.g., "Open with the problem stated as kinetic typography — 'You waste 4 hours a week on context switches.' Cut to a composed kanban board where cards animate from chaos into organization. Close on the brand mark + tagline."]

> - [Alternative sketch with a different arc, e.g., "Reveal arc: dark canvas → particles converging → product wordmark drawn stroke-by-stroke as the first feature lands. No problem statement — pure announcement energy."]

> - [If user wants demo: "Three composed UI panels — kanban, AI chat, command palette — each in your palette with the brand logo stamped top-left. Narration walks through each. Closer holds the wordmark."]

> Brand accents I could layer in: [list 1-3 captured assets that *might* earn a place: the SVG logo for opener/closer, a hero illustration as a depth layer in one scene, a gradient image as an ambient bg wash. Note these are candidates, not assignments — most beats won't need any.]"

**Important:** Lead every direction with **what the beat communicates**, then with **how it's built** (which primitives). The narrow no-go: if your first instinct is "the product-UI screenshot flies in," flip it — compose the UI from divs and CSS instead. That's the slideshow pattern this skill exists to break. For captured logos, illustrations, and hero art, no flip is needed — they're valid primary visuals when the concept calls for them.

The captured assets are a brand toolkit you reach for late in the storyboard, where they serve the concept — never as the starting point of the concept itself.

Present options:

- **I have specific ideas** — let me describe them

- **Surprise me** — you make the creative calls, I'll review the storyboard

- **Let me see some options first** — propose 2–3 different creative directions and I'll pick

### Question 4: Narration?

Not every video needs a voiceover. Ask:

- **Yes, with narration** — a voice guides the viewer through the video (most product demos, launch teasers, feature announcements)

- **No narration, visual-only** — music/SFX only, the visuals tell the story (brand reels, social ads, music-driven pieces)

- **Minimal narration** — just a hook sentence or tagline, rest is visual (short social ads, teasers)

This decision changes the pipeline:

- **With narration:** Step 3 includes a full script. Step 4 generates TTS, transcribes, maps timestamps to beats.

- **Without narration:** Step 3 has no script (VO cues in storyboard are empty). Step 4 is skipped — beat durations are planned manually in the storyboard based on rhythm and pacing.

### Question 5 (if applicable): Format?

Only ask if not already specified by the user:

- **Landscape** (1920×1080) — YouTube, LinkedIn, website embeds (default)

- **Portrait** (1080×1920) — Instagram Stories, TikTok, YouTube Shorts

- **Square** (1080×1080) — Instagram feed, Twitter/X

---

## How to Handle Responses

### "Surprise me" / minimal direction

When the user gives no creative direction, default to what the brand's visual identity and the video's purpose suggest. The minimum context you need before defaulting: **where the video is going** (social feed / landing page / pitch deck / TV ad) and **who it's for** (developers / consumers / enterprise / general audience). If either is missing, ask once — "where will this run, and who's the audience?" — then proceed.

With that minimum in hand, still write an ambitious storyboard. "Surprise me" means "impress me," not "play it safe." Go bold.

**Autonomous mode propagates — for user-preference gates only.** When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills downstream user-preference 💬 gates: Step 3's storyboard approval, Step 4's TTS provider choice, music yes/no, captions yes/no. Make those creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.

**Auto mode does NOT skip quality-verification gates.** These run regardless and must produce evidence in your final summary:

- Asset Audit (Step 3) — view contact sheets, justify USE/SKIP per asset

- Per-beat HTML evidence block (Step 5)

- DoD checklist (Step 6) — animation-map, per-warning WCAG verification, audio + motion playback (or explicit "deferred" disclosure)

- "What I did NOT verify" disclosure (Step 6)

**Test for "preference vs quality gate":** if the answer changes the _content_ of the video (which voice? captions on? beat 3 cinematic or fast?), it's a preference — auto mode decides. If the answer is "did the verification happen?", it's a quality gate — auto mode does NOT apply. Reasoning "auto mode says bias toward action, so I'll skip the contact sheets" misuses auto mode.

### Specific direction

If they say something vague ("make it really cool"), push back gently:

> "I want to make sure I nail what you're imagining. When you say 'cool' — do you mean: dramatic/cinematic(slow reveals and dark atmosphere)? Or high-energy (fast cuts and bold motion)? Or something else entirely?"

### Mixed direction

Parse each component separately. "Minimal but with cinematic transitions and a fast feature section" becomes:

- **Base style:** Minimal (moderate pacing, minimal density, elegant motion)

- **Transitions override:** Dramatic (shader effects for key moments)

- **Beats 3–5 override:** Fast pacing, balanced density, energetic motion

Note these per-beat overrides — they go into the storyboard.

### "Let me see options"

Propose 2–3 brief creative directions (3–4 sentences each) with different **narrative arcs** — what story the video tells, not what assets it shows. Each option leads with the message and the arc; visuals are composed scenes that serve them.

> **Option A — Problem → Solution (cinematic, narrated):** Open with the problem stated as kinetic typography over a dark canvas with a single accent glow. Cut to a composed kanban board where chaotic cards animate into organized columns as narration lands the value prop. Closer: brand mark drawn stroke-by-stroke on a shader bloom of the brand gradient. Apple-keynote register. ~25s with full VO.

> **Option B — Reveal arc (announcement, music-led):** Cold open: particles converging in darkness, no copy. The product wordmark draws itself across the frame as the first beat lands. Three composed feature panels each unveiled by a hard cut — kinetic typography labels, brand color washes, no screenshots. Closes on the mark + tagline + macOS hint. ~15s, music-driven, minimal narration.

> **Option C — Demonstration (narrated walkthrough):** Three composed UI scenes — kanban from cards-as-divs, AI chat with typewriter narration sync, command palette with character-typed search — each in the brand palette with the captured logo stamped top-left as identity. CSS crossfades between. Narration walks each one. ~35s, full VO.

Each option states: the arc, the primary visuals carrying it (composed or captured — whichever fits the beat), and any brand accents layered on top. **Never** an option whose primary content is a pasted product-UI screenshot — if you find yourself writing one, flip it: name what gets composed instead. Captured SVGs, illustrations, hero art, and brand photography are fine as primary visuals when the concept calls for them.

Let the user pick one or combine elements.

---

## Gate

Lock all of these before moving to Step 3. The first three are the strategic frame Step 3 builds the storyboard from — without them, the storyboard cannot land.

1. **Message** — the ONE thing this video must communicate, in a single sentence. (Required. Step 3 fails without this.)

2. **Narrative arc** — Problem→Solution / Reveal / Demonstration / Vibe / Comparison / custom. (Required.)

3. **Audience** — who's watching, where they're watching. (Required.)

4. **Video type** — social ad / product demo / launch teaser / brand reel / feature announcement / etc. Infer from prompt.

5. **Duration** — infer from type if not stated (demo: 30-45s, social: 15-20s, teaser: 15-25s).

6. **Style direction** — pace / mood / specifics — from the user's words, layered onto the brand baseline from Step 1.

7. **Specific requests** — any scenes/effects/beats they explicitly asked for.

8. **Narration** — yes / no / minimal.

9. **Format** — landscape unless specified otherwise.

**Do not ask the user to confirm what they already said.** If the prompt was "make a product demo for huly.io, show the kanban board, dark cinematic feel, full narration" — you already have type (demo), style (dark cinematic), specific requests (kanban board), and narration (full). Still need to derive or ask: the **message** ("the everything app for teams that hate context switches"), the **arc** (Demonstration), and the **audience** (small teams / fast-moving orgs). Proceed to Step 3 only when all 9 are locked.

mdskills/website-to-hyperframes/references/step-3-storyboard.md

47 kB

# Step 3: Storyboard + Script

Marketing videos are made concept-first. **The order is: message → narrative arc → beats that serve the arc → which assets and techniques bring each beat to life.** Captured assets (SVG logos, brand illustrations, hero art, gradients) are first-class beat content alongside composed beats — many of them will carry their own beats. The constraint is only that you shouldn't _start_ from the asset inventory ("we have these screenshots, let's build a slideshow"). Start from the message, then weave in the right captured assets and the right composed elements per beat.

**Read `capture/extracted/asset-descriptions.md` before writing beats.** Know what's in the capture. The brand's actual visual identity — its real logo, its real illustrations, its real gradients, its real hero art — is what makes the video feel like _this_ brand and not a generic dark cinematic template. Most beats will use one or two captured assets layered with composed motion.

## First decision: CONCEPT

Before pacing, before beats, before anything else — write the concept block at the top of `STORYBOARD.md`. Carry forward what was decided in Step 2's brief:

```markdown

**Message:** [the ONE thing this video must communicate — one sentence]

**Arc:** [Problem→Solution / Reveal / Demonstration / Vibe / Comparison — and a one-sentence shape of how it unfolds]

**Audience:** [who's watching, where they're watching — TikTok scrollers, LinkedIn viewers, embedded on landing page]

**Brand voice:** [confident / playful / clinical / urgent / premium — pulled from DESIGN.md]

**Why this matters now:** [GTM context if relevant — launch, feature ship, brand reposition, ongoing demo]

```

If any of those rows are blank, the storyboard cannot land. Go back to the brief — don't substitute "show the kanban" for a message.

**The single-sentence test:** _"What makes this video different from a generic [video type] for any [industry] brand?"_ If you can't answer it from the rows above, the concept isn't sharp enough. Sharpen it before writing pacing or beats.

---

## Second decision: PACING

With the concept locked, pick the pacing that serves it. This determines beat count, beat duration, and architecture — every downstream choice flows from here.

Read the message and arc from the concept block above plus the style direction from Step 2's brief. Map to one of these:

| ----------------------------------------------------------- | ------------ | ---------- | ------------- | ---------------------------------------------------------- |

**Write your pacing choice at the top of STORYBOARD.md.** Example: `**Pacing: Fast** — 12 beats, stacked divs, hard cuts.`

If the user said "dark cinematic feel" — that's SLOW, not fast. If they said "rapid cuts, bold typography" — that's FAST. Don't default to moderate when the prompt gives you a clear signal.

---

## Technique-pick checklist (REQUIRED, do this BEFORE writing beat copy)

For every beat you plan, name **2–4 techniques** it will use. A beat with one technique is a slideshow frame — if you can't name two, redesign that beat.

Pick from the inventory in [capabilities.md](capabilities.md) and implementation patterns in [techniques.md](../../hyperframes/references/techniques.md). Examples of composable beats:

```

Beat 3: composed kanban (4 cards-as-divs per column) + counter chip on In-Progress + back.out entrance stagger

techniques: layered panels (capabilities §1), counter via tl.set (techniques #15),

GSAP stagger with back.out(1.7) (techniques #4)

customize: real project name "Atlas Q3", brand purple #5b3fff, realistic backlog items

```

**Customize is the actual deliverable** — what makes this beat THIS brand's beat. Brand colors, real content, narration-sync timing. Generic "show the kanban" with no concrete techniques, no customize plan, no brand-specific data = lazy thinking. Beats must be invented from this brand's identity, not assembled from generic UI shapes.

---

**Re-read these files before writing:**

- **DESIGN.md** — your color palette, font rules, components, Do's/Don'ts. Every visual must be grounded in this brand identity. If it says "white backgrounds with purple accent" — plan light scenes, not dark moody ones.

- **Asset discovery — view the contact sheets carefully, every cell.** Open `capture/assets/contact-sheet-*.jpg` and `capture/assets/svgs/contact-sheet-*.jpg`. Both are paginated — view every page (`contact-sheet-1.jpg`, `contact-sheet-2.jpg`, etc.). **For each page, name 5 specific assets you can see before moving on.** Past agents have reported "viewed the contact sheet" after one glance and then wrote beats referencing assets that didn't exist or missed the brand logo entirely. Don't be that agent. When you find an asset that earns its place in a beat, note the filename from the label and reference it as `capture/assets/<filename>`. If a thumbnail is too small to judge resolution / fine detail, open the individual file. Also read `capture/extracted/asset-descriptions.md` for one-line summaries. **Never use contact sheets or scroll screenshots in the video itself** — contact sheets have grid labels baked in; scroll screenshots are raw browser captures. Both are for AI to BROWSE and understand the site, not to place in compositions.

- **[techniques.md](../../hyperframes/references/techniques.md)** — 13 primitive animation techniques with code patterns. Pick for beats, these are starting points to adapt, not templates to copy.

- **[text-effects.md](../../hyperframes/references/text-effects.md)** — 24 named text animation effects from the separate `pixel-point/animate-text` skill. The reference page tells you how to load the upstream skill; the IDs are listed inline. Assign a specific effect ID to every headline, label, and copy element in every beat — not generic "fades in" descriptions.

The storyboard is the creative north star. It tells the engineer exactly what to build for each beat — mood, camera, animations, transitions, assets, appearance, sound. Write it as if you're briefing a motion designer who's never seen the website.

**Incorporate the user's specific requests.** If they asked for "a 3D MacBook reveal" — that's in the storyboard. If they said "surprise me" — go ambitious, but just stay within the style direction.

Save as `STORYBOARD.md` in the project directory.

---

## Consider: Would Research Improve This Video?

Before diving into beats, pause and think: **would focused research make this video meaningfully better?**

This is NOT always needed. A simple social ad for a SaaS product probably doesn't need market research. But some videos benefit from context the website alone doesn't provide:

**Research when:**

- The video is for a competitive market — look at how competitors present their product, what visual language the industry uses, what trends are hot

- The video represents a company/product you know little about — search for reviews, press coverage, user opinions, company history to understand what matters to their audience

- The user asked for something specific to their field — a fintech launch video benefits from understanding how Stripe, Ramp, Mercury position themselves visually

- The video needs to reference real-world data, trends, or context not on the website

**Skip research when:**

- It's a straightforward brand reel or social ad from a clear website

- The user gave very specific creative direction ("I want exactly X, Y, Z")

- The website already contains all the context needed (features, stats, testimonials)

**What to research:** Competitor videos in the space, trending visual styles for the industry, audience expectations, any company context that helps you make better creative decisions. A 2-minute web search can give you the edge between a generic video and one that feels like it was made by someone who understands the market.

---

## Global Direction

Every STORYBOARD.md starts with global settings:

```markdown

**Format:** 1920×1080

**Audio:** [TTS provider] voiceover + underscore + SFX

**VO direction:** [voice character — e.g., "mid-age male, calm confident delivery,

Apple keynote register — economy of words, silence between sentences is a feature"]

**Style basis:** DESIGN.md (brand colors, fonts, components from the captured site)

```

**Global guardrails** — read [video-composition.md](../../hyperframes/references/video-composition.md) first. It defines the medium rules: density, color presence, scale, frame composition, and how design.md is brand truth not layout spec. Then apply these capture-specific additions:

- Captured assets are accents on composed beats, not the beats themselves — see Asset Audit below for which assets earn a place (typically 2-4 across the whole video).

- Use different techniques from techniques.md — not across the whole video, per beat. Don't default to basic fade/scale/opacity — mix in SVG path drawing, HTML-in-canvas, shaders, scrolling effects or movement effect, CSS 3D transforms, typing effects, counter animations, canvas procedural art. Each beat should feel like its own visual world. Use as many as makes sense for the storyboard.

**Underscore/music direction** (if applicable):

- Describe the mood, reference artists, when it swells or drops

- Example: "Minimal electronic. Warm sustained pad already playing when the video starts. Sits underneath everything, never competing with VO. Swells gently during the flex section, drops to near-nothing for the comparison, resolves on a final chord."

---

## Required Capabilities Discovery

Before writing any beats, you have to run these commands and paste the output below the Global Direction section. This tells you what's available beyond the standard techniques.

```bash

# 1. Check available shader transitions (installed in registry/blocks/)

ls registry/blocks/ 2>/dev/null | grep -E 'chromatic|cinematic|cross-warp|domain-warp|flash|glitch|gravitational|light-leak|ridged|ripple|sdf|swirl|thermal|whip' || echo "No shader transitions installed"

# 2. Check available VFX blocks

ls registry/blocks/ 2>/dev/null | grep vfx || echo "No VFX blocks installed"

# 3. Browse what's available to install

npx hyperframes catalog --type block 2>/dev/null | head -40

```

There might be VFX blocks available (vfx-liquid-glass, vfx-iphone-device, vfx-shatter, vfx-portal, etc.), use them for hero treatments instead of basic perspective tilt. You need to install any you want with `npx hyperframes add <name>`. Don't use too many shaders — maximum 2 per video unless user wants differently.

**Shader transitions — block name ≠ shader name.** When you run the commands above and see `domain-warp-dissolve` in `registry/blocks/`, the HyperShader runtime name is `domain-warp` (without "-dissolve"). After installing a block, open its showcase HTML (`compositions/<block-name>.html`) and find the actual shader name used in `HyperShader.init()`. That is what you put in the storyboard. Then delete the showcase file — it's a demo only and will pollute your compositions/ directory with lint warnings.

## Asset Audit — REQUIRED before writing beats (non-skippable)

The skill's #1 purpose is to USE the brand's captured assets — not rebuild them from CSS. Most of your beats should feature at least one captured asset: a hero illustration, a signature SVG, product photography, brand mark, distinctive graphic. **If your STORYBOARD.md ends with only the logo used, you have failed this step.**

**Why this gate exists:** Earlier sessions wrote their own "Asset Audit" that said SKIP for 60+ of 65 captured assets, used only the logo, and shipped a video that visually was indistinguishable from a generic dark-mode SaaS launch. The captured MetaBrain illustration, the GitHub-sync diagram, the knowledge-base hero — all left on the floor. The signature visuals that make a brand recognizable were absent. Don't repeat that.

**Required pre-storyboard procedure:**

1. **View every page of `capture/assets/contact-sheet-*.jpg`** AND every page of `capture/assets/svgs/contact-sheet-*.jpg`. These are the sheets generated by capture for this exact purpose. Open each page; scan cell-by-cell. Do not skim — you are looking for the brand's visual identity, frame by frame.

2. **For each contact sheet page, paste this block into STORYBOARD.md under an "Asset Audit" section:**

```

Contact sheet: capture/assets/contact-sheet-1.jpg (page 1 of N)

5 most visually distinctive assets I see (filename + one-sentence description of what the image shows):

1. <filename>: <what's actually pictured — not the filename, the content>

2. <filename>: <description>

3. <filename>: <description>

4. <filename>: <description>

5. <filename>: <description>

```

Repeat for every contact sheet page. The number of pages × 5 is your candidate asset pool.

3. **For each beat in STORYBOARD.md**, choose USE or SKIP for each candidate asset:

- **USE** means the asset appears in the beat's HTML at build time (`<img src=...>`, inline SVG, `background-image: url(...)`).

- **SKIP** requires a one-sentence reason explaining why this asset doesn't serve this beat. "Doesn't fit storyboard" is not a reason — name which storyboard moment failed to find a use for it.

4. **Brand-defaults floor:** at least ONE beat must use the brand's signature visual (hero illustration, hero photograph, or signature diagram — not the logo). If you've named 5+ candidate hero illustrations in step 2 above and zero of them appear in any beat, that is the failure mode this gate exists to catch.

**Forbidden:**

- Writing "SKIP" for every asset except the logo without per-asset justification

- Reading `capture/extracted/asset-descriptions.md` (the text file) and making decisions from filenames alone, without opening the contact sheets

- Concluding "I'll rebuild the GitHub-sync diagram in CSS" when the brand's own SVG of that diagram is sitting in `capture/assets/`. Use the real asset.

If your final beat list uses less than ~30% of relevant captured assets (relevant = anything except the favicon and tiny UI icons), revisit. The brand is visually carried by its own art; rebuilding it from divs erases what makes it recognizable.

### HTML-in-Canvas — plan for it here, build in Step 5

The `drawElementImage` Chrome API captures any live HTML/CSS as a GPU-accelerated texture at 60fps. This is HyperFrames' highest-impact capability — it lets you render captured product screenshots or UI through:

- **3D geometry** — a rotating iPhone or laptop model, a sphere, a curved surface

- **WebGL shaders** — liquid glass refraction, shatter into fragments, portal reveal, noise distortion

- **Post-processing** — bloom, depth-of-field, film grain, color grading

When planning beats, decide which ones deserve an HTML-in-Canvas treatment vs. a standard GSAP animation. If you want it, name it in the storyboard — Step 5 will read [`../../hyperframes/references/html-in-canvas-patterns.md`](../../hyperframes/references/html-in-canvas-patterns.md) for implementation. You don't need to specify the API details here.

### SFX assignment — happens here, not in Step 5

**Before writing beats,** read the SFX manifest. Locate it from your current directory:

```bash

find "$HOME" -path '*/website-to-hyperframes/assets/sfx/manifest.json' -maxdepth 10 2>/dev/null | head -1

```

Or if you already copied SFX into the project (Step 5 does this), read your local `sfx/manifest.json`. Each entry has a filename, duration in seconds, and description. Assign **specific SFX files** to exact moments in the storyboard. Step 5 implements what you specify here — it makes no SFX decisions.

Per beat, specify SFX like:

- `sfx/impact-bass-1.mp3` at `0.2s`, volume `0.35` — on the hero image snapping into frame

- `sfx/chime.mp3` at `3.8s`, volume `0.5` — on the logo appearing

**Less is more.** Most beats need zero SFX. One SFX per beat is typical; multiple only if the beat has genuinely distinct punctuation moments. Never place SFX on shader transitions directly — shader transitions are already an audio-visual event.

**How to place each sound type** (industry-standard rules):

- **Impact/hit sounds** (`impact-bass-1`, `ping`, `pop`, `glitch-*`): peak is at the start of the clip. Trigger exactly at the visual moment. Let the decay tail bleed into the next scene — this is normal, called a J-Cut, and sounds professional. `data-duration` = full manifest duration, never trimmed.

- **Riser/build-up sounds** (`riser`, `whoosh-cinematic`): peak is at the END of the clip. To make the peak land on a climax moment (a transition, a reveal), trigger at `climax_time - sfx_duration`. For `riser.mp3` (10.03s) peaking at a t=20s transition: trigger at t=9.97s.

- **Short accent sounds** (`click`, `click-soft`, `chime`, `sparkle`, `ping`): trigger at the exact visual punctuation moment. Duration is short, no tail concern.

**Volume when SFX overlaps narration:** HyperFrames has no automatic audio ducking. If an SFX plays under spoken narration, set its volume to 0.2–0.3 max, not 0.5+. Specify this in the storyboard entry so Step 5 wires it correctly.

**data-duration rule** (for Step 5 to implement): always equals the manifest's duration field exactly. Never set it shorter to "fit" the remaining beat time — truncating an impact mid-decay is the exact problem causing the cut-off sounds in v2 videos.

### Architecture Constraint: Each Beat is an Independent Composition

Each beat is built as a separate HTML file (`compositions/beat-N.html`). These are loaded independently — they do NOT share state, WebGL contexts, Three.js scenes, or DOM elements with other beats. This means:

- **No "persistent" elements across beats** — you can't have a MacBook model that stays on screen while only the screen content changes between beats 2, 3, 4. Each beat loads its own MacBook from scratch. If you want visual continuity, each beat must independently set up the element at the same position/rotation, so it APPEARS continuous.

- **No shared 3D scenes** — each beat that uses Three.js creates its own renderer, scene, and camera. If beats 2 and 3 both show a rotating laptop, they each load the model independently and must start from matching positions.

- **Shader transitions happen between beats** (in index.html), not within beats. Don't plan a shader transition "inside" a beat.

Plan your storyboard within these constraints. If you describe "the MacBook stays in place while content swaps," you need to specify that each beat independently recreates the MacBook at the same position — not that it persists.

### Device Mockups: Use the Registry Block

If the storyboard calls for a MacBook or iPhone mockup, use the pre-built `vfx-iphone-device` registry block — it has both **iPhone 15 Pro Max AND MacBook Pro** GLTF models with live HTML-in-Canvas screens, camera choreography, and glass lens morphing. Install with `npx hyperframes add vfx-iphone-device`.

Do NOT hand-code a Three.js device scene from scratch. The registry block handles UV mapping, screen textures, lighting, and camera angles correctly. Hand-coded versions consistently produce broken screen textures, wrong UV flipping, and path resolution bugs. Use the block.

---

## Per-Beat Direction

Each beat is a SHOT, not a layout. Write what the CAMERA does and what the FRAME reveals — not "what's positioned where on the page."

### A beat is a shot — pick the framing before writing CSS

Every beat header should declare its shot type in the first line. **Shot types:**

| Shot | Use for | What the frame contains |

| --------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |

| **Extreme close-up** | a single card / number / character / cursor / button as the entire subject | one element fills 60–90% of frame, everything else blurred or absent |

| **Close-up** | a small UI region (a single column, a card stack, a chart, a code block) | the subject fills 40–60% of frame with depth-layered context behind |

| **Medium** | a section of UI — kanban with 3 columns, chat with 3 messages, dashboard with 2-3 panels | the subject fills 60–80% of frame, edges of nearby UI bleed in |

| **Wide** | full UI assembly visible — only when the WHOLE thing is the point | full UI at 70–90% scale with deliberate negative space |

| **Over-the-shoulder** | viewer "behind" the user — cursor / hands / device foreground, UI midground | foreground element bottom 1/3, UI fills upper 2/3 with parallax depth |

| **Dutch angle** | tension, urgency, "something's off" | the frame is tilted 4–8°, content composed to feel unstable |

**The "wide shot" trap:** _Every_ beat at wide framing looks like a screenshot in CSS. Most product-demo videos should be 60% close-up + close-up + 20% medium + 10% wide + 10% extreme close-up. Wide is the rare establishing shot, not the default.

### Camera motion is the subject, not the elements

In website thinking: elements animate in, then sit still while the user reads. In video thinking: the camera moves THROUGH the scene. The composition shifts.

Every beat needs at least one camera-style move. Pick from:

- **Dolly in** — composition scales 1.0 → 1.08 over the beat duration, slight x/y drift

- **Dolly out / pull-back** — composition scales 1.15 → 1.0, revealing more context

- **Push** — fast scale-up (1.0 → 1.05, ~0.5s power3.out) on a key moment

- **Parallax pan** — background drifts opposite to foreground at different speeds

- **Orbit** — the subject rotates in 3D, or the camera circles it

- **Rack focus** — blur shifts from one element to another (background blurs as foreground sharpens)

If a beat has NO camera-style move and elements only animate inward at the start, it will read as a webpage with entrance animations. That's not a video beat.

### Forbidden patterns (the video-as-webpage failures)

These appear in nearly every iteration where sub-agents revert to website thinking. Refuse to write any beat that includes:

- ❌ **macOS / browser window chrome** as a frame around the content — traffic-light dots, URL bars, browser tabs, breadcrumbs — UNLESS the beat IS specifically about that chrome (e.g., "the macOS window itself is the subject of the shot")

- ❌ **Sidebars, navigation rails, page headers, page footers** unless the beat demonstrates navigation as its concept

- ❌ **"Centered card / panel / window with 60–120px margin on all sides"** — that's the standard webpage layout; videos use the full frame and meaningful negative space

- ❌ **"Hold with breathing" micro-animations** where elements move y: ±1–2px or scale 1.01 — invisible at video resolution; this is sub-agents pretending the beat has motion when it doesn't

- ❌ **Settled holds longer than 1.5s** with no continuous camera or compositional change — fix by adding camera dolly, depth-layer parallax, or new sub-elements entering mid-beat

- ❌ **Hover-state demonstrations** — videos have no hover; if the brand has a hover effect to communicate, find a way to show the BEFORE and AFTER as discrete frames, not a hover simulation

- ❌ **Tooltips and modal cards "for context"** that explain what something is — videos communicate through visual language, not popup hint text

### Required for every beat (the floor for video grammar)

Every beat must specify, in its visual description:

1. **Shot type** (one of the six above)

2. **Camera move** (which one, when it starts, how long it lasts)

3. **Depth strategy** (what's in foreground / midground / background, how they parallax)

4. **Motion magnitudes** that read at video scale (30px+ y/x movements, scale changes ≥0.05, opacity transitions ≥0.5)

5. **The shot's purpose** — what specifically is the viewer supposed to feel or notice in this 3–5 seconds?

---

### Existing beat-level fields (below) layer on top of the shot grammar above

Each beat is a WORLD, not a layout. Write what the viewer EXPERIENCES before you write CSS specs.

**Motion verbs** — every animated element gets one. Pick from the beat's concept, not from an energy bucket:

- **Impact:** SLAMS, CRASHES, PUNCHES, DROPS, SHATTERS

- **Directional:** SLIDES, PUSHES, WIPES, CUTS

- **Reveals:** DRAWS, FILLS, GROWS, ASSEMBLES, COUNTS UP

- **Organic:** FLOATS, DRIFTS, BREATHES, PULSES, ORBITS

- **Mechanical:** TYPES ON, CLICKS, LOCKS IN, SNAPS, STEPS

**Transition decision matrix** — shader vs CSS vs hard cut:

| Shader transition for | CSS crossfade for | Hard cut for |

|---|---|---|

| Hero reveals, logo unveils, "wow" moments | Continuous motion between beats, editorial pacing | Rapid-fire lists, percussive edits, comedy timing |

1–2 shader transitions per video (hero + CTA). Too many flatten their impact. Mix shader and CSS crossfade in one HyperShader composition by omitting `shader` on any transition entry.

**Rhythm** — declare your scene rhythm before implementing: fast-fast-SLOW-fast-SHADER-hold. The rhythm comes from the brand and content, not a template.

Use the pacing you decided at the top of this step. The beat count, duration, and architecture are already set.

**Cut the video to match the narration length** — if the script produces 22 seconds of audio, the video should be 24 seconds with a 2-second CTA hold, not 30 seconds with 8 seconds of dead silence. Empty time at the end where nothing is happening loses the viewer.

**Frame-filling rule:** When describing visuals per beat, specify sizes as FRAME FILL PERCENTAGES, not pixels. "Product screenshot fills 80% of frame" not "600px wide card."

**Use whatever primitives the beat needs — alone or in combination.** A beat can layer HTML/CSS, SVG (captured or hand-drawn), WebGL/Canvas shaders, Three.js scenes, captured illustrations and photographs, kinetic typography, captured Lottie — all at once if the scene calls for that. They're inputs to one output (the video frame); there's no rule mapping intent to primitive. The video should feel **alive in every frame** — motion that's continuous and tangible, **like things exist in a physical world**. Narrow no-go: never paste a product-UI screenshot as load-bearing content (the slideshow pattern). Everything else is open.

**Opener default: fast intro to stop the scrollers.** Even a cinematic video should start with a punch — a flash, a shader bloom, a logo strike, a kinetic word build, a particle burst — anything that lands inside the first 1.0–1.5 seconds. Slow intros work for prestige trailers; videos shipping anywhere social or feed-based need a hook that beats the 1.5-second scroll threshold. Plan the opener as the most ambitious beat in the storyboard, not the gentlest one.

**CTA / closing beats** are consistently the weakest. Agents treat them as "logo + tagline + done." A good CTA should: make the logo entrance an event (SVG path draw, scale with overshoot, or anything awesome really), have continuous background motion, and hold only 2-3 seconds after the last spoken word — NOT 8-10 seconds of silence.

**VO start timing — decide here, not in Step 5.** When does the narration actually begin relative to the first visual? Options: (a) VO starts over the visual intro (heard before content settles — creates urgency), (b) VO starts after the visual intro settles (viewer sees the opening, then hears the voice — creates drama), (c) a few seconds of music-only visual before VO enters. None of these is a default — pick based on the brand and the opening beat's concept. State the intended narration start time explicitly in the storyboard's Global Direction, e.g. `**Narration start:** 0.8s (after hero intro settles)`. Step 5 wires this as the audio element's `data-start`.

**Concept-first beats.** Every beat starts with its CONCEPT — not "what technique to use" but "what does this scene should show, what did the previous showed and what will the next show...?" What idea is being communicated? The crazy and interesting concept drives every technical decision.

In the capture pipeline, each beat includes:

### Concept

What does this scene REPRESENT in terms of previous (if exists) and next scenes? Not "show features" but a specific idea and logic.

### VO cue

Which narration line plays over this beat (Also keep in mind the whole narration of the video to understand and keep in mind the flow).

### Visual description

What the viewer sees — described cinematically, not as CSS specs. Use camera language and production motion designer vocabulary (pan, zoom, drift, settle, and more of those words). Think in layers — what's supposed to happen in the foreground, midground, background simultaneously?

**When a captured asset is the primary visual** (logo opener / closer, hero illustration with parallax, hero photograph with motion treatment, gradient as full-bleed background, etc.): specify which asset, how much of the frame it fills (%), and where text/labels go relative to its safe zones. Don't blindly center text over busy product UI. The narrow no-go: never paste a product-UI screenshot as full-bleed beat content — that's the slideshow pattern this workflow exists to break. Captured logos, illustrations, hero art, and photography are fine as primary visuals when the concept calls for them.

### Composition + Accents

Two things, both required:

**Composed (load-bearing — what carries the beat):**

- Describe the UI / element / scene you're building from scratch: markup structure, the techniques powering it (cite [capabilities.md](capabilities.md) sections + [techniques.md](../../hyperframes/references/techniques.md) entries), key animation events. E.g. "Composed kanban: 3 column divs, 4 cards each, drag-and-drop with `back.out(1.7)` entrance stagger, counter chip on In-Progress incrementing via `tl.set()`."

- **Brand-inflect:** brand colors from DESIGN.md, real product data (project names, real metrics, real copy — not placeholder labels), narration-sync moments. Make this beat THIS brand's beat, not a generic UI demo.

**Accents (decoration only — what brand-inflects the beat):**

- Optional. Most beats need 0-1 accent. Format: `capture/assets/<filename>` — how it appears: position, opacity, treatment, motion (e.g. `capture/assets/logo.svg` — top-left, 60×60, fades in at 0.4s, breathes during hold).

- Common accent uses (when the primary visual is something else): brand logo stamped on a UI beat, hero illustration as a depth layer behind kinetic type, gradient image as ambient background wash. When the captured asset IS the primary visual (logo drawing itself on the opener, hero illustration with parallax as a hero beat), it isn't an accent — it's the beat content; document it under Composition, not here.

- If a beat has no obvious accent need, leave this blank. The primary visual is enough.

Write this section for THIS project's actual brand and the assets audited above — not from memory.

### Text Animations

Every text element in this beat must name a specific effect from the catalog. The reference page is at [`../../hyperframes/references/text-effects.md`](../../hyperframes/references/text-effects.md) (or locate it with `find "$HOME" -path '*/hyperframes/references/text-effects.md' -maxdepth 10 2>/dev/null | head -1`). It lists 24 effect IDs (from the separate `pixel-point/animate-text` skill); pick what fits the brand and this beat's mood — don't default to the same effect every beat.

Format (FORMAT EXAMPLES of structure, not prescriptions — pick based on brand/mood/context):

- `[element — e.g. "main headline"]`: `[effect-id]`

- `[element — e.g. "eyebrow label"]`: `[effect-id]`

At build time, the sub-agent loads `/animate-text` (the upstream skill) and reads each named effect's spec from `.agents/skills/animate-text/assets/effects/<id>.json`. No creative decisions at build time — just spec retrieval and implementation.

### Beat Timing

Two numbers Step 5 needs to wire `data-start` and `data-duration` correctly:

- **HyperShader transition in at:** `[time]s` (the `time:` value in the transitions array for the transition INTO this beat — or 0 for beat 1)

- **GSAP timeline duration:** `[duration]s` (how long this beat's internal animations run — when does the last tween end?)

Example: `Transition in at: 4.2s · GSAP duration: 5.5s` → Step 5 sets `data-start="4.2" data-duration="5.5"`.

### Animation Sequence — must span the ENTIRE beat

A beat is a SCENE with internal life, not a single entrance followed by a static hold. Things should be happening throughout the entire duration — new elements appearing, existing elements transforming, camera drifting, details revealing, sub-moments unfolding.

If your animation sequence only has events in the first 2 seconds and the beat lasts longer, the rest is dead air. Plan moments across the full duration. Nothing should sit unchanged for more than ~2 seconds — if an element is on screen, give it continuous motion (drift, breathe, pulse, parallax).

Describe the feel precisely: "snappy overshoot bounce settling into place" → back.out; "slow heavy drift" → power1.inOut. Vague adjectives are useless.

---

## Brand Accents Pass (LAST creative decision — happens after beats are written)

Your beats are now conceptually defined. Each one has a primary visual that carries it (composed UI, captured asset, kinetic typography, WebGL, etc.). **Now**, do a single pass to decide which captured assets — if any — earn an accent role on the beats where another primitive carries the visual.

This is the LAST creative pass before file-tree time. It comes here intentionally: assets serve concept-defined beats — as primary visual or as accent, depending on what each beat needs — but they don't seed beats. If you find yourself wanting to add a beat _because_ an asset would look cool, the asset is doing the storyboarding — go back and rewrite that beat from the message instead.

### Brand defaults (nice-to-haves for most brand videos)

Two defaults that work for most brand-focused videos. Skip them when the concept calls for it; they're not hard requirements.

1. **The brand mark in opener + closer.** For most brand videos, the logo / wordmark SVG lands in the opener (as the entry tag) and the closer (as the sign-off). It gives the viewer the brand at both ends of the watch. Skip when the concept calls for it — e.g., a teaser that deliberately delays the brand reveal until beat 3 for narrative tension, or a video where the brand mark would feel redundant against the captured hero art.

2. **The site's signature visual somewhere in the video.** Every captured site has one: a gradient wave, a hero illustration, a distinctive product UI mark, the wordmark animation, a color combination, a hero photograph. It's whatever a viewer who knows the brand would point at and say "that's them." Find it during Step 0; place it where the concept can use it. Not required — but if a brand video doesn't include this, ask whether the video still feels like _this_ brand.

These are defaults, not requirements. Beyond them, aim for 2-4 brand accents total across the whole video, not per beat. Most beats need 0-1. Everything beyond the floor has to justify itself against the question: _"Does this asset make the beat MORE this brand, or is it filler?"_

Print this table once your beats are written:

| ------------------------------ | -------- | --------------- | ------------------------------------------------------------------------------- |

Mark assets `SKIP` when a composed equivalent (dashboards, kanban, chat, terminal, file tree, calendar, pricing cards, etc.) does a better job — that's the strong default for product UI. Use the brand's _real_ data (project names, real metrics, real product copy) in composed beats — never the placeholder labels a screenshot would have.

**Update each beat's Composition + Accents section** based on what this pass produced. Most beats stay accent-free. The few that earn one get a single line under "Accents" with the file, position, opacity, and motion.

**The bar:** Every beat's visuals use whatever combination of primitives the scene needs. Accents are optional brand inflections layered on top; the brand-defaults section above (logo in opener + closer, signature visual once) covers most brand videos but isn't a hard requirement.

---

## Production Architecture

Include this file tree at the bottom of the storyboard:

```

project/

├── index.html root — VO + underscore + beat orchestration

├── DESIGN.md brand reference (from Step 1)

├── SCRIPT.md narration text (from Step 3)

├── STORYBOARD.md THIS FILE — creative north star

├── transcript.json word-level timestamps (from Step 4)

├── narration.wav TTS audio (from Step 4)

├── capture/ captured website data (from Step 0)

│ ├── screenshots/

│ ├── assets/

│ │ ├── svgs/

│ │ ├── fonts/

│ │ ├── lottie/

│ │ └── videos/

│ ├── extracted/

│ │ ├── tokens.json

│ │ ├── design-styles.json

│ │ ├── visible-text.txt

│ │ ├── asset-descriptions.md

│ │ ├── animations.json

│ │ ├── assets-catalog.json

│ │ └── detected-libraries.json

│ ├── AGENTS.md

│ └── CLAUDE.md

└── compositions/

├── beat-1-hook.html

├── beat-2-features.html

├── ...

└── captions.html

```

---

## Example: Beat-by-Beat Format

The two beats below are from the real Claude Design × HyperFrames production video. They show the expected level of specificity — exact timing, exact GSAP values, exact animation sequences.

**Why only 2 beats are shown:** Earlier versions of this reference showed all 10 beats, and agents pattern-matched from them regardless of the brand being captured. Moodboard layouts, capabilities grids, and orbital letter closers started appearing in every video. The concepts in those beats are specific to HyperFrames as a product — they should not appear in a video about a fintech tool or a wellness app. Only two beats are shown here to demonstrate the format level, not to suggest these specific techniques.

### BEAT 1 — LIGHT BALL OPENER (0:00–0:03)

**Concept:** No title card, no fade from black. A single point of warm light appears in total darkness. It blooms into a horizon-spanning glow. The viewer leans in before a single word is spoken.

**Visual:** Deep black canvas (#050507) with grain overlay (mix-blend-mode: overlay, 0.12 opacity) and extended vignette (inset: -200px for long falloff). The `.ball-core` is a 40px radial-gradient orb (white center → accent → transparent). Animation sequence:

- 0.0s: Orb appears tiny (scale: 0.15, opacity: 0→1, 0.18s, expo.out)

- 0.18s: Orb grows continuously (scale: 0.4→1.4, 0.7s, power1.in). Simultaneously the `.ball-halo` (140% width, 70% height ellipse, accent-tinted radial-gradient, blur: 60px) blooms in (scale: 0.4→1, opacity: 0→1, 0.55s, sine.out)

- 0.65s: Orb keeps growing as it fades (scale: 1.4→8, opacity: 1→0, 0.4s, power2.in) — the point of light dissolves into pure glow. Halo expands further (scale: 1→1.25, opacity: 0.85)

- 0.85s: Horizontal beam line emerges from center (scaleX: 0→1, 0.4s, expo.out) with warm box-shadow glow (0 0 24px 1px rgba(255,240,220,0.4))

- 1.0s: Title "Claude Design × HyperFrames" fades up above the line (opacity: 0→1, y: 14→0, 0.7s, power3.out). Ampersand in italic accent color.

- 1.3s: Date subtitle appears below the line (0.6s, power2.out). Monospace font, 0.32em letter-spacing, uppercase.

- 2.2s: Bottom credit line fades in ("This entire video was made with HyperFrames in Claude Design")

- 3.0–4.4s: Hold — halo breathes (opacity drifts to 0.55, scale to 1.4, sine.inOut), headline drifts slightly (y: -3px)

- 4.4s: Everything fades to black together (0.6s, power2.in)

Corner marks (monospace, 11px, 0.45 opacity) at top-left and bottom-right for editorial feel.

**SFX:** Deep ambient bass pad already playing from frame 1.

---

_(Beats 2–9 intentionally omitted. See above for why.)_

### BEAT 10 — ORBITAL LETTERS / CLOSE (example of a closing beat spec)

**VO:** (resolving — the brand name assembles)

**Concept:** Individual letterforms of "HYPER FRAMES" burst in from alternating sides, each with rotation and offset. They bounce into place with back.out(2.0) overshoot. An accent line draws itself across the width. An orbit ring expands with a glowing dot tracing a full 360° rotation. A tagline types itself out: "HTML in. Video out." with deliberate pauses after each word. Everything breathes after assembly — letters float gently, glow pulses, connector lines shimmer.

**Visual:** Deep black. Center glow: 900px radial-gradient orb (accent #e8a769 at 0.35 → 0.12 → 0.025 → transparent), blur(100px).

**Animation sequence:**

- 0.1s: 12 character elements ("H Y P E R [space] F R A M E S") enter staggered 0.06s apart, each from y: 80 with alternating x offset (odd: -30, even: +30) and rotation: -15. Landing: back.out(2.0), 0.7s — gives each letter a satisfying overshoot bounce.

- 1.0s: Accent SVG line draws across the full 1920px width (strokeDashoffset: 1920→0, 0.6s, power3.out). #e8a769 stroke, 2px.

- 1.0s: Glow breathes in (opacity: 0→0.2, sine.inOut, 0.4s), then back to 0.1.

- 1.4s: Orbit ring (600px circle, 1px border rgba(accent, 0.3)) expands from scale: 0.5 to 1.0 (expo.out, 0.5s). A glowing orbit dot (8px, accent color, box-shadow glow) on the ring traces a full 360° rotation over 2.5s (linear easing — constant speed).

- 1.25s onward: Letters begin a subtle float — alternating directions (y: ±2px, sine.inOut, 1.4s, yoyo, repeat 1), staggered 0.04s. Keeps the assembled word feeling alive.

- 1.8s: Tagline types itself in monospace (24px, accent color, 0.15em letter-spacing): "HTML" (pause 0.2s), " in." (pause 0.25s), " Video" (pause 0.1s), " out." — each segment at 0.03s per character using steps(N) easing for discrete character appearance.

- 1.8s onward: Glow continues gentle breathing (opacity: 0.1→0.14, sine.inOut, 1.2s, yoyo, repeat 1).

**SFX:** Soft chime on letter assembly completion. Silence under the tagline typing — let it land.

---

## Write the Narration Script (same step — write alongside the storyboard)

The script and storyboard are one step. Every beat already has a VO cue — the script is just all those VO cues assembled into a single document. As you write each beat, write its narration line. Then assemble them into `SCRIPT.md`.

The script serves the storyboard — write words that fit the visual plan, not the other way around. Reference real product features, real stats, and real components from `capture/extracted/visible-text.txt`. Use exact numbers.

**Script length depends on the creative direction, not a formula.** A cinematic video with dramatic pauses and visual-only moments might have 40 words across 30 seconds. A rapid feature showcase might pack 100 words into 30 seconds. The storyboard's pacing and style (from Step 2's brief) determine how much narration vs. silence the video needs. Some beats are narrated; some are pure visual. Let the creative plan drive the word count, not the other way around.

The key constraint: don't pad with dead silence where nothing is happening. If a beat has no narration, something visual must be carrying the viewer's attention. Empty frames = lost viewers.

Save as `SCRIPT.md` in the project directory.

**Script writing rules:**

- ~2.5 words/sec natural pace. 15s = ~37 words, 30s = ~75 words.

- Use contractions ("it's", "you'll"). Read it out loud — if it sounds robotic, rewrite.

- Write numbers as spoken: `$1.9T` → "nearly two trillion dollars", `API` → "A P I", `10x` → "ten times"

- **Hook first** — bold claim, provocative question, contrast, or shocking number. Never "Welcome to..." or "Introducing..."

- Structure: Hook → Story → Proof → CTA. 15s ads can skip Story.

---

## User Review Gate

After writing the storyboard AND the script, present BOTH to the user for review. The storyboard and script are coupled — the user needs to see them together to judge whether the video works.

### How to Present

Summarize the plan clearly. Don't dump the full STORYBOARD.md — give the user a beat-by-beat overview they can scan in 30 seconds:

> **Here's what I've planned for your [duration] [type]:**

> **Beat 1 (0:00–0:04):** [one sentence — what happens visually + what the narration says]

> **Beat 2 (0:04–0:10):** [one sentence]

> **Beat 3 (0:10–0:18):** [one sentence] _(hero beat — 3D MacBook reveal with bloom effect)_

> ...

> **Beat N (closing):** [one sentence — CTA/logo]

> **Style:** [dimension summary — e.g., "Cinematic pacing, dark mood, dramatic transitions for hero, clean for the rest"]

> **Narration:** [first and last line of the script]

> **Total duration:** [X]s with [N] beats

> **Does this match what you envisioned?** I can adjust: beats, pacing, specific effects, the script tone, or anything else. Or if this looks good, I'll proceed to voice generation.

### What to do with feedback

- **"Looks good" / approval** → proceed to Step 4 (VO)

- **Specific feedback** ("make beat 3 longer", "change the opening to be faster", "I don't want the typing effect") → update STORYBOARD.md and SCRIPT.md, re-present

- **Major direction change** ("actually I want it more playful, not cinematic") → revisit Step 2's brief dimensions, rewrite storyboard

- **Iterate until the user is satisfied.** This is the cheapest place to make changes — changing a storyboard beat costs 30 seconds. Changing a built composition costs 5 minutes.

### Gate

Both STORYBOARD.md and SCRIPT.md exist AND the user has explicitly approved the plan.

**Autonomous mode exception:** if the user signaled autonomous mode in Step 2 ("surprise me" / "decide for me" / "just build it"), skip the approval wait. Present the storyboard summary inline as a heads-up and proceed straight to Step 4.

mdskills/website-to-hyperframes/references/step-4-vo.md

13 kB

# Step 4: VO, Timing + Captions

## If Step 2 said "no narration"

Skip the TTS sections below. The storyboard already has beat durations planned based on pacing and rhythm — those become `data-start` and `data-duration` values directly in Step 5.

**Background music:** Ask the user before moving to Step 5:

> "Do you have a music track for this video? If not, I can suggest where to find one:

> - **Artlist.io** or **Musicbed** — licensed music for commercial use

> - **Uppbeat.io** or **Pixabay Music** — free tracks with attribution

> - **Freesound.org** — free samples and loops

> Or share a reference track ('something like this') and I can find something similar."

If the user provides a track: note the file path and BPM in the storyboard for Step 5 to wire into `index.html`. If they skip music entirely, the video uses SFX only — confirm that's intentional.

Move to Step 5.

---

## Generate a test clip before full narration — calibrate timing first

Generate a 2-sentence test clip NOW using the script's opening lines. Measure the actual duration. Kokoro compresses scripts by ~40% (35s planned → 19s actual) and HeyGen runs faster than expected. If you discover the audio is 40% shorter than expected, you'll need to revise the storyboard beat timings before investing time in full narration generation.

**Do this before committing to beat count and durations:**

```bash

# Quick Kokoro test (2 sentences):

npx hyperframes tts "First sentence. Second sentence." --voice af_nova --output /tmp/test-tts.wav

# Measure: seconds ÷ words × total script words = estimated full audio length

```

If the estimate puts your video at ±15% of the planned duration, proceed. If it's more than 15% off, recalibrate the script length first:

- **Audio TOO SHORT** (more than 15% under planned duration) → add strategic pauses. In `narration.txt`, insert blank lines between paragraphs (≈0.6s each) or `...` between sentences (≈0.4s each). Aim for the pauses to land at storyboard beat boundaries so the silence feels intentional, not dead air.

- **Audio TOO LONG** (more than 15% over planned duration) → identify the beat in your storyboard with the highest words-per-second density. Cut one supporting sentence from THAT beat's lines — preserve the lead sentence (the one that names the beat's idea). Re-measure with another test clip before committing to full generation.

- **Audio matches plan but beat boundaries drift** → adjust the storyboard durations to match the actual narration, not the other way around. The audio is the ground truth once narration is generated.

The script formula assumes constant words-per-second, but punctuation, dramatic pauses, and silence cues all stretch real audio. Always trust a measured test clip over the formula.

## Background music

**Always ask about background music** — even when narration is present:

> "Do you want background music under the narration? (Artlist.io, Musicbed for licensed; Uppbeat/Pixabay for free; or share a reference track). Even a subtle ambient underscore makes pauses between sentences feel intentional rather than empty."

If they want music, note the track in the storyboard for Step 5 to wire into `index.html`.

## TTS Provider

Ask the user which voice provider they'd like:

> **Which voice provider would you like to use for narration?**

> 1. **HeyGen TTS** — Good quality voices, and it returns word-level timestamps automatically (saves a separate transcription step). Requires HeyGen API key.

> 2. **ElevenLabs** — Large voice library, very natural output. Requires ElevenLabs API key. Does not return word timestamps — you'll transcribe separately.

> 3. **Kokoro** (Free) — Runs locally, no API key needed. Decent quality but more robotic than the others. Good for drafts or budget runs.

If the user picks ElevenLabs or HeyGen and doesn't have a key set up yet, help them:

- **ElevenLabs:** "Add `ELEVENLABS_API_KEY=your-key` to a `.env` file in the project root, or just paste it here and I'll set it up."

- **HeyGen:** "Add `HEYGEN_API_KEY=your-key` to a `.env` file, or paste it here."

Don't judge or critique if the user pastes a key directly in chat — just use it and move on.

## Audition voices

After the provider is selected, audition at least 2 voices with the first sentence of SCRIPT.md.

**ElevenLabs:**

- If the ElevenLabs MCP is available: use `mcp__elevenlabs__search_voices` to browse, `mcp__elevenlabs__text_to_speech` to generate.

- If no MCP: call the REST API directly:

```bash

# List voices

curl -s "https://api.elevenlabs.io/v1/voices" \

-H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[:5] | .[].name'

# Generate speech (replace VOICE_ID with chosen voice)

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/VOICE_ID" \

-H "xi-api-key: $ELEVENLABS_API_KEY" \

-H "Content-Type: application/json" \

-d '{"text":"First sentence of your script","model_id":"eleven_multilingual_v2"}' \

--output narration.mp3

```

- Does not return word timestamps — transcribe separately after generating.

**HeyGen TTS:**

- If the HeyGen MCP is available: use the TTS tool directly.

- If no MCP: use the v3 API (current; v1/v2 deprecated, supported until Oct 2026):

```bash

# List voices — response shape: { "data": [...], "has_more": bool }

# data is a direct list (NOT data.voices — that was v2)

curl -s "https://api.heygen.com/v3/voices?engine=starfish&type=public&limit=20" \

-H "x-api-key: $HEYGEN_API_KEY" | python3 -c \

"import json,sys; v=json.load(sys.stdin)['data']; [print(x['voice_id'], x['name'], x['language']) for x in v[:10]]"

# Generate audio — response: { "data": { "audio_url": ..., "word_timestamps": [...] } }

curl -s -X POST "https://api.heygen.com/v3/voices/speech" \

-H "x-api-key: $HEYGEN_API_KEY" \

-H "Content-Type: application/json" \

-d '{"text":"Your script here","voice_id":"VOICE_ID","speed":1.0}' \

| python3 -c "

import json,sys

r=json.load(sys.stdin)

d=r['data']

print(d['audio_url'])

open('transcript_raw.json','w').write(json.dumps(d.get('word_timestamps',[]),indent=2))

# Then download the audio

curl -sL "AUDIO_URL_FROM_ABOVE" --output narration.mp3

```

- Returns word-level timestamps directly in the response — no separate transcription step needed.

**Kokoro (free, local):**

```bash

npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav

```

No API key, no MCP needed. Runs locally. Use `--list` to see all 54 available voices.

Pick the voice that sounds most natural and conversational. Listen for pacing — does it breathe between sentences? Does it sound like a person or a robot?

## Script length check

Before generating, verify the script makes sense for the video. Word count depends entirely on the creative direction. The storyboard's pacing and style determine how much narration the video needs.

The key check: are there stretches where NOTHING is happening — no narration AND no compelling visual movement? Those are dead spots that lose the viewer. Every second needs either spoken words or strong visual energy carrying it.

## Generate full narration

Generate the full script as `narration.wav` (or `.mp3`) in the project directory.

**If any command hangs for more than 60 seconds — don't just wait.** The user is sitting there watching you do nothing. Escalation order:

1. **Try again** — kill the process, run the same command again (transient failures are common)

2. **Try different flags** — smaller model (`--model tiny.en`), different voice, shorter test sentence first

3. **Try a different tool for the same task** — if `hyperframes transcribe` hangs, try `whisper-cli` directly, or Groq API (`npx hyperframes transcribe --provider groq`), or OpenAI API

4. **Switch provider entirely** — if ElevenLabs is down, try HeyGen or Kokoro. If Kokoro hangs, try ElevenLabs.

Never sit idle for 10 minutes hoping a stuck process will finish.

**Kokoro pronunciation issues:** Kokoro mispronounces product names and tech terms. Always apply substitutions before generating. Known problems and fixes:

- `API` → `A P I` (spell it out)

- `UI` → `U I`, `SaaS` → `sass`, `DevOps` → `dev ops`

- Product names with unusual spelling: test the first sentence first and listen. Common failure: "Vercel" → "versatile", "WorkOS" → "work O S", "One API" → "Wanna PI"

- If a name sounds wrong: write it phonetically in `narration.txt` (e.g., `Vercel` → `Ver-sell`, `Supabase` → `Soopa-base`)

- Always generate a short test clip with the first 2 sentences before generating the full audio

- **No SSML tags** — Kokoro reads them as literal text. `<break time="1s"/>` is spoken as "break time equals one slash." Use blank lines or `...` for pauses in `narration.txt`

For ElevenLabs and HeyGen TTS, substitutions are usually unnecessary — they handle product names correctly.

**Also save the exact spoken text** — with pronunciation substitutions applied (e.g., `API` → `A P I`, `$2T` → `two trillion` and etc.) — as `narration.txt` in the same directory. This is the string passed to TTS, distinct from `SCRIPT.md` which is the human-readable creative doc. Having `narration.txt` makes it trivial to regenerate the audio later with a different voice without re-deriving the substitutions. Name it exactly `narration.txt`.

## Transcribe for word-level timestamps

**If you used HeyGen v3 TTS:** word timestamps were returned in the generate call. Normalize the format before saving — HeyGen v3 uses `word` but the pipeline expects `text`:

```python

import json

raw = json.load(open('transcript_raw.json'))

normalized = [{"text": w["word"], "start": w["start"], "end": w["end"]} for w in raw]

json.dump(normalized, open('transcript.json', 'w'), indent=2)

```

No separate transcription step needed.

**If you used ElevenLabs or Kokoro:**

```bash

npx hyperframes transcribe narration.wav

```

Produces `transcript.json` with `[{ text, start, end }]` for every word. These timestamps are the source of truth for all beat durations.

## Map timestamps to beats

Go through STORYBOARD.md beat by beat. For each beat:

1. Find the first word of that beat's VO cue in `transcript.json`

2. Find the last word of that beat's VO cue

3. Set `beat.start = firstWord.start`, `beat.end = lastWord.end`

4. Add 0.3-0.5s padding at the end for visual breathing room

Update STORYBOARD.md with real durations. Replace estimated times (e.g., "0:00-0:05") with actual timestamps as precise as possible (e.g., "0.00-3.21s").

Beat boundaries land on word onsets — hard cuts to the VO.

## Timing reconciliation — required before Step 5

After mapping all beats, compare real total audio duration against the storyboard's planned duration:

```

real_total = last_word.end + cta_hold (typically 2–3s)

planned_total = sum of all beat planned durations

delta = |real_total - planned_total|

```

**If delta > 15% of planned total — do not proceed to Step 5 without resolving it.** Common causes and fixes:

- **Audio shorter than planned (most common with Kokoro):** Kokoro generates compressed speech with minimal pauses. Proportionally scale all non-CTA beat durations down to match the real audio. Example: planned 30s, audio 19s — multiply each beat duration by 19/30 (excluding the CTA hold). Update STORYBOARD.md.

- **Audio much longer than planned (>30% over):** The script was too long for the intended duration. Trim the script (remove one beat's VO), regenerate audio, re-transcribe.

- **CTA beat timing:** The CTA beat should hold for 2–3 seconds after the last spoken word — not extend to fill empty time. `cta_start = last_word.end + 0.3s`, `cta_duration = 2.5s`. Hard cap. Dead silence after the CTA hold loses the viewer.

**Always tell the user** if you adjusted durations significantly from the storyboard plan. They approved a specific beat structure — if it changed, they need to know.

## Captions

After the narration is generated and transcribed, ask the user:

> **Would you like captions on the video?**

> - **Yes** — per-word captions synced to the narration. Great for social media (most viewers watch on mute) and accessibility.

> - **No** — narration audio only, no text overlay.

If yes, captions are built as a separate composition (`compositions/captions.html`) in Step 5. The `transcript.json` drives the timing — each word appears/highlights as it's spoken. Read [the captions reference](../../hyperframes/references/captions.md) for styling options (scale-pop, typewriter, fade+slide, etc.) and positioning rules.

## Save timing data for Step 5

Record the final beat timings (start, duration) so Step 5 (Build) can use them when building `index.html`. The storyboard now has real timestamps — these become `data-start` and `data-duration` values on each scene slot when the root composition is assembled in Step 5.

mdskills/website-to-hyperframes/references/step-5-build.md

28 kB

# Step 5: Build Compositions

**Captions rule — read before building anything:** Never create `compositions/captions.html` with an empty transcript (`const script = []`). If the VO/transcript step was skipped or failed, do not create a captions composition at all. An empty captions file silently does nothing and wastes a track slot. Only create it when `transcript.json` has real word timestamps.

**Captions stacking bug:** Every caption word group must start with `opacity: 0` (or `visibility: hidden`) and be positioned `position: absolute`. Never show more than one group at a time — GSAP controls visibility sequentially. If multiple groups are visible simultaneously it means either (a) the initial CSS state isn't hidden, or (b) a group's exit tween is missing before the next group's entrance fires. After building captions.html, take a snapshot at 3–4 timestamps mid-narration and verify only one word group is visible per frame.

**Before building, verify you have:**

- **STORYBOARD.md** — the beat-by-beat plan. Re-read it now if you don't remember every beat's concept, assets, and techniques.

- **DESIGN.md** — if you need to check a specific value (color, font, component style) you can't recall, look it up. Don't re-read the whole file.

- **`capture/extracted/asset-descriptions.md`** — when the storyboard assigns an asset to a beat, check the description to understand what it shows. Re-read this file if you can't recall the asset inventory.

- **transcript.json** — word-level timestamps that drive scene durations.

Load the `hyperframes` skill — it has the rules for data attributes, timeline contracts, deterministic rendering, and layout. Read it now if you haven't already this session.

**For capabilities.md and techniques.md:** read the Table of Contents to orient yourself, then go deep only on the sections your storyboard actually calls for. You don't need to re-read sections for animation engines, registry blocks, or techniques that none of your beats use.

---

## 1. Copy SFX to project

```bash

cp -r skills/website-to-hyperframes/assets/sfx/ <project-dir>/sfx/

# If skill is installed elsewhere:

find . -path "*/website-to-hyperframes/assets/sfx" -exec cp -r {} <project-dir>/sfx/ \;

```

## 2. Build the root index.html

Create `index.html` yourself. This is the orchestrator — it holds beat slots, narration audio, SFX, and shader transitions (if any).

**Critical CSS — every beat must overlap in the same frame:**

```css

.scene {

position: absolute;

top: 0;

left: 0;

width: 1920px;

height: 1080px;

overflow: hidden;

}

```

**Beat structure:**

```html

<div

id="root"

data-composition-id="main"

data-start="0"

data-duration="TOTAL"

data-width="1920"

data-height="1080"

<div

id="beat-1"

class="scene"

data-composition-id="beat-1-hook"

data-composition-src="compositions/beat-1-hook.html"

data-start="0"

data-duration="5.5"

data-track-index="1"

data-width="1920"

data-height="1080"

></div>

<audio

id="narration"

src="narration.wav"

data-start="0"

data-duration="NARRATION_LENGTH"

data-track-index="0"

data-volume="1"

></audio>

<audio

id="sfx-impact"

src="sfx/impact-bass-1.mp3"

data-start="0.3"

data-duration="2.1"

data-track-index="41"

data-volume="0.35"

></audio>

</div>

```

SFX were assigned in the storyboard (Step 3) — implement exactly what STORYBOARD.md specifies. Each SFX entry has a file, trigger time, and volume. Wire each one as an `<audio>` element with the exact `data-start`, `data-duration`, and `data-volume` from the storyboard. Do not add, remove, or substitute SFX beyond what the storyboard says.

**Choose architecture based on pacing (from Step 3)**

| Pacing | Architecture | Why |

| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |

| **Fast** (billboard-per-beat) | Single `index.html`, stacked `<div class="beat">` elements, GSAP opacity sequencing. NO sub-compositions, NO HyperShader. Hard cuts via `tl.set()`. See stacked-beats pattern below. | Sub-compositions add latency; hard cuts need instant swaps. One file = zero load delay. |

| **Moderate / Slow / Arc** | Sub-compositions with `HyperShader.init()`. Each beat in `compositions/beat-N.html`. CSS crossfades or shader transitions between scenes. | Transitions need HyperShader's compositing. Sub-agents build each beat independently. |

If the storyboard says "fast" pacing: use the stacked-beats pattern below. Do not use HyperShader — it adds scene registration overhead that creates gaps between hard cuts. Every frame is content, no transition frames.

**Stacked-beats pattern (fast pacing):**

Each beat composes from whatever primitives the storyboard called for — HTML/CSS, SVG, captured assets, WebGL, Canvas, Three.js, kinetic typography, Lottie — alone or in combination. Narrow no-go: never a full-bleed product-UI screenshot as load-bearing content. Each beat's structure comes from the storyboard's Composition + Accents spec.

```html

<div

data-composition-id="video"

data-width="1920"

data-height="1080"

data-start="0"

data-duration="TOTAL"

style="position:relative;width:1920px;height:1080px;"

<span class="w">context-switching.</span>

</div>

<div class="card">Triage tickets</div>

<div class="card">Review PR</div>

</div>

<div class="card active">Design spec</div>

</div>

</div>

</div>

</div>

```

If you ever find yourself writing `<img src="capture/assets/...">` as a beat's primary visual where the asset is a product-UI screenshot, stop. That's the slideshow pattern this skill exists to break. Build the element from divs and CSS using the brand colors from DESIGN.md. The legitimate `<img>` uses are: (a) the brand logo when it's purely raster, (b) a hero illustration layered as ambient depth behind composed content, (c) a gradient/texture image as a background wash. Never a product UI screenshot as the load-bearing visual.

```css

.beat {

position: absolute;

inset: 0;

width: 1920px;

height: 1080px;

display: flex;

align-items: center;

justify-content: center;

opacity: 0;

overflow: hidden;

}

```

```javascript

var beats = [

{ id: "b01", at: 0, dur: 1.8 },

{ id: "b02", at: 1.8, dur: 1.0 },

// ...

];

beats.forEach(function (b) {

var el = document.getElementById(b.id);

if (b.id !== "b01") tl.set(el, { opacity: 1 }, b.at);

gsap.set(el, { scale: 1.012 });

tl.to(el, { scale: 1, duration: 0.25, ease: "power2.out" }, b.at);

if (b !== beats[beats.length - 1]) tl.set(el, { opacity: 0 }, b.at + b.dur);

});

```

Each beat gets its own visual world — different background, different color, different energy. No two consecutive beats should look alike. Scale pulse (1.012→1.0) on every beat entry is subtle but felt.

If the storyboard says "slow" or "cinematic": build each beat as a sub-composition. Use long crossfades (0.8–1.2s `duration` with no `shader` key = CSS crossfade). Inside each beat, use continuous subtle motion — nothing is static:

- Slow camera drift on the composed scene root: `tl.fromTo(scene, {scale:1.05, x:20}, {scale:1, x:-20, duration: BEAT, ease:"none"})` (Ken-Burns style, but on your composed elements — not on a screenshot)

- Parallax text layers: `tl.fromTo(text, {y:30}, {y:-30, duration: BEAT, ease:"power1.inOut"})`

- 1–2s breathing room before text enters (don't animate everything at t=0)

- Soft easing: `expo.out` for entrances, `power1.inOut` for drifts

**Multi-scene index.html with HyperShader — for moderate/slow/arc pacing**

For videos with sub-composition beats and scene transitions, `index.html` MUST use `HyperShader.init()`. This is the entire scene orchestration layer. Do NOT try to use registry block sub-compositions (e.g. `compositions/domain-warp-dissolve.html`) for transitions — those are standalone showcase demos, not how HyperShader works in multi-scene compositions.

Copy the local shader build first:

```bash

cp packages/shader-transitions/dist/index.global.js <project-dir>/hyper-shader-local.js

```

Full working `index.html` pattern — every field matters:

```html

<div id="root" data-composition-id="main" data-start="0" data-duration="TOTAL"

data-width="1920" data-height="1080">

<!-- Host divs: MUST have both id AND data-composition-id matching the same value.

HyperShader.init() uses getElementById() — without id="beat-1" it fails with

"scene ids not found in DOM". -->

<div id="beat-1" class="scene"

data-composition-id="beat-1-hook"

data-composition-src="compositions/beat-1-hook.html"

data-start="0"

data-duration="4.5"

data-track-index="1"

data-width="1920" data-height="1080"

style="background: #YOUR_BEAT_BG_COLOR;">

</div>

<div id="beat-2" class="scene"

data-composition-id="beat-2-features"

data-composition-src="compositions/beat-2-features.html"

data-start="4.0"

data-duration="5.5"

data-track-index="2"

data-width="1920" data-height="1080"

style="background: #YOUR_BEAT_BG_COLOR;">

</div>

<!-- ALWAYS add a dummy s-end scene as the LAST entry.

HyperShader renders scenes[N-1] as black in some contexts.

s-end is invisible — it just prevents your CTA from being last. -->

<div id="s-end" class="scene"

data-composition-id="s-end"

data-start="TOTAL_MINUS_0.1"

data-duration="0.1"

data-track-index="N"

data-width="1920" data-height="1080">

</div>

window.__timelines = window.__timelines || {};

var tl = HyperShader.init({

bgColor: "#000000",

accentColor: "#YOUR_ACCENT",

scenes: ["beat-1", "beat-2", "beat-3", ..., "s-end"],

transitions: [

{ time: 4.0, shader: "sdf-iris", duration: 0.7 }, // WebGL shader

{ time: 9.5, duration: 0.5 }, // CSS crossfade (no shader)

// ... one transition per scene boundary ...

{ time: TOTAL_MINUS_0.1, duration: 0.1 } // dummy → s-end

});

// Add ALL beat animations to the returned tl AFTER init()

window.__timelines["main"] = tl;

</script>

```

**Track index and the linter:** Use sequential track indices (`data-track-index="1"`, `"2"`, `"3"`...) for each beat — NOT all on track `"1"`. The linter flags overlapping clips on the same track as an error, and HyperShader compositions always have overlapping beats (the transition window). Using sequential indices silences the linter; HyperShader manages which scene is VISIBLE via opacity regardless of track index.

**Scene background colors:** setting `style="background: #3139FB"` on the host `<div id="beat-1">` in index.html is the simplest pattern — it's visible at a glance from the root file. Setting background inside the sub-composition's CSS also works. Either is fine; host div is preferred for clarity.

**Critical: beat host divs must have sequential `data-start` and matching `data-duration`.** Do NOT set `data-start="0"` on all beats — the render engine seeks each beat's GSAP timeline to `global_time - data_start`. At t=10s with `data-start=0`, a 5.5s timeline is seeked past its end and all content disappears.

`data-duration` must match the GSAP `BEAT` constant in the composition (the length of the sub-composition's internal timeline). If the two disagree, animations get cut off.

**Storyboard Beat Timing section** tells you both values — use them directly:

- `data-start` = "Transition in at:" value from the storyboard

- `data-duration` = "GSAP duration:" value from the storyboard

**Font handling:** Common fonts are auto-resolved by the renderer: use `"Inter"` (not `"Inter Variable"` — the compiler only maps the base name), `"Roboto"`, `"JetBrains Mono"`, `"Poppins"`. If a composition uses `"Inter Variable"` it will log compiler warnings and may fall back incorrectly — always use `"Inter"`. Only brand-specific fonts (GT Walsheim, Aeonik, etc.) need `@font-face`. Check `capture/assets/fonts/` — hashed filenames are Google Fonts subsets that auto-resolve; recognizable filenames (e.g. `BrandSans-Bold.woff2`) are brand fonts that need `@font-face` declarations.

**Brand font @font-face:** If the storyboard's BRAND VALUES lists a brand-specific font with a path in `capture/assets/fonts/`, add the `@font-face` block at the top of each composition that uses it — sub-agents won't do this unless you tell them explicitly. Paste the exact `@font-face` declaration in the sub-agent prompt's BRAND VALUES section. Without this, every composition falls back to `system-ui` and the brand typeface never loads.

**⚠ ASSET PATHS — most common sub-agent mistake (5+ agents per run):** When a composition references a captured accent (logo, gradient layer, hero illustration), the path must be relative to the **PROJECT ROOT**, not to the composition file. `compositions/beat-N.html` lives one directory deep, but paths must be written as if from the root.

- ✅ `capture/assets/logo.svg`

- ❌ `../capture/assets/logo.svg`

The Studio preview server rewrites base URLs to the project root — `../` paths that seem to work locally will 404 in preview and in renders. Add this verbatim to every sub-agent prompt's RULES section.

## 3. Build each composition — USE SUB-AGENTS

**Before dispatching, re-read DESIGN.md and STORYBOARD.md.** You wrote these files earlier in the session and you think you remember them. You don't — not the exact hex values, not the specific font families, not the button border-radius, not the Do's/Don'ts. Re-read them now so you can paste accurate brand rules and beat specs into each sub-agent prompt.

**If your runtime supports parallel sub-agents** (Claude Code, Cursor, most agent frameworks): dispatch one sub-agent per beat — 3 to 4× faster than building sequentially. For 3+ beats, always dispatch in parallel. For 1–2 beats, sequential is fine.

**If your runtime does not support parallel sub-agents** (some Codex setups, serial-only models): build sequentially using the same context-packing template below. The template gives each build pass the same context a sub-agent would get — paste prev/this/next beat + brand values — so output quality is the same, just slower.

In either case, use the template. Do not skip it and build from memory.

Each sub-agent reads [beat-builder-guide.md](beat-builder-guide.md) — it has everything: rules, easing, file references, validation commands. **Do not try to paste all rules into the prompt yourself.** Instead, tell the sub-agent to read the guide file. You paste only the beat-specific context: the storyboard sections, brand values, and asset paths.

```

Build the composition for Beat N. Save to compositions/beat-N-name.html.

FIRST: Locate and read the beat-builder guide. Your CWD is the project directory, so

the skill lives outside it — run this to find it:

find "$HOME" -path '*/website-to-hyperframes/references/beat-builder-guide.md' -maxdepth 10 2>/dev/null | head -1

Read that file end to end. It has your full workflow, all rules, easing vocabulary,

and file references. Follow its workflow exactly:

build → lint (`npx hyperframes lint .`)

→ snapshot (`npx hyperframes snapshot . --frames 3`)

→ view contact sheet AND read snapshots/descriptions.md

→ fix issues

After you finish, the main agent will READ your composition HTML top-to-bottom

and cross-check it against DESIGN.md and STORYBOARD.md — does the brand bg/accent

hex actually appear in your CSS, are the captured assets the storyboard called

for actually referenced, is the headline ≥80px, does the GSAP timeline cover

the full beat duration. Do the work honestly. Reports of "looks good" without

the work being done will be caught when the main agent opens the file.

═══ PREVIOUS BEAT (Beat N-1) ═══

[paste the FULL previous beat section from STORYBOARD.md]

═══ THIS BEAT (Beat N) ═══

[paste the FULL beat section from STORYBOARD.md — this IS the build spec]

═══ NEXT BEAT (Beat N+1) ═══

[paste the FULL next beat section from STORYBOARD.md]

═══ BRAND VALUES (from DESIGN.md) ═══

Colors:

--bg: #[hex] primary background

--fg: #[hex] primary text

--accent: #[hex] CTA / highlights

--surface: #[hex] card / panel backgrounds

[add more if needed]

Fonts:

Headlines: [font family], [weight]

Body: [font family], [weight]

[brand font path if needed: capture/assets/fonts/Brand.woff2]

Key component styles:

[paste relevant lines from DESIGN.md]

═══ CAPTURED ASSETS FOR THIS BEAT ═══

[Paste ACTUAL file paths + descriptions from asset-descriptions.md:

- capture/assets/hero-dashboard.png — full-bleed product dashboard, dark theme

- capture/assets/logo.svg — brand wordmark, white on transparent

Do NOT say "see asset-descriptions.md". Paste the paths here.]

```

The storyboard beat already contains everything — the concept, the visual choreography with exact timings, the CSS values, the SFX cues. The sub-agent's job is to translate that description into working HTML/CSS/GSAP, not to re-invent the creative direction. If you want, you can also paste any other relative and useful context to subagents if think it's good, why not.

### Per-composition process

For each beat:

**1. Read the storyboard beat.** The storyboard IS the build spec. It tells you what elements exist, how they enter, what they do during the beat, and how they exit. Follow it. If something in the storyboard isn't clear or seems impossible, research how to do it or ask — don't silently skip it.

**2. Build the static end-state first.** Position every element at its most visible moment. HTML+CSS only, no GSAP yet. The CSS position is the ground truth.

**3. Add the animation sequence.** Follow the storyboard's choreography — it specifies what happens and when. Use `tl.fromTo()` (not `tl.from()`) for entrances. Build the timeline in the order the storyboard describes.

**4. Add exit** (if CSS transition out). If shader transition — no exit animation needed.

**5. View the result.** After building, take a snapshot of this beat at different timestamps (where things are supposed to happen, animate, move and etc) and look at it from all angles, corners and positinos. Is the frame full and everything is exactly where it supposed to be? Are you sure??? Are elements readable? Does it match what the storyboard describes?

### Technical rules

- **No `repeat: -1`** — calculate exact repeats from beat duration

- **No `Math.random()`** — use a seeded PRNG

- **No bare `gsap.to()`** — all tweens on `tl`, never standalone

- **No full-screen dark linear gradients** — H.264 banding

- **Minimum fonts**: 80px+ headlines, 20px+ body

- **WCAG contrast on gradient backgrounds:** The contrast validator samples actual background pixels under the text element — if the background is a gradient image, darker parts of the image make the measured ratio _worse_ when you darken the text color, not better. Fix: either place text over a solid-color zone, or add `data-layout-ignore` attribute to decorative labels that don't need WCAG compliance. Don't blindly darken text color when the background isn't solid.

## 4. After all compositions are built — reconciliation check

Before moving to Step 6, run this sanity check:

```bash

# List every file in compositions/ and verify each one has a host div in index.html

ls compositions/

```

For every `.html` file in `compositions/`, confirm that `index.html` has a `data-composition-src="compositions/<filename>"` pointing to it. If any composition file is not referenced in `index.html`, add the missing host div now — an unreferenced composition is completely invisible at runtime.

**Captions stub rule:** Never create a `compositions/captions.html` with an empty transcript (`const script = [];`). If the VO/transcript step was skipped or failed, do not create the captions composition at all. An empty captions file that returns immediately is worse than no captions file — it silently does nothing and wastes a track slot.

### Parallel sub-agent snapshots are stale — re-snapshot after all complete

When you dispatch sub-agents in parallel (one per beat), each sub-agent snapshots a project where sibling beats may not exist yet. Their per-beat snapshots are valid for THEIR beat in isolation, but **any snapshot at a beat boundary or during a shader transition will show the wrong content** — typically the previous beat's content because the next beat hasn't been built.

Example: Beat 6's sub-agent took a snapshot at t=25.7s and saw Beat 1's content because Beat 5 didn't exist yet when Beat 6's sub-agent ran. The sub-agent reported this as "shader transition behavior showing previous scene" — a plausible-sounding but wrong diagnosis.

**Required after all sub-agents complete:**

```bash

node /<repo-root>/packages/cli/dist/cli.js snapshot <project-dir> --frames <N>

```

where N follows the snapshot formula: `max(beats × 3, ceil(duration_seconds / 2))`. This is the canonical snapshot that Step 6's DoD uses — not any individual sub-agent's intermediate snapshots.

Sub-agents' snapshots are still useful as per-beat sanity checks, but they are not the deliverable. The post-completion snapshot is. Don't skip it because "the sub-agents already snapshotted."

## 5. Read each beat HTML top-to-bottom — REQUIRED gate before Step 6

**This gate is non-skippable.** "I read it and it looks fine", "the sub-agent confirmed", "the snapshots look right" are NOT acceptable. Snapshots are 3 frames out of 300+ in motion — they hide everything that goes wrong between them.

**Why this gate exists:** Earlier sessions had sub-agents reply "looks good, 0 errors" and the main agent trusted them — that's how videos shipped with mismatched colors, missing logos, headlines too small to read, and SFX firing 1 second late because the agent typed timestamps "by eye" instead of computing them.

For each `compositions/beat-N.html`:

1. **Open the file and read it top-to-bottom.** Not a glance. Not a grep. Read the `<style>` block, then the markup, then the `<script>` block.

2. **Fill in this evidence block — every line, with quoted values from the file:**

```

Beat N: compositions/beat-N-NAME.html

BG color in CSS: <hex from line Y> ← quote the exact line

Accent color in CSS: <hex from line Z> ← quote the exact line

Headline font-size: <px from line> (≥80? yes/no)

Headline font-family: <stack from line> (matches DESIGN.md? yes/no)

@font-face src paths: <list> (each path exists? yes/no)

Captured assets used: <full list of paths from <img src=>, inline SVG ids, background-image url()>

Storyboard called for: <list from STORYBOARD.md beat N>

Assets match storyboard? yes/no — if no, specify the gap

GSAP first event: tl.X("...", {...}, <t>) beat-local t=<num>

GSAP last event: tl.X("...", {...}, <t>) beat-local t=<num>

Beat duration: <N>s (events span full duration? yes/no)

SFX trigger: <element> data-start=<num>

Storyboard SFX line: "<quote the line>" → expected t=<num>

SFX timestamp matches? yes/no — if no, specify the drift

Technical gates: data-composition-id matches window.__timelines key? yes/no

script INSIDE <template>? yes/no

no Math.random / no repeat:-1 / no bare gsap.to? yes/no

VERDICT: PASS / FIX (specify exactly what)

```

If you cannot fill any line (e.g., "I see no SFX trigger" or "headline font-family not specified"), that IS a finding — fix or escalate, don't paper over.

3. **Open each frame in `snapshots/beat-N/`** and confirm visually that entrance/hold/exit match the storyboard.

**Anything off — fix it inline (small CSS/GSAP correction) or re-dispatch the sub-agent with the specific problem quoted.** Do not move to Step 6 until every beat has its evidence block filled and PASS.

### SFX timestamp computation — compute, don't eyeball

Every SFX `data-start` value MUST be computed from STORYBOARD.md, not estimated visually.

For each SFX entry:

1. Storyboard names beat-local time (e.g. "Beat 2 at 1.2s into the beat").

2. Get the beat's global start time from beat ordering (e.g. Beat 1: 0–3.5s → Beat 2 starts at 3.5s globally).

3. Add beat-local + global start: `3.5 + 1.2 = 4.7s`.

4. Write `data-start="4.7"` in index.html.

**Forbidden:** writing `data-start="<approximate visual moment>"` by reading the storyboard and estimating by eye. The evidence block above MUST quote both the storyboard SFX line and the index.html `data-start` line — and confirm they match within ±0.1s (≈3 frames at 30fps; same tolerance `w2h-verify.mjs` enforces and `step-6-validate.md` uses for playback verification). A 1-second drift is not a rounding error; it's a build failure.

### Surface recurring sub-agent workarounds to the user

When 2+ sub-agents independently report the same workaround (e.g., "I had to base64-encode the data URI because the linter false-positives on inline SVG"), that's a tooling bug worth surfacing. List these in your Step 5 final report under "Tooling issues encountered" even if each instance was resolved. Format:

```

TOOLING ISSUES (worth filing):

- 3 sub-agents (beats 1, 4, 6) hit `root_missing_composition_id` false positive on

inline SVG data URI in CSS. Workarounds: base64 (beat 1), removed overlay (beats 4, 6).

Worth filing as a regression against packages/core/src/lint.

```

Burying recurring workarounds means the next session hits the same bug and works around it again. Don't.

### Brand-defaults check (whole-video, after every beat passes its own read)

These are defaults for most brand videos, not hard requirements:

- First beat references the brand logo / wordmark SVG from `capture/assets/svgs/`

- Last beat references the brand logo / wordmark

- The site's signature visual (hero illustration, gradient wave, distinctive UI mark) shows up at least once

If any are missing, check the storyboard — if STORYBOARD.md deliberately delays brand reveal or omits the signature visual for a concept reason, that's fine. If the omission was unintentional, fix it (or ask the main agent / user before adding).

Once every beat reads clean, move to Step 6 (Validate & Deliver) for lint, validate, snapshots, and visual review.

mdskills/website-to-hyperframes/references/step-6-validate.md

23 kB

# Step 6: Validate & Deliver

This is the quality gate. Before the user sees anything, YOU verify that the video matches the storyboard, the creative direction from Step 2, and DESIGN.md. Deliver something you'd be proud to post with your name on it.

## Definition of Done — required before ANY preview or summary

**You may not say the video is ready, looks good, or present a preview URL until every item below is checked.** No exceptions. Do not summarize your impressions — paste the actual evidence for each.

Score each item 1–5. If any item scores below 3, fix it before continuing. **Do not rush these.** Each checkbox is its own pass through the artifacts — slow down, look at every frame, write the actual observation, not a summary impression.

```

[ ] Every beat HTML read top-to-bottom → see "Per-beat file read" below; paste the per-beat verdict

[ ] Lint: zero errors → paste the lint output (not "lint passed")

[ ] Snapshot taken, N frames confirmed → state the exact frame count

[ ] descriptions.md read in full → quote the WORST frame Gemini described, verbatim

[ ] Contact sheet viewed cell-by-cell → for EACH beat, one sentence: what's in frame, what's moving, what brand assets are present

[ ] No mid-video dark frames → state explicitly which frames (if any) are dark and why

[ ] Brand assets actually visible → for each beat, name which captured SVG / illustration / screenshot is on screen and at what timestamp. If a beat shows zero captured assets, justify why.

[ ] Audio duration matches video ±0.5s → paste both numbers

[ ] animation-map.json generated → run `node <repo-root>/skills/hyperframes/scripts/animation-map.mjs <project-dir>`; confirm every beat has events listed and no bbox/flag warnings

[ ] w2h-verify report → run `node <repo-root>/skills/website-to-hyperframes/scripts/w2h-verify.mjs <project-dir>`; paste the FULL output (every row, every percent) verbatim into your final user-facing summary — see "w2h-verify — the source of truth" below

[ ] Audio + motion verification done → see "Audio + motion verification" below; played the full preview, confirmed SFX lands at storyboard timestamps

[ ] Critic sub-agent run → paste its single biggest quality gap finding, verbatim

```

### w2h-verify — the source of truth

The skill ran for months on agents reading "REQUIRED" and skipping anyway. The verify script ends that — it computes facts the agent cannot fudge:

- **Required artifacts present** (STORYBOARD.md, DESIGN.md, SCRIPT.md, index.html)

- **Brand visuals used** — at least 1 beat must reference a captured `hero-*`, `image-*`, or `svgs/*.svg` asset (logo doesn't count). Catches the "9% asset usage / brand isn't visually present" failure.

- **Headline font-size** — per-beat, the largest CSS `font-size` must be ≥80px. Catches the "headlines too small to read" failure that surfaces later as inspect `clipped_text` errors.

- **Timeline coverage** — per-beat, GSAP event positions must span ≥70% of the beat's `data-duration`. Catches "webpage not shot" failures where the beat has entrance tweens then goes static.

- **Shader transitions consistency** — shaders declared in STORYBOARD.md must appear in index.html (with HyperShader runtime present, not just as SFX file references).

- **SFX timestamp drift** — storyboard `t=X.Xs` vs index.html `data-start=X.X`, picks the closest index timestamp per file for multi-timestamp SFX.

- **Beat duration consistency** — storyboard's beat ranges (`B4 — Name | 16.600 – 21.000s |`) must match `data-duration` in index.html within ±0.5s. Catches storyboard staleness.

- **Rendered MP4 existence** — INFO only; flagged when claiming verified motion without rendering.

Run it as the LAST gate in your DoD pass, after fixing everything else:

```bash

node <repo-root>/skills/website-to-hyperframes/scripts/w2h-verify.mjs <project-dir>

```

(Locate the repo root from a project subdirectory: `find "$HOME" -path '*/skills/website-to-hyperframes/scripts/w2h-verify.mjs' -maxdepth 10 2>/dev/null | head -1`.)

**The script's output is the deliverable.** Paste the entire report — the table, the percentages, the FAIL lines — verbatim into your final user-facing summary, in the "What I verified" / "What I did NOT verify" section. The user will read it directly. You don't get to summarize, simplify, or omit rows.

**If any row says FAIL:**

- Either fix the underlying issue and re-run until the row says PASS

- Or include the FAIL row verbatim in your final summary's "What I did NOT verify" section with a one-sentence explanation of why you chose not to fix it

**Forbidden:**

- Hand-writing your own verification summary that doesn't match the script's output

- Cherry-picking which rows to include

- Replacing percentages with adjectives ("most assets used" instead of "8%")

- Running the script, seeing FAIL, and not mentioning it

The script's exit code is 0 (all pass) or 1 (one or more fail). If you ship with exit=1, the user knows from the report exactly what they're getting.

### Per-beat file read

This is what verification means now: you open each `compositions/beat-N.html` and read it top-to-bottom against DESIGN.md and STORYBOARD.md. Step 5 already required this once before advancing here — repeat it here as the final check, in case fixes during Step 5 introduced new problems.

For each beat, write a per-beat verdict in this form:

```

Beat N (Ns–Ns) — <name>

CSS bg: <hex> (DESIGN.md says <hex>, matches: yes/no)

CSS accent: <hex> (DESIGN.md says <hex>, matches: yes/no)

Headline font-size: <px> (≥80: yes/no)

Captured assets referenced: <list of paths from <img>, inline SVG, background-image> (storyboard called for: <list>)

GSAP timeline coverage: events from <first t> to <last t>, beat duration <N>s (full coverage: yes/no)

Storyboard alignment: <one sentence — does this beat deliver what its STORYBOARD.md section described>

VERDICT: PASS / NEEDS FIX (<what specifically>)

```

The pre-fix-era flow took longer specifically because it caught these problems. Don't trade the careful look for a green checkmark.

**Why this matters:** The natural tendency is to look at a contact sheet, see that content is present, and declare it done. That is not verification — that is pattern-matching to a completion signal. Verification means opening every file the sub-agents produced, reading every line, and reporting the raw result. "Frame 7 at 14.2s shows the Raycast logo SVG drawing its final stroke at 0.85 opacity against #07080A, the headline 'Crush your sprint' has settled in 96px Inter SemiBold below" is evidence. "The video looks great" is not.

---

## Lint + Validate + Snapshot

The `hyperframes` skill (which you loaded in Step 5) already covers the mechanics of linting, validating, and snapshotting. Follow those rules — run lint, validate, take snapshots scaled to the video length (formula: `max(beats × 3, ceil(duration_seconds / 2))`). Fix errors. This step adds the **pipeline-specific verification** on top of that.

**Errors:** Fix ALL of them. These are real problems — missing timeline registration, broken scripts, missing assets.

**Warnings:** Read each one and decide. Some are real quality issues you must fix:

- **GSAP tween overlaps** — elements fighting over the same property = visual glitches

- **Unscoped selectors** — will target elements in ALL compositions when bundled, causing data loss

- **Missing `class="clip"`** — element visible for entire video instead of its scheduled time

- **Missing `data-start` on root** — playback won't begin

Some are style suggestions you can safely ignore:

- **File too large** — composition works fine, just harder to read

- **Deprecated attributes** (data-layer, data-end) — still work, just not preferred

- **Dense tracks** — informational, not a bug

**WCAG contrast warnings — per-warning verification, not blanket dismissal.**

The validator samples text colors at fixed timestamps. Elements at `opacity: 0` (pre-entrance) or mid-fade get measured as if fully visible — real false positives exist. BUT this is a per-warning judgment, not a blanket excuse.

**For EACH warning the validator emits, paste this block in your verdict:**

```

Warning N: <quote the validator output verbatim>

Element: <selector>

Sampled timestamp: t=<n>

At t=<n>, is this element on-screen at full opacity? (yes/no — confirm by viewing snapshot at that timestamp)

Verdict: REAL ISSUE / SAMPLING ARTIFACT (justify in one sentence)

Action: <hex change at line N> OR NONE because <reason>

```

**Forbidden:** writing "the N warnings are mostly transition-window false positives" without per-warning evidence. That phrasing alone fails the gate. The validator does not report 158 warnings as a group — it reports them individually, and you verify them individually.

Don't blindly ignore. Don't blindly fix. Verify each.

## Visual Verification (snapshot)

After lint and validate pass, capture snapshot frames to SEE your own output. **Take many snapshots — as much as you can actually read and view all of them without hitting diminishing returns**. This is your only visual feedback before the user sees the project. You wanna be honored and proud of what you give to the user.

Scale snapshot count to the video — not a fixed number. Formula: `max(beats × 3, ceil(duration_seconds / 2))`. A 3-beat 10s video: max(9, 5) = 9 frames. An 8-beat 60s video: max(24, 30) = 30 frames. Aim for at least 3 frames per beat: entrance, hold, and near-exit.

```bash

# The CLI auto-loads .env from the current working directory, so a

# .env file in <project-dir> with GEMINI_API_KEY=... is enough — no

# explicit `export` needed. If you've set GEMINI_API_KEY in your shell

# environment, that works too.

npx hyperframes snapshot <project-dir> --frames <N>

# Pass a custom question to Gemini instead of the default prompt:

npx hyperframes snapshot <project-dir> --frames <N> \

--describe "Is the brand logo visible in every beat? Is any beat showing a black or blank frame?"

```

Output lands in `<project-dir>/snapshots/`. Gemini writes `snapshots/descriptions.md` automatically.

**If `descriptions.md` is missing or empty after the snapshot:** `GEMINI_API_KEY` was not set — confirm it's in `<project-dir>/.env` (the CLI loads .env from CWD) or in your shell environment. Re-run after fixing.

**Fallback if Gemini is genuinely unavailable** (no key, key invalid, or quota exhausted): use your own image-reading capability to inspect each frame in `snapshots/` directly. For each frame, write one sentence describing what's on screen — focus on the dimensions Gemini would catch (blank/dark frames, missing brand assets, text legibility, layout problems). Save these descriptions as `snapshots/descriptions.md` yourself so the rest of the checklist still has a single source of truth. State explicitly in your verdict that descriptions were agent-authored, not Gemini-authored, so the user knows to spot-check.

**Gemini descriptions will flag two frames as "blank/black" — these two are expected and not bugs:**

- `frame-00-at-0.0s.png` — always dark, animations haven't started

- The last frame of the video — always dark, the s-end dummy scene is intentionally invisible

Every other frame described as "black," "blank," "no visible content," or "loading screen" in the middle of the video IS a bug. Investigate and fix it.

**Two required reads — both, not one. Then a per-beat verdict.**

1. **Read `snapshots/descriptions.md`** — Gemini's objective written analysis of every frame. Read every line. Do not skim.

2. **View `snapshots/contact-sheet.jpg` cell-by-cell.** Not a glance. Look at every cell, name what's in it. Past agents have reported "contact sheet looks good" after a single scan and missed: a beat that was visually black for 80% of its duration, a logo placed off-screen, a headline clipped at the canvas edge, captions running off the bottom. The contact sheet is the only place these failures are visible together. **For each cell, write one sentence: what's in frame, what's moving, which brand assets are present, anything that looks wrong.** If you find yourself wanting to summarize the contact sheet as a whole, stop and go back to cell-by-cell.

After reading both, write a per-beat verdict for every beat:

```

Beat 1 (0.0s–4.5s): [what Gemini described] | [what contact sheet shows] | PASS / NEEDS FIX

Beat 2 (4.0s–9.5s): ...

Beat 3 ...

CTA beat: ...

```

A beat PASSES only if:

- Gemini description matches what STORYBOARD.md says should be happening

- Contact sheet shows visible content (not black, not blank, not loading)

- Brand colors/fonts visible

- No elements clipped or mispositioned

A beat that "has some content" does not automatically pass. Compare against what was _planned_, not just "something is there."

**If any beat fails: fix it, re-snapshot, re-read descriptions.md, re-write the per-beat verdict from scratch.** Do not carry forward old verdicts after a fix — re-evaluate everything because fixes can break adjacent beats.

**Keep iterating until every beat passes.** There is no time limit. A video with one black CTA beat is not done.

## Critic Sub-Agent — do not skip

**This is not optional. Run it after your per-beat verdicts all pass — before you start preview.**

Spawn a sub-agent with this exact prompt:

```

You are a senior motion designer and creative director reviewing a brand video before it ships. You have high standards and have seen hundreds of these.

Read these files:

- STORYBOARD.md (what was planned)

- DESIGN.md (brand rules)

- snapshots/descriptions.md (what Gemini sees in each frame)

- snapshots/contact-sheet.jpg (view it)

Score each dimension 1–5. Be specific — name the beat and timestamp for every problem you identify.

1. **Beat execution** (1–5): Does every beat deliver what STORYBOARD.md planned? Name any beat that underdelivers and what exactly is wrong.

2. **Brand accuracy** (1–5): Does this feel made for THIS brand specifically, or could it be for any company? Name one element that is distinctly on-brand and one that is generic.

3. **Captured asset utilization** (1–5): The user captured the brand's actual SVG logos, hero illustrations, and screenshots into `capture/assets/`. Are they on screen in this video, or did the agents recreate everything from divs and CSS? List which captured assets appear in which beats. If beats are missing them, flag it — a video that recreates everything in CSS is generic, not branded.

4. **Visual quality** (1–5): Any blank frames, clipped text, centering failures, invisible elements? Cite exact frame timestamps.

5. **Motion design** (1–5): Do animations feel intentional and polished, or default and mechanical? Name the weakest transition and why.

6. **CTA beat** (1–5): Is the final beat clear, centered, readable, and does it hold long enough? Describe exactly what is visible on the CTA frame.

End with: What is the single most important fix before this ships? Name the beat, the element, and the specific change.

If you cannot find any problems and want to score everything 4–5, you are not looking hard enough. Look again.

```

Read every score. Fix anything below 3 before showing the user. If the CTA scores below 3, fix the CTA. Do not rationalize low scores as "the user can decide."

## Audio + motion verification — three paths, pick one

Snapshots are silent stills. 18 PNG snapshots from a 30s 30fps video = 18/900 = 2% of frames. The other 98% — including all motion, all transitions, all audio — is unverified by snapshots alone. "Confirmed via snapshot" is not coverage.

You MUST do ONE of these three paths before declaring done:

### Path 1 (preferred): Play the preview

Open the Studio URL in a browser via Playwright (or another browser tool you have). Play start-to-end at 1.0× speed (NOT scrubbed). Confirm:

```

[ ] Played full video front-to-back at 1.0× — actually played, not scrubbed

[ ] For each SFX in STORYBOARD.md: sound lands at the visual moment within ±0.1s

(Beat N SFX `<file>`: storyboard says t=<x>s → heard at t=<y>s → drift <z>s)

[ ] Narration delivers the right line per beat (no off-by-one or missing lines)

[ ] No moments where audio is present but visual is mid-transition unintentionally

[ ] Audio audible and not clipped/peaked

```

### Path 2: Render a low-res MP4 and read it frame-by-frame

When Playwright isn't available, render at 540p (fast — ~30s for a 30s video) and read the MP4:

```bash

node /<repo-root>/packages/cli/dist/cli.js render <project-dir> \

--width 960 --height 540 --quality medium

```

Then sample the resulting MP4 at minimum 5fps (use `ffmpeg -i <mp4> -r 5 frames/frame-%04d.png` if needed). Read those frames sequentially. For each SFX moment in STORYBOARD.md, find the corresponding frame and confirm the visual matches.

### Path 3 (last resort): Explicit deferred disclosure with quantified gap

If neither Path 1 nor Path 2 is possible in this session, your final summary MUST contain this verbatim:

```

**Audio + motion verification: NOT POSSIBLE in this session.**

- Snapshots cover: <N> frames out of <video_duration × fps> total (<percentage>% coverage)

- NOT verified: motion between snapshots, SFX/visual timing alignment, shader transition smoothness, audio mix levels, narration sync to beats

- Recommended user action: open the preview URL above and play start-to-end; flag anything that feels off

```

**Forbidden everywhere:**

- "Confirmed via snapshot" or "snapshots look right" as audio/motion evidence

- "Preview is running, looks good" without actually playing it

- Path 3 disclosure that omits the quantified coverage gap (the percentage is mandatory)

## Preview (always do this)

Always start the preview so the user can see and scrub through the project:

```bash

npx hyperframes preview

```

The Studio URL is the deliverable. In your final response, always include it:

```text

http://localhost:<port>/#project/<project-name>

```

Use the actual port and project name from the preview command output. Do NOT present `index.html` as the project link — that's the source file. The user-facing project is the running Studio preview.

### Honest disclosure — REQUIRED in your final summary

Your final message to the user MUST end with these two sections, even if everything passed. Both sections appear AFTER the preview URL, BEFORE you stop talking.

```

**What I verified:**

- <one bullet per DoD item that passed, with the actual evidence cited inline>

(e.g. "Lint: zero errors — output pasted above")

(e.g. "Per-beat read: 7/7 beats PASS, evidence blocks above")

(e.g. "WCAG: 3 warnings flagged, all 3 verified as sampling artifacts — see verdicts above")

**What I did NOT verify (spot-check these):**

- <one bullet per item you skipped, deferred, or could not complete — and why>

(e.g. "Audio + motion verification deferred — no Playwright in this session. SFX timing is computed but unconfirmed in playback.")

(e.g. "animation-map.json skipped — script not found at expected path; manually confirmed timeline coverage in per-beat reads instead.")

(e.g. "Beat 5 has a 0.4s window where the doc card is visible but contents are still opacity 0 — sub-agent flagged it, I chose not to fix because it was below my threshold; worth your eye.")

```

The user reads this section to know what to spot-check.

**UNACCEPTABLE final summaries:**

- "Looks great, ready to ship" (no disclosure)

- "All checks pass" (when one was actually skipped)

- "Sub-agents confirmed everything" (delegating trust without verifying)

- Omitting the "What I did NOT verify" section because you happened to verify everything (still include it — write "None" if true, but the section header must appear).

Lying or omitting here is worse than skipping a check honestly. A short user spot-check beats a hidden broken video every time.

## Render (on-demand only)

**Do NOT render automatically.** Preview is the delivery — the user scrubs, spots tweaks, and you iterate. Rendering takes minutes per pass and is wasted if the user wants changes.

Only render when the user **explicitly asks** — "render it", "make the final", "export the MP4", "I'm happy, produce the file."

When rendering, **always specify quality and resolution explicitly.** Don't use defaults silently — pick the right settings for the use case and tell the user what you're rendering:

```bash

# Standard quality, 1080p landscape (default for most videos)

npx hyperframes render --output renders/<name>.mp4 --quality standard --fps 30

# High quality for final delivery

npx hyperframes render --output renders/<name>.mp4 --quality high --fps 30

# Portrait for Instagram Stories / TikTok

npx hyperframes render --output renders/<name>.mp4 --quality standard --fps 30 --resolution portrait

# 4K for premium output

npx hyperframes render --output renders/<name>.mp4 --quality high --fps 30 --resolution 4k

```

**Available options:**

| Flag | Values | Notes |

| ----------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |

| `--quality` | `draft`, `standard`, `high` | draft = fast/low, standard = balanced, high = slow/best |

| `--fps` | `24`, `30`, `60` | 30 is standard, 24 for cinematic feel, 60 for smooth motion |

| `--resolution` | `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` | Aliases: `1080p`, `4k`, `uhd` |

| `--format` | `mp4`, `webm`, `mov`, `png-sequence` | mp4 default. mov/webm for transparency. png-sequence for AE/Nuke |

| `--output` | path | Always set to `renders/<project-name>.mp4` for readable names |

| `--gpu` | flag | Use GPU encoding if available (faster) |

| `--crf` | integer | Override encoder quality (lower = better, mutually exclusive with --video-bitrate) |

| `--video-bitrate` | e.g. `10M` | Target bitrate (mutually exclusive with --crf) |

Tell the user what you're rendering and why: "Rendering at standard quality, 1080p landscape, 30fps — this gives good quality with reasonable render time. Want me to use high quality or 4K instead?"

mjsskills/website-to-hyperframes/scripts/w2h-verify.mjs

28 kB

#!/usr/bin/env node

// w2h-verify.mjs — verification report for a website-to-hyperframes project.

// Computes quality signals the agent cannot fudge. Each check is designed to

// catch a specific failure mode observed across three real agent debriefs.

// Result becomes the Step 6 deliverable — paste verbatim into the final

// user-facing summary so the user sees exactly what shipped.

// Pure file analysis. No shell spawns. Run lint + inspect separately and

// paste alongside.

// Usage:

// node skills/website-to-hyperframes/scripts/w2h-verify.mjs <project-dir>

// Exit codes:

// 0 = all gates pass

// 1 = one or more gates failed

// 2 = script error (project-dir missing, etc.)

import { readFile, readdir } from "node:fs/promises";

import { join, resolve } from "node:path";

import { existsSync } from "node:fs";

const PROJECT_DIR = resolve(process.argv[2] || ".");

// Thresholds — change here, not by interpretation.

const HEADLINE_MIN_PX = 80; // 80px floor for primary headline at 1920×1080

const TIMELINE_COVERAGE_MIN = 0.7; // max GSAP event position must reach ≥70% of beat duration

const SFX_DRIFT_TOLERANCE_S = 0.1; // 3 frames at 30fps; matches step-5 evidence rule + step-6 playback floor

const BEAT_DURATION_DRIFT_TOLERANCE_S = 0.5;

const SHADER_NAMES = [

"cross-warp-morph",

"cross-warp",

"cinematic-zoom",

"gravitational-lens",

"glitch",

"light-leak",

"flash-through-white",

"whip-pan",

"domain-warp",

"thermal-bloom",

"swirl",

"ridged-noise",

"sdf-reveal",

"chromatic-aberration",

"ripple",

];

async function main() {

if (!existsSync(PROJECT_DIR)) {

console.error(`✗ Project directory not found: ${PROJECT_DIR}`);

process.exit(2);

}

const results = [];

results.push(await checkRequiredArtifacts());

results.push(await checkBrandVisualsUsed());

results.push(await checkPerBeatHeadlineSize());

results.push(await checkPerBeatTimelineCoverage());

results.push(await checkShaderTransitionsConsistency());

results.push(await checkSfxTimestampConsistency());

results.push(await checkBeatDurationConsistency());

results.push(await checkMp4Exists());

printReport(results);

const anyFail = results.some((r) => r.status === "FAIL");

process.exit(anyFail ? 1 : 0);

}

// ─── Checks ──────────────────────────────────────────────────────────────────

async function checkRequiredArtifacts() {

const required = ["STORYBOARD.md", "DESIGN.md", "SCRIPT.md", "index.html"];

const missing = required.filter((f) => !existsSync(join(PROJECT_DIR, f)));

if (missing.length === 0) {

return { name: "Required artifacts", status: "PASS", detail: required.join(", ") };

}

return {

status: "FAIL",

detail: `missing: ${missing.join(", ")}`,

};

}

// Catches the biggest failure mode: agent uses only the logo and rebuilds

// every "hero illustration" from CSS, ignoring the brand's actual visual identity.

async function checkBrandVisualsUsed() {

const compositions = await readBeatCompositions();

if (compositions.length === 0) {

return { name: "Brand visuals used", status: "INFO", detail: "no beat compositions found" };

}

// A "brand visual" is anything captured under capture/assets/ that ISN'T:

// - a font file

// - a logo file (filename contains "logo")

// - a favicon / apple-touch-icon

// i.e., hero-*.jpg, image-*.png, illustrations, photographs, svgs/<icons>.svg

const brandRegex =

const beatsUsingBrand = [];

for (const beat of compositions) {

const matches = beat.content.match(brandRegex) || [];

if (matches.length > 0) {

beatsUsingBrand.push({ beat: beat.name, count: new Set(matches).size });

}

const pass = beatsUsingBrand.length >= 1;

if (pass) {

return {

status: "PASS",

detail: `${beatsUsingBrand.length}/${compositions.length} beats reference a hero/image/svg captured asset`,

extra:

beatsUsingBrand.length === 1

? "Only 1 beat uses a captured visual — consider whether the brand's hero illustrations or signature graphics fit other beats too."

: null,

};

}

return {

status: "FAIL",

detail: `0/${compositions.length} beats reference any hero-*/image-*/svgs/ captured asset (logo doesn't count)`,

extra:

"Open capture/assets/contact-sheet-*.jpg and capture/assets/svgs/contact-sheet-*.jpg. The brand's actual visuals are sitting there. Rebuilding them in CSS erases what makes the brand recognizable.",

};

}

// Catches "headlines too small to read" — inspect typically catches the

// overflow afterward, but this catches the cause earlier.

async function checkPerBeatHeadlineSize() {

const compositions = await readBeatCompositions();

if (compositions.length === 0) {

return { name: "Headline font-size", status: "INFO", detail: "no beat compositions found" };

}

// Only flag beats where the LARGEST font-size is in the "aspiring headline

// but too small" range (40–<80px). Below 40px = the beat has no headline by

// design (UI labels, code text, decorative). ≥80px = proper headline.

// This skips legitimate non-headline beats (terminal beats, SVG-only beats,

// pure-image beats) without losing the real "headline too small" signal.

const HEADLINE_FLOOR_FOR_CHECK = 40;

const offenders = [];

const skipped = [];

for (const beat of compositions) {

const sizes = [...beat.content.matchAll(/font-size:\s*(\d+(?:\.\d+)?)px/g)].map((m) =>

parseFloat(m[1]),

);

if (sizes.length === 0) {

skipped.push({ beat: beat.name, reason: "no font-size declared" });

continue;

}

const max = Math.max(...sizes);

if (max < HEADLINE_FLOOR_FOR_CHECK) {

skipped.push({ beat: beat.name, reason: `largest font is ${max}px — no headline by design` });

continue;

}

if (max < HEADLINE_MIN_PX) {

offenders.push({ beat: beat.name, maxSize: max });

}

const pass = offenders.length === 0;

const checked = compositions.length - skipped.length;

return {

status: pass ? "PASS" : "FAIL",

detail: pass

? `${checked}/${compositions.length} beats with a headline-sized text element, all ≥${HEADLINE_MIN_PX}px`

: `${offenders.length} beat(s) with headline-sized text below ${HEADLINE_MIN_PX}px floor`,

extra: pass

? null

: [

...offenders.map((o) => `${o.beat}: largest font-size is ${o.maxSize}px`),

...(skipped.length > 0

? [

`(skipped ${skipped.length} beat(s) with no headline-sized text: ${skipped.map((s) => s.beat).join(", ")})`,

]

: []),

].join("\n "),

};

}

// Catches "webpage not shot" failures — entrance tweens in the first second

// then nothing. Snapshots look fine (static end state) but motion is dead.

async function checkPerBeatTimelineCoverage() {

const compositions = await readBeatCompositions();

const beatDurations = await readBeatDurationsFromIndex();

if (compositions.length === 0) {

return { name: "Timeline coverage", status: "INFO", detail: "no beat compositions found" };

}

const offenders = [];

const skipped = [];

// Pattern detectors: beats that use these idioms have events at positions

// the static parser can't read (loop iterators, variable arithmetic).

// Don't flag them as "webpage not shot" — they have events the parser

// simply can't see. Note: single-tween yoyo/repeat is NOT enough to skip

// — it only oscillates one element, not the whole beat.

const dynamicPatterns = [

{

re: /\.forEach\s*\([^{]*\{[\s\S]{0,2000}?\btl\.(?:to|set|fromTo|from)\(/,

{

re: /\bfor\s*$[^)]*$\s*\{[\s\S]{0,2000}?\btl\.(?:to|set|fromTo|from)\(/,

];

for (const beat of compositions) {

const beatId = beat.name.replace(/\.html$/, "");

const dur = beatDurations[beatId] ?? beatDurations[beat.name];

if (!dur) {

skipped.push({ beat: beat.name, reason: "no data-duration in index.html" });

continue;

}

// Check for dynamic patterns first — if present, coverage cannot be

// statically determined; treat as informational, not a failure.

const matchedDynamic = dynamicPatterns.find((p) => p.re.test(beat.content));

if (matchedDynamic) {

skipped.push({

beat: beat.name,

reason: `dynamic event pattern detected (${matchedDynamic.name}) — coverage not statically measurable`,

});

continue;

}

// Long-duration tween check: if there's a tween with duration ≥ 70% of

// beat duration, that single tween covers the whole beat — likely a

// camera dolly, breathing animation, or persistent motion. Skip the

// position-based coverage check.

const durationRe = /\btl\.(?:to|set|fromTo|from)\([\s\S]{0,500}?duration:\s*([0-9.]+)/g;

let dm;

let hasLongTween = false;

let longTweenDur = 0;

while ((dm = durationRe.exec(beat.content)) !== null) {

const d = parseFloat(dm[1]);

if (d >= dur * TIMELINE_COVERAGE_MIN) {

hasLongTween = true;

longTweenDur = d;

break;

}

if (hasLongTween) {

skipped.push({

beat: beat.name,

reason: `long-duration tween covers ${longTweenDur.toFixed(2)}s of ${dur.toFixed(2)}s beat — full coverage via persistent motion`,

});

continue;

}

// Extract GSAP event positions for static cases.

// Use balanced-paren scanning so multi-line calls and rgba(...) values

// inside option objects don't false-match.

const positions = extractTopLevelPositionArgs(beat.content);

if (positions.length === 0) {

offenders.push({ beat: beat.name, reason: "no GSAP events with explicit position found" });

continue;

}

const maxPos = Math.max(...positions);

const coverage = maxPos / dur;

if (coverage < TIMELINE_COVERAGE_MIN) {

offenders.push({

beat: beat.name,

reason: `static events span 0–${maxPos.toFixed(2)}s of ${dur.toFixed(2)}s beat (${Math.round(coverage * 100)}%)`,

});

}

const pass = offenders.length === 0;

const checked = compositions.length - skipped.length;

return {

status: pass ? "PASS" : "FAIL",

detail: pass

? `${checked}/${compositions.length} statically-measurable beats span ≥${Math.round(TIMELINE_COVERAGE_MIN * 100)}% of duration`

: `${offenders.length} beat(s) below ${Math.round(TIMELINE_COVERAGE_MIN * 100)}% static coverage — likely "webpage not shot" failures`,

extra:

[

...offenders.map((o) => `${o.beat}: ${o.reason}`),

...(skipped.length > 0 ? skipped.map((s) => `(skipped ${s.beat}: ${s.reason})`) : []),

].join("\n ") || null,

};

}

async function checkShaderTransitionsConsistency() {

const storyboardPath = join(PROJECT_DIR, "STORYBOARD.md");

const indexPath = join(PROJECT_DIR, "index.html");

if (!existsSync(storyboardPath) || !existsSync(indexPath)) {

return {

status: "INFO",

detail: "STORYBOARD.md or index.html missing — cannot check",

};

}

const storyboard = await readFile(storyboardPath, "utf-8");

const index = await readFile(indexPath, "utf-8");

// For each shader name, count it as "declared" only if it appears in a

// transition-use context — NOT in an inventory list (3+ names on one line)

// and NOT exclusively as part of an SFX filename (sfx/glitch-1.mp3).

const sbLines = storyboard.split("\n");

// Longest-name matching to avoid substring double-counting.

const sortedNames = [...SHADER_NAMES].sort((a, b) => b.length - a.length);

const seen = new Set();

const declared = [];

for (const name of sortedNames) {

let foundInUseContext = false;

for (const line of sbLines) {

if (seen.has(name)) break;

if (!line.includes(name)) continue;

// Skip inventory listing lines (3+ shader names on one line).

const namesOnLine = SHADER_NAMES.filter((n) => line.includes(n)).length;

if (namesOnLine >= 3) continue;

// Skip lines where the shader name only appears in SFX filename context.

const sfxContext = line.includes(`sfx/${name}`) || line.includes(`sfx-${name}`);

// Count this name if it appears in a non-SFX, non-inventory line.

if (!sfxContext) {

foundInUseContext = true;

break;

}

if (foundInUseContext) {

declared.push(name);

seen.add(name);

}

if (declared.length === 0) {

return {

status: "PASS",

detail: "STORYBOARD declared none — no shader transitions expected",

};

}

// A shader is "present" only if HyperShader runtime is in index.html AND the

// shader name appears in a line that is NOT an SFX reference.

const hasHyperShader = /HyperShader\s*[(.]/.test(index);

const indexLines = index.split("\n");

const present = !hasHyperShader

? []

: declared.filter((name) =>

indexLines.some((line) => {

if (!line.includes(name)) return false;

if (line.includes(`sfx/${name}`) || line.includes(`sfx-${name}`)) return false;

return true;

}),

);

const missing = declared.filter((name) => !present.includes(name));

const pass = missing.length === 0;

return {

status: pass ? "PASS" : "FAIL",

detail: `STORYBOARD declared ${declared.length}, ${present.length} present in index.html, ${missing.length} missing`,

extra: pass

? null

: `Missing from build: ${missing.join(", ")}. STORYBOARD.md and index.html disagree — either re-add the transitions or update STORYBOARD.md.`,

};

}

async function checkSfxTimestampConsistency() {

const storyboardPath = join(PROJECT_DIR, "STORYBOARD.md");

const indexPath = join(PROJECT_DIR, "index.html");

if (!existsSync(storyboardPath) || !existsSync(indexPath)) {

return {

status: "INFO",

detail: "STORYBOARD.md or index.html missing",

};

}

const storyboard = await readFile(storyboardPath, "utf-8");

const index = await readFile(indexPath, "utf-8");

const sfxRefs = [];

for (const line of storyboard.split("\n")) {

const fileMatch = line.match(/sfx\/([\w-]+\.mp3)/);

// Require trailing `s` so we capture the time column, not the volume column.

const timeMatch = line.match(/\|\s*(\d+(?:\.\d+)?)s\b/);

if (fileMatch && timeMatch) {

sfxRefs.push({ file: fileMatch[1], storyboardT: parseFloat(timeMatch[1]) });

}

if (sfxRefs.length === 0) {

return {

status: "INFO",

detail: "No SFX entries detected in STORYBOARD.md",

};

}

// Collect ALL audio tags per file (multi-timestamp SFX like click.mp3 have

// 3 tags). Use a two-step extraction so we don't depend on src= and

// data-start= attribute ordering — the documented canonical pattern in

// capabilities.md puts src= LAST in the tag, which an order-dependent

// regex would miss → false MISSING reports.

const indexSfx = new Map();

const audioTagRegex = /<audio[^>]*?>/g;

let tagMatch;

while ((tagMatch = audioTagRegex.exec(index)) !== null) {

const tag = tagMatch[0];

const srcMatch = tag.match(/src=["'](?:[^"']*\/)?sfx\/([\w-]+\.mp3)["']/);

const dsMatch = tag.match(/data-start=["']([0-9.]+)["']/);

if (!srcMatch || !dsMatch) continue;

const file = srcMatch[1];

const t = parseFloat(dsMatch[1]);

if (!indexSfx.has(file)) indexSfx.set(file, []);

indexSfx.get(file).push(t);

}

const drifts = [];

const missing = [];

for (const ref of sfxRefs) {

if (!indexSfx.has(ref.file)) {

missing.push(ref.file);

continue;

}

const indexTs = indexSfx.get(ref.file);

const closest = indexTs.reduce((best, t) =>

Math.abs(t - ref.storyboardT) < Math.abs(best - ref.storyboardT) ? t : best,

);

const drift = Math.abs(closest - ref.storyboardT);

if (drift > SFX_DRIFT_TOLERANCE_S) {

drifts.push({ file: ref.file, storyboardT: ref.storyboardT, indexT: closest, drift });

}

const indexCount = [...indexSfx.values()].reduce((sum, arr) => sum + arr.length, 0);

const pass = missing.length === 0 && drifts.length === 0;

return {

status: pass ? "PASS" : "FAIL",

detail: `${sfxRefs.length} SFX in STORYBOARD · ${indexCount} in index.html · ${missing.length} missing · ${drifts.length} drifted >${SFX_DRIFT_TOLERANCE_S}s`,

extra: pass

? null

: [

...missing.map((f) => `MISSING in index.html: ${f}`),

...drifts.map(

(d) =>

`DRIFT: ${d.file} storyboard=${d.storyboardT}s closest index=${d.indexT}s drift=${d.drift.toFixed(2)}s`,

].join("\n "),

};

}

// Catches storyboard staleness on beat timings — agent shipped with different

// beat durations than the storyboard documented, leaving the spec lying.

async function checkBeatDurationConsistency() {

const storyboardPath = join(PROJECT_DIR, "STORYBOARD.md");

if (!existsSync(storyboardPath)) {

return { name: "Beat durations", status: "INFO", detail: "STORYBOARD.md missing" };

}

const storyboard = await readFile(storyboardPath, "utf-8");

const indexDurations = await readBeatDurationsFromIndex();

// Filter to only numbered beats (beat-1, beat-2, ...). Skip "main" / root

// composition and any non-numbered placeholders.

const buildBeatIds = Object.keys(indexDurations).filter((id) => /^beat-\d+/i.test(id));

if (buildBeatIds.length === 0) {

return {

status: "INFO",

detail: "no numbered beat data-duration in index.html",

};

}

// Parse storyboard beat durations. The expected pattern is a timing-table row:

// | B4 — MetaBrain | 16.600 – 21.000s | ... |

// We extract start–end and compute duration = end - start. Falls back to a

// direct duration mention ("duration: X.Xs") if the range format isn't found.

// A beat with no parseable duration is skipped — we don't flag missing rows.

const drifts = [];

const unparseable = [];

for (const beatId of buildBeatIds) {

const num = beatId.match(/beat-(\d+)/i)?.[1];

if (!num) continue;

let storyT = null;

// Strategy 1: standalone beat row "B4 — Name | 16.600 – 21.000s |".

// Require `B${num}` to be followed by a non-digit-non-dot char so "B3.1"

// doesn't false-match for B3.

const rangeRe = new RegExp(

`\\bB${num}(?![\\.\\d])[^\\n|]*\\|\\s*(\\d+(?:\\.\\d+)?)s?\\s*[–-]\\s*(\\d+(?:\\.\\d+)?)s`,

"i",

);

const rm = storyboard.match(rangeRe);

if (rm) {

storyT = parseFloat(rm[2]) - parseFloat(rm[1]);

} else {

// Strategy 2: sum sub-beats "B${num}.X — ... | start – end s |".

// Useful when a beat is broken into sub-rows (B3.1, B3.2, ...) instead

// of having a standalone row.

const subRe = new RegExp(

`\\bB${num}\\.\\d+\\b[^\\n|]*\\|\\s*(\\d+(?:\\.\\d+)?)s?\\s*[–-]\\s*(\\d+(?:\\.\\d+)?)s`,

"gi",

);

let sum = 0;

let count = 0;

let mm;

while ((mm = subRe.exec(storyboard)) !== null) {

sum += parseFloat(mm[2]) - parseFloat(mm[1]);

count++;

}

if (count > 0) storyT = sum;

}

if (storyT === null) {

// Strategy 3: bare-number timing table — "| 1 | 0.00s | 5.20s | 5.20s |"

// (Beat | Start | End | Duration). The duration column is the 4th cell,

// OR derive from end - start (columns 2 and 3). Match a row that starts

// with `| <num> |` and has at least 2 time cells.

// Allow optional leading `>` (blockquote) before the pipe.

const tableRe = new RegExp(

`^\\s*>?\\s*\\|\\s*${num}\\s*\\|\\s*(\\d+(?:\\.\\d+)?)s?\\s*\\|\\s*(\\d+(?:\\.\\d+)?)s`,

"im",

);

const tm = storyboard.match(tableRe);

if (tm) {

const start = parseFloat(tm[1]);

const end = parseFloat(tm[2]);

storyT = end - start;

}

// Note: removed the previous "duration: X.Xs near beat label" fallback —

// it false-matched non-beat durations (e.g., "shader runs — duration 0.7s"

// near a "Beat 1" mention). If a storyboard's timing format isn't a clean

// range or table row, the beat is reported as unparseable rather than

// guessed at.

if (storyT === null) {

unparseable.push(beatId);

continue;

}

const buildT = indexDurations[beatId];

const drift = Math.abs(storyT - buildT);

if (drift > BEAT_DURATION_DRIFT_TOLERANCE_S) {

drifts.push({ beat: beatId, storyboardDuration: storyT, buildDuration: buildT, drift });

}

const parseable = buildBeatIds.length - unparseable.length;

if (drifts.length === 0) {

return {

status: "PASS",

detail: `${parseable}/${buildBeatIds.length} beats parseable, storyboard durations match within ±${BEAT_DURATION_DRIFT_TOLERANCE_S}s`,

extra:

unparseable.length > 0

? `(skipped: ${unparseable.join(", ")} — could not find duration in STORYBOARD.md)`

: null,

};

}

return {

status: "FAIL",

detail: `${drifts.length} beat(s) drift between STORYBOARD.md and index.html > ${BEAT_DURATION_DRIFT_TOLERANCE_S}s`,

extra: [

...drifts.map(

(d) =>

`${d.beat}: storyboard=${d.storyboardDuration.toFixed(2)}s build=${d.buildDuration}s drift=${d.drift.toFixed(2)}s`,

...(unparseable.length > 0

? [`(skipped: ${unparseable.join(", ")} — could not find duration in STORYBOARD.md)`]

: []),

].join("\n "),

};

}

async function checkMp4Exists() {

const candidates = [PROJECT_DIR, join(PROJECT_DIR, "output"), join(PROJECT_DIR, "renders")];

for (const dir of candidates) {

if (!existsSync(dir)) continue;

try {

const files = await readdir(dir);

if (files.some((f) => f.endsWith(".mp4"))) {

return {

status: "PASS",

detail: `found .mp4 in ${dir.replace(PROJECT_DIR, ".")}`,

};

}

} catch {

/* ignore */

}

return {

status: "INFO",

detail:

"no .mp4 found — preview-only delivery; if claiming verified motion, render is required (Path 2 of audio+motion verification)",

};

}

// ─── Helpers ─────────────────────────────────────────────────────────────────

// Cached so multiple checks don't re-read the same files. The script is a

// one-shot CLI so a process-scoped cache is fine; no invalidation needed.

let _compositionsCache = null;

async function readBeatCompositions() {

if (_compositionsCache) return _compositionsCache;

const dir = join(PROJECT_DIR, "compositions");

if (!existsSync(dir)) {

_compositionsCache = [];

return _compositionsCache;

}

const files = await readdir(dir);

const beats = files.filter((f) => /^beat-/i.test(f) && f.endsWith(".html"));

const out = [];

for (const f of beats) {

const content = await readFile(join(dir, f), "utf-8");

out.push({ name: f, content });

}

_compositionsCache = out;

return out;

}

// Extract the trailing numeric position argument from each `tl.<method>(...)`

// call in a script. Uses balanced-paren scanning so multi-line calls and

// nested patterns like rgba(86,131,218,0.35) don't false-match.

function extractTopLevelPositionArgs(content) {

const positions = [];

let startMatch;

while ((startMatch = methodRe.exec(content)) !== null) {

let i = startMatch.index + startMatch[0].length;

let depth = 1;

let lastTopLevelCommaIdx = -1;

let inString = false;

let stringChar = null;

while (i < content.length && depth > 0) {

const c = content[i];

if (inString) {

if (c === "\\") {

i += 2;

continue;

}

if (c === stringChar) inString = false;

i++;

continue;

}

if (c === '"' || c === "'" || c === "`") {

inString = true;

stringChar = c;

i++;

continue;

}

if (c === "(" || c === "{" || c === "[") depth++;

else if (c === ")" || c === "}" || c === "]") {

depth--;

if (depth === 0) break;

} else if (c === "," && depth === 1) lastTopLevelCommaIdx = i;

i++;

}

if (depth === 0 && lastTopLevelCommaIdx > 0) {

const lastArg = content.substring(lastTopLevelCommaIdx + 1, i).trim();

const numMatch = lastArg.match(/^([0-9.]+)$/);

if (numMatch) positions.push(parseFloat(numMatch[1]));

}

return positions;

}

// Returns a map of { "beat-1-name": durationInSeconds, ... } from index.html.

// Cached per-process (one-shot CLI, no invalidation needed).

let _beatDurationsCache = null;

async function readBeatDurationsFromIndex() {

if (_beatDurationsCache) return _beatDurationsCache;

const indexPath = join(PROJECT_DIR, "index.html");

if (!existsSync(indexPath)) {

_beatDurationsCache = {};

return _beatDurationsCache;

}

const content = await readFile(indexPath, "utf-8");

const map = {};

// Pattern: <div data-composition-id="beat-N-name" ... data-duration="5.5" ...>

// OR: data-composition-src="compositions/beat-N-name.html" ... data-duration="5.5"

const divRegex = /<div[^>]*?>/g;

let m;

while ((m = divRegex.exec(content)) !== null) {

const tag = m[0];

const idMatch = tag.match(/data-composition-id=["']([^"']+)["']/);

const srcMatch = tag.match(/data-composition-src=["'][^"']*?\/?(beat-[\w-]+)\.html["']/);

const durMatch = tag.match(/data-duration=["']([0-9.]+)["']/);

if (!durMatch) continue;

const dur = parseFloat(durMatch[1]);

if (idMatch) map[idMatch[1]] = dur;

if (srcMatch) map[srcMatch[1]] = dur;

}

_beatDurationsCache = map;

return map;

}

// ─── Report ──────────────────────────────────────────────────────────────────

function printReport(results) {

const cols = { name: 26, status: 8, detail: 60 };

const line = "─".repeat(cols.name + cols.status + cols.detail + 6);

console.log("");

console.log(`w2h-verify · ${PROJECT_DIR}`);

console.log(line);

console.log("Check".padEnd(cols.name) + " │ " + "Status".padEnd(cols.status) + " │ " + "Detail");

console.log(line);

for (const r of results) {

const symbol = r.status === "PASS" ? "✓" : r.status === "FAIL" ? "✗" : "·";

console.log(

r.name.padEnd(cols.name) +

" │ " +

`${symbol} ${r.status}`.padEnd(cols.status) +

" │ " +

(r.detail || ""),

);

if (r.extra) {

const indent = " ".repeat(cols.name + cols.status + 6 + 4);

console.log(

"".padEnd(cols.name) +

" │ " +

"".padEnd(cols.status) +

" │ " +

r.extra.split("\n").join("\n" + indent),

);

}

console.log(line);

const pass = results.filter((r) => r.status === "PASS").length;

const fail = results.filter((r) => r.status === "FAIL").length;

const info = results.filter((r) => r.status === "INFO").length;

console.log(`SUMMARY: ${pass} PASS · ${fail} FAIL · ${info} INFO`);

if (fail > 0) {

console.log("");

console.log("Step 6 NOT done. Fix FAIL items, OR include this report verbatim in your final");

console.log("summary's \"What I did NOT verify\" section so the user knows what's broken.");

} else {

console.log("");

console.log(

"All gates pass. Paste this report into your final user-facing summary as evidence.",

);

}

console.log("");

}

main().catch((e) => {

console.error("w2h-verify script error:", e);

process.exit(2);

});

mdskills/website-to-hyperframes/SKILL.md

10.0 kB

---

description: |

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

---

# Website to HyperFrames

Capture a website, then produce a professional video from it.

Users say things like:

- "Capture https://... and make me a 25-second product launch video"

- "Turn this website into a 15-second social ad for Instagram"

- "Create a 30-second product tour from https://..."

The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.

**Autonomous mode is NOT "skip all gates."** Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:

- Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset

- Per-beat HTML read (Step 5) — structured evidence block per beat

- DoD checklist (Step 6) — including animation-map, per-warning WCAG verification, audio/motion playback

- Honest disclosure section (Step 6) — "What I did NOT verify" must appear in your final summary

If you find yourself reasoning "auto mode says bias toward action, so I'll skip X" — and X is a verification gate, not a preference question — that reasoning is wrong. Bias toward action applies to deciding _what to build_, not to deciding _whether to verify_.

---

## Step 0: Capture & Understand the Brand

**Read:** [references/step-0-capture.md](references/step-0-capture.md)

Capture the site, then read the extracted data to understand the **brand and product** — what it does, who it's for, what voice it speaks in, what mood it lives in. The captured assets are a brand toolkit for later, not the building blocks the video is made from.

**Gate:** Site summary printed — strategy-first (what the product does, who it's for, brand voice) before the asset / color / font inventory.

---

## Step 1: Brand Identity

**Read:** [references/step-1-design.md](references/step-1-design.md)

Write DESIGN.md — a brand cheat sheet covering the visual identity: colors, typography, component styles, layout principles. Use `design-styles.json` for exact computed values.

**Speed option:** For fast-pacing videos (billboard-per-beat), DESIGN.md can be a 50-line summary of colors + fonts + do's/don'ts — not a 300-line document. The sub-agent prompt in Step 5 pastes brand values directly, so DESIGN.md depth only matters for complex compositions.

**Gate:** `DESIGN.md` exists (any length) with at minimum: color palette, font choices, and do's/don'ts.

---

## Step 2: Strategy & Messaging

**Read:** [references/step-2-brief.md](references/step-2-brief.md), [references/capabilities.md](references/capabilities.md) (scan the Table of Contents — deep-dive sections only as needed)

Align with the user on **what the video must communicate** before talking visuals or assets. Parse the user's prompt — they probably already gave you the video type and style. Ask only what's missing: the ONE thing this video must say, the narrative arc, and the audience.

**Gate:** Video type, duration, format, and — critically — the message and narrative arc are locked. Without those, Step 3 can't write a concept-first storyboard.

---

## Step 3: Storyboard + Script 💬

**Read:** [references/step-3-storyboard.md](references/step-3-storyboard.md)

Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. Present both to the user with a beat-by-beat summary. Iterate until they approve.

**Gate:** `STORYBOARD.md` + `SCRIPT.md` exist AND the user has approved the plan.

---

## Step 4: VO, Timing + Captions 💬

**Read:** [references/step-4-vo.md](references/step-4-vo.md)

If Step 2 said no narration — ask about background music, then skip to Step 5. Otherwise: ask the user which TTS provider (HeyGen TTS, ElevenLabs, or Kokoro), generate audio, transcribe, map timestamps to beats. Then ask about captions.

**Gate:** Either (a) no narration was requested and storyboard has manual beat timings, or (b) `narration.wav` + `transcript.json` exist and beat timings updated with real durations.

---

## Step 5: Build Compositions

**Read:** The `hyperframes` skill (load it — every rule matters)

**Read:** [references/step-5-build.md](references/step-5-build.md)

Build index.html and compositions following the architecture and pacing chosen in the storyboard (Step 3). Sub-agents run `hyperframes lint` and `hyperframes snapshot` on each beat before reporting back.

**Gate:** Every `compositions/beat-N.html` has been read top-to-bottom by the main agent against DESIGN.md and STORYBOARD.md. The per-beat checklist lives in [step-5-build.md](references/step-5-build.md).

---

## Step 6: Validate & Deliver

**Read:** [references/step-6-validate.md](references/step-6-validate.md)

Lint, validate, take snapshots scaled to video length (formula: `max(beats × 3, ceil(duration_seconds / 2))`), and review each one. Fix issues before delivering. Deliver the localhost Studio project URL — only render to MP4 on explicit user request.

**Deliver something you're proud of.** Before handing off, ask yourself: would I post this on social media with my name on it? If not, fix what's wrong.

**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors, and the final response includes the active Studio project URL.

---

## Quick Reference

### Video Types

Typical constraints by video type — use as a starting point, not a formula. Beat count should follow from the content and the narration, not from a target range.

| --------------------- | ---------------- | ------------------ | --------------------- |

Beat count is not in this table intentionally — it should come from the storyboard, not from "social ad = 3-4 beats." A social ad for a complex product might need 5 well-timed beats. A brand reel with one strong visual thesis might need 3.

### Format

- **Landscape**: 1920x1080 (default)

- **Portrait**: 1080x1920 (Instagram Stories, TikTok)

- **Square**: 1080x1080 (Instagram feed)

### Reference Files

| File | When to read |

| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |

| [step-0-capture.md](references/step-0-capture.md) | Step 0 — capture, understand the brand and product, write strategy-first site summary |

| [step-1-design.md](references/step-1-design.md) | Step 1 — write DESIGN.md brand cheat sheet (5 sections, 250-350 lines; 50-line fast-path for billboard-style social ads) |

| [step-2-brief.md](references/step-2-brief.md) | Step 2 — align on message, narrative arc, audience with user |

| [capabilities.md](references/capabilities.md) | Steps 2 & 5 — full inventory of what HyperFrames can do (24 sections). Scan the TOC during the brief, deep-dive specific sections during build |

| [step-3-storyboard.md](references/step-3-storyboard.md) | Step 3 — storyboard + script (combined) with user review gate |

| [step-4-vo.md](references/step-4-vo.md) | Step 4 — TTS provider choice, generation, timing |

| [step-5-build.md](references/step-5-build.md) | Step 5 — build index.html + compositions |

| [step-6-validate.md](references/step-6-validate.md) | Step 6 — lint, validate, snapshots (scaled to video length), preview |

| [techniques.md](../hyperframes/references/techniques.md) | Steps 3 & 5 — 13 primitive animation techniques with code patterns (adapt, don't copy-paste) |

| [html-in-canvas-patterns.md](../hyperframes/references/html-in-canvas-patterns.md) | Step 5 — complete code patterns for HTML-in-Canvas effects (lives in the hyperframes skill) |

AIpkg/registry · box · “Your wish is our command line” sealed