dsh-hyperframes 0.1.1 → 0.3.0

package/skills/embedded-captions/references/direction-catalog.md

@@ -0,0 +1,138 @@
+# Direction catalog
+
+10 distinct aesthetic directions the skill can express. Each is a complete look: font, motion, color, placement, rhetorical defaults. The agent picks by **content tone × shot type × platform**, not preset name.
+
+Current shipped templates (`modes/cinematic/*`) cover about 30% of this catalog. The rest are future ship-ready aesthetics.
+
+Classification matrix — pick direction by intersection:
+
+| Tone ↓ / Platform → | 9:16 portrait                            | 16:9 landscape           | 1:1 square               |
+| ------------------- | ---------------------------------------- | ------------------------ | ------------------------ |
+| **Documentary**     | documentary-dignified (vertical variant) | documentary-dignified    | broadcast-dignified      |
+| **Conversational**  | portrait-header + default                | memory-wall OR champion  | broadcast-dignified      |
+| **Energetic**       | high-energy-vlog                         | high-energy-vlog-wide    | high-energy-vlog-sq      |
+| **Poetic**          | lyrical-poem-on-wall (portrait)          | lyrical-poem-on-wall     | chapter-card             |
+| **Keynote/tech**    | — (9:16 not ideal)                       | tech-keynote-confident   | tech-keynote-confident   |
+| **Investigative**   | —                                        | investigative-typewriter | investigative-typewriter |
+| **Music video**     | k-pop-lyric                              | k-pop-lyric              | k-pop-lyric              |
+
+---
+
+## Direction specs
+
+### 1. documentary-dignified _(Errol Morris / PBS Frontline)_ — Standard-mode direction (no prebuilt Cinematic template)
+
+- **Family**: Söhne Mono OR GT Sectra for name cards; Inter for body
+- **Weights**: 500 body, 700 name card
+- **Color**: bone `#F5EFE6` on charcoal, OR charcoal `#1A1A1A` on bone. No accent.
+- **Motion**: burn-in (no animation). Held 0.5s past last word.
+- **Placement**: bottom-left block, 10% margin, locked position for whole interview.
+- **Rules**: 2-line max. Speaker name card once at first utterance + after each cut. No emphasis styling — gravitas IS the style.
+- **Rhetorical**: aggressive filler suppression. Every word is chosen.
+
+### 2. cinematic-noir _(Kyle Cooper / Se7en)_
+
+- **Family**: Distressed serif (Hoefler Text) + tight mono for detail
+- **Weights**: 700 mostly; thin italic ONLY for whispers
+- **Color**: off-white `#E8E0D0` with deep red `#8B0000` single-word accent for menace
+- **Motion**: typewriter with 10% chance of 1px jitter on entry; scratched etch for chapter beats
+- **Placement**: off-axis — avoid dead-center, slightly high-left or low-right
+- **Rules**: no emoji, no rounded corners, everything hand-feeling
+
+### 3. tech-keynote-confident _(Apple / Jony Ive ad)_
+
+- **Family**: SF Pro Display OR Inter, nothing else
+- **Weights**: 800 headline keyword, 400 context
+- **Color**: pure white on any bg; `mix-blend-mode: difference` fallback for bright scenes
+- **Motion**: swipe-reveal from bottom via clip-path (400ms); exit fades 400ms
+- **Placement**: dead center, large. NOT lower-third.
+- **Rules**: one caption on screen at a time. 2–5 words per caption. Long held silences between. Feels like slides.
+
+### 4. lyrical-poem-on-wall _(extends current memory-wall template)_
+
+- **Family**: Serif with personality — EB Garamond / GT Sectra / Caslon Italic
+- **Weights**: 400–500 only. **This direction rejects bold.**
+- **Color**: picks up wall via `mix-blend-mode: overlay`, opacity 0.85, no stroke
+- **Motion**: etch in 600ms, hold 1.5–3s, etch out
+- **Placement**: always on a surface in the scene (back wall, foam, whiteboard). Uses matte pipeline.
+- **Rules**: captions are **fewer** than spoken text — 40–60%. Intentional silences. No other tool does this; strong differentiation.
+
+### 5. high-energy-vlog _(controlled Hormozi)_
+
+- **Family**: Inter ExtraBold, uppercase
+- **Weights**: 900 always
+- **Color**: white body + ONE accent (`#FFD600` or `#00E676`) + narrow 2px dark stroke
+- **Motion**: word-pop with elastic, 60ms stagger; active word scales 1.15× on speech onset
+- **Placement**: center-frame, ~35% from top
+- **Rules**: max 3 words per frame. Hard break at breath pauses. Accent color on ~15% of words. **One full silence every 10s** (what Hormozi imitators miss).
+
+### 6. chapter-card _(Wes Anderson / Grand Budapest)_
+
+- **Family**: Futura Bold (modern) / Archer (warm) / Bodoni (formal)
+- **Weights**: 700 chapter title, 400 attribution
+- **Color**: pastel hue sampled from scene
+- **Motion**: full-frame static card between interview segments
+- **Placement**: centered card for chapters; lower-left name card during speech
+- **Rules**: chapter cards get their own beat (0.8s silence before, 0.4s after). Feels authored.
+
+### 7. investigative-typewriter _(Frontline / 60 Minutes / Morris Interrotron)_
+
+- **Family**: IBM Plex Mono OR JetBrains Mono
+- **Weights**: 500
+- **Color**: white with 3px shadow, no stroke
+- **Motion**: typewriter char-by-char 25ms/char; cursor blink 600ms after last char
+- **Placement**: bottom band with 40% opacity gradient up — **NOT a hard box**
+- **Rules**: one line only, two-line max. Every caption ends with 1-frame cursor-hold before next enters.
+
+### 8. k-pop-lyric _(music video typographic flex)_
+
+- **Family**: oversized display serif (Playfair Display / GT Super) + tiny mono detail line
+- **Weights**: display 900, mono 400
+- **Color**: deep saturated single hue per song/segment
+- **Motion**: cascade entries alternating sides; words cross subject with mix-blend
+- **Placement**: intentionally LARGE — sometimes bigger than the face
+- **Rules**: emotional/musical moments only. Never informational content. **Breaks rule #1 (subject wins) on purpose** — that's the whole point.
+
+### 9. broadcast-dignified _(BBC / NYT documentary standard)_
+
+- **Family**: Helvetica Now / Neue Haas Grotesk
+- **Weights**: 500 body, 700 name
+- **Color**: white on 40% black gradient pill (not hard box, not plain shadow — gradient is the signature)
+- **Motion**: 200ms fade-up, 150ms fade-down
+- **Placement**: bottom-center, 10% margin, title-safe locked
+- **Rules**: strict BBC — 160–180wpm, 32–34 chars/line, 2 lines max, 1.5s min gap. "Export to broadcast" mode. Boring on purpose. Never wrong.
+
+### 10. conference-lower-third-killer _(B2B but not lame)_
+
+- **Family**: GT America / Aktiv Grotesk
+- **Weights**: dual-weight name card — role 400, name 700, same size
+- **Color**: scene-sampled accent on name, white on role
+- **Motion**: name card swipes in from left 400ms on first appearance only; subsequent static
+- **Placement**: lower-left card + active-word highlight inline in dialogue above
+- **Rules**: mode for podcast clips, founder interviews, keynote pulls. Sophisticated without being arty.
+
+---
+
+## Which to ship next
+
+Current templates: `memory-wall` (roughly direction #4), `champion` (roughly a mix of #5 and #9), `portrait-header` (default vertical).
+
+Priority ship order based on competitive gap:
+
+1. **documentary-dignified** — no one else does this well; Errol Morris aesthetic is an unserved niche
+2. **lyrical-poem-on-wall** (as distinct template) — the one that most uses our matte-embed moat
+3. **high-energy-vlog** — matches but out-designs Hormozi/Submagic presets
+4. **tech-keynote-confident** — big for product launch videos
+5. **investigative-typewriter** — niche but highly distinctive
+
+---
+
+## How the agent picks
+
+1. Classify the clip: `tone × shot × platform` (see matrix above)
+2. Look up direction in matrix
+3. Read that direction's spec in this file
+4. Translate spec into plan.json parameters OR clone the canonical HTML from `examples/`
+5. Tune layout per scene (agent judgment, see `aesthetic-principles.md §1–18`)
+
+If no direction fits cleanly → **Standard mode**. Don't fake-fit an ill-matched direction.

package/skills/embedded-captions/references/example-renders/champion.html

@@ -0,0 +1,371 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #000;
+        font-family: "Inter", system-ui, sans-serif;
+      }
+
+      #a-roll {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+
+      /*
+        This scene has no flat wall — subject is center with a busy
+        bookshelf backdrop. So instead of a wall-plane, we place a
+        HEADER band across the top of the frame with subtle perspective
+        (slight rotateX so it lies on the bookshelf rather than floats).
+        Screen-blend picks up the shelf's darker patches.
+      */
+      #stage {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 1920px;
+        height: 1080px;
+        perspective: 2400px;
+        perspective-origin: 25% 50%;
+        pointer-events: none;
+        z-index: 2;
+      }
+
+      /*
+        Left-column layout: subject fills x=550-1200, so the bookshelf
+        at x=0-550 is the clean zone. Captions right-align there, with
+        a mild perspective that makes them lie on the shelf.
+      */
+      .left-plane {
+        position: absolute;
+        /* Upper-left region. Hands gesture widely below y≈460, so we
+           keep the plane above that line. Head sits to the right of
+           x≈600, so x=40-720 here is the clean bookshelf zone. */
+        top: 40px;
+        left: 40px;
+        width: 720px;
+        height: 420px;
+        transform-style: preserve-3d;
+        transform: rotateY(4deg);
+        transform-origin: left center;
+        padding: 24px 36px;
+      }
+
+      /* Each cap stacks at the same absolute position within the plane
+         so hidden captions don't reserve flex space. */
+      .left-plane .cap {
+        position: absolute;
+        top: 24px;
+        right: 36px;
+        max-width: 648px; /* plane 720 - padding 36×2 */
+      }
+
+      /* A single "crown" caption placed center-stage for the payoff
+         ("A WIMBLEDON CHAMPION") — deliberately crosses the head to
+         deliver the emphasis via cinematic occlusion. */
+      .crown-plane {
+        position: absolute;
+        top: 420px;
+        left: 0;
+        right: 0;
+        text-align: center;
+        pointer-events: none;
+      }
+
+      .cap {
+        display: block;
+        position: relative;
+        line-height: 1.02;
+        opacity: 0;
+        mix-blend-mode: screen;
+        color: #fff5df;
+        text-shadow:
+          0 0 18px rgba(255, 220, 170, 0.55),
+          0 3px 8px rgba(0, 0, 0, 0.85);
+        filter: brightness(1.12) contrast(1.08);
+        will-change: transform, opacity;
+      }
+
+      .cap .w {
+        display: inline-block;
+        opacity: 0;
+        will-change: opacity, transform;
+      }
+
+      /*
+        Story beats sized to emphasize meaning:
+        - intros / fillers = smaller italic
+        - key statement phrases = bigger upright
+        - emphasis phrases (incredible things) = largest bold
+        - crown (Wimbledon Champion) = huge, center-stage, behind subject
+      */
+      .cap-intro {
+        font-size: 52px;
+        font-weight: 500;
+        font-style: italic;
+        letter-spacing: -0.005em;
+      }
+      .cap-phrase {
+        font-size: 60px;
+        font-weight: 600;
+        font-style: normal;
+        letter-spacing: -0.015em;
+      }
+      .cap-emph {
+        font-size: 70px;
+        font-weight: 800;
+        font-style: normal;
+        letter-spacing: -0.025em;
+      }
+      .cap-dream {
+        font-size: 64px;
+        font-weight: 700;
+        font-style: italic;
+        letter-spacing: -0.015em;
+      }
+      .cap-crown {
+        font-size: 140px;
+        font-weight: 900;
+        font-style: normal;
+        letter-spacing: -0.035em;
+        text-transform: uppercase;
+        line-height: 1;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="12.08"
+      data-width="1920"
+      data-height="1080"
+    >
+      <video
+        id="a-roll"
+        class="clip"
+        src="source.mp4"
+        muted
+        playsinline
+        data-duration="12.08"
+        data-track-index="0"
+        style="z-index: 1"
+      ></video>
+
+      <div id="stage">
+        <!-- Left column: G1-G5 live here, on the clean bookshelf -->
+        <div class="left-plane">
+          <div id="cg-0" class="cap cap-intro">
+            <span class="w" data-i="0">You</span>
+            <span class="w" data-i="1">know,</span>
+            <span class="w" data-i="2">for</span>
+            <span class="w" data-i="3">me</span>
+          </div>
+          <div id="cg-1" class="cap cap-phrase">
+            <span class="w" data-i="0">I've</span>
+            <span class="w" data-i="1">had</span>
+            <span class="w" data-i="2">this</span>
+            <span class="w" data-i="3">kind</span>
+            <span class="w" data-i="4">of</span>
+            <span class="w" data-i="5">upbringing</span>
+          </div>
+          <div id="cg-2" class="cap cap-phrase">
+            <span class="w" data-i="0">the</span>
+            <span class="w" data-i="1">great</span>
+            <span class="w" data-i="2">foundation</span>
+          </div>
+          <div id="cg-3" class="cap cap-emph">
+            <span class="w" data-i="0">I've</span>
+            <span class="w" data-i="1">achieved</span>
+            <span class="w" data-i="2">incredible</span>
+            <span class="w" data-i="3">things</span>
+          </div>
+          <div id="cg-4" class="cap cap-dream">
+            <span class="w" data-i="0">dreaming</span>
+            <span class="w" data-i="1">of</span>
+            <span class="w" data-i="2">becoming</span>
+            <span class="w" data-i="3">number</span>
+            <span class="w" data-i="4">one</span>
+          </div>
+        </div>
+        <!-- Center-stage crown: the payoff. Sits where the subject is,
+             matte layering makes it *behind* him — the occlusion is the moment. -->
+        <div class="crown-plane">
+          <div id="cg-5" class="cap cap-crown">
+            <span class="w" data-i="0">Wimbledon</span>
+            <span class="w" data-i="1">Champion</span>
+          </div>
+        </div>
+      </div>
+
+      <audio
+        id="a-roll-audio"
+        src="source.mp4"
+        data-start="0"
+        data-duration="12.08"
+        data-track-index="3"
+        data-volume="1"
+      ></audio>
+    </div>
+
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      const DUR = 12.08;
+
+      /* Word-level transcript — ElevenLabs scribe_v2 */
+      const GROUPS = [
+        {
+          id: "cg-0",
+          in: 0.1,
+          out: 1.45,
+          tone: "soft",
+          words: [
+            { text: "You", start: 0.18, end: 0.24 },
+            { text: "know", start: 0.28, end: 0.36 },
+            { text: "for", start: 0.46, end: 0.62 },
+            { text: "me", start: 0.66, end: 0.86 },
+          ],
+        },
+        {
+          id: "cg-1",
+          in: 1.4,
+          out: 3.35,
+          tone: "soft",
+          words: [
+            { text: "I've", start: 1.5, end: 1.68 },
+            { text: "had", start: 1.76, end: 1.94 },
+            { text: "this", start: 1.98, end: 2.14 },
+            { text: "kind", start: 2.2, end: 2.34 },
+            { text: "of", start: 2.36, end: 2.44 },
+            { text: "upbringing", start: 2.48, end: 3.06 },
+          ],
+        },
+        {
+          id: "cg-2",
+          in: 3.5,
+          out: 5.35,
+          tone: "soft",
+          words: [
+            { text: "the", start: 3.56, end: 3.64 },
+            { text: "great", start: 3.7, end: 3.9 },
+            { text: "foundation", start: 3.96, end: 4.6 },
+          ],
+        },
+        {
+          id: "cg-3",
+          in: 6.05,
+          out: 8.3,
+          tone: "present",
+          words: [
+            { text: "I've", start: 6.36, end: 6.5 },
+            { text: "achieved", start: 6.62, end: 7.08 },
+            { text: "incredible", start: 7.38, end: 7.86 },
+            { text: "things", start: 7.88, end: 8.16 },
+          ],
+        },
+        {
+          id: "cg-4",
+          in: 8.5,
+          out: 10.4,
+          tone: "present",
+          words: [
+            { text: "dreaming", start: 8.54, end: 8.84 },
+            { text: "of", start: 8.88, end: 9.0 },
+            { text: "becoming", start: 9.04, end: 9.4 },
+            { text: "number", start: 9.48, end: 9.64 },
+            { text: "one", start: 9.72, end: 9.8 },
+          ],
+        },
+        {
+          id: "cg-5",
+          in: 10.8,
+          out: 12.08,
+          tone: "present",
+          words: [
+            { text: "Wimbledon", start: 10.92, end: 11.28 },
+            { text: "Champion", start: 11.38, end: 11.84 },
+          ],
+        },
+      ];
+
+      GROUPS.forEach(function (g) {
+        var sel = "#" + g.id;
+        var words = g.words.map(function (_, i) {
+          return sel + " .w[data-i='" + i + "']";
+        });
+        var isSoft = g.tone === "soft";
+
+        /* Container visible just before entrance; single-layer fade is on words. */
+        tl.set(sel, { opacity: 1, y: 0 }, Math.max(0, g.in - 0.01));
+
+        g.words.forEach(function (w, i) {
+          if (isSoft) {
+            tl.fromTo(
+              words[i],
+              { opacity: 0, y: 8 },
+              { opacity: 1, y: 0, duration: 0.42, ease: "power2.out", overwrite: "auto" },
+              w.start,
+            );
+          } else {
+            tl.fromTo(
+              words[i],
+              { opacity: 0, y: 6, scale: 1.04 },
+              {
+                opacity: 1,
+                y: 0,
+                scale: 1.0,
+                duration: 0.22,
+                ease: "power3.out",
+                transformOrigin: "50% 50%",
+                overwrite: "auto",
+              },
+              w.start,
+            );
+          }
+        });
+
+        /* Group exit — each group fades out before the next enters. */
+        if (g.out < DUR) {
+          tl.to(
+            sel,
+            { opacity: 0, duration: 0.45, ease: "power2.in", overwrite: "auto" },
+            g.out - 0.45,
+          );
+        }
+        tl.set(sel, { opacity: 0, visibility: "hidden" }, g.out);
+      });
+
+      /* Self-lint */
+      GROUPS.forEach(function (g) {
+        var el = document.getElementById(g.id);
+        if (!el) return;
+        tl.seek(g.out + 0.01);
+        var cs = window.getComputedStyle(el);
+        if (cs.opacity !== "0" && cs.visibility !== "hidden") {
+          console.warn("[caption-lint] " + g.id + " visible at t=" + (g.out + 0.01).toFixed(2));
+        }
+      });
+      tl.seek(0);
+
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>