dsh-hyperframes 0.9.1 → 0.9.3

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/biennale-yellow/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Biennale Yellow — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a biennale literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a biennale literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -150,7 +149,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/blockframe/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   BlockFrame — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a blockframe literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a blockframe literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -29,7 +28,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -153,7 +152,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/blue-professional/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Blue Professional — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a blue-professional
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a blue-professional
   literal fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -152,7 +151,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/bold-poster/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Bold Poster — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a bold-poster
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a bold-poster
   literal fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -29,7 +28,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -159,7 +158,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/broadside/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Broadside — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a broadside literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a broadside literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -154,7 +153,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/capsule/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Capsule — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a capsule literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a capsule literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -153,7 +152,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/cartesian/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Cartesian — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a cartesian literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a cartesian literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -151,7 +150,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/cobalt-grid/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Cobalt Grid — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a cobalt literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a cobalt literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -30,7 +29,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -167,7 +166,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/code-editorial/FRAME.md

@@ -270,8 +270,8 @@ to the diff; commit/issue numbers are chrome.
 
 ## Known Gaps
 
-- **Motion intentionally out of scope.** frame.md specifies composition only. Code editorial's motion register — short cross-dissolves, no overshoot/bounce/elastic, coral the only "draw-on", numbers count up, code types on line by line — lives in the workflow's `motion-language.md` + `hyperframes-animation`, not here.
-- **EB Garamond + Inter + JetBrains Mono ship as licensed local WOFF2 assets with this preset.** `build-frame.mjs` stages weights 400 + 700 into `assets/fonts/` and appends the exact `@font-face` block to the generated `frame.md`, so Studio, snapshots, and renders resolve them offline without a first-run Google Fonts fetch. Author display at **weight 400** (700 reads as a heavy bold, off-register), and treat italic as the browser-synthesized slant (acceptable for the pull-quote register; add a real italic face only if a project leans hard on it). EB Garamond is a warm old-style serif (low contrast, humanist); if it ever fails, fall to Georgia or another old-style serif — never to a sans. CJK: Noto Serif SC (display) / Noto Sans SC (body) / Noto Sans Mono CJK (code); the sentence-case warmth carries when the serif drops.
+- **Motion intentionally out of scope.** frame.md specifies composition only. Code editorial's motion register — short cross-dissolves, no overshoot/bounce/elastic, coral the only "draw-on", numbers count up, code types on line by line — lives in the skill's `references/motion.md`, not here.
+- **EB Garamond + Inter + JetBrains Mono ship as licensed local WOFF2 assets with this preset.** Copy the six files in this preset's `fonts/` folder (weights 400 + 700) into the project's `assets/fonts/` and add one `@font-face` per file, so Studio, snapshots, and renders resolve them offline without a first-run Google Fonts fetch. Nothing stages them for you. Author display at **weight 400** (700 reads as a heavy bold, off-register), and treat italic as the browser-synthesized slant (acceptable for the pull-quote register; add a real italic face only if a project leans hard on it). EB Garamond is a warm old-style serif (low contrast, humanist); if it ever fails, fall to Georgia or another old-style serif — never to a sans. CJK: Noto Serif SC (display) / Noto Sans SC (body) / Noto Sans Mono CJK (code); the sentence-case warmth carries when the serif drops.
 - **Syntax colors (teal `#5DB8A6` / amber `#E8A55A` / status) are fixed decoration**, declared in §Colors — they are NOT in the remixable `colors:` block, so a brand remix never repaints them.
 - **The code itself is the `code-*` registry blocks**, not this preset — this preset owns only the surrounding warm-navy surface + mono chrome.
 - **9:16 / 1:1 are guidance**; verify the legibility floor and that the cream/tile warmth + one-coral discipline hold per ratio.

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/code-editorial/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Code editorial — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  (and pr-to-video's) Step 2 copies it into the project as caption-skin.html;
-  captions.mjs then fills the three reserved holes, wraps the fragment in a
-  <template>, and writes compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a code-editorial literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a code-editorial literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -153,7 +152,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/coral/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Coral — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a coral literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a coral literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -29,7 +28,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -155,7 +154,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/creative-mode/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Creative Mode — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a creative-mode
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a creative-mode
   literal fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -156,7 +155,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/daisy-days/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Daisy Days — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has a daisy-days literal
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has a daisy-days literal
   fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -28,7 +27,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -159,7 +158,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/{hyperframes-creative → hyperframes/assets}/frame-presets/editorial-forest/caption-skin.html

@@ -1,16 +1,15 @@
 <!--
   Editorial Forest — caption skin (preset-local source).
 
-  This is the preset's own lower-third karaoke caption look. product-launch-video's
-  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
-  three reserved holes, wraps the fragment in a <template>, and writes
-  compositions/captions.html:
+  This is the preset's own lower-third karaoke caption look: a caption skin to read or
+  copy, not to mount as is. A copy used as compositions/captions.html fills its three
+  reserved holes and wraps the fragment in a <template>:
     · the empty GROUPS array            → the engine's scene-aware word groups
     · the 0 duration + 0 width/height   → real total + canvas size
     · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
 
-  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
-  frame.md, so the Step-2 brand overlay flows through; each var has an editorial-forest
+  Token contract — reference ONLY this fixed vocab (set it from the
+  project's frame.md; each var has an editorial-forest
   literal fallback for standalone preview):
     --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
     --font-body · --cap-band-top · --cap-band-height
@@ -29,7 +28,7 @@
 -->
 <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
 
-<!-- captions.mjs injects the project's :root tokens here -->
+<!-- the project's :root tokens go here -->
 <style data-brand-tokens></style>
 
 <style>
@@ -152,7 +151,7 @@
 </div>
 
 <script>
-  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  // the scene-aware word groups + real duration go here.
   var GROUPS = [];
   var DURATION = 0;
 

package/skills/hyperframes/references/captions.md

@@ -0,0 +1,46 @@
+# Captions
+
+## Words and timings
+
+- `npx hyperframes transcribe <file> --json` and a HeyGen voiceover (`/media-use`) give every word's start and end. Work from those as `[{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 }, …]`.
+- `npx hyperframes transcribe` defaults to the `small.en` whisper model, which **translates** non-English speech into English. Pass the model: `npx hyperframes transcribe <file> --model small.en` for English, `--model small --language <code>` otherwise, `--model medium.en` for speech over music. It writes `assets/transcript.json` (its JSON names the path) and overwrites it on the next run; `--to srt` or `--to vtt` writes a sidecar.
+- For Chinese, Japanese and other unspaced scripts, local transcription returns a whole sentence as one "word", sometimes in the other script (Traditional for Simplified speech). Split each segment's text into short phrases and spread its time across them by character count; check the characters against what is said.
+- Whisper invents "Thank you." over silence and repeats lines over a silent tail: drop words that start inside a final silence (`silencedetect=noise=-35dB:d=0.6`; real speech sits around −16 to −26 dB).
+- Never put two words in one timed entry, and match transcript words to caption words by position, not text, or a repeated word takes the wrong time.
+- Read the transcript before using it. More than 20% `♪` or `�` tokens, or nonsense words, means it failed: retry with a larger model, or take lyrics from the person. Drop non-word tokens before building groups.
+
+## Structure
+
+- One sub-composition host with `data-track-kind="captions"` holds every caption group, so Studio shows them on one captions track.
+- Ready-made styles: `npx hyperframes catalog --tag caption-style --json`. An installed one is source you can restyle.
+
+## Groups
+
+- 2–3 words for high energy, 3–5 conversational, 4–6 calm. Break at a sentence end, a pause of 150 ms or more, or the word limit.
+- One group visible at a time. A group opens at or before its first word's start and closes at or after its last word's end. A caption at exactly 0 s looks pre-existing: start 0.1–0.3 s in.
+- Every group ends with a hard kill after its exit, or a stale group can stay on screen:
+
+```js
+tl.to(group, { opacity: 0, duration: 0.12, ease: "power2.in" }, end - 0.12);
+tl.set(group, { opacity: 0, visibility: "hidden" }, end);
+```
+
+`tl.set` is an instant flip, so setting `visibility` on the group is fine; never tween it on a `.clip`.
+
+## Fit and place
+
+- Size each group to fit: `window.__hyperframes.fitTextFontSize(text, { fontFamily, fontWeight, maxWidth })` returns `{ fontSize }`. Defaults: `maxWidth` 1600 landscape, 900 portrait; base 78, minimum 42, step 2. When a word scales up for emphasis, divide `maxWidth` by that scale.
+- A full-width absolute container, centred with text alignment. Never `left: 50%; transform: translateX(-50%)`, which clips at the frame edges.
+- `overflow: visible`, not `hidden`, which cuts off scaled words and glows.
+- Landscape: 80–120 px from the bottom. Portrait: about 600–700 px from the bottom. Never over the speaker's face; inside the 80% title-safe box.
+- Position each group absolutely. In a flex column a group hidden with `visibility: hidden` still takes space, so the next one lands lower. In a stack that accumulates, groups in one block share one exit time, or the stack reflows.
+- Fade the group or its words, not both: the opacities multiply and read as a pop. A gradient or `background-clip: text` fill goes on the inner text span, not the transformed container.
+- Over footage, choose the blend by the brightness (0–255) behind the text: under 60 `screen`, 60–180 `overlay`, over 180 `normal` with opaque colour. Plain subtitles above brightness 60 get a scrim sized to the text (30–40%), never a full-width bar.
+- Footage may already carry burned-in subtitles only mid-clip: scan a 1 fps contact sheet before placing captions.
+
+## Text behind the speaker
+
+- Stack the video, then the captions, then a cutout of the person from `npx hyperframes remove-background` (`/media-use`), ordered by `z-index`. Shake or punch in the video and the cutout together in one wrapper.
+- `check` treats a `<video>` as opaque across its whole box, so a WebM cutout fails every caption behind it with `text_occluded`: put `data-layout-allow-occlusion` on the cutout and judge from `snapshot`.
+- A big word behind the head reads best 30–55% covered: under about 15% it floats, over about 65% it is eaten. Re-lay out when a content word is 80% covered, or two adjacent words 50% each. Measure the rendered word boxes against the matte over each caption's own time window (heads move: one clip went from y=224 to y=96 in 8 s); estimates from character widths were wrong both ways.
+- The matte model drops mic arms, lets large rigs near the body leak in, and flickers on held objects. Its first run downloads 168 MB, and it runs at about 2 fps at 1080p on CPU.