dsh-hyperframes 0.3.1 → 0.4.0

package/skills/product-launch-video/scripts/build-frame-subsets.test.mjs

@@ -0,0 +1,152 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const workflows = ["product-launch-video", "faceless-explainer", "pr-to-video"];
+const css = `<style>
+/* cyrillic */
+@font-face { font-family: 'Manrope'; font-style: normal; font-weight: 200 800;
+  src: url(assets/fonts/aaa.woff2) format('woff2'); unicode-range: U+0400-045F; }
+/* latin */
+@font-face { font-family: 'Manrope'; font-style: normal; font-weight: 200 800;
+  src: url("assets/fonts/zzz.woff2") format('woff2'); unicode-range: U+0000-00FF; }
+</style>`;
+
+for (const skill of workflows) {
+  const scripts = new URL("../../" + skill + "/scripts/", import.meta.url);
+  const { brandFontFaces } = await import(new URL("captions.mjs", scripts));
+  test(skill + " stages every captured subset and captions preserve the same coverage", () => {
+    const project = mkdtempSync(join(tmpdir(), "frame-subsets-"));
+    try {
+      mkdirSync(join(project, "capture/extracted"), { recursive: true });
+      mkdirSync(join(project, "capture/assets/fonts"), { recursive: true });
+      writeFileSync(
+        join(project, "capture/extracted/tokens.json"),
+        JSON.stringify({ fonts: [{ family: "Manrope" }] }),
+      );
+      writeFileSync(join(project, "capture/extracted/page.html"), css);
+      writeFileSync(join(project, "capture/assets/fonts/aaa.woff2"), "cyrillic bytes");
+      writeFileSync(join(project, "capture/assets/fonts/zzz.woff2"), "latin bytes");
+      for (let pass = 0; pass < 2; pass++) {
+        execFileSync(
+          process.execPath,
+          [
+            fileURLToPath(new URL("build-frame.mjs", scripts)),
+            "--preset",
+            "capsule",
+            "--hyperframes",
+            project,
+          ],
+          { stdio: "pipe" },
+        );
+        const frame = readFileSync(join(project, "frame.md"), "utf8");
+        const captions = brandFontFaces(join(project, "frame.md"), project);
+        for (const output of [frame, captions]) {
+          assert.match(output, /unicode-range:\s*U\+0400-045F/);
+          assert.match(output, /unicode-range:\s*U\+0000-00FF/);
+          assert.equal((output.match(/font-weight:\s*200 800/g) ?? []).length, 2);
+          assert.equal((output.match(/@font-face/g) ?? []).length, 2);
+          for (const match of output.matchAll(/url\(["']?(assets\/fonts\/[^"')]+)["']?\)/g)) {
+            assert.ok(
+              ["cyrillic bytes", "latin bytes"].includes(
+                readFileSync(join(project, match[1]), "utf8"),
+              ),
+            );
+          }
+        }
+        assert.equal(readdirSync(join(project, "assets/fonts")).length, 2);
+      }
+    } finally {
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+}
+
+test("captured font helper copies stay equal to the owner", () => {
+  const owner = readFileSync(new URL("./lib/captured-fonts.mjs", import.meta.url), "utf8");
+  for (const skill of workflows.slice(1)) {
+    assert.equal(
+      readFileSync(
+        new URL("../../" + skill + "/scripts/lib/captured-fonts.mjs", import.meta.url),
+        "utf8",
+      ),
+      owner,
+    );
+  }
+});
+
+test("captured rules stage only available local sources for requested families", async () => {
+  const { stageCapturedFonts } = await import("./lib/captured-fonts.mjs");
+  const project = mkdtempSync(join(tmpdir(), "captured-font-sources-"));
+  try {
+    mkdirSync(join(project, "capture/extracted"), { recursive: true });
+    mkdirSync(join(project, "capture/assets/fonts"), { recursive: true });
+    writeFileSync(join(project, "capture/assets/fonts/local.woff2"), "first");
+    writeFileSync(
+      join(project, "capture/extracted/page.html"),
+      `<style>
+      @font-face { font-family: Other; src: url(assets/fonts/local.woff2); }
+      @font-face { font-family: Manrope; font-weight: 600; unicode-range: U+0000-00FF;
+        src: local(Manrope), url(https://example.com/remote.woff2), url(assets/fonts/missing.woff2), url(assets/fonts/local.woff2) format("woff2"); }
+    </style>`,
+    );
+    const first = stageCapturedFonts(project, ["Manrope"]);
+    assert.equal(first.faces.length, 1);
+    assert.deepEqual([...first.families], ["manrope"]);
+    assert.doesNotMatch(first.faces[0], /Other|https:|missing|local\(/);
+    assert.match(first.faces[0], /unicode-range: U\+0000-00FF/);
+    const [file] = first.files;
+    assert.equal(readFileSync(join(project, file), "utf8"), "first");
+    writeFileSync(join(project, "capture/assets/fonts/local.woff2"), "refreshed");
+    stageCapturedFonts(project, ["Manrope"]);
+    assert.equal(readFileSync(join(project, file), "utf8"), "refreshed");
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+for (const skill of workflows) {
+  test(
+    skill + " keeps captured family ownership when downloads are missing or names overlap",
+    async () => {
+      const { brandFontFaces } = await import(
+        new URL("../../" + skill + "/scripts/captions.mjs", import.meta.url)
+      );
+      const project = mkdtempSync(join(tmpdir(), "font-ownership-"));
+      try {
+        mkdirSync(join(project, "capture/extracted"), { recursive: true });
+        mkdirSync(join(project, "capture/assets/fonts"), { recursive: true });
+        writeFileSync(
+          join(project, "frame.md"),
+          'typography:\n  display: { fontFamily: "TT Norms Pro Mono", weight: 400 }\n  body: { fontFamily: "TT Norms Pro", weight: 400 }\n',
+        );
+        writeFileSync(
+          join(project, "capture/assets/fonts/TT_Norms_Pro_Mono_Regular.woff2"),
+          "mono",
+        );
+        writeFileSync(
+          join(project, "capture/extracted/page.html"),
+          `<style>
+        @font-face { font-family: 'TT Norms Pro Mono'; src: url(assets/fonts/TT_Norms_Pro_Mono_Regular.woff2); unicode-range: U+0000-00FF; }
+      </style>`,
+        );
+        const mixed = brandFontFaces(join(project, "frame.md"), project);
+        assert.equal((mixed.match(/@font-face/g) ?? []).length, 1);
+        assert.doesNotMatch(mixed, /font-family: 'TT Norms Pro';/);
+        writeFileSync(
+          join(project, "capture/extracted/page.html"),
+          `<style>
+        @font-face { font-family: 'TT Norms Pro Mono'; src: url(assets/fonts/missing.woff2); }
+      </style>`,
+        );
+        assert.equal(brandFontFaces(join(project, "frame.md"), project), "");
+      } finally {
+        rmSync(project, { recursive: true, force: true });
+      }
+    },
+  );
+}

package/skills/product-launch-video/scripts/build-frame.mjs

@@ -42,6 +42,8 @@ import {
   UA_DEFAULT_COLORS,
 } from "./lib/tokens.mjs";
 
+import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
 const flag = (name, def) => {
@@ -479,11 +481,12 @@ if (brandFonts.length) {
   const famOf = (f) =>
     fams.length === 1 ? fams[0] : ranked.find((x) => norm(f).includes(norm(x)));
   const outDir = join(hyperframesDir, "assets/fonts");
-  const faces = [];
-  const stagedNames = new Set();
+  const captured = stageCapturedFonts(hyperframesDir, fams);
+  const faces = [...captured.faces];
+  const stagedNames = new Set(captured.files);
   for (const { d, f } of files) {
     const fam = famOf(f);
-    if (!fam) continue;
+    if (!fam || captured.families.has(fam.toLowerCase())) continue;
     const { n, w } = weightInfo(f);
     const style = styleOf(f);
     const clean = `${fam.replace(/[^A-Za-z0-9]/g, "")}-${w}${style === "italic" ? "-Italic" : ""}.${extOf(f)}`;

package/skills/product-launch-video/scripts/captions.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
 // captions.mjs — build the captions sub-composition from STORYBOARD + audio_meta.
 //
 // One mode: `build`. Reads STORYBOARD.md (frame order + durations → cumulative
@@ -263,7 +264,7 @@ function buildFromSkin(skin, groups, total, W, H, tokens, die, faces = "", fonts
   out = fillOnce(
     out,
     /var GROUPS = \[\];/,
-    `var GROUPS = ${JSON.stringify(groups)};`,
+    `var GROUPS = ${JSON.stringify(groups).replace(/</g, "\\u003c")};`,
     "`var GROUPS = [];` hole",
   );
   out = fillOnce(out, /var DURATION = 0;/, `var DURATION = ${total};`, "`var DURATION = 0;` hole");
@@ -344,7 +345,8 @@ function brandFontFaces(framePath, hyperframesDir) {
   // underscore/hyphen-named brand font (e.g. TT Norms Pro), which is exactly the
   // font_family_without_font_face bug.
   const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
-  const faces = [];
+  const captured = stageCapturedFonts(hyperframesDir, families);
+  const faces = [...captured.faces];
   const seen = new Set();
   const claimed = new Set(); // each file is claimed by the MOST SPECIFIC family only
   // Match the longest family key first so "TT Norms Pro" can't swallow the files that
@@ -363,12 +365,13 @@ function brandFontFaces(framePath, hyperframesDir) {
         if (!/\.(woff2|woff|ttf|otf)$/i.test(f)) continue;
         if (claimed.has(f)) continue; // a more specific family already took this file
         if (!norm(f.replace(/\.(woff2|woff|ttf|otf)$/i, "")).startsWith(key)) continue;
+        claimed.add(f);
+        if (captured.families.has(fam.toLowerCase())) continue;
         const w = weightOf(f);
         const style = styleOf(f);
         const dedup = `${fam}-${w}-${style}`;
         if (seen.has(dedup)) continue; // one src per face; assets/fonts wins over capture
         seen.add(dedup);
-        claimed.add(f);
         faces.push(
           `      @font-face { font-family: '${fam}'; src: url('${d.rel}/${f}') format('${fmtOf(f)}'); font-weight: ${w}; font-style: ${style}; font-display: block; }`,
         );
@@ -480,7 +483,7 @@ function buildCaptionsHtml(groups, total, W, H) {
   <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
   <script>
     (function () {
-      var GROUPS = ${JSON.stringify(groups)};
+      var GROUPS = ${JSON.stringify(groups).replace(/</g, "\\u003c")};
       var cap = document.getElementById("cap");
       var tl = gsap.timeline({ paused: true });
       GROUPS.forEach(function (g) {

package/skills/product-launch-video/scripts/frame-packets.mjs

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// Thin wrapper over the shared packet builder in hyperframes-core — this file only
+// Thin wrapper over the shared packet builder in hyperframes — this file only
 // pins the paths that are specific to this workflow skill. The logic (frame
 // splitting, rule citation, packet bounds, `_role.md` assembly) has one owner:
-// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs
+// ../../hyperframes/scripts/lib/frame-packets-core.mjs
 
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";
+import * as core from "./lib/frame-packets-core.mjs";
 
 const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const CONFIG = {
   animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
-  corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
+  corePath: resolve(SKILL_DIR, "../hyperframes/references/frame-worker-core.md"),
   deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
 };
 

package/skills/product-launch-video/scripts/lib/bgm-volume.mjs

@@ -0,0 +1,4 @@
+// Music sits under narration; a silent film brings music forward.
+export const BGM_BED_VOLUME = 0.12;
+export const BGM_SILENT_VOLUME = 0.9;
+export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);

package/skills/product-launch-video/scripts/lib/captured-fonts.mjs

@@ -0,0 +1,58 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Capture preserves subset and variable-axis descriptors in extracted/page.html.
+// Filenames alone cannot identify a face's character coverage.
+export function stageCapturedFonts(projectDir, families) {
+  const page = join(projectDir, "capture/extracted/page.html");
+  const result = { faces: [], families: new Set(), files: new Set() };
+  if (!existsSync(page)) return result;
+  const wanted = new Set(families.map((family) => family.toLowerCase()));
+  const html = readFileSync(page, "utf8");
+  const copied = new Set();
+  for (const style of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) {
+    const css = style[1].replace(/\/\*[\s\S]*?\*\//g, "");
+    for (const match of css.matchAll(/@font-face\s*\{([^}]+)\}/gi)) {
+      const body = match[1];
+      const familyValue = /(?:^|;)\s*font-family\s*:\s*([^;]+)/i.exec(body)?.[1]?.trim();
+      if (!familyValue) continue;
+      const family = familyValue.replace(/^(['"])(.*)\1$/, "$2");
+      if (!wanted.has(family.toLowerCase())) continue;
+      result.families.add(family.toLowerCase());
+      const source = /(?:^|;)\s*src\s*:\s*([^;]+)/i.exec(body);
+      if (!source) continue;
+      const sources = localFontSources(source[1], projectDir);
+      if (!sources.length) {
+        console.warn("Captured font has no downloaded source: " + family);
+        continue;
+      }
+      for (const file of sources) {
+        if (copied.has(file.name)) continue;
+        if (!copied.size) mkdirSync(join(projectDir, "assets/fonts"), { recursive: true });
+        copyFileSync(file.source, join(projectDir, file.target));
+        copied.add(file.name);
+        result.files.add(file.target);
+      }
+      const src = sources.map((file) => file.css).join(", ");
+      const rule = "@font-face{" + body.replace(source[1], src) + "}";
+      if (!result.faces.includes(rule)) result.faces.push(rule);
+    }
+  }
+  return result;
+}
+
+function localFontSources(source, projectDir) {
+  const files = [];
+  for (const match of source.matchAll(
+    /url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)(\s*format\([^)]*\))?/gi,
+  )) {
+    const url = match[1] ?? match[2] ?? match[3];
+    const name = /^assets\/fonts\/([a-z0-9_.-]+\.(?:woff2?|ttf|otf))$/i.exec(url)?.[1];
+    if (!name) continue;
+    const path = join(projectDir, "capture/assets/fonts", name);
+    if (!existsSync(path)) continue;
+    const target = "assets/fonts/captured-" + name;
+    files.push({ name, source: path, target, css: 'url("' + target + '")' + (match[4] ?? "") });
+  }
+  return files;
+}

package/skills/product-launch-video/scripts/lib/frame-packets-core.mjs

@@ -0,0 +1,194 @@
+// Frame packets inline the storyboard frame, blueprint and cited recipes.
+// Workflow wrappers supply resource paths and workflow-specific sections.
+// The role combines the shared worker contract with the workflow delta.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function field(block, name) {
+  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
+  return match?.[1]?.trim() ?? null;
+}
+
+export function splitFrames(storyboard) {
+  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
+  return matches.map((match, index) => {
+    const start = match.index;
+    const end = matches[index + 1]?.index ?? storyboard.length;
+    return {
+      heading: match[1].trim(),
+      block: storyboard.slice(start, end).trim(),
+    };
+  });
+}
+
+export function frameId(frame) {
+  const src = field(frame.block, "src");
+  if (!src) throw new Error(`${frame.heading}: missing src`);
+  return basename(src).replace(/\.html?$/i, "");
+}
+
+export function selectedFile(path, heading) {
+  if (!path || !existsSync(path)) return "";
+  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
+}
+
+function escapeRegExp(id) {
+  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function knownRuleIds(animationDir) {
+  const rulesDir = join(animationDir, "rules");
+  if (!existsSync(rulesDir)) {
+    console.warn(
+      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
+    );
+    return [];
+  }
+  return readdirSync(rulesDir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => name.replace(/\.md$/, ""));
+}
+
+export function citedRules(block, ruleIds) {
+  const explicit = (field(block, "rules") ?? "")
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim())
+    .filter(Boolean);
+  const mentioned = ruleIds.filter((id) =>
+    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
+  );
+  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
+}
+
+// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
+// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
+// the filename. Parse the field into the id it names (or null for `compose`), so
+// no caller ever resolves a raw field value against the blueprints directory.
+export function blueprintId(block) {
+  const raw = field(block, "blueprint");
+  if (!raw) return null;
+  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
+  return id && id.toLowerCase() !== "compose" ? id : null;
+}
+
+export function resourceSections(block, { animationDir, ruleIds, frameId }) {
+  let sections = "";
+  const blueprint = blueprintId(block);
+  if (blueprint) {
+    const blueprintsDir = join(animationDir, "blueprints");
+    const path = join(blueprintsDir, `${blueprint}.md`);
+    // An installed library must contain the named blueprint.
+    // An absent on-demand library warns, like missing motion rules.
+    if (!existsSync(blueprintsDir)) {
+      console.warn(
+        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
+      );
+    } else if (!existsSync(path)) {
+      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
+    } else {
+      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
+    }
+  }
+  for (const rule of citedRules(block, ruleIds)) {
+    sections += selectedFile(
+      join(animationDir, "rules", `${rule}.md`),
+      `Selected motion rule: ${rule}`,
+    );
+  }
+  return sections;
+}
+
+export function buildRolePayload({ corePath, deltaPath, outDir }) {
+  const core = readFileSync(corePath, "utf8").trim();
+  const delta = readFileSync(deltaPath, "utf8").trim();
+  const role = `${core}\n\n---\n\n${delta}\n`;
+  mkdirSync(outDir, { recursive: true });
+  const path = join(outDir, "_role.md");
+  writeFileSync(path, role);
+  return { path, bytes: Buffer.byteLength(role) };
+}
+
+export function buildFramePackets({
+  projectDir,
+  storyboardPath = join(projectDir, "STORYBOARD.md"),
+  outDir = join(projectDir, ".hyperframes", "frame-packets"),
+  maxPacketBytes = 48_000,
+  animationDir,
+  corePath,
+  deltaPath,
+  // Per-workflow hooks (all optional):
+  // designTruthLine(projectDir) -> the packet's design-truth input line
+  // validateFrame(frame, id)   -> throw to reject a frame before packing
+  // extraSections(block)       -> extra packet sections appended after the rule recipes
+  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
+  validateFrame,
+  extraSections,
+}) {
+  const storyboard = readFileSync(storyboardPath, "utf8");
+  const frames = splitFrames(storyboard);
+  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
+  const ruleIds = knownRuleIds(animationDir);
+
+  const packets = frames.map((frame) => {
+    const id = frameId(frame);
+    if (validateFrame) validateFrame(frame, id);
+    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
+    const bytes = Buffer.byteLength(packet);
+    if (bytes > maxPacketBytes) {
+      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
+    }
+    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
+  });
+
+  mkdirSync(outDir, { recursive: true });
+  for (const { path, packet } of packets) writeFileSync(path, packet);
+  buildRolePayload({ corePath, deltaPath, outDir });
+  return packets.map(({ packet: _packet, ...result }) => result);
+}
+
+export function flag(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+
+// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
+// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
+// a raw compare silently skips main() when invoked through any symlinked path.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}
+
+export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
+  const argv = process.argv.slice(2);
+  const projectDir = resolve(flag(argv, "project", "."));
+  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
+  try {
+    const packets = build({
+      projectDir,
+      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
+      outDir,
+    });
+    const role = buildRole({ outDir });
+    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
+    for (const packet of packets)
+      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
+    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
+  } catch (error) {
+    console.error(`✗ frame packets: ${error.message}`);
+    process.exit(1);
+  }
+}

package/skills/product-launch-video/scripts/lib/storyboard.mjs

@@ -5,7 +5,7 @@
 // ship standalone: installed via `npx skills add`, a skill's scripts can't reach
 // the monorepo's core package, and the core export points at .ts source that
 // `node` (which runs these scripts) can't load. CANONICAL contract = the core
-// parser + skills/hyperframes-core/references/storyboard-format.md; keep this in
+// parser + skills/hyperframes/references/storyboard-format.md; keep this in
 // lockstep. Behavior: never throws, accepts freeform narrative, recognizes
 // Frame/Beat/Scene headings at H2/H3, preserves unknown keys verbatim under
 // `extra` (keys lowercased). Pure node — no deps.

package/skills/product-launch-video/scripts/lib/transitions.json

@@ -34,11 +34,11 @@
       "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
       "gsap_template_horizontal": [
         "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ],
       "gsap_template_vertical": [
         "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     },
     {
@@ -61,7 +61,7 @@
       "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
       "gsap_template": [
         "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     }
   ],

package/skills/product-launch-video/scripts/transitions.mjs

@@ -117,16 +117,18 @@ function extendFrameTail(hyperframesDir, frame, baseDuration, targetDuration, di
   let extended = 0;
   const rewritten = html.replace(/<([A-Za-z][\w:-]*)\b([^>]*)>/g, (tag, name, attrs) => {
     const durationMatch = attrs.match(/\bdata-duration="([\d.]+)"/);
-    if (!durationMatch) return tag;
-    const duration = Number(durationMatch[1]);
-    if (!Number.isFinite(duration)) return tag;
-
     const compositionMatch = attrs.match(/\bdata-composition-id="([^"]+)"/);
     if (compositionMatch?.[1] === compId && !foundRoot) {
       foundRoot = true;
-      return tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${targetDuration}"`);
+      return durationMatch
+        ? tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${targetDuration}"`)
+        : tag.replace(/(\s*\/?>)$/, ` data-duration="${targetDuration}"$1`);
     }
 
+    if (!durationMatch) return tag;
+    const duration = Number(durationMatch[1]);
+    if (!Number.isFinite(duration)) return tag;
+
     if (name.toLowerCase() === "audio") return tag;
     const startMatch = attrs.match(/\bdata-start="([\d.]+)"/);
     if (!startMatch) return tag;

package/skills/product-launch-video/scripts/transitions.test.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+const workflowScripts = [
+  ["product-launch-video", new URL("./transitions.mjs", import.meta.url).pathname],
+  ["pr-to-video", new URL("../../pr-to-video/scripts/transitions.mjs", import.meta.url).pathname],
+];
+
+function runInject(script, rootId) {
+  const project = mkdtempSync(join(tmpdir(), "hf-transition-root-"));
+  const framesDir = join(project, "compositions", "frames");
+  mkdirSync(framesDir, { recursive: true });
+  writeFileSync(
+    join(project, "STORYBOARD.md"),
+    `---\nformat: 1920x1080\n---\n\n## Frame 1 — First\n\n- duration: 3s\n- transition_in: cut\n- src: compositions/frames/frame-01.html\n\n## Frame 2 — Second\n\n- duration: 3s\n- transition_in: crossfade 0.5s\n- src: compositions/frames/frame-02.html\n`,
+  );
+  writeFileSync(
+    join(framesDir, "frame-01.html"),
+    `<div data-composition-id="${rootId}" data-width="1920" data-height="1080"><div class="clip" data-start="0" data-duration="3"></div></div>`,
+  );
+  writeFileSync(
+    join(framesDir, "frame-02.html"),
+    '<div data-composition-id="frame-02" data-duration="3"></div>',
+  );
+  writeFileSync(
+    join(project, "index.html"),
+    `<div data-composition-id="main" data-duration="6">
+      <div id="el-frame-01" data-start="0" data-duration="3" data-track-index="0"></div>
+      <div id="el-frame-02" data-start="3" data-duration="3" data-track-index="0"></div>
+    </div><script>window.__timelines = {}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>`,
+  );
+  const result = spawnSync(
+    process.execPath,
+    [script, "inject", "--storyboard", join(project, "STORYBOARD.md"), "--hyperframes", project],
+    { encoding: "utf8" },
+  );
+  return {
+    project,
+    result,
+    frameHtml: () => readFileSync(join(framesDir, "frame-01.html"), "utf8"),
+  };
+}
+
+for (const [workflow, script] of workflowScripts) {
+  test(`${workflow} inserts duration on a valid durationless frame root`, () => {
+    const fixture = runInject(script, "frame-01");
+    try {
+      assert.equal(fixture.result.status, 0, fixture.result.stderr);
+      assert.match(fixture.frameHtml(), /data-composition-id="frame-01"[^>]*data-duration="3\.5"/);
+    } finally {
+      rmSync(fixture.project, { recursive: true, force: true });
+    }
+  });
+
+  test(`${workflow} still rejects a genuinely mismatched frame root`, () => {
+    const fixture = runInject(script, "wrong-root");
+    try {
+      assert.notEqual(fixture.result.status, 0);
+      assert.match(fixture.result.stderr, /has no data-composition-id="frame-01" root/);
+    } finally {
+      rmSync(fixture.project, { recursive: true, force: true });
+    }
+  });
+}

package/skills/product-launch-video/sub-agents/frame-worker.md

@@ -1,6 +1,6 @@
 # Frame worker — product-launch delta
 
-> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a product-launch frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+> The shared law is the core contract above (the packet builder prepends `../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a product-launch frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
 
 ## Your `focal:` / `roles:` — real captured media