hyperframes 0.8.57 → 0.8.59

package/dist/skills/media-use/scripts/lib/media-search.mjs

@@ -0,0 +1,107 @@
+const STOP = new Set(
+  (
+    "the a an and or of to in on at is are be it its for with that this as by from into " +
+    "one two must not no all over under across while when where which who whom whose they " +
+    "them their we our you your he she his her but if then than so such can may might will " +
+    "would should each other another same both few more most some any every"
+  ).split(" "),
+);
+
+const PLURAL_RULES = [
+  [/([^aeiou])ies$/, "$1y"],
+  [/(ch|sh|ss|x)es$/, "$1"],
+  [/(ss|us|is)$/, "$&"],
+  [/s$/, ""],
+];
+const STRONG_FIELD_WEIGHT = 3;
+const INFERRED_TOKEN_WEIGHT = 0.35;
+
+function singularize(word) {
+  if (word.length <= 3) return word;
+  for (const [pattern, replacement] of PLURAL_RULES) {
+    if (pattern.test(word)) return word.replace(pattern, replacement);
+  }
+  return word;
+}
+
+function tokenize(text) {
+  const words =
+    String(text)
+      .toLowerCase()
+      .match(/[a-z]+/g) || [];
+  return words.filter((word) => word.length > 2 && !STOP.has(word)).map(singularize);
+}
+
+export function rankMediaRows(query, rows) {
+  const asked = tokenize(query);
+  const normalizedLiteralQuery = String(query).trim().toLowerCase();
+  const normalizedQuery = asked.join(" ");
+  const want = new Map(asked.map((token) => [token, 1]));
+  if (want.size === 0) return [];
+
+  const parsed = rows.map((row) => {
+    const strongTokens = new Set(tokenize(`${row.id} ${row.title}`));
+    const allTokens = new Set([
+      ...strongTokens,
+      ...tokenize(`${row.description} ${row.tags.join(" ")} ${row.kind}`),
+    ]);
+    return {
+      row,
+      strongTokens,
+      allTokens,
+      literalId: row.id.trim().toLowerCase() === normalizedLiteralQuery,
+      stemmedId: tokenize(row.id).join(" ") === normalizedQuery,
+    };
+  });
+  const vocabulary = new Set(parsed.flatMap(({ allTokens }) => [...allTokens]));
+  for (const token of asked) {
+    if (token.length < 6) continue;
+    for (let cut = 3; cut <= token.length - 3; cut++) {
+      const head = token.slice(0, cut);
+      const tail = token.slice(cut);
+      if (vocabulary.has(head) && vocabulary.has(tail)) {
+        want.set(head, INFERRED_TOKEN_WEIGHT);
+        want.set(tail, INFERRED_TOKEN_WEIGHT);
+        break;
+      }
+    }
+  }
+  for (let index = 0; index < asked.length - 1; index++) {
+    const joined = `${asked[index]}${asked[index + 1]}`;
+    if (vocabulary.has(joined)) want.set(joined, INFERRED_TOKEN_WEIGHT);
+  }
+
+  const idf = new Map();
+  for (const token of want.keys()) {
+    const documentFrequency = parsed.filter(({ allTokens }) => allTokens.has(token)).length;
+    idf.set(token, Math.log((parsed.length + 1) / (documentFrequency + 1)) + 1);
+  }
+  return parsed
+    .map(({ row, strongTokens, allTokens, literalId, stemmedId }) => {
+      let score = 0;
+      for (const [token, asking] of want) {
+        const weight = (idf.get(token) || 1) * asking;
+        if (strongTokens.has(token)) score += STRONG_FIELD_WEIGHT * weight;
+        else if (allTokens.has(token)) score += weight;
+      }
+      return { row, score, literalId, stemmedId };
+    })
+    .filter(({ score }) => score > 0)
+    .sort(
+      (a, b) =>
+        Number(b.literalId) - Number(a.literalId) ||
+        Number(b.stemmedId) - Number(a.stemmedId) ||
+        b.score - a.score,
+    )
+    .map(({ row }) => row);
+}
+
+export async function rankMediaRowsWithVectors(query, rows, semanticRanking) {
+  const words = rankMediaRows(query, rows);
+  if (words.length > 0) return { rows: words, tier: "words" };
+  if (!semanticRanking) return { rows: [], tier: "words" };
+  const semantic = await semanticRanking(query, rows);
+  return semantic
+    ? { rows: semantic.map(({ row }) => row), tier: "on-device" }
+    : { rows: [], tier: "words" };
+}

