takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/hyperframes-registry/examples/add-component.md

@@ -1,73 +1,73 @@
-# Worked Example: Adding a Component
-
-## Scenario
-
-User wants to add a shimmer light sweep effect to their title text.
-
-## Steps
-
-### 1. Install the component
-
-```bash
-hyperframes add shimmer-sweep
-```
-
-### 2. Read the snippet
-
-Open `compositions/components/shimmer-sweep.html` and read the comment header.
-
-### 3. Wire into your composition
-
-**HTML** — wrap target elements:
-
-```html
-<div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)">
-  <h1 class="title">AI-Powered Video</h1>
-</div>
-```
-
-**CSS** — paste the `.shimmer-sweep-target` and `.shimmer-mask` rules from the snippet.
-
-**JS** — paste the auto-injection script (before timeline code):
-
-```js
-document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
-  if (!el.querySelector(".shimmer-mask")) {
-    const mask = document.createElement("div");
-    mask.className = "shimmer-mask";
-    el.appendChild(mask);
-  }
-});
-```
-
-**Timeline** — add the sweep:
-
-```js
-tl.fromTo(
-  ".shimmer-sweep-target",
-  {
-    "--shimmer-pos": "-20%",
-  },
-  {
-    "--shimmer-pos": "120%",
-    duration: 1.2,
-    ease: "power2.inOut",
-    stagger: 0.15,
-  },
-  1.5,
-);
-```
-
-### 4. Lint and preview
-
-```bash
-hyperframes lint
-hyperframes preview
-```
-
-### 5. Customize
-
-- `--shimmer-color`: highlight color per element
-- `--shimmer-width`: light band width (default 20%)
-- `--shimmer-angle`: sweep direction (default 120deg)
-- Timeline `duration`, `ease`, `stagger`: control speed and feel
+# Worked Example: Adding a Component
+
+## Scenario
+
+User wants to add a shimmer light sweep effect to their title text.
+
+## Steps
+
+### 1. Install the component
+
+```bash
+hyperframes add shimmer-sweep
+```
+
+### 2. Read the snippet
+
+Open `compositions/components/shimmer-sweep.html` and read the comment header.
+
+### 3. Wire into your composition
+
+**HTML** — wrap target elements:
+
+```html
+<div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)">
+  <h1 class="title">AI-Powered Video</h1>
+</div>
+```
+
+**CSS** — paste the `.shimmer-sweep-target` and `.shimmer-mask` rules from the snippet.
+
+**JS** — paste the auto-injection script (before timeline code):
+
+```js
+document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
+  if (!el.querySelector(".shimmer-mask")) {
+    const mask = document.createElement("div");
+    mask.className = "shimmer-mask";
+    el.appendChild(mask);
+  }
+});
+```
+
+**Timeline** — add the sweep:
+
+```js
+tl.fromTo(
+  ".shimmer-sweep-target",
+  {
+    "--shimmer-pos": "-20%",
+  },
+  {
+    "--shimmer-pos": "120%",
+    duration: 1.2,
+    ease: "power2.inOut",
+    stagger: 0.15,
+  },
+  1.5,
+);
+```
+
+### 4. Lint and preview
+
+```bash
+hyperframes lint
+hyperframes preview
+```
+
+### 5. Customize
+
+- `--shimmer-color`: highlight color per element
+- `--shimmer-width`: light band width (default 20%)
+- `--shimmer-angle`: sweep direction (default 120deg)
+- Timeline `duration`, `ease`, `stagger`: control speed and feel

package/assets/.agent/skills/hyperframes-registry/references/contributing.md

