hyperframes 0.1.6 → 0.1.8

package/dist/skills/compose-video/patterns.md

@@ -0,0 +1,118 @@
+# 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);
+```
+
+## 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
+<div class="slide" data-start="0" data-duration="30" data-track-index="3">...</div>
+<div class="slide" data-start="30" data-duration="25" data-track-index="3">...</div>
+<div class="slide" data-start="55" data-duration="20" data-track-index="3">...</div>
+```
+
+## 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"
+>
+  <!-- Primitive clips -->
+  <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>
+  <img id="el-3" data-start="5" data-duration="4" data-track-index="1" src="..." />
+  <audio id="el-4" data-start="0" data-duration="30" data-track-index="2" src="..." />
+
+  <!-- Sub-compositions loaded from files -->
+  <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>
+
+  <script>
+    // Just register the timeline — framework auto-nests sub-compositions
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["my-video"] = tl;
+  </script>
+</div>
+```

package/dist/templates/_shared/CLAUDE.md

@@ -0,0 +1,50 @@
+# HyperFrames Composition Project
+
+## Skills — USE THESE FIRST
+
+**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `class="clip"`, `window.__timelines`, `data-*` attributes) that are NOT in generic web docs. Skipping them produces broken compositions.
+
+| Skill                | Command             | When to use                                                                                            |
+| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
+| **compose-video**    | `/compose-video`    | Creating or editing ANY HTML composition — videos, animations, title cards, overlays, sub-compositions |
+| **captions**         | `/captions`         | Building captions from whisper transcripts — style detection, per-word styling                         |
+| **gsap-core**        | `/gsap-core`        | GSAP tweens: `gsap.to()`, `from()`, `fromTo()`, easing, stagger, defaults                              |
+| **gsap-timeline**    | `/gsap-timeline`    | Timeline sequencing, position parameter, labels, nesting                                               |
+| **gsap-performance** | `/gsap-performance` | Animation performance — transforms over layout props, will-change, batching                            |
+
+> **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` and
+> `npx skills add greensock/gsap-skills`.
+
+## Commands
+
+```bash
+npx hyperframes dev          # preview in browser (studio editor)
+npx hyperframes render       # render to MP4
+npx hyperframes lint         # validate compositions
+npx hyperframes docs <topic> # reference docs in terminal
+```
+
+Available doc topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `templates`, `troubleshooting`
+
+Full docs: [hyperframes.heygen.com](https://hyperframes.heygen.com)
+
+## Project Structure
+
+- `index.html` — main composition (root timeline)
+- `compositions/` — sub-compositions referenced via `data-composition-src`
+- `meta.json` — project metadata (id, name)
+- `transcript.json` — whisper word-level transcript (if generated)
+
+## Key Rules
+
+1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
+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"` to reference other HTML files
+6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "hyperframes",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heygen-com/hyperframes",
+    "directory": "packages/cli"
+  },
   "bin": {
     "hyperframes": "./dist/cli.js"
   },
@@ -15,7 +20,7 @@
     "build:fonts": "cd ../producer && tsx scripts/generate-font-data.ts",
     "build:studio": "cd ../studio && bun run build",
     "build:runtime": "tsx scripts/build-runtime.ts",
-    "build:copy": "mkdir -p dist/studio dist/docs dist/templates && cp -r ../studio/dist/* dist/studio/ && cp -r src/templates/blank src/templates/warm-grain src/templates/play-mode src/templates/swiss-grid src/templates/vignelli dist/templates/ && (cp src/docs/*.md dist/docs/ 2>/dev/null || true)",
+    "build:copy": "mkdir -p dist/studio dist/docs dist/templates dist/skills && cp -r ../studio/dist/* dist/studio/ && cp -r src/templates/blank src/templates/warm-grain src/templates/play-mode src/templates/swiss-grid src/templates/vignelli src/templates/_shared dist/templates/ && cp -r ../../skills/compose-video ../../skills/captions dist/skills/ && (cp src/docs/*.md dist/docs/ 2>/dev/null || true)",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {