npm - hyperframes - Versions diffs - 0.6.97 → 0.6.99 - Mend

hyperframes 0.6.97 → 0.6.99

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/dist/studio/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-Cfye9xzo.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-B0twsRu0.css">
+    <script type="module" crossorigin src="/assets/index-DrwSRbsl.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B62bDCQv.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/templates/_shared/AGENTS.md CHANGED Viewed

@@ -1,14 +1,28 @@
 # HyperFrames Composition Project
-## Skills
+## Skills — USE THESE FIRST
-This project uses AI agent skills for framework-specific patterns. Install them if not already present:
+**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.
-```bash
-npx skills add heygen-com/hyperframes
-```
+**Doing anything with HyperFrames?** Start at `/hyperframes-read-first` — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), and routes every "make me a video" request to the right workflow. Read it first, especially when there's no project context to orient you. The video workflows it routes to:
+- `/product-launch-video` — a **product** URL or brief / script → 60-90s product launch / SaaS / promo video.
+- `/website-to-video` — a **general** website / URL → a video _of_ the site (tour / showcase / social clip from captured visuals); a product **launch / promo** is `/product-launch-video`.
+- `/faceless-explainer` — arbitrary text (topic / article / notes), **no URL, no website capture** → 60-90s faceless explainer.
+- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched.
+- `/graphic-overlays` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.)
+- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor).
+- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
+- `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition); the original hyperframes authoring flow, any length.
+**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above.
+The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-creative`, `/hyperframes-cli`, `/hyperframes-media`, `/hyperframes-registry`) and the full capability map live inside `/hyperframes-read-first` — it is the single source of truth for which skill handles which intent.
+> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`.
-Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, Tailwind v4 browser-runtime styling for `--tailwind` projects, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.
+> **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
+> agent session, or install manually: `npx skills add heygen-com/hyperframes`.
 ## Commands
@@ -17,46 +31,57 @@ npm run dev          # start the preview server (long-running — keep it alive
 npm run check        # lint + validate + inspect
 npm run render       # render to MP4
 npm run publish      # publish and get a shareable link
+npx hyperframes lint --verbose  # include info-level findings
+npx hyperframes lint --json     # machine-readable output for CI
 npx hyperframes docs <topic> # reference docs in terminal
 ```
 > **`npm run dev` is a long-running server, not a one-shot command.** It blocks until stopped.
-> Always run it as a background process so it stays alive while you edit compositions.
-> Running it in the foreground will time out and kill the server, breaking the browser preview.
+> In Claude Code, always run it with `run_in_background: true`. Never run it as a foreground
+> command — it will time out and the server will die, breaking the browser preview.
+## Documentation
+**For quick reference**, use the local CLI docs command (no network required):
+```bash
+npx hyperframes docs <topic>
+```
+Topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting`
+**For full documentation**, discover pages via the machine-readable index — do NOT guess URLs:
+```
+https://hyperframes.heygen.com/llms.txt
+```
 ## Project Structure
 - `index.html` — main composition (root timeline)
 - `compositions/` — sub-compositions referenced via `data-composition-src`
-- `assets/` — media files (video, audio, images)
 - `meta.json` — project metadata (id, name)
 - `transcript.json` — whisper word-level transcript (if generated)
-## Linting — Always Run After Changes
+## Linting — ALWAYS RUN AFTER CHANGES
-After creating or editing any `.html` composition, run the full check before considering the task complete:
+After creating or editing any `.html` composition, **always** run the full check before considering the task complete:
 ```bash
 npm run check
 ```
-Fix all errors before presenting the result.
+Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.
 ## Key Rules
 1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
-2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control
-3. GSAP timelines must be paused and registered on `window.__timelines`:
+2. Elements with timing **MUST** have `class="clip"` — the framework uses this for visibility control
+3. Timelines must be paused and registered on `window.__timelines`:
    ```js
    window.__timelines = window.__timelines || {};
    window.__timelines["composition-id"] = gsap.timeline({ paused: true });
    ```
 4. Videos use `muted` with a separate `<audio>` element for the audio track
-5. Sub-compositions use `data-composition-src="compositions/file.html"`
+5. Sub-compositions use `data-composition-src="compositions/file.html"` to reference other HTML files
 6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches
-## Documentation
-Full docs: https://hyperframes.heygen.com/introduction
-Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt

package/dist/templates/_shared/CLAUDE.md CHANGED Viewed

@@ -4,20 +4,22 @@
 **Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions.
-| Skill                      | Command                   | When to use                                                                                       |
-| -------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
-| **hyperframes**            | `/hyperframes`            | Creating or editing HTML compositions, captions, TTS, audio-reactive animation, marker highlights |
-| **hyperframes-cli**        | `/hyperframes-cli`        | Dev-loop CLI: init, lint, inspect, preview, render, doctor                                        |
-| **hyperframes-media**      | `/hyperframes-media`      | Asset preprocessing: tts (Kokoro), transcribe (Whisper), remove-background (u2net)                |
-| **hyperframes-registry**   | `/hyperframes-registry`   | Installing blocks and components via `hyperframes add`                                            |
-| **website-to-hyperframes** | `/website-to-hyperframes` | Capturing a URL and turning it into a video — full website-to-video pipeline                      |
-| **tailwind**               | `/tailwind`               | Tailwind v4 browser-runtime styles for projects created with `hyperframes init --tailwind`        |
-| **gsap**                   | `/gsap`                   | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
-| **animejs**                | `/animejs`                | Anime.js animations registered on `window.__hfAnime`                                              |
-| **css-animations**         | `/css-animations`         | CSS keyframes that HyperFrames can pause and seek                                                 |
-| **lottie**                 | `/lottie`                 | `lottie-web` and dotLottie players registered on `window.__hfLottie`                              |
-| **three**                  | `/three`                  | Three.js scenes rendered from HyperFrames `hf-seek` events                                        |
-| **waapi**                  | `/waapi`                  | Web Animations API motion driven through `document.getAnimations()`                               |
+**Doing anything with HyperFrames?** Start at `/hyperframes-read-first` — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), and routes every "make me a video" request to the right workflow. Read it first, especially when there's no project context to orient you. The video workflows it routes to:
+- `/product-launch-video` — a **product** URL or brief / script → 60-90s product launch / SaaS / promo video.
+- `/website-to-video` — a **general** website / URL → a video _of_ the site (tour / showcase / social clip from captured visuals); a product **launch / promo** is `/product-launch-video`.
+- `/faceless-explainer` — arbitrary text (topic / article / notes), **no URL, no website capture** → 60-90s faceless explainer.
+- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched.
+- `/graphic-overlays` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.)
+- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor).
+- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
+- `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition); the original hyperframes authoring flow, any length.
+**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above.
+The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-creative`, `/hyperframes-cli`, `/hyperframes-media`, `/hyperframes-registry`) and the full capability map live inside `/hyperframes-read-first` — it is the single source of truth for which skill handles which intent.
+> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`.
 > **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
 > agent session, or install manually: `npx skills add heygen-com/hyperframes`.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.6.97",