package/dist/skills/media-use/scripts/lib/mflux-provider.mjs

@@ -0,0 +1,128 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describeDownload, probeSpecs } from "./specs.mjs";
+import { buildArgv, selectModelLadder } from "./local-models.mjs";
+
+// Local image generation via mflux (FLUX-on-MLX), the Mac-native runner.
+// Spec-gated: selectModelLadder("imagegen", specs) returns every FLUX-class
+// model the machine's AVAILABLE RAM can actually run (medium FLUX-schnell
+// --low-ram on ~24GB, up to Qwen-Image on 64GB+), best first. When nothing
+// local fits, or no fitting tier can actually run here, this returns null so
+// the registry falls through to the codex image upsell.
+//
+// The official FLUX repos are HF-gated, so the model entries point --path at
+// non-gated community 4-bit re-uploads; the repo is resolved to a local snapshot
+// (hf download, idempotent) because a bare repo id breaks mlx unflatten.
+
+// Resolve an HF repo to its local snapshot dir. `hf download` is idempotent and
+// prints the snapshot path as its last line.
+function resolveSnapshot(repo, execFn, pathExists) {
+  const out = execFn("hf", ["download", repo], {
+    encoding: "utf8",
+    timeout: 1_800_000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const path = out?.trim().split(/\r?\n/).pop()?.trim();
+  return path && pathExists(path) ? path : null;
+}
+
+export async function mfluxImageGenerate(
+  intent,
+  ctx,
+  execFn = execFileSync,
+  pathExists = existsSync,
+  unlinkFn = unlinkSync,
+) {
+  const specs = ctx?.specs || probeSpecs();
+  const ladder = selectModelLadder("imagegen", specs, { preferTier: ctx?.preferTier });
+  if (!ladder.length) return null; // no local model fits -> codex upsell/fallback
+
+  // Each attempt mints its own timestamped output path, so a partial artifact
+  // from a failed tier is orphaned rather than overwritten - and a lower tier
+  // then succeeding hides it. Discard it before demoting. Best-effort: a
+  // partial we cannot remove must never mask the real failure.
+  const discardPartial = (path) => {
+    try {
+      if (pathExists(path)) unlinkFn(path);
+    } catch {
+      // nothing actionable: the generate failure below is the real story
+    }
+  };
+
+  // Best tier first, demoting past any tier that cannot run here (runner off
+  // PATH, a snapshot that won't download, an OOM) rather than failing local
+  // image gen outright. Every demotion is reported, so a quietly smaller model
+  // is never mistaken for the tier the machine nominally qualified for.
+  for (const model of ladder) {
+    const bin = model.invoke.trim().split(/\s+/)[0];
+    // Not installed? Surface the exact enable-command (before the model
+    // download) so the agent learns the free local path is available instead of
+    // silently taking the codex upsell.
+    try {
+      execFn("which", [bin], { stdio: ["ignore", "ignore", "ignore"] });
+    } catch {
+      console.error(
+        `media-use: local image gen not enabled (\`${bin}\` not on PATH). Install for free on-device FLUX: ${model.install}. Heads up: ${model.id} ${describeDownload(model.sizeMB)}.`,
+      );
+      continue;
+    }
+
+    const outPath = join(tmpdir(), `media-use-mflux-${process.pid}-${Date.now()}.png`);
+    const vars = {
+      prompt: intent,
+      w: ctx?.width || 512,
+      h: ctx?.height || 512,
+      seed: ctx?.seed ?? 42,
+      out: outPath,
+    };
+    if (model.repo && model.invoke.includes("{model_path}")) {
+      let snap = null;
+      let why = `could not resolve a local snapshot of ${model.repo}`;
+      try {
+        snap = resolveSnapshot(model.repo, execFn, pathExists);
+      } catch (err) {
+        why = `hf download failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`;
+      }
+      if (!snap) {
+        console.error(`media-use: local image gen (${model.id}): ${why}`);
+        continue;
+      }
+      vars.model_path = snap;
+    }
+
+    const argv = buildArgv(model.invoke, vars);
+    argv.shift(); // drop the bin (already validated)
+    try {
+      execFn(bin, argv, {
+        encoding: "utf8",
+        timeout: 1_800_000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (err) {
+      discardPartial(outPath);
+      console.error(
+        `media-use: local image gen (${model.id}) failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`,
+      );
+      continue;
+    }
+    if (!pathExists(outPath)) {
+      console.error(
+        `media-use: local image gen (${model.id}) exited cleanly but wrote no output file`,
+      );
+      continue;
+    }
+    return {
+      localPath: outPath,
+      ext: ".png",
+      source: "generated",
+      metadata: {
+        description: intent,
+        provider: `mflux.${model.id}`,
+        provenance: { model: model.id, tier: model.tier, prompt: intent },
+      },
+    };
+  }
+  return null;
+}

package/dist/skills/media-use/scripts/lib/mflux-provider.test.mjs

@@ -0,0 +1,174 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mfluxImageGenerate } from "./mflux-provider.mjs";
+
+// 40GB clears the 32GB klein tier and the 8GB schnell tier below it; the 64GB
+// qwen tier stays out of reach. Two rungs is what makes demotion observable.
+const bothTiersSpecs = { availableRamMB: 40000, gpu: { present: true } };
+const SNAPSHOT = "/tmp/hf-snapshot";
+
+// exec stub covering all three shells-out mflux does: the PATH probe, the
+// idempotent `hf download`, and the generate itself.
+function stubExec({ failGenerateFor = [], failWhichFor = [] } = {}) {
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") {
+      if (failWhichFor.includes(argv[0])) throw new Error("not found");
+      return "";
+    }
+    if (bin === "hf") return `Fetching 6 files...\n${SNAPSHOT}\n`;
+    if (failGenerateFor.some((id) => argv.join(" ").includes(id))) {
+      const err = new Error("exit 1");
+      err.stderr = "mlx.core.metal: out of memory";
+      throw err;
+    }
+    return "";
+  };
+  return { calls, exec };
+}
+
+const generateCalls = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => argv.join(" "));
+
+test("no local model fits: falls through to the upsell without shelling out", async () => {
+  const { calls, exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: { availableRamMB: 100, gpu: { present: true } } },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(calls, []);
+});
+
+test("a top tier that cannot run demotes to the next fitting tier", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  const generated = generateCalls(calls);
+  assert.equal(generated.length, 2, "klein attempted first, then schnell");
+  assert.match(generated[0], /flux2-klein-4b/);
+  assert.match(generated[1], /--model schnell/);
+  assert.equal(errors.length, 1, "the demotion is reported, not silent");
+  assert.match(errors[0], /flux2-klein-mflux-q4\) failed/);
+});
+
+test("a snapshot that will not resolve demotes rather than failing outright", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") return "";
+    // klein's weights won't download; schnell's do
+    if (bin === "hf") {
+      if (argv[1].includes("FLUX.2-klein")) throw new Error("403 Forbidden");
+      return `${SNAPSHOT}\n`;
+    }
+    return "";
+  };
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "demoted past the ungettable weights");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /hf download failed/);
+});
+
+test("runner missing from PATH reports the install hint per tier and returns null", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { exec } = stubExec({ failWhichFor: ["mflux-generate"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.equal(errors.length, 2, "both fitting tiers reported");
+  assert.match(errors[0], /uv pip install mflux/);
+  // each hint states that tier's download cost before the user commits
+  assert.match(errors[0], /GB of weights to/);
+  assert.match(errors[1], /GB of weights to/);
+});
+
+// Same per-attempt temp path, same orphaning risk as the LTX provider: a
+// partial png from a failed tier must not survive a lower tier succeeding.
+const outputOf = (argv) => argv[argv.indexOf("--output") + 1];
+const attemptedOutputs = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => outputOf(argv));
+
+test("a failed attempt's partial output is discarded before demoting", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.deepEqual(unlinked, [attemptedOutputs(calls)[0]], "the failed klein partial is removed");
+});
+
+test("every tier failing discards every partial, one per attempt", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b", "schnell"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(unlinked, attemptedOutputs(calls), "nothing is left behind");
+});
+
+test("a successful generation is never discarded", async () => {
+  const unlinked = [];
+  const { exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result);
+  assert.deepEqual(unlinked, [], "the returned artifact must survive");
+});

