dsh-hyperframes 0.10.2 → 0.11.0

package/skills/media-use/scripts/lib/coverage.test.mjs

@@ -0,0 +1,136 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { listTypes, getProviders } from "./registry.mjs";
+import { CAPABILITIES, listModels } from "./local-models.mjs";
+
+// Capstone: media-use must actually OWN each hyperframes media weakness. This
+// test enforces the weakness→owner matrix in references/meta.md so a claim can't rot — if
+// a capability's entrypoint disappears, this fails.
+
+const SKILL = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "..",
+  "..",
+  "..",
+  "skills",
+  "media-use",
+);
+
+test("weakness: audio-only → media-use resolves image + icon", () => {
+  for (const t of ["image", "icon"]) {
+    assert.ok(getProviders(t).length > 0, `no provider for ${t}`);
+  }
+});
+
+test("weakness: no third-party brand logos → media-use resolves logo", () => {
+  assert.ok(listTypes().includes("logo"), "logo type missing");
+  assert.deepEqual(
+    getProviders("logo").map((p) => p.name),
+    ["thesvg", "github.avatar", "favicon.ddg"],
+    "logo cascade incomplete",
+  );
+});
+
+test("weakness: no voice/audio gen → media-use exposes voice + the audio engine", () => {
+  assert.ok(listTypes().includes("voice"), "voice type missing");
+  assert.ok(getProviders("voice").length > 0, "no enabled voice provider (Bin approved)");
+  assert.ok(existsSync(join(SKILL, "audio", "scripts", "audio.mjs")), "audio engine missing");
+});
+
+test("weakness: scattered audio engine → consolidated under media-use (hyperframes-media gone)", () => {
+  assert.ok(existsSync(join(SKILL, "audio", "scripts", "lib", "tts.mjs")), "tts engine missing");
+  assert.ok(
+    existsSync(join(SKILL, "audio", "assets", "sfx", "manifest.json")),
+    "bundled SFX missing",
+  );
+});
+
+test("weakness: no media-ops → ops guidance reference exists", () => {
+  assert.ok(existsSync(join(SKILL, "references", "operations.md")), "operations.md missing");
+});
+
+test("weakness: no transcript-driven cutting → cut compiler entrypoints exist", async () => {
+  assert.ok(existsSync(join(SKILL, "scripts", "transcript-cut.mjs")), "transcript-cut missing");
+  assert.ok(
+    existsSync(join(dirname(fileURLToPath(import.meta.url)), "cutlist.mjs")),
+    "cutlist lib missing",
+  );
+  const cutlist = await import("./cutlist.mjs");
+  assert.equal(typeof cutlist.compileCutList, "function");
+});
+
+test("weakness: whisper.cpp is weak → better local ASR (Parakeet) entrypoint exists", async () => {
+  assert.ok(existsSync(join(SKILL, "scripts", "transcribe.mjs")), "transcribe.mjs missing");
+  const pw = await import("./parakeet-words.mjs");
+  assert.equal(typeof pw.mergeTokensToWords, "function", "token->word merge missing");
+  const lm = await import("./local-models.mjs");
+  const asr = lm.listModels("asr");
+  const parakeet = asr.find((m) => m.id === "parakeet-mlx");
+  assert.ok(parakeet && parakeet.rank === 0, "Parakeet must be the rank-0 preferred ASR");
+});
+
+test("weakness: no auto-duck/loudness → duck compiler and recipes exist", async () => {
+  assert.ok(existsSync(join(SKILL, "scripts", "audio-duck.mjs")), "audio-duck missing");
+  assert.ok(
+    existsSync(join(dirname(fileURLToPath(import.meta.url)), "duck.mjs")),
+    "duck lib missing",
+  );
+  assert.ok(existsSync(join(SKILL, "references", "operations.md")), "operations.md missing");
+  const duck = await import("./duck.mjs");
+  assert.equal(typeof duck.speechSpans, "function");
+  assert.equal(typeof duck.duckKeyframes, "function");
+});
+
+test("weakness: no cross-project memory → global cache + ingest entrypoints exist", async () => {
+  const cache = await import("./cache.mjs");
+  assert.equal(typeof cache.cachePut, "function");
+  assert.equal(typeof cache.promote, "function");
+  assert.equal(typeof cache.globalMediaDir, "function");
+  const freeze = await import("./freeze.mjs");
+  assert.equal(typeof freeze.isDirectMediaUrl, "function", "ingest URL guard missing");
+});
+
+// Wenbo (06-29): heygen free-usage is the default; local models are the opt-out
+// fallback ("if user no, then local"). We still assert the fallback table is
+// populated so the opt-out path stays real.
+test("weakness: weak local defaults → local models exist as the opt-out fallback (tts/asr/upscale)", () => {
+  for (const cap of ["tts", "asr", "upscale"]) {
+    assert.ok(CAPABILITIES.includes(cap), `capability ${cap} missing`);
+    assert.ok(listModels(cap).length > 0, `no local models for ${cap}`);
+  }
+});
+
+test("weakness: no image generation → local mflux (RAM-graded) + codex upsell", async () => {
+  const ps = getProviders("image");
+  assert.ok(
+    ps.some((p) => p.name === "mflux.local" && typeof p.generate === "function"),
+    "local image gen missing",
+  );
+  assert.ok(
+    ps.some((p) => p.name === "codex.image_gen" && typeof p.generate === "function"),
+    "codex image upsell missing",
+  );
+  const lm = await import("./local-models.mjs");
+  assert.ok(lm.CAPABILITIES.includes("imagegen"), "imagegen capability missing");
+  assert.ok(lm.listModels("imagegen").length >= 3, "imagegen RAM ladder too small");
+  assert.equal(typeof lm.describeModelLadder, "function", "agent-facing ladder missing");
+});
+
+test("weakness: no video generation → local videogen ladder + heygen avatar upsell", async () => {
+  const lm = await import("./local-models.mjs");
+  assert.ok(lm.CAPABILITIES.includes("videogen"), "videogen capability missing");
+  assert.ok(lm.listModels("videogen").length >= 2, "videogen ladder too small");
+  const ops = existsSync(join(SKILL, "references", "operations.md"));
+  assert.ok(ops, "operations.md (avatar-upsell recipe) missing");
+});
+
+test("every resolve type has at least one enabled provider", () => {
+  for (const t of listTypes()) {
+    assert.ok(getProviders(t).length > 0, `type ${t} has no enabled provider`);
+  }
+});