@@ -1,166 +1,166 @@
-# Contributing a Block or Component to the Registry
-
-Guide the user from idea to merged PR for a new registry block or component.
-
-## Workflow
-
-```
-1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
-```
-
-### Step 1: Clarify
-
-Ask what they're building. The registry has two item types:
-
-- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
-- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.
-
-Then ask:
-
-- One-sentence description of the effect
-- Visual reference (URL, screenshot, or description)
-- Who uses this and when?
-
-### Step 2: Scaffold
-
-Create the registry structure:
-
-**For blocks:**
-
-```
-registry/blocks/{block-name}/
-  {block-name}.html
-  registry-item.json
-```
-
-**For components:**
-
-```
-registry/components/{component-name}/
-  {component-name}.html
-  registry-item.json
-```
-
-**Naming convention:**
-
-| Item name        | ID prefix | Example IDs            |
-| ---------------- | --------- | ---------------------- |
-| `cap-hormozi`    | `hz`      | `hz-cg-0`, `hz-cw-3`   |
-| `cap-typewriter` | `tw`      | `tw-cg-0`, `tw-ch-0-5` |
-| `vfx-chrome`     | `vc`      | `vc-canvas`            |
-
-Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.
-
-**registry-item.json** — use the canonical templates in [templates.md](templates.md) (block and component variants, both with all required fields).
-
-### Step 3: Build
-
-Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.
-
-#### Caption blocks
-
-**Non-negotiable caption rules:**
-
-- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
-- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
-- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group
-- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
-- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
-- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.
-
-**Per-character animation** (typewriter, scramble):
-
-- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`
-- Stagger via `tl.set` at computed intervals from word timestamps
-- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)
-
-**Positioning variants:**
-
-- Centered: `display: flex; align-items: center; justify-content: center;`
-- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
-- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`
-
-#### VFX blocks (Three.js)
-
-- Use `three@0.147.0` from CDN (global script)
-- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
-- State proxy pattern: GSAP animates plain JS object, render function reads it
-- Seeded PRNG (`mulberry32`) for randomness
-
-#### All types
-
-- `data-composition-id` MUST match `window.__timelines["id"]`
-- All element IDs prefixed with block abbreviation
-- `gsap.timeline({ paused: true })` — always paused
-- No `Math.random()`, no `Date.now()`
-
-### Step 4: Validate
-
-```bash
-hyperframes lint                    # 0 errors required
-hyperframes validate --no-contrast  # 0 console errors required
-```
-
-### Step 5: Preview
-
-```bash
-# Render preview video
-hyperframes render -o preview.mp4
-
-# Snapshot for visual QA
-hyperframes snapshot --at "1.0,3.0,5.0,7.0"
-
-# Publish to hyperframes.dev for review
-npx hyperframes publish
-```
-
-**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:
-
-- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
-- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.
-
-### Step 6: Ship
-
-**All steps are required. Missing any one produces a broken catalog entry.**
-
-`{kind}` is `blocks` or `components` depending on what you built in Step 1.
-
-```bash
-# 1. Create branch
-git checkout -b feat/registry-{name}
-
-# 2. Format HTML
-npx oxfmt registry/{kind}/{name}/*.html
-
-# 3. Update registry/registry.json — add entry to the "items" array:
-#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")
-
-# 4. Generate catalog docs page
-npx tsx scripts/generate-catalog-pages.ts
-
-# 5. Publish to hyperframes.dev so reviewers can preview
-npx hyperframes publish
-
-# 6. Stage everything
-git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
-
-# 7. Commit
-git commit -m "feat(registry): add {name} — {one sentence}"
-
-# 8. Push and open PR with hyperframes.dev link
-git push origin feat/registry-{name}
-gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
-```
-
-**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.
-
-## Quality Gate
-
-- [ ] `hyperframes lint` → 0 errors
-- [ ] `hyperframes validate` → 0 console errors
-- [ ] `npx oxfmt --check` passes
-- [ ] `registry/registry.json` updated with new entry
-- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
-- [ ] `npx hyperframes publish` run (claim your project URL)
-- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
-- [ ] All IDs unique and prefixed
+# Contributing a Block or Component to the Registry
+
+Guide the user from idea to merged PR for a new registry block or component.
+
+## Workflow
+
+```
+1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
+```
+
+### Step 1: Clarify
+
+Ask what they're building. The registry has two item types:
+
+- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
+- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.
+
+Then ask:
+
+- One-sentence description of the effect
+- Visual reference (URL, screenshot, or description)
+- Who uses this and when?
+
+### Step 2: Scaffold
+
+Create the registry structure:
+
+**For blocks:**
+
+```
+registry/blocks/{block-name}/
+  {block-name}.html
+  registry-item.json
+```
+
+**For components:**
+
+```
+registry/components/{component-name}/
+  {component-name}.html
+  registry-item.json
+```
+
+**Naming convention:**
+
+| Item name        | ID prefix | Example IDs            |
+| ---------------- | --------- | ---------------------- |
+| `cap-hormozi`    | `hz`      | `hz-cg-0`, `hz-cw-3`   |
+| `cap-typewriter` | `tw`      | `tw-cg-0`, `tw-ch-0-5` |
+| `vfx-chrome`     | `vc`      | `vc-canvas`            |
+
+Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.
+
+**registry-item.json** — use the canonical templates in [templates.md](templates.md) (block and component variants, both with all required fields).
+
+### Step 3: Build
+
+Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.
+
+#### Caption blocks
+
+**Non-negotiable caption rules:**
+
+- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
+- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
+- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group
+- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
+- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
+- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.
+
+**Per-character animation** (typewriter, scramble):
+
+- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`
+- Stagger via `tl.set` at computed intervals from word timestamps
+- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)
+
+**Positioning variants:**
+
+- Centered: `display: flex; align-items: center; justify-content: center;`
+- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
+- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`
+
+#### VFX blocks (Three.js)
+
+- Use `three@0.147.0` from CDN (global script)
+- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
+- State proxy pattern: GSAP animates plain JS object, render function reads it
+- Seeded PRNG (`mulberry32`) for randomness
+
+#### All types
+
+- `data-composition-id` MUST match `window.__timelines["id"]`
+- All element IDs prefixed with block abbreviation
+- `gsap.timeline({ paused: true })` — always paused
+- No `Math.random()`, no `Date.now()`
+
+### Step 4: Validate
+
+```bash
+hyperframes lint                    # 0 errors required
+hyperframes validate --no-contrast  # 0 console errors required
+```
+
+### Step 5: Preview
+
+```bash
+# Render preview video
+hyperframes render -o preview.mp4
+
+# Snapshot for visual QA
+hyperframes snapshot --at "1.0,3.0,5.0,7.0"
+
+# Publish to hyperframes.dev for review
+npx hyperframes publish
+```
+
+**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:
+
+- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
+- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.
+
+### Step 6: Ship
+
+**All steps are required. Missing any one produces a broken catalog entry.**
+
+`{kind}` is `blocks` or `components` depending on what you built in Step 1.
+
+```bash
+# 1. Create branch
+git checkout -b feat/registry-{name}
+
+# 2. Format HTML
+npx oxfmt registry/{kind}/{name}/*.html
+
+# 3. Update registry/registry.json — add entry to the "items" array:
+#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")
+
+# 4. Generate catalog docs page
+npx tsx scripts/generate-catalog-pages.ts
+
+# 5. Publish to hyperframes.dev so reviewers can preview
+npx hyperframes publish
+
+# 6. Stage everything
+git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
+
+# 7. Commit
+git commit -m "feat(registry): add {name} — {one sentence}"
+
+# 8. Push and open PR with hyperframes.dev link
+git push origin feat/registry-{name}
+gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
+```
+
+**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.
+
+## Quality Gate
+
+- [ ] `hyperframes lint` → 0 errors
+- [ ] `hyperframes validate` → 0 console errors
+- [ ] `npx oxfmt --check` passes
+- [ ] `registry/registry.json` updated with new entry
+- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
+- [ ] `npx hyperframes publish` run (claim your project URL)
+- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
+- [ ] All IDs unique and prefixed