package/dist/skills/media-use/scripts/lib/misses.mjs

@@ -0,0 +1,49 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MISSES_FILE = "misses.jsonl";
+
+function missesPath() {
+  return join(homedir(), ".media", MISSES_FILE);
+}
+
+export function recordMiss({ type, intent, provider_override, local_only }) {
+  try {
+    const dir = join(homedir(), ".media");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      join(dir, MISSES_FILE),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        type,
+        intent,
+        provider_override: !!provider_override,
+        local_only: !!local_only,
+      }) + "\n",
+    );
+  } catch {
+    // local miss logging is best-effort; never surface into resolve
+  }
+}
+
+export function readMisses() {
+  const p = missesPath();
+  try {
+    if (!existsSync(p)) return [];
+    const raw = readFileSync(p, "utf8");
+    const records = [];
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        records.push(JSON.parse(trimmed));
+      } catch {
+        // skip malformed local lines, don't crash stats
+      }
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}

package/dist/skills/media-use/scripts/lib/misses.test.mjs

@@ -0,0 +1,78 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readMisses, recordMiss } from "./misses.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-misses-"));
+  const home = join(root, "home");
+  mkdirSync(home, { recursive: true });
+  process.env.HOME = home;
+  return { root, home };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+test("recordMiss appends a well-formed local miss", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    recordMiss({ type: "bgm", intent: "moody synth pulse", provider_override: true });
+    const misses = readMisses();
+    assert.equal(misses.length, 1);
+    assert.equal(misses[0].type, "bgm");
+    assert.equal(misses[0].intent, "moody synth pulse");
+    assert.equal(misses[0].provider_override, true);
+    assert.equal(misses[0].local_only, false);
+    assert.ok(!Number.isNaN(Date.parse(misses[0].ts)));
+
+    const raw = readFileSync(join(home, ".media/misses.jsonl"), "utf8");
+    assert.match(raw, /moody synth pulse/);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("recordMiss swallows filesystem failures", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    writeFileSync(join(home, ".media"), "not a directory");
+    assert.doesNotThrow(() =>
+      recordMiss({ type: "image", intent: "unwritable", local_only: true }),
+    );
+    assert.equal(existsSync(join(home, ".media/misses.jsonl")), false);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readMisses skips corrupt lines", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(
+      join(home, ".media/misses.jsonl"),
+      [
+        JSON.stringify({ ts: "2026-07-09T00:00:00.000Z", type: "bgm", intent: "one" }),
+        "{not json",
+        JSON.stringify({ ts: "2026-07-09T00:00:01.000Z", type: "sfx", intent: "two" }),
+      ].join("\n"),
+    );
+    assert.deepEqual(
+      readMisses().map((miss) => miss.intent),
+      ["one", "two"],
+    );
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/skills/media-use/scripts/lib/npx-sync.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
+
+// Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites
+// that must hard-fail (rather than fall through to another provider) when npx
+// cannot be resolved. On Windows a bare "npx" is npx.cmd, which
+// execFileSync/spawnSync cannot exec (spawnSync npx ENOENT) —
+// resolveSpawnCommand reroutes it through node + npx-cli.js, no shell:true.
+//
+// `platform`/`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 and
+// localTtsGenerate.
+export function resolveNpxInvocation(
+  argv,
+  opts,
+  platform = process.platform,
+  env = process.env,
+  pathExists = existsSync,
+) {
+  const resolved = resolveSpawnCommand("npx", argv, opts, platform, env, pathExists);
+  if (!resolved) {
+    // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
+    // spawnP warns about, surfaced as a throw for callers with no fallback.
+    throw new Error(
+      "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 resolved;
+}

package/dist/skills/media-use/scripts/lib/npx-sync.test.mjs

@@ -0,0 +1,50 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveNpxInvocation } from "./npx-sync.mjs";
+
+// Coverage parity with tts-local-provider.test.mjs, for the whisper.cpp
+// fallback's call-site shape (transcribe.mjs runWhisper): the same three
+// branches, but with the hard-fail contract — no fallback provider exists,
+// so an unresolvable npx must throw actionably instead of returning null.
+
+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;
+
+const WHISPER_ARGV = ["hyperframes", "transcribe", "C:\\media\\input.wav", "--dir", "C:\\work"];
+const WHISPER_OPTS = { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 };
+
+test("win32: routes the whisper fallback through node + npx-cli, never bare npx", () => {
+  const resolved = resolveNpxInvocation(
+    WHISPER_ARGV,
+    WHISPER_OPTS,
+    "win32",
+    envWithNpxCli,
+    pathExists,
+  );
+
+  assert.equal(resolved.cmd, envWithNpxCli.npm_node_execpath);
+  assert.equal(resolved.args[0], npxCliPath);
+  assert.deepEqual(resolved.args.slice(1, 3), ["hyperframes", "transcribe"]);
+  // execFileSync options survive the rerouting (the timeout bounds the
+  // whisper build/model download; the pipes surface its errors).
+  assert.deepEqual(resolved.opts.stdio, ["ignore", "pipe", "pipe"]);
+  assert.equal(resolved.opts.timeout, 1_800_000);
+});
+
+test("win32 without a resolvable npx-cli: throws the actionable install hint", () => {
+  assert.throws(
+    () => resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "win32", {}, () => false),
+    /npx-cli\.js was not found/,
+  );
+});
+
+test("non-win32: spawns plain npx unchanged", () => {
+  const resolved = resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "darwin", {}, () => false);
+
+  assert.equal(resolved.cmd, "npx");
+  assert.deepEqual(resolved.args, WHISPER_ARGV);
+});

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

@@ -0,0 +1,27 @@
+// Merge Parakeet-MLX token timestamps into word timestamps.
+//
+// parakeet-mlx JSON emits SUB-WORD tokens (" H", "ello", ...) with per-token
+// start/end. Captions + transcript-cut need WORD timestamps, so join tokens
+// into words on the space boundary: a token whose text starts with a space
+// (or the very first token) begins a new word; the rest append. Output matches
+// the { words: [{ text, start, end }] } shape the rest of media-use consumes
+// (see words.mjs / cutlist.mjs).
+
+export function mergeTokensToWords(parakeet) {
+  const sentences = Array.isArray(parakeet?.sentences) ? parakeet.sentences : [];
+  const words = [];
+  for (const s of sentences) {
+    for (const t of s.tokens ?? []) {
+      const raw = typeof t.text === "string" ? t.text : "";
+      const startsWord = raw.startsWith(" ") || words.length === 0;
+      if (startsWord) {
+        words.push({ text: raw.trim(), start: t.start, end: t.end });
+      } else {
+        const w = words[words.length - 1];
+        w.text += raw;
+        w.end = t.end;
+      }
+    }
+  }
+  return { text: (parakeet?.text ?? "").trim(), words: words.filter((w) => w.text.length > 0) };
+}