dsh-hyperframes 0.2.0 → 0.3.1

package/skills/hyperframes-registry/references/placeholder-material.md

@@ -0,0 +1,149 @@
+# Placeholder material
+
+Registry items ship with stand-in content: a rectangle where the user's screenshot goes, a
+bar where their number goes, a chip where their teammate's face goes. That stand-in is
+**placeholder material**, and it is monochrome. No hue, no colour ramps, no purple-to-blue
+diagonal fill.
+
+The rule exists because placeholder colour is always arbitrary. A violet card, a blue logo
+tile and a rainbow avatar row assert a brand the composition does not have; across 250 items
+the same three arbitrary hues become the catalog's identity instead of the author's. Value
+says everything colour was saying here, and says it truthfully.
+
+## The one rule
+
+> Placeholder content carries no hue. It is built from four alpha steps of the composition's
+> own ink over the composition's own ground, plus a hairline. Accent marks one element per
+> composition, and never a placeholder.
+
+## The ramp
+
+Four fill steps and a hairline. All of them are the ink at an alpha, so the ramp inverts for
+free on dark themes and needs no second table.
+
+| Step   | Ink alpha | What it is for                                                               |
+| ------ | --------- | ---------------------------------------------------------------------------- |
+| `ink`  | 100%      | Real content: headline, number, label. Not placeholder.                      |
+| `L1`   | 72%       | The subject. Chart bars, a filled logo mark, a play glyph, a front avatar.   |
+| `L2`   | 45%       | Support. A comparison series, avatars behind the front one, secondary icons. |
+| `L3`   | 18%       | Media fill and skeleton text lines. "Content lives here."                    |
+| `L4`   | 8%        | Recessed plate interiors. The tray a card sits in.                           |
+| `hair` | 14%       | Every 1px boundary. Replaces the separation a gradient edge was doing.       |
+
+Write them the way the file already writes colour:
+
+```css
+/* theme-token primitives (--fg / --surface available) */
+background: color-mix(in srgb, var(--fg, #f8fafc) 18%, transparent);
+
+/* fixed-palette ports (local --hf-ink, no theme tokens) */
+background: rgba(17, 24, 39, 0.18);
+```
+
+**Four steps, not eight.** Grays go muddy when adjacent steps sit close together, so every
+step is at least 1.6x the alpha of the one below it. Reaching for a fifth value is the signal
+that the layout, not the palette, needs the work. Snap to the nearest step instead.
+
+Contrast, measured against both shipped grounds (`neutral` light `#fcfcfd`, `bold` dark
+`#1b1230`): L1 is 7.7:1 / 8.9:1, L2 is 3.1:1 / 4.4:1, L3 and L4 are below 3:1 by design.
+Therefore **text never goes below L1**, and L2 is the floor for any graphic a viewer has to
+compare (a chart series, a state indicator). L3 and L4 are for surfaces only.
+
+## Depth without colour
+
+In priority order. Reach for the first one that works.
+
+1. **Value step.** Nothing sits on the same step as its ground. One full step of separation
+   minimum. This alone resolves most stacking.
+2. **Hairline.** `1px` of `hair` on every plate boundary. A border separates two surfaces more
+   cleanly than a gradient ever did, and survives video compression that eats a soft edge.
+3. **Negative space.** Padding is elevation. A plate with `--space-2` inside it reads as raised
+   without any fill difference at all.
+4. **Texture, at the finest grain only.** A `repeating-linear-gradient` at `L3`-and-below,
+   period 2-4px, achromatic. This is the one thing value cannot say: a flat gray rectangle
+   reads as an empty box, the same rectangle finely hatched reads as a surface with content on
+   it. Use it to mark media, nothing else.
+
+Shadows are allowed and must be achromatic and diffuse: `0 Npx 3Npx rgba(0,0,0,0.18)`. Never a
+coloured glow; a glow is an accent wearing a shadow's clothes.
+
+## Reading each kind in black and white
+
+A gray rectangle has to still say _screen_ and not _image_. Shape, aspect, glyph and texture
+carry the meaning that hue was carrying badly.
+
+| Kind            | Signature                                                                                                                                |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Screen / device | Device aspect + `--radius` + `hair` + scanline texture at L3 + inset vignette. The chrome is the signal; the fill is L3 and stays quiet. |
+| Video footage   | Screen signature plus a centred play triangle in a ring at L1. The glyph is what makes it video rather than a static screen.             |
+| Image           | 4:3 or 3:2 plate at L3 with a horizon-and-disc glyph at L2, offset toward a corner, never centred. Offset is what reads as "photo".      |
+| Card            | Plate at L4, `hair` border, two skeleton rules at L3 (100% and 62% width). Two rules of unequal length is the whole idiom.               |
+| Avatar / person | **Circle** at L2 with initials knocked out in the ground colour. Stacks differ by step (L1 front, L2, L3), never by hue.                 |
+| Logo / brand    | **Rounded square** at L1 with the mark knocked out in the ground colour. Every mark on the same step: a logo wall means "many, equal".   |
+| Chart series    | Flat fills. Primary series L1, comparison series L2, gridlines `hair`. Never a gradient inside a bar.                                    |
+| Text block      | Rounded rules at L3, widths 100 / 86 / 62%. The ragged right edge is what reads as prose.                                                |
+
+Circle means person, rounded square means app or brand. Keeping those two shapes distinct is
+what lets both live at the same value step without ambiguity.
+
+Why no gradient inside a chart bar: a vertical light-to-dark fill makes every bar lighter at
+its top, so the tallest bar reads _palest_ exactly where the eye lands to compare heights. The
+decoration contradicts the data. Flat fills are both plainer and more honest.
+
+## Accent
+
+The accent enum stays. `green` rides `--brand`, `blue` rides `--accent`, `violet` rides
+`--accent-2`, exactly as before, and every declared `accent` or `tone` variable keeps working
+unchanged. What changes is where accent is allowed to land:
+
+> Accent marks at most **one** element per composition, and only where the accent _is_ the
+> meaning: the selected tier, the current step, the figure a count-up lands on, the ink of a
+> stroke being drawn. Placeholder content is never accent-coloured.
+
+Fixed-palette ports have no theme tokens, so they get the accent through their own
+variable with a neutral fallback:
+
+```css
+/* was: --hf-accent: #2563eb; */
+--hf-accent: var(--accent, #18181b);
+```
+
+Unthemed, the item renders in pure black and white. Drop it into a themed composition and
+the author's accent lands on that one element and nowhere else. Where the accent is chosen by
+an enum, the lookup table maps to tokens, never to hex: `green` to `var(--brand, <neutral>)`,
+`blue` to `var(--accent, <neutral>)`, `violet` to `var(--accent-2, <neutral>)`. The enum's
+declared options and default are unchanged, so no mount breaks.
+
+"One element" means one role, not one node: an app mark repeated on three devices of the same
+mock is still one element.
+
+Killing accent outright was the alternative and it is worse. Accent is already load-bearing in
+exactly the cases where it is correct, and it is the only hook an author has for their own
+brand; removing it would push those cases into value tricks for a job one hue does better with
+one element. The failure was never that accent existed, it was that accent had become the
+default fill for every placeholder. Capping it at one element fixes the failure with no
+variable migration.
+
+## Gradients that stay
+
+The ban is on **hue-carrying fills**, not on the CSS function. These are material, not
+placeholder, and flattening them breaks the thing the item exists to do:
+
+- **Physical surfaces** — device bezels, brushed metal, glass, a screen's inner vignette.
+- **Sheens and sweeps** — `linear-gradient(90deg, transparent, rgba(255,255,255,0.75), transparent)`
+  driven across an element. That is motion, not decoration.
+- **Scrims and vignettes** — `rgba(0,0,0,α)` ramps that buy text contrast over media.
+- **Effects whose subject is the gradient** — aurora, liquid glass, chromatic aberration,
+  grain fields, shader transitions. The gradient is the product.
+
+All four are achromatic or physically motivated. If a gradient is neither, it is placeholder
+slop and it goes.
+
+## Checklist
+
+- [ ] No `#7c3aed`, `#2563eb`, `#6366f1`, `#8b5cf6`, `#a855f7`, `#4f46e5` anywhere in the item.
+- [ ] Every placeholder fill is `ink` at 72 / 45 / 18 / 8 / 14 percent, and nothing else.
+- [ ] At most one accent-coloured element, and it means something.
+- [ ] Text sits at L1 or above; L3 and L4 carry no text.
+- [ ] Every remaining gradient is a surface, a sweep, a scrim, or the effect itself.
+- [ ] `hyperframes check` passes, and a rendered frame was looked at.

