@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/transcriptCutFade.test.mjs

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fadeFilterFor } from "./transcriptCutFade.mjs";
+
+test("fades in only at the first segment's trailing splice", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: true }), "afade=t=out:st=1.97:d=0.03");
+});
+
+test("fades both edges of a middle segment's two splices", () => {
+  assert.equal(
+    fadeFilterFor(2, { fadeIn: true, fadeOut: true }),
+    "afade=t=in:st=0:d=0.03,afade=t=out:st=1.97:d=0.03",
+  );
+});
+
+test("fades out only at the last segment's leading splice", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: true, fadeOut: false }), "afade=t=in:st=0:d=0.03");
+});
+
+test("a single kept segment borders no splice at all", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: false }), null);
+});
+
+test("still scales the ramp down on a short segment with both edges faded", () => {
+  assert.equal(
+    fadeFilterFor(0.08, { fadeIn: true, fadeOut: true }),
+    "afade=t=in:st=0:d=0.02,afade=t=out:st=0.06:d=0.02",
+  );
+});
+
+test("skips a degenerate segment even when a splice is requested", () => {
+  assert.equal(fadeFilterFor(0.005, { fadeIn: true, fadeOut: true }), null);
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/tts-local-provider.mjs

@@ -0,0 +1,94 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
+import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
+
+// Local voiceover via the packaged Kokoro-82M TTS (the `hyperframes tts` CLI),
+// the free/private default now that HeyGen TTS costs wallet credits. Kokoro runs
+// on-device (CPU, faster-than-realtime, bundled voices, native word timestamps),
+// so no key and no per-call charge. When Kokoro is not set up, this returns null
+// and the registry falls through to the HeyGen TTS upsell.
+//
+// Delegated to the hyperframes CLI (same as transcribe / remove-background), not
+// re-implemented here. ffprobe reads the duration back for the ledger.
+
+function probeDurationSeconds(ffprobe, file) {
+  try {
+    const out = execFileSync(
+      ffprobe,
+      ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", file],
+      { encoding: "utf8", timeout: 15000 },
+    );
+    const d = parseFloat(String(out).trim());
+    return Number.isFinite(d) ? d : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// `platform`/`execFn`/`env`/`pathExists` params (defaulting to the real
+// values) exist so tests can exercise the win32 branch without mocking
+// node:child_process (its ESM exports are non-configurable) — same idiom as
+// spawnP in ../../audio/scripts/lib/tts.mjs.
+export async function localTtsGenerate(
+  intent,
+  ctx,
+  platform = process.platform,
+  execFn = execFileSync,
+  env = process.env,
+  pathExists = existsSync,
+) {
+  const ffprobe = ffprobeBinary();
+  const outPath = join(tmpdir(), `media-use-kokoro-${process.pid}-${Date.now()}.wav`);
+  const argv = ["hyperframes", "tts", intent, "--output", outPath];
+  if (ctx?.voice) argv.push("--voice", ctx.voice);
+  if (ctx?.lang && ctx.lang !== "en") argv.push("--lang", ctx.lang);
+  // On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
+  // (spawnSync npx ENOENT) — resolveSpawnCommand reroutes it through
+  // node + npx-cli.js, same as the audio engine's TTS spawns.
+  const resolved = resolveSpawnCommand(
+    "npx",
+    argv,
+    { encoding: "utf8", timeout: 300000, stdio: ["ignore", "pipe", "pipe"] },
+    platform,
+    env,
+    pathExists,
+  );
+  if (!resolved) {
+    // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
+    // spawnP warns about. Fall through to the next provider rather than crash.
+    console.error(
+      "media-use: local voice not enabled (kokoro). Cannot run npx on Windows: " +
+        "npm's npx-cli.js was not found (install npm with Node, or run via npx/npm run so npm_execpath is set).",
+    );
+    return null;
+  }
+  try {
+    execFn(resolved.cmd, resolved.args, resolved.opts);
+  } catch (err) {
+    // `hyperframes tts` prints its "kokoro-onnx not installed" hint to stdout
+    // (clack UI), so read both streams and surface the actionable enable-command
+    // rather than a bare "Command failed": otherwise resolve silently falls
+    // through to the PAID HeyGen TTS upsell when free local voice was one pip away.
+    const out = `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim();
+    const hint = /not installed|pip install kokoro/i.test(out)
+      ? "install for free on-device voice: pip install kokoro-onnx soundfile (or set HYPERFRAMES_PYTHON to a venv that has it)"
+      : out.slice(-200) || err.message;
+    console.error(`media-use: local voice not enabled (kokoro). ${hint}`);
+    return null;
+  }
+  if (!existsSync(outPath) || statSync(outPath).size === 0) return null;
+  return {
+    localPath: outPath,
+    ext: ".wav",
+    source: "generated",
+    metadata: {
+      description: intent,
+      provider: "kokoro.local",
+      duration: probeDurationSeconds(ffprobe, outPath),
+      provenance: { engine: "kokoro-82m", prompt: intent },
+    },
+  };
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/tts-local-provider.test.mjs

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { localTtsGenerate } from "./tts-local-provider.mjs";
+
+// Regression: on Windows, a bare "npx" is npx.cmd, which execFileSync cannot
+// exec — the Kokoro delegation failed with `spawnSync npx ENOENT` instead of
+// synthesizing (or cleanly falling through to the next provider). The spawn
+// must route through node + npx-cli.js on win32, same as the audio engine's
+// TTS spawns (see ../../audio/scripts/lib/tts.spawn.test.mjs).
+
+const envWithNpxCli = {
+  npm_execpath: "C:/Program Files/nodejs/node_modules/npm/bin/npm-cli.js",
+  npm_node_execpath: "C:/Program Files/nodejs/node.exe",
+};
+const npxCliPath = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
+const pathExists = (path) => path === npxCliPath;
+
+test("win32: routes the hyperframes tts call through node + npx-cli, never bare npx", async () => {
+  const captured = [];
+  const fakeExec = (cmd, args, opts) => {
+    captured.push({ cmd, args, opts });
+    // Synthesize nothing — the provider then returns null via the
+    // missing-output check, which is fine: we only assert the spawn shape.
+  };
+
+  await localTtsGenerate(
+    "hello there",
+    { voice: "am_michael" },
+    "win32",
+    fakeExec,
+    envWithNpxCli,
+    pathExists,
+  );
+
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].cmd, envWithNpxCli.npm_node_execpath);
+  assert.equal(captured[0].args[0], npxCliPath);
+  assert.deepEqual(captured[0].args.slice(1, 4), ["hyperframes", "tts", "hello there"]);
+  assert.ok(captured[0].args.includes("--voice"));
+  // execFileSync options survive the rerouting (pipes are what let the caller
+  // read the "kokoro-onnx not installed" hint back out).
+  assert.deepEqual(captured[0].opts.stdio, ["ignore", "pipe", "pipe"]);
+});
+
+test("win32 without a resolvable npx-cli: falls through to the next provider (null), no spawn", async () => {
+  const captured = [];
+  const fakeExec = (...call) => captured.push(call);
+
+  const result = await localTtsGenerate(
+    "hello",
+    {},
+    "win32",
+    fakeExec,
+    {}, // no npm_execpath, and pathExists finds nothing
+    () => false,
+  );
+
+  assert.equal(result, null);
+  assert.equal(captured.length, 0);
+});
+
+test("non-win32: spawns plain npx unchanged", async () => {
+  const captured = [];
+  const fakeExec = (cmd, args) => captured.push({ cmd, args });
+
+  await localTtsGenerate("hola", { lang: "es" }, "darwin", fakeExec, {}, () => false);
+
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].cmd, "npx");
+  assert.deepEqual(captured[0].args.slice(0, 3), ["hyperframes", "tts", "hola"]);
+  assert.ok(captured[0].args.includes("--lang"));
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/usage.mjs

@@ -0,0 +1,57 @@
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Asset in-use detection: which manifest assets are actually referenced by the
+// project's compositions. Answers "is this safe to prune?" from the CLI. (The
+// Studio Asset tab computes its in-use filter separately from the live timeline;
+// this is the skill-side equivalent for headless use.)
+//
+// ponytail: substring match of each asset's filename against the .html text
+// (covers src= / href= / url() / data-* without parsing HTML). False positives
+// only if a filename literally appears in prose; fine for a filter. Upgrade to
+// attribute parsing if that ever bites.
+
+function compositionHtml(projectDir) {
+  let files = [];
+  try {
+    files = readdirSync(projectDir).filter((f) => f.endsWith(".html"));
+  } catch {
+    return "";
+  }
+  const sub = join(projectDir, "compositions");
+  if (existsSync(sub)) {
+    try {
+      for (const f of readdirSync(sub))
+        if (f.endsWith(".html")) files.push(join("compositions", f));
+    } catch {
+      // ignore unreadable subdir
+    }
+  }
+  return files
+    .map((f) => {
+      try {
+        return readFileSync(join(projectDir, f), "utf8");
+      } catch {
+        return "";
+      }
+    })
+    .join("\n");
+}
+
+/** Tag each record with `inUse` (referenced by some composition). */
+export function tagUsage(records, projectDir) {
+  const html = compositionHtml(projectDir);
+  return records.map((r) => {
+    const file = r.path ? r.path.split("/").pop() : r.id;
+    return { ...r, inUse: Boolean(file) && html.includes(file) };
+  });
+}
+
+/** Split records into { used, unused } for the filter. */
+export function partitionUsage(records, projectDir) {
+  const tagged = tagUsage(records, projectDir);
+  return {
+    used: tagged.filter((r) => r.inUse),
+    unused: tagged.filter((r) => !r.inUse),
+  };
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/usage.test.mjs

@@ -0,0 +1,54 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { tagUsage, partitionUsage } from "./usage.mjs";
+
+function project(html) {
+  const dir = mkdtempSync(join(tmpdir(), "mu-usage-"));
+  writeFileSync(join(dir, "index.html"), html);
+  return dir;
+}
+
+const records = [
+  { id: "bgm_001", path: ".media/audio/bgm/bgm_001.wav", description: "used track" },
+  { id: "bgm_002", path: ".media/audio/bgm/bgm_002.wav", description: "orphan track" },
+];
+
+test("an asset referenced by a composition is marked in-use", () => {
+  const dir = project(`<audio src="assets/bgm_001.wav"></audio>`);
+  try {
+    const tagged = tagUsage(records, dir);
+    assert.equal(tagged.find((r) => r.id === "bgm_001").inUse, true);
+    assert.equal(tagged.find((r) => r.id === "bgm_002").inUse, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("partitionUsage splits used vs unused for the filter", () => {
+  const dir = project(`<img src="bgm_001.wav">`);
+  try {
+    const { used, unused } = partitionUsage(records, dir);
+    assert.deepEqual(
+      used.map((r) => r.id),
+      ["bgm_001"],
+    );
+    assert.deepEqual(
+      unused.map((r) => r.id),
+      ["bgm_002"],
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("no compositions -> everything reads as unused (safe default)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-usage-"));
+  try {
+    assert.equal(partitionUsage(records, dir).used.length, 0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/voice-provider.mjs

@@ -0,0 +1,57 @@
+import { HEYGEN_CLIENT_SOURCE_ARGV, runHeygenJson } from "./heygen-cli.mjs";
+
+// Voice / TTS generation via the HeyGen CLI — the only external CLI media-use
+// shells (CLI-only invariant: media-use holds no keys; the CLI owns auth).
+// Flags verified against `heygen voice speech create --help` (v0.3.0).
+
+function result(url, duration, provider, intent) {
+  if (!url) return null;
+  return {
+    url,
+    source: "generated",
+    metadata: {
+      description: intent,
+      provider,
+      ...(duration != null && { duration }),
+      provenance: { prompt: intent },
+    },
+  };
+}
+
+// HeyGen TTS requires a starfish-engine voice. Default to the first one the
+// catalog returns (deterministic order); pass ctx.voiceId to override.
+// ponytail: listed once per process; the resolved asset is frozen + cached after
+// first use, so the network list only happens on a cache miss. Cache only a
+// truthy id -- a transient list failure must not poison the cache with `null`
+// and permanently disable TTS for the rest of the process.
+let cachedVoiceId;
+function defaultVoiceId() {
+  if (cachedVoiceId) return cachedVoiceId;
+  const j = runHeygenJson(
+    "heygen",
+    ["voice", "list", "--engine", "starfish", "--limit", "1"],
+    "voice list",
+  );
+  cachedVoiceId = j?.data?.[0]?.voice_id || null;
+  return cachedVoiceId;
+}
+
+export async function heygenTtsGenerate(intent, ctx) {
+  const voiceId = ctx?.voiceId || defaultVoiceId();
+  if (!voiceId) return null;
+  const p = runHeygenJson(
+    "heygen",
+    [
+      ...HEYGEN_CLIENT_SOURCE_ARGV,
+      "voice",
+      "speech",
+      "create",
+      "--text",
+      intent,
+      "--voice-id",
+      voiceId,
+    ],
+    "tts",
+  );
+  return result(p?.data?.audio_url, p?.data?.duration, "heygen.tts", intent);
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/voice-provider.test.mjs

@@ -0,0 +1,46 @@
+import { strict as assert } from "node:assert";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { heygenTtsGenerate } from "./voice-provider.mjs";
+
+test("tags TTS generation but not voice discovery with the media-use client source", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-voice-provider-"));
+  const capturePath = join(dir, "argv.log");
+  const heygenPath = join(dir, "heygen");
+  const previousPath = process.env.PATH;
+  const previousCapturePath = process.env.HEYGEN_CAPTURE_PATH;
+
+  writeFileSync(
+    heygenPath,
+    `#!/bin/sh
+printf '%s\\n' "$*" >> "$HEYGEN_CAPTURE_PATH"
+case "$*" in
+  *"voice list"*) printf '%s\\n' '{"data":[{"voice_id":"voice-123"}]}' ;;
+  *"voice speech create"*) printf '%s\\n' '{"data":{"audio_url":"https://example.com/voice.mp3","duration":1.5}}' ;;
+esac
+`,
+  );
+  chmodSync(heygenPath, 0o755);
+  process.env.PATH = `${dir}:${previousPath ?? ""}`;
+  process.env.HEYGEN_CAPTURE_PATH = capturePath;
+
+  try {
+    const result = await heygenTtsGenerate("Hello from media-use", {});
+    const invocations = readFileSync(capturePath, "utf8").trim().split("\n");
+
+    assert.equal(invocations.length, 2);
+    assert.match(invocations[0], /^voice list /);
+    assert.doesNotMatch(invocations[0], /X-HeyGen-Client-Source/);
+    assert.match(invocations[1], /voice speech create/);
+    assert.match(invocations[1], /X-HeyGen-Client-Source: media-use/);
+    assert.equal(result?.url, "https://example.com/voice.mp3");
+  } finally {
+    if (previousPath === undefined) delete process.env.PATH;
+    else process.env.PATH = previousPath;
+    if (previousCapturePath === undefined) delete process.env.HEYGEN_CAPTURE_PATH;
+    else process.env.HEYGEN_CAPTURE_PATH = previousCapturePath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/words.mjs

@@ -0,0 +1,18 @@
+export function normalizeWords(input) {
+  const raw = Array.isArray(input) ? input : Array.isArray(input?.words) ? input.words : [];
+  return raw
+    .map((w, index) => {
+      const text = String(w?.text ?? w?.word ?? "").trim();
+      const start = Number(w?.start);
+      const end = Number(w?.end);
+      if (!text || !Number.isFinite(start) || !Number.isFinite(end)) return null;
+      return { id: w?.id ?? `w${index}`, text, start, end };
+    })
+    .filter(Boolean);
+}
+
+export function wordListsFromMediaMeta(input) {
+  if (Array.isArray(input) || Array.isArray(input?.words)) return [normalizeWords(input)];
+  if (!Array.isArray(input?.voices)) return [];
+  return input.voices.map((voice) => normalizeWords(voice)).filter((words) => words.length > 0);
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/prefs.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Remembered defaults CLI — the lightweight tier of HyperFrames user memory.
+ *
+ *   node prefs.mjs get --hyperframes . [--json]
+ *     Print the merged view (project `.media/preferences.json` over user
+ *     `~/.media/preferences.json`), each key with its source and the receipt
+ *     material (confirmed_in, updated_at).
+ *
+ *   node prefs.mjs record --hyperframes . --key destination --value x-feed [--workflow <w>]
+ *     Record one confirmed brief answer into the project tier; the same value
+ *     confirmed in two different projects promotes the key to the user tier.
+ *
+ * Consumption rules live in hyperframes/references/brief-contract.md § 2
+ * (Remembered defaults): a remembered value becomes the recommended option
+ * with a receipt — it never skips a question.
+ */
+import { parseArgs } from "node:util";
+import { mergedPreferences, recordPreference } from "./lib/prefs-store.mjs";
+
+const { values: args, positionals } = parseArgs({
+  options: {
+    hyperframes: { type: "string", default: "." },
+    key: { type: "string" },
+    value: { type: "string" },
+    workflow: { type: "string" },
+    json: { type: "boolean", default: false },
+  },
+  allowPositionals: true,
+});
+
+const verb = positionals[0];
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (verb === "get") {
+  const merged = mergedPreferences(args.hyperframes);
+  if (args.json) {
+    console.log(JSON.stringify(merged, null, 2));
+  } else if (Object.keys(merged).length === 0) {
+    console.log("no remembered preferences yet");
+  } else {
+    for (const [key, entry] of Object.entries(merged)) {
+      console.log(
+        `${key} = ${entry.value}  (${entry.source}; confirmed in ${entry.confirmed_in.join(", ")})`,
+      );
+    }
+  }
+} else if (verb === "record") {
+  if (!args.key || !args.value) fail("record needs --key and --value");
+  try {
+    const result = recordPreference({
+      projectDir: args.hyperframes,
+      key: args.key,
+      value: args.value,
+      workflow: args.workflow,
+    });
+    const promotion = result.promoted ? "; promoted to user tier" : "";
+    console.log(`recorded ${result.key} = ${result.value} (project${promotion})`);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+} else {
+  fail(
+    "usage: prefs.mjs <get|record> --hyperframes . [--key <k> --value <v> --workflow <w>] [--json]",
+  );
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/recipe.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Recipes CLI — the heavyweight tier of HyperFrames user memory.
+ *
+ *   node recipe.mjs freeze --hyperframes . --name <n> [--workflow <w>] [--blocks a,b,c]
+ *     Freeze the current approved run as a named recipe: frame.md + the
+ *     storyboard skeleton (structure kept, content blanked) + the brief
+ *     skeleton (when BRIEF.md exists) + the confirmed brief values.
+ *     The workflow is read from BRIEF.md; --workflow only covers projects
+ *     briefed before BRIEF.md existed. Re-freezing the same name bumps the
+ *     version and archives the old folder as <name>@v<N>. Promotes to
+ *     ~/.media/recipes/ immediately.
+ *
+ *   node recipe.mjs list --hyperframes . [--workflow <w>] [--json]
+ *     Two-tier merged listing (project wins), newest approval first.
+ *
+ *   node recipe.mjs use --hyperframes . --name <n> [--json]
+ *     Adopt a recipe: import it from the user tier if needed, copy its
+ *     frame.md over the project's, and print the brief values + skeleton path.
+ *
+ * When recipes are offered/consumed is the review loop's and the intent
+ * layer's business — see hyperframes/references/review-loop.md § 4 and
+ * the intent layer's recipe check (hyperframes SKILL.md § 4).
+ */
+import { parseArgs } from "node:util";
+import { freezeRecipe, listRecipes, useRecipe } from "./lib/recipe-store.mjs";
+
+const { values: args, positionals } = parseArgs({
+  options: {
+    hyperframes: { type: "string", default: "." },
+    name: { type: "string" },
+    workflow: { type: "string" },
+    blocks: { type: "string" },
+    json: { type: "boolean", default: false },
+  },
+  allowPositionals: true,
+});
+
+const verb = positionals[0];
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+try {
+  if (verb === "freeze") {
+    if (!args.name) fail("freeze needs --name");
+    const frozen = freezeRecipe({
+      projectDir: args.hyperframes,
+      name: args.name,
+      workflow: args.workflow,
+      blocks: args.blocks
+        ? args.blocks
+            .split(",")
+            .map((b) => b.trim())
+            .filter(Boolean)
+        : undefined,
+    });
+    if (args.json) console.log(JSON.stringify({ ok: true, ...frozen }));
+    else {
+      console.log(
+        `froze recipe ${frozen.slug} (v${frozen.version}, ${frozen.workflow}) → ${frozen.dir}`,
+      );
+      if (frozen.workflowOverridden)
+        console.log(`  (BRIEF.md says "${frozen.workflow}" — the --workflow flag was ignored)`);
+      if (!frozen.briefSkeleton)
+        console.log("  (no BRIEF.md in the project — brief skeleton skipped)");
+    }
+  } else if (verb === "list") {
+    const list = listRecipes({ projectDir: args.hyperframes, workflow: args.workflow });
+    if (args.json) console.log(JSON.stringify(list));
+    else if (list.length === 0) console.log("no recipes yet");
+    else {
+      for (const r of list) {
+        console.log(
+          `${r.name}  v${r.version}  ${r.workflow}  (${r.source}; approved ${String(r.approved_at ?? "?").slice(0, 10)})`,
+        );
+      }
+    }
+  } else if (verb === "use") {
+    if (!args.name) fail("use needs --name");
+    const used = useRecipe({ projectDir: args.hyperframes, name: args.name });
+    if (args.json) console.log(JSON.stringify({ ok: true, ...used }));
+    else {
+      console.log(
+        `using recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`,
+      );
+      console.log(`  frame spec → ${used.frameSpecPath} (copied over)`);
+      console.log(`  storyboard skeleton → ${used.skeletonPath}`);
+      if (used.briefSkeletonPath) console.log(`  brief skeleton → ${used.briefSkeletonPath}`);
+      for (const key of ["destination", "aspect", "language", "voice", "style_preset"]) {
+        if (used.recipe[key]) console.log(`  ${key}: ${used.recipe[key]}`);
+      }
+    }
+  } else {
+    fail(
+      "usage: recipe.mjs <freeze|list|use> --hyperframes . [--name <n>] [--workflow <w>] [--blocks a,b] [--json]",
+    );
+  }
+} catch (err) {
+  fail(err instanceof Error ? err.message : String(err));
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/resolve-plugin.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+test(
+  "plugin resolver uses the release CLI without a repository checkout",
+  { skip: process.platform === "win32" },
+  (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-resolve-plugin-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    mkdirSync(join(dir, "lib"));
+    for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+      copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(dir, file));
+    }
+    writeFileSync(
+      join(dir, "npx"),
+      `#!${process.execPath}\nconsole.log(JSON.stringify({args:process.argv.slice(2),skip:process.env.HYPERFRAMES_SKIP_SKILLS}));process.exit(7);`,
+      { mode: 0o755 },
+    );
+    const result = spawnSync(process.execPath, [join(dir, "resolve.mjs"), "--intent", "a & b"], {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PATH: `${dir}${delimiter}${process.env.PATH}`,
+        HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+        HYPERFRAMES_SKIP_SKILLS: "1",
+      },
+    });
+    assert.equal(result.status, 7, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout), {
+      args: ["--yes", "hyperframes@1.2.3", "media-use", "resolve", "--intent", "a & b"],
+      skip: "1",
+    });
+  },
+);
+
+test("helper package override keeps a contributor's local CLI", (t) => {
+  const root = mkdtempSync(join(tmpdir(), "hf-resolve-local-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const scripts = join(root, "skills/media-use/scripts");
+  mkdirSync(join(scripts, "lib"), { recursive: true });
+  mkdirSync(join(root, "packages/cli/dist"), { recursive: true });
+  for (const file of ["resolve.mjs", "lib/npx-sync.mjs"]) {
+    copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(scripts, file));
+  }
+  writeFileSync(join(root, "packages/cli/dist/cli.js"), 'console.log("local-cli");');
+  const result = spawnSync(process.execPath, [join(scripts, "resolve.mjs")], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      HYPERFRAMES_PLUGIN_VERSION: "",
+      HYPERFRAMES_SKILL_PKG_VERSION: "0.8.79",
+    },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout.trim(), "local-cli");
+});