dsh-hyperframes 0.9.1 → 0.9.3

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

@@ -1,194 +0,0 @@
-// 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/pad-frame-duration.mjs

@@ -1,36 +0,0 @@
-// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
-// sync with the padded index.html wrapper duration transitions.mjs computes.
-//
-// The frame's OWN internal file declares its #root/clip data-duration to the
-// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
-// upstream"). When an outgoing transition pads the index.html WRAPPER's
-// data-duration to cover the transition tail, the frame's own internal
-// duration is left short — the render engine clip-gates the sub-composition's
-// visible content at that shorter value, so content vanishes abruptly at
-// content-end instead of fading gracefully through the wrapper's extended
-// fade-out tween. Pad the frame's own file to match so both durations agree.
-
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-
-export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
-  const framePath = resolve(hyperframesDir, frameSrc);
-  let html;
-  try {
-    html = readFileSync(framePath, "utf8");
-  } catch (err) {
-    if (err?.code === "ENOENT") return;
-    throw err;
-  }
-  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
-  let m;
-  while ((m = tagRe.exec(html)) !== null) {
-    const tag = m[0];
-    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
-    if (!/data-duration="[\d.]+"/.test(tag)) continue;
-    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
-    if (newTag === tag) return;
-    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
-    return;
-  }
-}

package/skills/product-launch-video/scripts/lib/pad-frame-duration.test.mjs