package/assets/.agent/skills/hyperframes-registry/references/demo-html-pattern.md

@@ -1,54 +1,54 @@
-# The demo.html Convention
-
-## Why components ship demo.html
-
-Every component in the registry ships a companion `demo.html` file alongside its snippet. The demo serves two purposes:
-
-1. **Preview fixture** — the CI preview pipeline renders the demo to generate thumbnail images and preview videos for the catalog docs page.
-
-2. **Usage example** — the demo shows the component effect applied to representative content, serving as a working reference.
-
-## Demo structure
-
-A demo is a complete, standalone HTML composition:
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=1920, height=1080" />
-    <title>Component Name — Demo</title>
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <style>
-      /* reset + canvas size */
-    </style>
-  </head>
-  <body>
-    <div data-composition-id="<name>-demo" data-width="1920" data-height="1080" data-duration="N">
-      <!-- Demo content showing the effect -->
-      <!-- Component snippet inlined here -->
-    </div>
-    <script>
-      // GSAP timeline demonstrating the effect
-      window.__timelines = window.__timelines || {};
-      window.__timelines["<name>-demo"] = tl;
-    </script>
-  </body>
-</html>
-```
-
-Key conventions:
-
-- `data-composition-id` is `<component-name>-demo` to avoid collisions
-- The demo is self-contained — all CSS and JS from the snippet is inlined
-- The GSAP timeline is registered on `window.__timelines`
-- Duration should be long enough to showcase the effect (typically 5-8 seconds)
-
-## Blocks don't need demo.html
-
-Blocks are already standalone compositions that can be rendered directly. Only components need the demo wrapper.
-
-## Demos are not installed
-
-The `demo.html` is NOT installed by `hyperframes add` — it exists only in the registry for preview generation and as a reference.
+# The demo.html Convention
+
+## Why components ship demo.html
+
+Every component in the registry ships a companion `demo.html` file alongside its snippet. The demo serves two purposes:
+
+1. **Preview fixture** — the CI preview pipeline renders the demo to generate thumbnail images and preview videos for the catalog docs page.
+
+2. **Usage example** — the demo shows the component effect applied to representative content, serving as a working reference.
+
+## Demo structure
+
+A demo is a complete, standalone HTML composition:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Component Name — Demo</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      /* reset + canvas size */
+    </style>
+  </head>
+  <body>
+    <div data-composition-id="<name>-demo" data-width="1920" data-height="1080" data-duration="N">
+      <!-- Demo content showing the effect -->
+      <!-- Component snippet inlined here -->
+    </div>
+    <script>
+      // GSAP timeline demonstrating the effect
+      window.__timelines = window.__timelines || {};
+      window.__timelines["<name>-demo"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Key conventions:
+
+- `data-composition-id` is `<component-name>-demo` to avoid collisions
+- The demo is self-contained — all CSS and JS from the snippet is inlined
+- The GSAP timeline is registered on `window.__timelines`
+- Duration should be long enough to showcase the effect (typically 5-8 seconds)
+
+## Blocks don't need demo.html
+
+Blocks are already standalone compositions that can be rendered directly. Only components need the demo wrapper.
+
+## Demos are not installed
+
+The `demo.html` is NOT installed by `hyperframes add` — it exists only in the registry for preview generation and as a reference.