package/skills/media-use/scripts/lib/cube-build.mjs

@@ -0,0 +1,181 @@
+const DEFAULT_SIZE = 33;
+const MAX_SIZE = 64;
+
+function clamp(value, min, max) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(max, Math.max(min, value));
+}
+
+function clampUnit(value) {
+  return clamp(value, 0, 1);
+}
+
+function readParam(params, key, min, max) {
+  return clamp(Number(params?.[key] ?? 0), min, max);
+}
+
+function luma([r, g, b]) {
+  // Rec.709 luma weightings (matches the color space the grading runtime uses).
+  return r * 0.2126 + g * 0.7152 + b * 0.0722;
+}
+
+function smoothstep(edge0, edge1, value) {
+  const t = clampUnit((value - edge0) / (edge1 - edge0));
+  return t * t * (3 - 2 * t);
+}
+
+function applyLiftGain(color, params) {
+  const y = luma(color);
+  const blacks = readParam(params, "blacks", -1, 1);
+  const shadows = readParam(params, "shadows", -1, 1);
+  const highlights = readParam(params, "highlights", -1, 1);
+  const whites = readParam(params, "whites", -1, 1);
+  const shadowMask = 1 - smoothstep(0.18, 0.62, y);
+  const highlightMask = smoothstep(0.38, 0.82, y);
+  const offset =
+    blacks * 0.08 + shadows * 0.12 * shadowMask + highlights * 0.12 * highlightMask + whites * 0.08;
+  return color.map((channel) => clampUnit(channel + offset));
+}
+
+function applyExposure(color, params) {
+  const exposure = readParam(params, "exposure", -2, 2);
+  const gain = 2 ** exposure;
+  const lift = Math.max(0, exposure) * 0.015;
+  return color.map((channel) => clampUnit(channel * gain + lift));
+}
+
+function applyContrast(color, params) {
+  const contrast = readParam(params, "contrast", -1, 1);
+  if (contrast === 0) return color;
+  const factor = 1 + contrast * 1.2;
+  return color.map((channel) => clampUnit(0.5 + (channel - 0.5) * factor));
+}
+
+function applyWhiteBalance(color, params) {
+  const temperature = readParam(params, "temperature", -1, 1);
+  const tint = readParam(params, "tint", -1, 1);
+  const redScale = 1 + temperature * 0.28 + tint * 0.08;
+  const greenScale = 1 - Math.abs(tint) * 0.1 - tint * 0.08;
+  const blueScale = 1 - temperature * 0.28 + tint * 0.08;
+  return [
+    clampUnit(color[0] * redScale),
+    clampUnit(color[1] * greenScale),
+    clampUnit(color[2] * blueScale),
+  ];
+}
+
+function applySplitTone(color, params) {
+  const split = params?.splitTone;
+  if (!split) return color;
+  const intensity = clampUnit(Number(split.intensity ?? 0));
+  if (intensity === 0) return color;
+  const balance = clampUnit(Number(split.balance ?? 0.5));
+  const y = luma(color);
+  const shadowMask = 1 - smoothstep(balance - 0.25, balance + 0.2, y);
+  const highlightMask = smoothstep(balance - 0.2, balance + 0.25, y);
+  const shadows = Array.isArray(split.shadows) ? split.shadows : [0, 0, 0];
+  const highlights = Array.isArray(split.highlights) ? split.highlights : [0, 0, 0];
+  return color.map((channel, i) =>
+    clampUnit(
+      channel +
+        Number(shadows[i] ?? 0) * shadowMask * intensity +
+        Number(highlights[i] ?? 0) * highlightMask * intensity,
+    ),
+  );
+}
+
+function applySaturation(color, params) {
+  const saturation = readParam(params, "saturation", -1, 1);
+  const vibrance = readParam(params, "vibrance", -1, 1);
+  if (saturation === 0 && vibrance === 0) return color;
+  const y = luma(color);
+  const currentSat = Math.max(
+    Math.abs(color[0] - y),
+    Math.abs(color[1] - y),
+    Math.abs(color[2] - y),
+  );
+  const vibranceWeight = 1 - clampUnit(currentSat * 2);
+  const factor = clamp(1 + saturation + vibrance * vibranceWeight, 0, 2.5);
+  return color.map((channel) => clampUnit(y + (channel - y) * factor));
+}
+
+function applyParams(color, params) {
+  let out = applyLiftGain(color, params);
+  out = applyExposure(out, params);
+  out = applyContrast(out, params);
+  out = applyWhiteBalance(out, params);
+  out = applySplitTone(out, params);
+  out = applySaturation(out, params);
+  return out;
+}
+
+function formatNumber(value) {
+  return clampUnit(value).toFixed(6);
+}
+
+export function buildCube(params = {}, size = DEFAULT_SIZE) {
+  if (!Number.isInteger(size) || size < 2 || size > MAX_SIZE) {
+    throw new Error(`LUT size must be an integer from 2 to ${MAX_SIZE}`);
+  }
+  const lines = [
+    `TITLE "media-use parametric grade"`,
+    "DOMAIN_MIN 0 0 0",
+    "DOMAIN_MAX 1 1 1",
+    `LUT_3D_SIZE ${size}`,
+  ];
+  const denom = size - 1;
+  for (let b = 0; b < size; b++) {
+    for (let g = 0; g < size; g++) {
+      for (let r = 0; r < size; r++) {
+        const out = applyParams([r / denom, g / denom, b / denom], params);
+        lines.push(`${formatNumber(out[0])} ${formatNumber(out[1])} ${formatNumber(out[2])}`);
+      }
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function paramsFromIntent(intent) {
+  const text = String(intent ?? "").toLowerCase();
+  const params = {};
+  let matched = false;
+
+  if (/\b(warm|golden|sunlit|sunny)\b/.test(text)) {
+    params.temperature = 0.18;
+    matched = true;
+  } else if (/\b(cool|blue|icy|crisp)\b/.test(text)) {
+    params.temperature = -0.16;
+    matched = true;
+  }
+
+  if (/\b(cinematic|film|movie)\b/.test(text)) {
+    params.contrast = 0.08;
+    params.saturation = 0.04;
+    matched = true;
+  }
+  if (/\b(punchy|contrast|dramatic|bold)\b/.test(text)) {
+    params.contrast = Math.max(params.contrast ?? 0, 0.22);
+    matched = true;
+  }
+  if (/\b(bright|airy|lift)\b/.test(text)) {
+    params.exposure = 0.16;
+    params.shadows = 0.08;
+    matched = true;
+  }
+  if (/\b(dark|moody|low-key)\b/.test(text)) {
+    params.exposure = -0.12;
+    params.contrast = Math.max(params.contrast ?? 0, 0.12);
+    matched = true;
+  }
+  if (/\b(vibrant|saturated|colorful)\b/.test(text)) {
+    params.saturation = Math.max(params.saturation ?? 0, 0.16);
+    params.vibrance = 0.12;
+    matched = true;
+  }
+  if (/\b(muted|desaturated|washed)\b/.test(text)) {
+    params.saturation = Math.min(params.saturation ?? 0, -0.16);
+    matched = true;
+  }
+
+  return matched ? params : null;
+}

package/skills/media-use/scripts/lib/cube-build.test.mjs

@@ -0,0 +1,80 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { buildCube, paramsFromIntent } from "./cube-build.mjs";
+import { validateCube } from "./cube-validate.mjs";
+
+function rows(cube) {
+  return cube
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => /^[+-]?(?:\d|\.\d)/.test(line))
+    .map((line) => line.split(/\s+/).map(Number));
+}
+
+function rowAt(cubeRows, size, r, g, b) {
+  return cubeRows[(b * size + g) * size + r];
+}
+
+function luma(row) {
+  return row[0] * 0.2126 + row[1] * 0.7152 + row[2] * 0.0722;
+}
+
+test("all-zero params produce a near-identity LUT", () => {
+  const cube = buildCube({}, 3);
+  assert.equal(validateCube(cube).ok, true);
+  const parsed = rows(cube);
+  for (let b = 0; b < 3; b++) {
+    for (let g = 0; g < 3; g++) {
+      for (let r = 0; r < 3; r++) {
+        const row = rowAt(parsed, 3, r, g, b);
+        assert.ok(Math.abs(row[0] - r / 2) < 0.000001);
+        assert.ok(Math.abs(row[1] - g / 2) < 0.000001);
+        assert.ok(Math.abs(row[2] - b / 2) < 0.000001);
+      }
+    }
+  }
+});
+
+test("positive exposure increases unclipped output luma", () => {
+  const identity = rows(buildCube({}, 5));
+  const exposed = rows(buildCube({ exposure: 0.3 }, 5));
+  for (let i = 0; i < identity.length; i++) {
+    const before = luma(identity[i]);
+    if (before > 0.02 && before < 0.95) {
+      assert.ok(luma(exposed[i]) > before, `row ${i} should brighten`);
+    }
+  }
+});
+
+test("positive temperature warms mid-gray", () => {
+  const parsed = rows(buildCube({ temperature: 0.2 }, 3));
+  const mid = rowAt(parsed, 3, 1, 1, 1);
+  assert.ok(mid[0] > 0.5, "red channel should rise");
+  assert.ok(mid[2] < 0.5, "blue channel should fall");
+});
+
+test("positive contrast darkens shadows and brightens highlights", () => {
+  const parsed = rows(buildCube({ contrast: 0.3 }, 5));
+  const shadow = rowAt(parsed, 5, 1, 1, 1);
+  const highlight = rowAt(parsed, 5, 3, 3, 3);
+  assert.ok(luma(shadow) < 0.25, "below-mid gray should darken");
+  assert.ok(luma(highlight) > 0.75, "above-mid gray should brighten");
+});
+
+test("outputs validate at the default size and are deterministic", () => {
+  const params = { exposure: 0.15, contrast: 0.2, temperature: -0.1, saturation: 0.12 };
+  const a = buildCube(params);
+  const b = buildCube(params);
+  assert.equal(a, b);
+  assert.equal(validateCube(a).ok, true);
+  assert.equal(validateCube(a).size, 33);
+});
+
+test("paramsFromIntent declines zero-overlap prompts and maps technical words", () => {
+  assert.equal(paramsFromIntent("zqxv imaginary neutron look"), null);
+  assert.deepEqual(paramsFromIntent("warm cinematic"), {
+    temperature: 0.18,
+    contrast: 0.08,
+    saturation: 0.04,
+  });
+});

package/skills/media-use/scripts/lib/cube-validate.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+// Standalone mirror of packages/core/src/colorLuts.ts. media-use cannot import
+// the TypeScript source at runtime, so cube-validate.test.mjs mirrors core
+// parser cases to catch drift in accepted .cube files before freezing them.
+
+import { readFileSync } from "node:fs";
+import { isMainModule } from "./main-module.mjs";
+
+export const DEFAULT_MAX_CUBE_LUT_SIZE = 64;
+
+const DEFAULT_DOMAIN_MIN = [0, 0, 0];
+const DEFAULT_DOMAIN_MAX = [1, 1, 1];
+
+class CubeValidateError extends Error {
+  constructor(message, lineNumber = null) {
+    super(lineNumber == null ? message : `${message} at line ${lineNumber}`);
+    this.name = "CubeValidateError";
+    this.lineNumber = lineNumber;
+  }
+}
+
+function stripComment(line) {
+  let inQuote = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') inQuote = !inQuote;
+    if (char === "#" && !inQuote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseFiniteNumber(value, lineNumber) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new CubeValidateError(`Invalid number "${value}"`, lineNumber);
+  }
+  return parsed;
+}
+
+function parseVec3(parts, keyword, lineNumber) {
+  if (parts.length !== 3) {
+    throw new CubeValidateError(`${keyword} expects three numbers`, lineNumber);
+  }
+  return [
+    parseFiniteNumber(parts[0], lineNumber),
+    parseFiniteNumber(parts[1], lineNumber),
+    parseFiniteNumber(parts[2], lineNumber),
+  ];
+}
+
+function parseSize(value, keyword, lineNumber) {
+  if (!value) throw new CubeValidateError(`${keyword} expects a size`, lineNumber);
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 2) {
+    throw new CubeValidateError(`${keyword} must be an integer greater than 1`, lineNumber);
+  }
+  return parsed;
+}
+
+function validateDomain(domainMin, domainMax) {
+  if (
+    domainMax[0] <= domainMin[0] ||
+    domainMax[1] <= domainMin[1] ||
+    domainMax[2] <= domainMin[2]
+  ) {
+    throw new CubeValidateError("DOMAIN_MAX values must be greater than DOMAIN_MIN values");
+  }
+}
+
+function isNumericDataLine(token) {
+  return /^[+-]?(?:\d|\.\d)/.test(token);
+}
+
+function parseCube(input, options = {}) {
+  const maxSize = options.maxSize ?? DEFAULT_MAX_CUBE_LUT_SIZE;
+  let domainMin = DEFAULT_DOMAIN_MIN;
+  let domainMax = DEFAULT_DOMAIN_MAX;
+  let lut1dSize = null;
+  let lut3dSize = null;
+  let rows = 0;
+
+  const lines = String(input)
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1;
+    const line = stripComment(lines[i] ?? "").trim();
+    if (!line) continue;
+    const parts = line.split(/\s+/);
+    const keyword = (parts[0] ?? "").toUpperCase();
+    const rest = parts.slice(1);
+
+    if (keyword === "TITLE") continue;
+    if (keyword === "DOMAIN_MIN") {
+      domainMin = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "DOMAIN_MAX") {
+      domainMax = parseVec3(rest, keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_INPUT_RANGE") {
+      if (rest.length !== 2) {
+        throw new CubeValidateError(`${keyword} expects two numbers`, lineNumber);
+      }
+      const min = parseFiniteNumber(rest[0], lineNumber);
+      const max = parseFiniteNumber(rest[1], lineNumber);
+      if (max <= min) {
+        throw new CubeValidateError("LUT_3D_INPUT_RANGE max must exceed min", lineNumber);
+      }
+      domainMin = [min, min, min];
+      domainMax = [max, max, max];
+      continue;
+    }
+    if (keyword === "LUT_1D_SIZE") {
+      lut1dSize = parseSize(rest[0], keyword, lineNumber);
+      continue;
+    }
+    if (keyword === "LUT_3D_SIZE") {
+      lut3dSize = parseSize(rest[0], keyword, lineNumber);
+      if (lut3dSize > maxSize) {
+        throw new CubeValidateError(`LUT_3D_SIZE ${lut3dSize} exceeds max ${maxSize}`, lineNumber);
+      }
+      continue;
+    }
+
+    if (!isNumericDataLine(keyword)) {
+      if (keyword.startsWith("LUT_")) {
+        throw new CubeValidateError(`Unsupported cube keyword ${keyword}`, lineNumber);
+      }
+      continue;
+    }
+    if (!lut3dSize) {
+      if (lut1dSize) {
+        throw new CubeValidateError("1D cube LUTs are not supported yet", lineNumber);
+      }
+      throw new CubeValidateError("LUT data appears before LUT_3D_SIZE", lineNumber);
+    }
+    if (parts.length !== 3) {
+      throw new CubeValidateError("LUT data rows must contain three numbers", lineNumber);
+    }
+    parseFiniteNumber(parts[0], lineNumber);
+    parseFiniteNumber(parts[1], lineNumber);
+    parseFiniteNumber(parts[2], lineNumber);
+    rows++;
+  }
+
+  if (lut1dSize && lut3dSize) {
+    throw new CubeValidateError("Mixed 1D and 3D cube LUTs are not supported yet");
+  }
+  if (!lut3dSize) {
+    if (lut1dSize) throw new CubeValidateError("1D cube LUTs are not supported yet");
+    throw new CubeValidateError("Missing LUT_3D_SIZE");
+  }
+  validateDomain(domainMin, domainMax);
+
+  const expectedRows = lut3dSize * lut3dSize * lut3dSize;
+  if (rows !== expectedRows) {
+    throw new CubeValidateError(
+      `Expected ${expectedRows} LUT rows for size ${lut3dSize}, found ${rows}`,
+    );
+  }
+
+  return { size: lut3dSize };
+}
+
+export function validateCube(input, options = {}) {
+  try {
+    const parsed = parseCube(input, options);
+    return { ok: true, size: parsed.size };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+export function validateCubeFile(filePath, options = {}) {
+  return validateCube(readFileSync(filePath, "utf8"), options);
+}
+
+function main(argv) {
+  const file = argv[2];
+  if (!file) {
+    console.error("usage: cube-validate.mjs <file.cube>");
+    process.exit(2);
+  }
+  const result = validateCubeFile(file);
+  if (!result.ok) {
+    console.error(`error: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`ok: LUT_3D_SIZE ${result.size}`);
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv);
+}