takomi 2.1.41 → 2.1.43

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

@@ -0,0 +1,61 @@
+# Wiring Blocks
+
+Blocks are standalone compositions with their own `data-composition-id`, dimensions, duration, and GSAP timeline. Include them in a host composition using `data-composition-src` on a `<div>`.
+
+## Basic wiring
+
+After `hyperframes add data-chart`, wire it into your `index.html`:
+
+```html
+<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
+  <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>
+
+  <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
+  <div
+    data-composition-id="data-chart"
+    data-composition-src="compositions/data-chart.html"
+    data-start="2"
+    data-duration="15"
+    data-track-index="1"
+    data-width="1920"
+    data-height="1080"
+  ></div>
+</div>
+```
+
+## Required attributes
+
+| Attribute              | Description                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `data-composition-src` | Path to the block HTML file (relative to index.html)                 |
+| `data-composition-id`  | Unique ID matching the block's internal composition ID               |
+| `data-start`           | When the block appears in the host timeline (seconds)                |
+| `data-duration`        | How long the block plays (seconds, at most the block's own duration) |
+| `data-track-index`     | Layer ordering — higher numbers render in front                      |
+| `data-width`           | Block canvas width (match the block's dimensions)                    |
+| `data-height`          | Block canvas height (match the block's dimensions)                   |
+
+## Timeline coordination
+
+The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its `window.__timelines` registration, and seeks the block in sync with the host, offset by `data-start`. You do NOT need to reference the block's timeline in your host's GSAP code.
+
+## Positioning blocks
+
+To position a block in a specific area of the screen, add CSS:
+
+```html
+<div
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-start="2"
+  data-duration="15"
+  data-track-index="1"
+  data-width="1920"
+  data-height="1080"
+  style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
+></div>
+```
+
+## Multiple blocks
+
+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/assets/.agent/skills/hyperframes-registry/references/wiring-components.md

@@ -0,0 +1,39 @@
+# Wiring Components
+
+Components are effect snippets — HTML, CSS, and optionally JS that you merge directly into an existing composition. Unlike blocks, components have no standalone timeline; they participate in the host composition's timeline.
+
+## General process
+
+1. Run `hyperframes add <component-name>`
+2. Open the installed file (e.g., `compositions/components/grain-overlay.html`)
+3. Read the comment header for usage instructions
+4. Copy the parts into your host composition:
+   - **HTML elements** — inside your `<div data-composition-id="...">`
+   - **CSS styles** — into your composition's `<style>` block
+   - **JS setup** — into your composition's `<script>`, before your timeline code
+   - **Timeline calls** — into your GSAP timeline (if the component exposes them)
+
+## Example: grain-overlay (CSS-only, no timeline integration)
+
+```html
+<!-- Paste the overlay div into your composition -->
+<div
+  id="grain-overlay"
+  style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;"
+>
+  <div class="grain-texture"></div>
+</div>
+```
+
+Then paste the CSS keyframes and `.grain-texture` rule into your styles. No GSAP timeline calls needed — the grain animates via CSS `@keyframes`.
+
+## Example: shimmer-sweep (needs timeline integration)
+
+See `examples/add-component.md` for the full shimmer-sweep walkthrough (HTML wrapping, CSS, JS setup, and timeline call).
+
+## Key principles
+
+- Components inherit the host composition's dimensions and duration
+- Place component HTML at the appropriate z-index relative to your content
+- Read the comment header in each snippet for customizable values
+- Run `hyperframes lint` after wiring to catch structural issues

package/assets/.agent/skills/media-use/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: media-use
+description: Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.
+---
+
+# media-use
+
+Resolve media needs into frozen local files. One verb, four types, zero context noise.
+
+## When to use
+
+Call `resolve` whenever a composition needs media — background music, sound effects, images, or icons. media-use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk.
+
+## Resolve
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
+```
+
+Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
+
+### Types
+
+| Type    | What it finds       | Provider                                 |
+| ------- | ------------------- | ---------------------------------------- |
+| `bgm`   | Background music    | HeyGen audio catalog (10k+ tracks)       |
+| `sfx`   | Sound effects       | Bundled 19-file library + HeyGen catalog |
+| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors)       |
+| `icon`  | Icons, logos        | HeyGen asset search (type=icon)          |
+
+### Examples
+
+```bash
+# Background music
+node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
+# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
+
+# Sound effect
+node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
+# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
+
+# Image
+node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
+# → resolved image_001 → .media/images/image_001.jpg (image)
+
+# Icon
+node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
+# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
+```
+
+### Flags
+
+| Flag            | Description                                |
+| --------------- | ------------------------------------------ |
+| `--type, -t`    | Media type: bgm, sfx, image, icon          |
+| `--intent, -i`  | What you need (natural language)           |
+| `--entity, -e`  | Entity name for cache matching (optional)  |
+| `--project, -p` | Project directory (default: .)             |
+| `--adopt`       | Bulk-import existing assets/ into manifest |
+| `--json`        | Output JSON instead of one-line result     |
+
+## How it works
+
+1. Check project `.media/manifest.jsonl` for exact-prompt match
+2. Scan existing `assets/` directory for unregistered files matching the need
+3. Check global cache `~/.media/` for reusable asset
+4. Search via provider (HeyGen audio catalog, HeyGen asset search)
+5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`
+
+The agent gets back **one line**. Candidates, scores, provenance stay on disk.
+
+## Adopt existing projects
+
+Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
+# → adopted 9 assets from assets/
+#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
+#   image_001 → assets/images/avatar.jpg (image, 400×400)
+```
+
+`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
+
+## Reading the inventory
+
+After resolve or adopt, read `.media/index.md` for the full inventory:
+
+```
+# .media · 4 assets
+
+id         type   dur   dims       path                          description
+bgm_001    bgm    25s   —          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
+sfx_001    sfx    0.6s  —          .media/audio/sfx/sfx_001.mp3  whoosh
+image_001  image  —     1920×1080  .media/images/image_001.jpg   gradient tech background
+icon_001   icon   —     200×200    .media/images/icon_001.png    rocket
+```
+
+## Cross-project reuse
+
+Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at `~/.media/` — no re-download, no provider call. Promote an asset explicitly with `organize --promote <id>` to make it reusable across all projects.
+
+## Files
+
+- `.media/manifest.jsonl` — machine SSOT, one JSON record per line
+- `.media/index.md` — agent-readable table (id, type, dur, dims, path, description)
+- `~/.media/` — global cross-project reuse cache (content-addressed, SHA-256)
+
+## CLI tools used
+
+| Tool      | Purpose                                    | Required?     |
+| --------- | ------------------------------------------ | ------------- |
+| `ffprobe` | Probe duration, dimensions, codec on adopt | Yes           |
+| `heygen`  | Audio catalog, asset search                | For providers |
+
+Install the `heygen` CLI (single static binary, no runtime) and authenticate:
+
+```bash
+curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # installs latest to ~/.local/bin
+heygen update                                               # if already installed: needs >= v0.1.6
+export HEYGEN_API_KEY=<your-key>                            # or: heygen auth login --key <key>
+```
+
+Requires **heygen >= v0.1.6** — the providers tag requests with the allowlisted `--headers 'X-HeyGen-Client-Source: media-use'` flag, added in v0.1.6. `asset search` is a pre-launch command hidden from `heygen --help`, but it runs. Without a `heygen` on PATH (or a valid key) the providers print a one-line diagnostic to stderr and resolve falls through to "no provider could resolve".

package/assets/.agent/skills/media-use/scripts/eval.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+/**
+ * media-use eval — compare baseline (no media-use) vs. with media-use
+ * on real registry blocks. Produces an HTML report.
+ */
+
+import {
+  mkdtempSync,
+  cpSync,
+  rmSync,
+  readFileSync,
+  readdirSync,
+  existsSync,
+  writeFileSync,
+} from "node:fs";
+import { join, basename, resolve, dirname } from "node:path";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(SCRIPT_DIR, "..", "..", "..");
+const RESOLVE_SCRIPT = join(SCRIPT_DIR, "resolve.mjs");
+
+const TEST_BLOCKS = [
+  "registry/blocks/nyc-paris-flight",
+  "registry/blocks/macos-tahoe-liquid-glass",
+  "registry/blocks/blue-sweater-intro-video",
+  "registry/blocks/vpn-youtube-spot",
+  "registry/blocks/apple-money-count",
+  "registry/blocks/liquid-glass-notification",
+  "registry/blocks/instagram-follow",
+];
+
+// Run resolve.mjs with args as a literal argv array (no shell), so values
+// interpolated from manifest metadata (--intent prompt, --type) can't inject
+// shell. Mirrors the execFileSync fix in probe.mjs / heygen-search.mjs.
+function run(args, opts = {}) {
+  try {
+    return {
+      ok: true,
+      output: execFileSync(process.execPath, [RESOLVE_SCRIPT, ...args], {
+        encoding: "utf8",
+        timeout: 15000,
+        stdio: "pipe",
+        ...opts,
+      }).trim(),
+    };
+  } catch (err) {
+    return { ok: false, output: (err.stdout || "") + (err.stderr || ""), code: err.status };
+  }
+}
+
+function countAssetFiles(dir) {
+  const assetsDir = join(dir, "assets");
+  if (!existsSync(assetsDir)) return { count: 0, files: [] };
+  const files = [];
+  function walk(d, base = "") {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(join(d, e.name), rel);
+      else files.push(rel);
+    }
+  }
+  walk(assetsDir);
+  return { count: files.length, files };
+}
+
+function evalBlock(blockPath) {
+  const fullPath = join(REPO_ROOT, blockPath);
+  if (!existsSync(fullPath)) return null;
+
+  const name = basename(blockPath);
+  const tmp = mkdtempSync(join(tmpdir(), `mu-eval-${name}-`));
+
+  try {
+    cpSync(fullPath, tmp, { recursive: true });
+
+    // baseline: what the agent sees WITHOUT media-use
+    const baseline = countAssetFiles(tmp);
+    const htmlFiles = readdirSync(tmp).filter((f) => f.endsWith(".html"));
+
+    // parse compositions for asset references
+    const assetRefs = [];
+    for (const hf of htmlFiles) {
+      const html = readFileSync(join(tmp, hf), "utf8");
+      const srcMatches = html.matchAll(/src=["']([^"']+?)["']/g);
+      for (const m of srcMatches) {
+        const ref = m[1];
+        if (ref.startsWith("data:") || ref.startsWith("http")) continue;
+        assetRefs.push({ composition: hf, ref });
+      }
+      const urlMatches = html.matchAll(/url\(["']?([^"')]+?)["']?\)/g);
+      for (const m of urlMatches) {
+        const ref = m[1];
+        if (ref.startsWith("data:") || ref.startsWith("http") || ref.startsWith("#")) continue;
+        assetRefs.push({ composition: hf, ref });
+      }
+    }
+
+    // with media-use: run --adopt
+    const adoptResult = run(["--adopt", "--project", tmp, "--json"]);
+    let adopted = { ok: false, adopted: 0, assets: [] };
+    if (adoptResult.ok) {
+      try {
+        adopted = JSON.parse(adoptResult.output);
+      } catch {
+        /* */
+      }
+    }
+
+    // read the generated index
+    const indexPath = join(tmp, ".media", "index.md");
+    const indexContent = existsSync(indexPath)
+      ? readFileSync(indexPath, "utf8")
+      : "(no index generated)";
+
+    // read manifest for detail
+    const manifestPath = join(tmp, ".media", "manifest.jsonl");
+    const manifest = existsSync(manifestPath)
+      ? readFileSync(manifestPath, "utf8")
+          .trim()
+          .split("\n")
+          .map((l) => {
+            try {
+              return JSON.parse(l);
+            } catch {
+              return null;
+            }
+          })
+          .filter(Boolean)
+      : [];
+
+    // test resolve cache hit: try resolving something that was adopted
+    let resolveTest = null;
+    if (manifest.length > 0) {
+      const first = manifest[0];
+      const prompt = first.provenance?.prompt || first.description;
+      const r = run(["--type", first.type, "--intent", prompt, "--project", tmp, "--json"]);
+      if (r.ok) {
+        try {
+          resolveTest = JSON.parse(r.output);
+        } catch {
+          /* */
+        }
+      }
+    }
+
+    // test resolve miss: try resolving something that doesn't exist
+    const missResult = run([
+      "--type",
+      "bgm",
+      "--intent",
+      "nonexistent query xyz",
+      "--project",
+      tmp,
+      "--json",
+    ]);
+    let resolveMiss = null;
+    if (!missResult.ok) {
+      try {
+        resolveMiss = JSON.parse(missResult.output);
+      } catch {
+        /* */
+      }
+    }
+
+    // coverage: which composition refs are covered by the manifest
+    const manifestPaths = new Set(manifest.map((m) => m.path));
+    const coverage = assetRefs.map((r) => ({
+      ...r,
+      covered: manifestPaths.has(r.ref),
+    }));
+
+    return {
+      name,
+      baseline: { fileCount: baseline.count, files: baseline.files, htmlCount: htmlFiles.length },
+      compositions: htmlFiles,
+      assetRefs: coverage,
+      adopted: { count: adopted.adopted, assets: adopted.assets || [] },
+      index: indexContent,
+      manifest,
+      resolveTest,
+      resolveMiss,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function generateReport(results) {
+  const all = results.filter(Boolean);
+  const passed = all.filter((r) => r.adopted.count > 0);
+
+  const rows = results
+    .filter(Boolean)
+    .map((r) => {
+      const hasMetadata = r.manifest.some((m) => m.duration || m.width);
+      const cacheHit = r.resolveTest?._source === "cached";
+      const missHandled = r.resolveMiss?.ok === false;
+
+      return `<tr>
+        <td><strong>${r.name}</strong></td>
+        <td>${r.baseline.fileCount} files, ${r.baseline.htmlCount} comp${r.baseline.htmlCount === 1 ? "" : "s"}</td>
+        <td>${r.adopted.count} adopted</td>
+        <td>${hasMetadata ? "<span class='pass'>with metadata</span>" : "<span class='warn'>no metadata</span>"}</td>
+        <td>${cacheHit ? "<span class='pass'>cache hit</span>" : "<span class='warn'>no hit</span>"}</td>
+        <td>${missHandled ? "<span class='pass'>handled</span>" : "<span class='fail'>unexpected</span>"}</td>
+      </tr>`;
+    })
+    .join("\n");
+
+  const details = results
+    .filter(Boolean)
+    .filter((r) => r.adopted.count > 0)
+    .map((r) => {
+      const assetRows = r.manifest
+        .map((m) => {
+          const dur = m.duration != null ? `${m.duration}s` : "—";
+          const dims = m.width && m.height ? `${m.width}×${m.height}` : "—";
+          return `<tr><td>${m.id}</td><td>${m.type}</td><td>${dur}</td><td>${dims}</td><td class="path">${m.path}</td><td>${m.description || ""}</td></tr>`;
+        })
+        .join("\n");
+
+      const coveredCount = r.assetRefs.filter((c) => c.covered).length;
+      const totalRefs = r.assetRefs.length;
+      const coveragePct = totalRefs > 0 ? Math.round((coveredCount / totalRefs) * 100) : 100;
+
+      const refRows = r.assetRefs
+        .map(
+          (c) =>
+            `<tr><td class="path">${c.composition}</td><td class="path">${c.ref}</td><td>${c.covered ? "<span class='pass'>covered</span>" : "<span class='warn'>not in manifest</span>"}</td></tr>`,
+        )
+        .join("\n");
+
+      return `<div class="block-detail">
+        <h3>${r.name}</h3>
+        <p style="font-size:13px;color:var(--muted)">${r.compositions.length} composition${r.compositions.length === 1 ? "" : "s"}: ${r.compositions.join(", ")}</p>
+
+        <div class="comparison">
+          <div class="col">
+            <h4>Baseline (no media-use)</h4>
+            <p>Agent sees: ${r.baseline.fileCount} raw files in assets/<br>No metadata, no type info, no relationship to compositions.</p>
+            <pre class="file-list">${r.baseline.files.join("\n") || "(no assets)"}</pre>
+          </div>
+          <div class="col">
+            <h4>With media-use (after --adopt)</h4>
+            <p>Agent reads index.md — structured, typed, with metadata:</p>
+            <pre class="index">${escapeHtml(r.index)}</pre>
+          </div>
+        </div>
+
+        ${
+          totalRefs > 0
+            ? `<h4>Composition → asset coverage <span class="${coveragePct === 100 ? "pass" : "warn"}">${coveragePct}%</span> (${coveredCount}/${totalRefs} refs)</h4>
+        <table class="manifest">
+          <thead><tr><th>composition</th><th>asset reference</th><th>in manifest?</th></tr></thead>
+          <tbody>${refRows}</tbody>
+        </table>`
+            : ""
+        }
+
+        <h4>Manifest records</h4>
+        <table class="manifest">
+          <thead><tr><th>id</th><th>type</th><th>dur</th><th>dims</th><th>path</th><th>description</th></tr></thead>
+          <tbody>${assetRows}</tbody>
+        </table>
+      </div>`;
+    })
+    .join("\n");
+
+  return `<title>media-use eval report</title>
+<style>
+:root { --bg: #fafaf7; --text: #1b1b18; --muted: #7a756a; --accent: #0d7377; --good: #1a7a3a; --warn: #b45309; --fail: #dc2626; --border: #e8e5df; --surface: #fff; --mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace; --sans: system-ui, -apple-system, sans-serif; --serif: Georgia, serif }
+* { box-sizing: border-box; margin: 0 } body { background: var(--bg); color: var(--text); font-family: var(--serif); line-height: 1.6; font-size: 15px; padding: 40px 24px }
+.wrap { max-width: 1100px; margin: 0 auto }
+h1 { font-family: var(--sans); font-size: 28px; font-weight: 700; margin-bottom: 8px; letter-spacing: -.02em }
+h2 { font-family: var(--sans); font-size: 20px; font-weight: 650; margin: 32px 0 12px; letter-spacing: -.01em }
+h3 { font-family: var(--sans); font-size: 17px; font-weight: 650; margin: 24px 0 8px }
+h4 { font-family: var(--sans); font-size: 14px; font-weight: 600; margin: 16px 0 6px; color: var(--muted) }
+p { margin-bottom: 10px }
+.meta { font-family: var(--mono); font-size: 12px; color: var(--muted); margin-bottom: 24px }
+.summary { display: flex; gap: 16px; margin: 16px 0; flex-wrap: wrap }
+.stat { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 14px 18px; flex: 1; min-width: 140px }
+.stat .num { font-family: var(--sans); font-size: 28px; font-weight: 700; color: var(--accent) }
+.stat .label { font-family: var(--mono); font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .1em }
+table { width: 100%; border-collapse: collapse; font-size: 13px; font-family: var(--sans); margin: 8px 0 }
+th { text-align: left; font-family: var(--mono); font-size: 10px; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); border-bottom: 2px solid var(--border); padding: 6px 8px; font-weight: 700 }
+td { border-bottom: 1px solid var(--border); padding: 7px 8px; vertical-align: top }
+td.path { font-family: var(--mono); font-size: 12px; color: var(--muted); max-width: 300px; overflow: hidden; text-overflow: ellipsis }
+.pass { color: var(--good); font-weight: 600 } .warn { color: var(--warn); font-weight: 600 } .fail { color: var(--fail); font-weight: 600 }
+.comparison { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 12px 0 }
+@media(max-width:700px) { .comparison { grid-template-columns: 1fr } }
+.col { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px }
+.col h4 { margin-top: 0 }
+pre { font-family: var(--mono); font-size: 12px; background: #1b1b18; color: #d4d0c8; border-radius: 6px; padding: 12px 14px; overflow-x: auto; margin: 6px 0; line-height: 1.5 }
+pre.file-list { background: var(--bg); color: var(--muted); border: 1px solid var(--border) }
+pre.index { white-space: pre; }
+.block-detail { border-top: 1px solid var(--border); padding-top: 20px; margin-top: 20px }
+.verdict { margin-top: 24px; padding: 16px 20px; border-radius: 8px; font-family: var(--sans); font-size: 15px }
+.verdict.ship { background: #edfbf0; border: 1px solid #1a7a3a; color: #1a7a3a }
+.verdict.wait { background: #fff3ec; border: 1px solid #d94f04; color: #d94f04 }
+</style>
+<div class="wrap">
+<h1>media-use eval report</h1>
+<p class="meta">${new Date().toISOString().slice(0, 10)} · ${all.length} blocks evaluated · baseline vs. media-use --adopt</p>
+
+<div class="summary">
+  <div class="stat"><div class="num">${all.length}</div><div class="label">blocks tested</div></div>
+  <div class="stat"><div class="num">${passed.length}</div><div class="label">with assets</div></div>
+  <div class="stat"><div class="num">${all.reduce((s, r) => s + r.adopted.count, 0)}</div><div class="label">assets adopted</div></div>
+  <div class="stat"><div class="num">${all.filter((r) => r.manifest.some((m) => m.duration || m.width)).length}</div><div class="label">with ffprobe metadata</div></div>
+  <div class="stat"><div class="num">${(() => {
+    const refs = all.flatMap((r) => r.assetRefs);
+    const covered = refs.filter((c) => c.covered).length;
+    return refs.length > 0 ? Math.round((covered / refs.length) * 100) + "%" : "—";
+  })()}</div><div class="label">composition coverage</div></div>
+</div>
+
+<h2>Results matrix</h2>
+<table>
+  <thead><tr><th>Block</th><th>Baseline</th><th>Adopted</th><th>Metadata</th><th>Cache hit</th><th>Miss handling</th></tr></thead>
+  <tbody>${rows}</tbody>
+</table>
+
+<h2>Before / after comparisons</h2>
+${details}
+
+<div class="verdict ${passed.length >= 3 ? "ship" : "wait"}">
+  ${
+    passed.length >= 3
+      ? `<strong>Ship it.</strong> ${passed.length}/${all.length} blocks adopted successfully with metadata. Resolve cache hits work. Miss handling is clean.`
+      : `<strong>Needs work.</strong> Only ${passed.length} blocks adopted. Check the failures above.`
+  }
+</div>
+</div>`;
+}
+
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+console.log("media-use eval · running against registry blocks...\n");
+
+const results = [];
+for (const block of TEST_BLOCKS) {
+  const fullPath = join(REPO_ROOT, block);
+  if (!existsSync(fullPath)) {
+    console.log(`  skip ${basename(block)} (not found)`);
+    results.push(null);
+    continue;
+  }
+  process.stdout.write(`  ${basename(block)}...`);
+  const result = evalBlock(block);
+  if (result) {
+    console.log(
+      ` ${result.adopted.count} adopted, ${result.manifest.filter((m) => m.duration || m.width).length} with metadata`,
+    );
+  } else {
+    console.log(" failed");
+  }
+  results.push(result);
+}
+
+const report = generateReport(results);
+const outPath = join(SCRIPT_DIR, "..", "eval-report.html");
+writeFileSync(outPath, report);
+console.log(`\nReport: ${outPath}`);