hyperframes 0.2.2-alpha.4 → 0.2.3-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.2.2-alpha.4",
+  "version": "0.2.3-alpha.1",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
@@ -21,14 +21,13 @@
     "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 dist/skills && cp -r ../studio/dist/* dist/studio/ && cp -r src/templates/blank src/templates/_shared dist/templates/ && cp -r ../../skills/hyperframes-compose ../../skills/hyperframes-captions ../../skills/hyperframes-tts dist/skills/ && (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/_shared dist/templates/ && cp -r ../../skills/hyperframes ../../skills/hyperframes-cli ../../skills/gsap dist/skills/ && (cp src/docs/*.md dist/docs/ 2>/dev/null || true)",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@hono/node-server": "^1.8.0",
     "@puppeteer/browsers": "^2.13.0",
     "adm-zip": "^0.5.16",
-    "cheerio": "^1.2.0",
     "citty": "^0.2.1",
     "compare-versions": "^6.1.1",
     "esbuild": "^0.25.0",
@@ -49,7 +48,6 @@
     "@types/mime-types": "^3.0.1",
     "@types/node": "^22.0.0",
     "adm-zip": "^0.5.16",
-    "cheerio": "^1.2.0",
     "hono": "^4.0.0",
     "linkedom": "^0.18.12",
     "mime-types": "^3.0.2",

package/dist/skills/hyperframes-captions/SKILL.md