+  "version": "0.6.99",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
@@ -17,9 +17,10 @@
   "scripts": {
     "test": "vitest run",
     "dev": "tsx src/cli.ts",
-    "build": "bun run build:fonts && tsup && bun run build:runtime && bun run build:copy",
+    "build": "bun run build:fonts && tsup && bun run build:runtime && bun run build:beat-analyzer && bun run build:copy",
     "build:fonts": "node scripts/build-fonts.mjs",
     "build:runtime": "tsx scripts/build-runtime.ts",
+    "build:beat-analyzer": "node scripts/build-beat-analyzer.mjs",
     "build:copy": "node scripts/build-copy.mjs",
     "typecheck": "tsc --noEmit"
   },

package/dist/pngDecodeBlitWorker.js DELETED Viewed

@@ -1,239 +0,0 @@
-import { createRequire as __hf_createRequire } from "node:module";
-import { fileURLToPath as __hf_fileURLToPath } from "node:url";
-import { dirname as __hf_dirname } from "node:path";
-var require = __hf_createRequire(import.meta.url);
-var __filename = __hf_fileURLToPath(import.meta.url);
-var __dirname = __hf_dirname(__filename);
-// ../producer/src/services/pngDecodeBlitWorker.ts
-import { parentPort } from "worker_threads";
-// ../engine/src/utils/alphaBlit.ts
-import { inflateSync } from "zlib";
-function paeth(a, b, c) {
-  const p = a + b - c;
-  const pa = Math.abs(p - a);
-  const pb = Math.abs(p - b);
-  const pc = Math.abs(p - c);
-  if (pa <= pb && pa <= pc) return a;
-  if (pb <= pc) return b;
-  return c;
-}
-function decodePngRaw(buf, caller) {
-  if (buf[0] !== 137 || buf[1] !== 80 || buf[2] !== 78 || buf[3] !== 71 || buf[4] !== 13 || buf[5] !== 10 || buf[6] !== 26 || buf[7] !== 10) {
-    throw new Error(`${caller}: not a PNG file`);
-  }
-  let pos = 8;
-  let width = 0;
-  let height = 0;
-  let bitDepth = 0;
-  let colorType = 0;
-  let interlace = 0;
-  let sawIhdr = false;
-  const idatChunks = [];
-  while (pos + 12 <= buf.length) {
-    const chunkLen = buf.readUInt32BE(pos);
-    const chunkType = buf.toString("ascii", pos + 4, pos + 8);
-    const chunkData = buf.subarray(pos + 8, pos + 8 + chunkLen);
-    if (chunkType === "IHDR") {
-      width = chunkData.readUInt32BE(0);
-      height = chunkData.readUInt32BE(4);
-      bitDepth = chunkData[8] ?? 0;
-      colorType = chunkData[9] ?? 0;
-      interlace = chunkData[12] ?? 0;
-      sawIhdr = true;
-    } else if (chunkType === "IDAT") {
-      idatChunks.push(Buffer.from(chunkData));
-    } else if (chunkType === "IEND") {
-      break;
-    }
-    pos += 12 + chunkLen;
-  }
-  if (!sawIhdr) {
-    throw new Error(`${caller}: PNG missing IHDR chunk`);
-  }
-  if (colorType !== 2 && colorType !== 6) {
-    throw new Error(`${caller}: unsupported color type ${colorType} (expected 2=RGB or 6=RGBA)`);
-  }
-  if (interlace !== 0) {
-    throw new Error(
-      `${caller}: Adam7-interlaced PNGs are not supported (interlace method ${interlace})`
-    );
-  }
-  const channels = colorType === 6 ? 4 : 3;
-  const bpp = channels * (bitDepth / 8);
-  const stride = width * bpp;
-  const compressed = Buffer.concat(idatChunks);
-  const decompressed = inflateSync(compressed);
-  const rawPixels = Buffer.allocUnsafe(height * stride);
-  const prevRow = new Uint8Array(stride);
-  const currRow = new Uint8Array(stride);
-  let srcPos = 0;
-  for (let y = 0; y < height; y++) {
-    const filterType = decompressed[srcPos++] ?? 0;
-    const rawRow = decompressed.subarray(srcPos, srcPos + stride);
-    srcPos += stride;
-    switch (filterType) {
-      case 0:
-        currRow.set(rawRow);
-        break;
-      case 1:
-        for (let x = 0; x < stride; x++) {
-          currRow[x] = (rawRow[x] ?? 0) + (x >= bpp ? currRow[x - bpp] ?? 0 : 0) & 255;
-        }
-        break;
-      case 2:
-        for (let x = 0; x < stride; x++) {
-          currRow[x] = (rawRow[x] ?? 0) + (prevRow[x] ?? 0) & 255;
-        }
-        break;
-      case 3:
-        for (let x = 0; x < stride; x++) {
-          const left = x >= bpp ? currRow[x - bpp] ?? 0 : 0;
-          const up = prevRow[x] ?? 0;
-          currRow[x] = (rawRow[x] ?? 0) + Math.floor((left + up) / 2) & 255;
-        }
-        break;
-      case 4:
-        for (let x = 0; x < stride; x++) {
-          const left = x >= bpp ? currRow[x - bpp] ?? 0 : 0;
-          const up = prevRow[x] ?? 0;
-          const upLeft = x >= bpp ? prevRow[x - bpp] ?? 0 : 0;
-          currRow[x] = (rawRow[x] ?? 0) + paeth(left, up, upLeft) & 255;
-        }
-        break;
-      default:
-        throw new Error(`${caller}: unknown filter type ${filterType} at row ${y}`);
-    }
-    rawPixels.set(currRow, y * stride);
-    prevRow.set(currRow);
-  }
-  return { width, height, bitDepth, colorType, rawPixels };
-}
-function decodePng(buf) {
-  const { width, height, bitDepth, colorType, rawPixels } = decodePngRaw(buf, "decodePng");
-  if (bitDepth !== 8) {
-    throw new Error(`decodePng: unsupported bit depth ${bitDepth} (expected 8)`);
-  }
-  const output = new Uint8Array(width * height * 4);
-  if (colorType === 6) {
-    output.set(rawPixels);
-  } else {
-    for (let i = 0; i < width * height; i++) {
-      output[i * 4 + 0] = rawPixels[i * 3 + 0] ?? 0;
-      output[i * 4 + 1] = rawPixels[i * 3 + 1] ?? 0;
-      output[i * 4 + 2] = rawPixels[i * 3 + 2] ?? 0;
-      output[i * 4 + 3] = 255;
-    }
-  }
-  return { width, height, data: output };
-}
-function buildSrgbToSignalLut(transfer) {
-  const lut = new Uint16Array(256);
-  const hlgA = 0.17883277;
-  const hlgB = 1 - 4 * hlgA;
-  const hlgC = 0.5 - hlgA * Math.log(4 * hlgA);
-  const pqM1 = 0.1593017578125;
-  const pqM2 = 78.84375;
-  const pqC1 = 0.8359375;
-  const pqC2 = 18.8515625;
-  const pqC3 = 18.6875;
-  const pqMaxNits = 1e4;
-  const sdrNits = 203;
-  for (let i = 0; i < 256; i++) {
-    if (transfer === "srgb") {
-      lut[i] = i * 257;
-      continue;
-    }
-    const v = i / 255;
-    const linear = v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
-    let signal;
-    if (transfer === "hlg") {
-      signal = linear <= 1 / 12 ? Math.sqrt(3 * linear) : hlgA * Math.log(12 * linear - hlgB) + hlgC;
-    } else {
-      const Lp = Math.max(0, linear * sdrNits / pqMaxNits);
-      const Lm1 = Math.pow(Lp, pqM1);
-      signal = Math.pow((pqC1 + pqC2 * Lm1) / (1 + pqC3 * Lm1), pqM2);
-    }
-    lut[i] = Math.min(65535, Math.round(signal * 65535));
-  }
-  return lut;
-}
-var SRGB_TO_SRGB_16 = buildSrgbToSignalLut("srgb");
-var SRGB_TO_HLG = buildSrgbToSignalLut("hlg");
-var SRGB_TO_PQ = buildSrgbToSignalLut("pq");
-function getSrgbToSignalLut(transfer) {
-  if (transfer === "pq") return SRGB_TO_PQ;
-  if (transfer === "hlg") return SRGB_TO_HLG;
-  return SRGB_TO_SRGB_16;
-}
-function blitRgba8OverRgb48le(domRgba, canvas, width, height, transfer = "hlg") {
-  const pixelCount = width * height;
-  const lut = getSrgbToSignalLut(transfer);
-  for (let i = 0; i < pixelCount; i++) {
-    const da = domRgba[i * 4 + 3] ?? 0;
-    if (da === 0) {
-      continue;
-    } else if (da === 255) {
-      const r16 = lut[domRgba[i * 4 + 0] ?? 0] ?? 0;
-      const g16 = lut[domRgba[i * 4 + 1] ?? 0] ?? 0;
-      const b16 = lut[domRgba[i * 4 + 2] ?? 0] ?? 0;
-      canvas.writeUInt16LE(r16, i * 6);
-      canvas.writeUInt16LE(g16, i * 6 + 2);
-      canvas.writeUInt16LE(b16, i * 6 + 4);
-    } else {
-      const alpha = da / 255;
-      const invAlpha = 1 - alpha;
-      const hdrR = (canvas[i * 6 + 0] ?? 0) | (canvas[i * 6 + 1] ?? 0) << 8;
-      const hdrG = (canvas[i * 6 + 2] ?? 0) | (canvas[i * 6 + 3] ?? 0) << 8;
-      const hdrB = (canvas[i * 6 + 4] ?? 0) | (canvas[i * 6 + 5] ?? 0) << 8;
-      const domR = lut[domRgba[i * 4 + 0] ?? 0] ?? 0;
-      const domG = lut[domRgba[i * 4 + 1] ?? 0] ?? 0;
-      const domB = lut[domRgba[i * 4 + 2] ?? 0] ?? 0;
-      canvas.writeUInt16LE(Math.round(domR * alpha + hdrR * invAlpha), i * 6);
-      canvas.writeUInt16LE(Math.round(domG * alpha + hdrG * invAlpha), i * 6 + 2);
-      canvas.writeUInt16LE(Math.round(domB * alpha + hdrB * invAlpha), i * 6 + 4);
-    }
-  }
-}
-// ../producer/src/services/pngDecodeBlitWorker.ts
-if (!parentPort) {
-  console.warn("[pngDecodeBlitWorker] no parentPort; module loaded on main thread");
-} else {
-  parentPort.on("message", (msg) => {
-    const { png, pngOffset, pngLength, dest, destOffset, destLength, width, height, transfer } = msg;
-    const pngBuf = Buffer.from(png, pngOffset, pngLength);
-    const destBuf = Buffer.from(dest, destOffset, destLength);
-    try {
-      const decodeStart = Date.now();
-      const { data: rgba } = decodePng(pngBuf);
-      const decodeMs = Date.now() - decodeStart;
-      const blitStart = Date.now();
-      blitRgba8OverRgb48le(
-        rgba,
-        destBuf,
-        width,
-        height,
-        transfer
-      );
-      const blitMs = Date.now() - blitStart;
-      const reply = {
-        ok: true,
-        png,
-        dest,
-        decodeMs,
-        blitMs
-      };
-      parentPort.postMessage(reply, [png, dest]);
-    } catch (err) {
-      const reply = {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-        png,
-        dest
-      };
-      parentPort.postMessage(reply, [png, dest]);
-    }
-  });
-}

package/dist/skills/gsap/SKILL.md DELETED Viewed

@@ -1,240 +0,0 @@
----
-name: gsap
-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
-<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-<script>
-  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/