package/skills/hyperframes-registry/references/templates.md

@@ -0,0 +1,417 @@
+# Contribute Templates
+
+Copy-paste starter templates for each component type. These embed the proven patterns that pass `lint` and `check`.
+
+## Caption Template
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800;900&display=swap"
+      rel="stylesheet"
+    />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      *,
+      *::before,
+      *::after {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      body {
+        background: #111;
+        overflow: hidden;
+      }
+      #root-BLOCKNAME {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #111;
+      }
+      .cap-container {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+      .cg {
+        position: absolute;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 32px;
+        max-width: 1700px;
+        overflow: visible;
+        opacity: 0;
+        visibility: hidden;
+      }
+      .cw {
+        font-family: "Montserrat", sans-serif;
+        font-weight: 900;
+        font-size: 128px;
+        color: #ffffff;
+        text-transform: uppercase;
+        line-height: 1;
+        display: inline-block;
+        -webkit-text-stroke: 3px rgba(0, 0, 0, 0.8);
+        paint-order: stroke fill;
+        text-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root-BLOCKNAME"
+      data-composition-id="BLOCKNAME"
+      data-start="0"
+      data-duration="9"
+      data-width="1920"
+      data-height="1080"
+    >
+      <div class="cap-container" id="cc-BLOCKNAME"></div>
+      <div
+        id="drv-BLOCKNAME"
+        class="clip"
+        data-start="0"
+        data-duration="9"
+        data-track-index="0"
+        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
+      ></div>
+    </div>
+    <script>
+      (function () {
+        window.__timelines = window.__timelines || {};
+
+        // REPLACE with actual transcript data
+        var WORDS = [
+          { text: "Welcome", start: 0.3, end: 0.65 },
+          { text: "to", start: 0.65, end: 0.8 },
+          { text: "the", start: 0.8, end: 0.95 },
+          { text: "future", start: 0.95, end: 1.4 },
+          // ... add all words
+        ];
+
+        var GROUPS = [
+          { start: 0.3, end: 1.3, wordStart: 0, wordEnd: 3, text: "Welcome to the future" },
+          // ... add all groups
+        ];
+
+        var container = document.getElementById("cc-BLOCKNAME");
+
+        GROUPS.forEach(function (g, gi) {
+          var groupEl = document.createElement("div");
+          groupEl.id = "PREFIX-cg-" + gi;
+          groupEl.className = "cg";
+
+          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
+            var wordEl = document.createElement("span");
+            wordEl.id = "PREFIX-cw-" + wi;
+            wordEl.className = "cw";
+            wordEl.textContent = WORDS[wi].text;
+            groupEl.appendChild(wordEl);
+          }
+
+          // Pretext overflow prevention
+          if (window.__hyperframes && window.__hyperframes.fitTextFontSize) {
+            var _fit = window.__hyperframes.fitTextFontSize(g.text.toUpperCase(), {
+              fontFamily: "Montserrat",
+              fontWeight: 900,
+              maxWidth: 1550,
+              baseFontSize: 128,
+              minFontSize: 48,
+            });
+            if (_fit.fontSize < 128) {
+              for (var _fi = 0; _fi < groupEl.children.length; _fi++) {
+                groupEl.children[_fi].style.fontSize = _fit.fontSize + "px";
+              }
+            }
+          }
+          container.appendChild(groupEl);
+        });
+
+        var tl = gsap.timeline({ paused: true });
+
+        GROUPS.forEach(function (g, gi) {
+          var groupEl = document.getElementById("PREFIX-cg-" + gi);
+
+          // SHOW — set opacity to 1 (never use tl.from with opacity:0 here)
+          tl.set(groupEl, { opacity: 1, visibility: "visible" }, g.start);
+
+          // ENTRANCE — customize this per style
+          tl.from(groupEl, { scale: 1.3, duration: 0.15, ease: "back.out(2)" }, g.start);
+
+          // KARAOKE — highlight each word
+          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
+            var wordEl = document.getElementById("PREFIX-cw-" + wi);
+            tl.to(wordEl, { color: "#FFD700", scale: 1.1, duration: 0.06 }, WORDS[wi].start);
+            tl.to(wordEl, { color: "#FFFFFF", scale: 1, duration: 0.08 }, WORDS[wi].end);
+          }
+
+          // EXIT
+          tl.to(groupEl, { opacity: 0, scale: 0.9, duration: 0.1 }, g.end - 0.1);
+
+          // HARD KILL (mandatory)
+          tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end);
+        });
+
+        window.__timelines["BLOCKNAME"] = tl;
+      })();
+    </script>
+  </body>
+</html>
+```
+
+**Replace checklist:**
+
+- `BLOCKNAME` → your block name (e.g., `cap-swoosh`)
+- `PREFIX` → short unique prefix for IDs (e.g., `sw`)
+- Font family, weight, size → your style's typography
+- Entrance animation → your style's entrance
+- Karaoke highlight → your style's active word treatment
+- Colors → your style's palette
+
+---
+
+## VFX Template
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>
+    <style>
+      *,
+      *::before,
+      *::after {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      body {
+        background: #030308;
+        overflow: hidden;
+      }
+      #root-BLOCKNAME {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #030308;
+      }
+      #canvas-BLOCKNAME {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 1920px;
+        height: 1080px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root-BLOCKNAME"
+      data-composition-id="BLOCKNAME"
+      data-start="0"
+      data-duration="10"
+      data-width="1920"
+      data-height="1080"
+    >
+      <canvas id="canvas-BLOCKNAME" width="1920" height="1080"></canvas>
+      <div
+        id="drv-BLOCKNAME"
+        class="clip"
+        data-start="0"
+        data-duration="10"
+        data-track-index="0"
+        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
+      ></div>
+    </div>
+    <script>
+      (function () {
+        window.__timelines = window.__timelines || {};
+
+        // Seeded PRNG — NEVER use Math.random()
+        function mulberry32(a) {
+          return function () {
+            a |= 0;
+            a = (a + 0x6d2b79f5) | 0;
+            var t = Math.imul(a ^ (a >>> 15), 1 | a);
+            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+          };
+        }
+        var rng = mulberry32(42);
+
+        var W = 1920,
+          H = 1080;
+        var canvas = document.getElementById("canvas-BLOCKNAME");
+        var renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
+        renderer.setSize(W, H);
+        renderer.setPixelRatio(1);
+        renderer.toneMapping = THREE.ACESFilmicToneMapping;
+        renderer.toneMappingExposure = 1.1;
+
+        var scene = new THREE.Scene();
+        scene.background = new THREE.Color(0x030308);
+        var camera = new THREE.PerspectiveCamera(50, W / H, 0.1, 100);
+        camera.position.set(0, 0, 8);
+
+        // YOUR SCENE SETUP HERE
+        // - lights
+        // - geometry
+        // - materials
+
+        // State proxy — GSAP animates this, render reads it
+        var st = {
+          rotY: 0,
+          camZ: 8,
+          // add your animated properties
+        };
+
+        var tl = gsap.timeline({ paused: true });
+
+        // YOUR TWEENS HERE
+        tl.to(st, { rotY: Math.PI * 2, duration: 10, ease: "none" }, 0);
+
+        window.__timelines["BLOCKNAME"] = tl;
+
+        function renderScene() {
+          // Apply state to Three.js objects
+          camera.position.z = st.camZ;
+          // mesh.rotation.y = st.rotY;
+
+          renderer.render(scene, camera);
+        }
+
+        // Render via onUpdate — NO requestAnimationFrame
+        tl.eventCallback("onUpdate", renderScene);
+        renderScene();
+      })();
+    </script>
+  </body>
+</html>
+```
+
+**Replace checklist:**
+
+- `BLOCKNAME` → your block name (e.g., `vfx-chrome-blob`)
+- Scene setup → your geometry, lights, materials
+- State proxy → your animated properties
+- Tweens → your animation timeline
+- renderScene → apply state to your Three.js objects
+
+---
+
+## registry-item.json Templates
+
+**For blocks:**
+
+```json
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "BLOCKNAME",
+  "type": "hyperframes:block",
+  "title": "Human-Readable Title",
+  "description": "One sentence: what it does and who uses it",
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 10,
+  "tags": ["category", "subcategory"],
+  "files": [
+    {
+      "path": "BLOCKNAME.html",
+      "target": "compositions/BLOCKNAME.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
+```
+
+**For components** (no `dimensions` or `duration`):
+
+```json
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "COMPONENTNAME",
+  "type": "hyperframes:component",
+  "title": "Human-Readable Title",
+  "description": "One sentence: what it does",
+  "tags": ["category"],
+  "files": [
+    {
+      "path": "COMPONENTNAME.html",
+      "target": "compositions/components/COMPONENTNAME.html",
+      "type": "hyperframes:snippet"
+    }
+  ]
+}
+```
+
+Tags by category:
+
+- Captions: `captions`, `viral`, `professional`, `karaoke`, `minimal`
+- VFX: `three-js`, `particles`, `shader`, `gpu`
+- Transitions: `transition`, `shader`, `wipe`, `dissolve`
+- Blocks: `lower-third`, `social`, `title-card`, `data-viz`
+- Components: `effect`, `overlay`, `text-treatment`
+
+---
+
+## Component Template
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      *,
+      *::before,
+      *::after {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      body {
+        background: transparent;
+        overflow: hidden;
+      }
+      .COMPNAME-wrap {
+        position: absolute;
+        inset: 0;
+        overflow: hidden;
+        pointer-events: none;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="COMPNAME-wrap">
+      <!-- Your reusable effect/overlay here -->
+    </div>
+    <script>
+      (function () {
+        // Component snippet — no data-composition-id, no __timelines.
+        // The parent composition controls timing.
+        // Keep all class names and IDs prefixed with COMPNAME.
+      })();
+    </script>
+  </body>
+</html>
+```
+
+**Replace checklist:**
+
+- `COMPNAME` → your component name (e.g., `shimmer-sweep`)
+- Background should be `transparent` so it overlays cleanly
+- No `data-composition-id` or `window.__timelines` — the parent owns timing

package/skills/hyperframes-registry/references/wiring-blocks.md

@@ -58,34 +58,4 @@ To position a block in a specific area of the screen, add CSS:
 
 ## Multiple blocks
 
-Include multiple blocks sequentially or overlapping:
-
-```html
-<div
-  data-composition-id="data-chart"
-  data-composition-src="compositions/data-chart.html"
-  data-start="0"
-  data-duration="15"
-  data-track-index="1"
-  data-width="1920"
-  data-height="1080"
-></div>
-<div
-  data-composition-id="flowchart"
-  data-composition-src="compositions/flowchart.html"
-  data-start="15"
-  data-duration="12"
-  data-track-index="1"
-  data-width="1920"
-  data-height="1080"
-></div>
-<div
-  data-composition-id="logo-outro"
-  data-composition-src="compositions/logo-outro.html"
-  data-start="27"
-  data-duration="6"
-  data-track-index="1"
-  data-width="1920"
-  data-height="1080"
-></div>
-```
+Add additional `<div data-composition-src="...">` siblings with non-overlapping or overlapping `data-start` values — each block's timeline is independent and seeked in sync by the runtime.

package/skills/hyperframes-registry/references/wiring-components.md

@@ -29,45 +29,7 @@ Then paste the CSS keyframes and `.grain-texture` rule into your styles. No GSAP
 
 ## Example: shimmer-sweep (needs timeline integration)
 
-Wrap target elements, paste CSS and JS, then drive the sweep from your timeline:
-
-```js
-tl.fromTo(
-  ".shimmer-sweep-target",
-  {
-    "--shimmer-pos": "-20%",
-  },
-  {
-    "--shimmer-pos": "120%",
-    duration: 1.2,
-    ease: "power2.inOut",
-    stagger: 0.15,
-  },
-  2.0,
-);
-```
-
-## Example: grid-pixelate-wipe (scene transition)
-
-Paste the overlay HTML and CSS, then drive `.grid-cell` scale in your timeline:
-
-```js
-// Cover screen
-tl.to(
-  ".grid-cell",
-  { scale: 1, duration: 0.6, stagger: { amount: 0.6, from: "center" }, ease: "power2.inOut" },
-  5.0,
-);
-// Swap scenes
-tl.set("#scene-a", { opacity: 0 }, 5.6);
-tl.set("#scene-b", { opacity: 1 }, 5.6);
-// Reveal
-tl.to(
-  ".grid-cell",
-  { scale: 0, duration: 0.6, stagger: { amount: 0.6, from: "edges" }, ease: "power2.inOut" },
-  5.6,
-);
-```
+See `examples/add-component.md` for the full shimmer-sweep walkthrough (HTML wrapping, CSS, JS setup, and timeline call).
 
 ## Key principles