@@ -1,212 +0,0 @@
----
-name: hyperframes-captions
-description: Captions, subtitles, lyrics, and karaoke synced to audio in HyperFrames. Tone-adaptive — detects script energy and applies matching typography, color, and animation with per-word styling.
-trigger: Syncing text to audio timing — captions, subtitles, lyrics, karaoke, transcription overlays, word-level or phrase-level text timed to speech or music.
----
-
-# Captions
-
-## 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.
-
-When transcribing:
-
-1. If the user says the language → use `--model small --language <code>` (no `.en` suffix)
-2. If the user says it's English → use `--model small.en`
-3. If the language is unknown → use `--model small` (no `.en`, no `--language`) — whisper auto-detects
-
-**Default model is `small` (not `small.en`).** Only add `.en` when explicitly told the audio is English.
-
----
-
-Analyze the spoken content to determine caption style. If the user specifies a style, use that. Otherwise, detect tone from the transcript.
-
-## Transcript Source
-
-The project's `transcript.json` contains a normalized word array with word-level timestamps:
-
-```json
-[
-  { "text": "Hello", "start": 0.0, "end": 0.5 },
-  { "text": "world.", "start": 0.6, "end": 1.2 }
-]
-```
-
-This is the only format the captions composition consumes. Use it directly:
-
-```js
-const words = JSON.parse(transcriptJson); // [{ text, start, end }]
-```
-
-For transcription commands, whisper model selection, external APIs (OpenAI, Groq), and supported input formats, see [transcript-guide.md](./transcript-guide.md).
-
-## Style Detection (Default — When No Style Is Specified)
-
-Read the full transcript before choosing a style. The style comes from the content, not a template.
-
-### Four Dimensions
-
-**1. Visual feel** — the overall aesthetic personality:
-
-- Corporate/professional scripts → clean, minimal, restrained
-- Energetic/marketing scripts → bold, punchy, high-impact
-- Storytelling/narrative scripts → elegant, warm, cinematic
-- Technical/educational scripts → precise, high-contrast, structured
-- Social media/casual scripts → playful, dynamic, friendly
-
-**2. Color palette** — driven by the content's mood:
-
-- Dark backgrounds with bright accents for high energy
-- Muted/neutral tones for professional or calm content
-- High contrast (white on black, black on white) for clarity
-- One accent color for emphasis — not multiple
-
-**3. Font mood** — typography character, not specific font names:
-
-- Heavy/condensed for impact and energy
-- Clean sans-serif for modern and professional
-- Rounded for friendly and approachable
-- Serif for elegance and storytelling
-
-**4. Animation character** — how words enter and exit:
-
-- Scale-pop/slam for punchy energy
-- Gentle fade/slide for calm or professional
-- Word-by-word reveal for emphasis
-- Typewriter for technical or narrative pacing
-
-## Per-Word Styling
-
-Scan the script for words that deserve distinct visual treatment. Not every word is equal — some carry the message.
-
-### What to Detect
-
-- **Brand names / product names** — larger size, unique color, distinct entrance
-- **ALL CAPS words** — the author emphasized them intentionally. Scale boost, flash, or accent color.
-- **Numbers / statistics** — bold weight, accent color. Numbers are the payload in data-driven content.
-- **Emotional keywords** — "incredible", "insane", "amazing", "revolutionary" → exaggerated animation (overshoot, bounce)
-- **Proper nouns** — names of people, places, events → distinct accent or italic
-- **Call-to-action phrases** — "sign up", "get started", "try it now" → highlight, underline, or color pop
-
-### How to Apply
-
-For each detected word, specify:
-
-- Font size multiplier (e.g., 1.3x for emphasis, 1.5x for hero moments)
-- Color override (specific hex value)
-- Weight/style change (bolder, italic)
-- Animation variant (overshoot entrance, glow pulse, scale pop)
-- **Marker highlight mode** — for visual emphasis beyond color/scale, add a marker-style effect: highlight sweep behind the word, hand-drawn circle around it, burst lines radiating from it, or scribble underline beneath it. See the `/marker-highlight` skill for patterns and the energy-to-mode mapping table.
-
-## Script-to-Style Mapping
-
-| Script tone          | Font mood                             | Animation                               | Color                                        | Size                 |
-| -------------------- | ------------------------------------- | --------------------------------------- | -------------------------------------------- | -------------------- |
-| Hype/launch          | Heavy condensed, 800-900 weight       | Scale-pop, back.out(1.7), fast 0.1-0.2s | Bright accent on dark (cyan, yellow, lime)   | Large 72-96px        |
-| Corporate/pitch      | Clean sans-serif, 600-700 weight      | Fade + slide-up, power3.out, 0.3s       | White/neutral on dark, single muted accent   | Medium 56-72px       |
-| Tutorial/educational | Mono or clean sans, 500-600 weight    | Typewriter or gentle fade, 0.4-0.5s     | High contrast, minimal color                 | Medium 48-64px       |
-| Storytelling/brand   | Serif or elegant sans, 400-500 weight | Slow fade, power2.out, 0.5-0.6s         | Warm muted tones, low opacity (0.85-0.9)     | Smaller 44-56px      |
-| Social/casual        | Rounded sans, 700-800 weight          | Bounce, elastic.out, word-by-word       | Playful colors, colored backgrounds on pills | Medium-large 56-80px |
-
-## Word Grouping by Tone
-
-Group size affects pacing. Fast content needs fast caption turnover.
-
-- **High energy:** 2-3 words per group. Quick turnover matches rapid delivery.
-- **Conversational:** 3-5 words per group. Natural phrase length.
-- **Measured/calm:** 4-6 words per group. Longer groups match slower pace.
-
-Break groups on sentence boundaries (period, question mark, exclamation), pauses (150ms+ gap), or max word count — whichever comes first.
-
-## Positioning
-
-- **Landscape (1920x1080):** Bottom 80-120px, centered
-- **Portrait (1080x1920):** Lower middle ~600-700px from bottom, centered
-- Never cover the subject's face
-- Use `position: absolute` — never relative (causes overflow)
-- One caption group visible at a time
-
-## Text Overflow Prevention
-
-Use `window.__hyperframes.fitTextFontSize()` to measure actual rendered text width and compute the correct font size. This replaces character-count heuristics with pixel-accurate measurement powered by [pretext](https://github.com/chenglou/pretext).
-
-```js
-GROUPS.forEach(function (group, gi) {
-  var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
-    fontFamily: "Outfit",
-    fontWeight: 900,
-    maxWidth: 1600,
-  });
-  wordEls.forEach(function (el) {
-    el.style.fontSize = result.fontSize + "px";
-  });
-});
-```
-
-| Option         | Default    | Description                                          |
-| -------------- | ---------- | ---------------------------------------------------- |
-| `maxWidth`     | `1600`     | Container width in px (1600 landscape, 900 portrait) |
-| `baseFontSize` | `78`       | Starting font size — used when text fits             |
-| `minFontSize`  | `42`       | Floor — never shrink below this                      |
-| `fontWeight`   | `900`      | Must match the CSS font-weight                       |
-| `fontFamily`   | `"Outfit"` | Must match the CSS font-family                       |
-| `step`         | `2`        | Decrement step in px per iteration                   |
-
-`fontWeight` and `fontFamily` must match the CSS applied to the text elements exactly, or measurements will be inaccurate.
-
-**Safety nets (still required in CSS):**
-
-- `max-width: 1600px` (landscape) or `max-width: 900px` (portrait) on caption container
-- `overflow: hidden` as a fallback for `fits: false` edge cases
-- `position: absolute` on all caption elements
-- Explicit `height` on caption container (e.g., `200px`)
-
-## Caption Exit Guarantee
-
-Captions that stick on screen are the most common caption bug. Every caption group **must** have a hard kill after its exit animation.
-
-```js
-// Animate exit (soft — can fail if tweens conflict)
-tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
-
-// Hard kill at group.end (deterministic — guarantees invisible)
-tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end);
-```
-
-**Why both?** The `tl.to` exit can fail to fully hide a group when karaoke word-level tweens conflict with the parent exit tween, `fromTo` entrance tweens lock values that override later tweens, or timeline scrubbing lands between the exit start and end. The `tl.set` at `group.end` is a deterministic kill — it fires at an exact time, doesn't animate, and can't be overridden.
-
-**Self-lint rule:** After building the timeline, verify every caption group has a hard kill:
-
-```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);
-```
-
-Place this **before** `window.__timelines[id] = tl` so it runs at composition init.
-
-## References
-
-For dynamic animation techniques (karaoke, clip-path reveals, slam words, scatter exits, elastic entrances, 3D rotation, audio-reactive captions, pretext-based positioning and grouping), see [dynamic-techniques.md](./dynamic-techniques.md).
-
-For animated text emphasis (highlight sweeps, hand-drawn circles, burst lines, scribble underlines, sketchout effects) that pairs with per-word styling, see the `/marker-highlight` skill.
-
-For transcription commands, whisper models, external APIs, and troubleshooting, see [transcript-guide.md](./transcript-guide.md).
-
-## Constraints
-
-- **Deterministic.** No `Math.random()`, no `Date.now()`.
-- **Sync to transcript timestamps.** Words appear when spoken.
-- **One group visible at a time.** No overlapping caption groups.
-- **Every caption group must have a hard `tl.set` kill at `group.end`.** Exit animations alone are not sufficient.
-- **Check project root** for font files before defaulting to Google Fonts.

package/dist/skills/hyperframes-tts/SKILL.md

@@ -1,79 +0,0 @@
----
-name: hyperframes-tts
-description: Generate speech audio locally using Kokoro-82M (no API key). Use when asked to create narration, voiceover, or text-to-speech audio for compositions, or when a user needs spoken audio from text. Covers voice selection, speed tuning, and integrating TTS output with compositions and captions.
----
-
-# Text-to-Speech
-
-## 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         |
-
-Run `npx hyperframes tts --list` for all 54 voices (8 languages: EN, JP, ZH, KO, FR, DE, IT, PT).
-
-## Speed Tuning
-
-- **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
-
-## Composing with TTS Audio
-
-Generate a voiceover and use it as the audio track:
-
-```bash
-npx hyperframes tts "Your script here" --voice af_nova --output narration.wav
-```
-
-Then reference it in the composition as a standard `<audio>` element:
-
-```html
-<audio
-  id="narration"
-  data-start="0"
-  data-duration="auto"
-  data-track-index="2"
-  src="narration.wav"
-  data-volume="1"
-></audio>
-```
-
-## TTS + Captions Workflow
-
-Generate speech, then transcribe it back for word-level caption timestamps:
-
-```bash
-# 1. Generate speech
-npx hyperframes tts script.txt --voice af_heart --output narration.wav
-
-# 2. Transcribe for word-level timestamps
-npx hyperframes transcribe narration.wav
-
-# 3. Result: narration.wav + transcript.json ready for captions
-```
-
-This avoids manually timing captions — whisper extracts precise word boundaries from the generated audio.
-
-## Long Scripts
-
-For scripts longer than a few paragraphs, write the text to a `.txt` file and pass the path:
-
-```bash
-npx hyperframes tts script.txt --voice bf_emma --output narration.wav
-```
-
-The model handles long text well but very long inputs (>5 minutes of speech) may benefit from splitting into segments.
-
-## Requirements
-
-- Python 3.8+ with `kokoro-onnx` and `soundfile` installed (`pip install kokoro-onnx soundfile`)
-- Model downloads automatically on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`)

package/dist/templates/blank/compositions/captions.html

@@ -1,95 +0,0 @@
-<template id="captions-template">
-  <div
-    data-composition-id="captions"
-    data-width="1920"
-    data-height="1080"
-    data-duration="__VIDEO_DURATION__"
-  >
-    <div id="captions-container"></div>
-
-    <style>
-      [data-composition-id="captions"] {
-        width: 1920px;
-        height: 1080px;
-        pointer-events: none;
-      }
-
-      [data-composition-id="captions"] #captions-container {
-        position: absolute;
-        bottom: 100px;
-        left: 50%;
-        transform: translateX(-50%);
-        display: flex;
-        justify-content: center;
-        align-items: center;
-        width: 100%;
-        height: 150px;
-      }
-
-      .caption-group {
-        position: absolute;
-        opacity: 0;
-        font-family: "Inter", sans-serif;
-        font-size: 48px;
-        font-weight: 700;
-        color: #ffffff;
-        text-shadow:
-          0 2px 8px rgba(0, 0, 0, 0.8),
-          0 0 2px rgba(0, 0, 0, 0.9);
-        white-space: nowrap;
-        max-width: 1600px;
-        overflow: hidden;
-      }
-    </style>
-
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <script>
-      (function () {
-        window.__timelines = window.__timelines || {};
-        const tl = gsap.timeline({ paused: true });
-
-        const script = [];
-
-        if (script.length === 0) {
-          window.__timelines["captions"] = tl;
-          return;
-        }
-
-        const container = document.getElementById("captions-container");
-
-        // Group words into lines (max 5 words per line)
-        const lines = [];
-        for (let i = 0; i < script.length; i += 5) {
-          const lineWords = script.slice(i, i + 5);
-          lines.push({
-            text: lineWords.map((w) => w.text).join(" "),
-            start: lineWords[0].start,
-            end: lineWords[lineWords.length - 1].end,
-          });
-        }
-
-        lines.forEach((line, index) => {
-          const el = document.createElement("div");
-          el.className = "caption-group";
-          el.textContent = line.text;
-          container.appendChild(el);
-
-          tl.fromTo(
-            el,
-            { opacity: 0, y: 20 },
-            { opacity: 1, y: 0, duration: 0.3, ease: "power3.out" },
-            line.start,
-          );
-
-          const hideTime =
-            index < lines.length - 1 ? Math.min(line.end, lines[index + 1].start) : line.end;
-
-          tl.to(el, { opacity: 0, y: -10, duration: 0.25, ease: "power2.in" }, hideTime - 0.25);
-          tl.set(el, { opacity: 0, visibility: "hidden" }, hideTime);
-        });
-
-        window.__timelines["captions"] = tl;
-      })();
-    </script>
-  </div>
-</template>