@@ -1,76 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { padFrameInternalDuration } from "./pad-frame-duration.mjs";
-
-// Regression: an outgoing transition pads the index.html WRAPPER's
-// data-duration to cover the transition tail, but the frame's own internal
-// file kept its shorter content-only duration, so the render engine
-// clip-gated the sub-composition's visible content at the shorter value —
-// content vanished abruptly instead of fading through the wrapper's
-// extended fade-out tween. A user diagnosed and verified this fix
-// themselves: pad the frame's own #root/clip data-duration to match.
-test("padFrameInternalDuration pads the matching frame's own data-duration", () => {
-  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-"));
-  const framesDir = join(dir, "compositions", "frames");
-  mkdirSync(framesDir, { recursive: true });
-  const frameSrc = "compositions/frames/scene-1.html";
-  const framePath = join(dir, frameSrc);
-  writeFileSync(
-    framePath,
-    `<template>
-  <div
-    id="root"
-    data-composition-id="scene-1"
-    data-width="1920"
-    data-height="1080"
-    data-duration="4.2"
-  ></div>
-</template>`,
-  );
-
-  try {
-    padFrameInternalDuration(dir, frameSrc, "scene-1", 4.7);
-    const updated = readFileSync(framePath, "utf8");
-    assert.match(updated, /data-duration="4\.7"/);
-    assert.doesNotMatch(updated, /data-duration="4\.2"/);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test("padFrameInternalDuration only touches the tag matching the given frame id", () => {
-  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-scope-"));
-  const framesDir = join(dir, "compositions", "frames");
-  mkdirSync(framesDir, { recursive: true });
-  const frameSrc = "compositions/frames/scene-2.html";
-  const framePath = join(dir, frameSrc);
-  const original = `<template>
-  <div id="root" data-composition-id="scene-2" data-duration="3.0">
-    <div data-composition-id="unrelated-child" data-duration="1.0"></div>
-  </div>
-</template>`;
-  writeFileSync(framePath, original);
-
-  try {
-    padFrameInternalDuration(dir, frameSrc, "scene-2", 3.5);
-    const updated = readFileSync(framePath, "utf8");
-    assert.match(updated, /data-composition-id="scene-2" data-duration="3\.5"/);
-    assert.match(updated, /data-composition-id="unrelated-child" data-duration="1\.0"/);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test("padFrameInternalDuration is a no-op when the frame file does not exist", () => {
-  const dir = mkdtempSync(join(tmpdir(), "transitions-pad-missing-"));
-  try {
-    assert.doesNotThrow(() =>
-      padFrameInternalDuration(dir, "compositions/frames/missing.html", "missing", 5),
-    );
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-});

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

@@ -1,249 +0,0 @@
-// storyboard.mjs — vendored lenient parser for STORYBOARD.md.
-//
-// Faithful plain-JS port of @hyperframes/core/storyboard
-// (packages/core/src/storyboard/parseStoryboard.ts). Vendored because skills
-// 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/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.
-
-export const FRAME_STATUSES = ["outline", "built", "animated"];
-export const DEFAULT_FRAME_STATUS = "outline";
-
-// Detection-only frame heading (ends at the keyword); ReDoS-hardened — keep as-is.
-const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
-const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
-const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
-const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
-const LEADING_INT_RE = /^(\d+)/;
-const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
-const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
-const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
-export const VOICEOVER_ALIASES = ["voiceover", "vo", "voice_over", "narration"];
-const VOICEOVER_KEYS = new Set(VOICEOVER_ALIASES);
-
-export function parseStoryboard(source) {
-  const warnings = [];
-  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
-  const frames = parseFrames(body, bodyStartLine, warnings);
-  return { globals, frames, warnings };
-}
-
-function emptyGlobals() {
-  return { extra: {} };
-}
-
-function isFrameStatus(value) {
-  return FRAME_STATUSES.includes(value);
-}
-
-// ── Frontmatter ─────────────────────────────────────────────────────────────
-function findFrontmatterRange(lines, warnings) {
-  let start = 0;
-  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
-  if ((lines[start] ?? "").trim() !== "---") return null;
-  for (let i = start + 1; i < lines.length; i++) {
-    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
-  }
-  warnings.push({
-    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
-    line: start + 1,
-  });
-  return null;
-}
-
-function parseFrontmatterEntries(lines, start, end, warnings) {
-  const globals = emptyGlobals();
-  for (let i = start + 1; i < end; i++) {
-    const raw = lines[i] ?? "";
-    if (raw.trim() === "") continue;
-    const colon = raw.indexOf(":");
-    if (colon === -1) {
-      warnings.push({
-        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
-        line: i + 1,
-      });
-      continue;
-    }
-    const key = raw.slice(0, colon).trim().toLowerCase();
-    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
-  }
-  return globals;
-}
-
-function parseFrontmatter(source, warnings) {
-  const lines = source.split(/\r?\n/);
-  const range = findFrontmatterRange(lines, warnings);
-  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };
-  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
-  const body = lines.slice(range.end + 1).join("\n");
-  return { globals, bodyStartLine: range.end + 2, body };
-}
-
-function assignGlobal(globals, key, value) {
-  switch (key) {
-    case "format":
-      globals.format = value;
-      break;
-    case "message":
-      globals.message = value;
-      break;
-    case "arc":
-      globals.arc = value;
-      break;
-    case "audience":
-      globals.audience = value;
-      break;
-    default:
-      globals.extra[key] = value;
-  }
-}
-
-// ── Frames ──────────────────────────────────────────────────────────────────
-function openFrameSection(line, headingLine) {
-  const match = FRAME_HEADING_RE.exec(line);
-  if (!match) return null;
-  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
-  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
-}
-
-function endsFrameSection(line, current) {
-  if (!current) return false;
-  const heading = HEADING_LEVEL_RE.exec(line);
-  return heading !== null && (heading[1] ?? "").length <= current.level;
-}
-
-function parseFrames(body, bodyStartLine, warnings) {
-  const lines = body.split(/\r?\n/);
-  const sections = [];
-  let current = null;
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const opened = openFrameSection(line, bodyStartLine + i);
-    if (opened) {
-      sections.push(opened);
-      current = opened;
-    } else if (endsFrameSection(line, current)) {
-      current = null;
-    } else if (current) {
-      current.lines.push(line);
-    }
-  }
-  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
-}
-
-function buildFrame(section, index, warnings) {
-  const frame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
-  const { number, title } = parseHeading(section.headingText);
-  if (number !== undefined) frame.number = number;
-  if (title) frame.title = title;
-
-  const narrativeLines = [];
-  for (const line of section.lines) {
-    const meta = META_RE.exec(line);
-    if (meta) {
-      applyMeta(
-        frame,
-        (meta[1] ?? "").toLowerCase(),
-        (meta[2] ?? "").trim(),
-        section.headingLine,
-        warnings,
-      );
-    } else {
-      narrativeLines.push(line);
-    }
-  }
-  frame.narrative = narrativeLines.join("\n").trim();
-  return frame;
-}
-
-function parseHeading(text) {
-  if (!text) return {};
-  const intMatch = LEADING_INT_RE.exec(text);
-  if (!intMatch) return { title: text };
-  const number = Number.parseInt(intMatch[1] ?? "", 10);
-  const rest = text
-    .slice((intMatch[0] ?? "").length)
-    .replace(/^[\s.:—-]+/, "")
-    .trim();
-  return { number, title: rest || undefined };
-}
-
-// Dispatch a recognized metadata key to its field, else stash under `extra`.
-// Mirrors core's META_SETTERS map exactly (direct keys + alias sets).
-function applyMeta(frame, key, value, headingLine, warnings) {
-  switch (key) {
-    case "duration":
-      applyDuration(frame, value, headingLine, warnings);
-      return;
-    case "status":
-      applyStatus(frame, value, headingLine, warnings);
-      return;
-    case "poster":
-      applyPoster(frame, value);
-      return;
-    case "src":
-      frame.src = value;
-      return;
-  }
-  if (TRANSITION_KEYS.has(key)) {
-    frame.transitionIn = value;
-    return;
-  }
-  if (SCENE_KEYS.has(key)) {
-    frame.scene = value;
-    return;
-  }
-  if (VOICEOVER_KEYS.has(key)) {
-    frame.voiceover = stripQuotes(value);
-    return;
-  }
-  frame.extra[key] = value;
-}
-
-function applyPoster(frame, value) {
-  const num = DURATION_NUM_RE.exec(value);
-  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
-}
-
-function applyDuration(frame, value, headingLine, warnings) {
-  frame.duration = value;
-  const num = DURATION_NUM_RE.exec(value);
-  if (num) {
-    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
-    return;
-  }
-  warnings.push({
-    message: `Frame ${frame.index}: could not parse duration "${value}".`,
-    line: headingLine,
-    frameIndex: frame.index,
-  });
-}
-
-function applyStatus(frame, value, headingLine, warnings) {
-  const normalized = value.toLowerCase();
-  if (isFrameStatus(normalized)) {
-    frame.status = normalized;
-    return;
-  }
-  frame.extra.status = value;
-  warnings.push({
-    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
-    line: headingLine,
-    frameIndex: frame.index,
-  });
-}
-
-function stripQuotes(value) {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-      return value.slice(1, -1);
-    }
-  }
-  return value;
-}