hyperframes 0.8.58 → 0.8.60

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

@@ -0,0 +1,95 @@
+import { wordListsFromMediaMeta } from "./words.mjs";
+
+// audio_meta.json word times are relative to each line's own file.
+export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false, gap = 0 } = {}) {
+  const merge = Number(mergeGap);
+  const lists = wordListsFromMediaMeta(meta);
+  const voices = Array.isArray(meta?.voices) ? meta.voices : [];
+  if (lists.length > 1 && !offsets && !sequential) {
+    throw new Error(
+      "audio_meta has multiple voice lines with file-relative times; pass --sequential or --offsets so spans land at composition time",
+    );
+  }
+  const intervals = [];
+  let cursor = 0;
+  for (let i = 0; i < lists.length; i++) {
+    const voice = voices[i];
+    let offset = 0;
+    if (offsets) {
+      const id = voice?.id ?? String(i);
+      if (!(id in offsets)) throw new Error(`--offsets is missing voice "${id}"`);
+      offset = Number(offsets[id]) || 0;
+    } else if (sequential) {
+      offset = cursor;
+      const lineDuration = Number(voice?.duration_s) || Math.max(...lists[i].map((w) => w.end), 0);
+      cursor += lineDuration + (Number(gap) || 0);
+    }
+    for (const word of lists[i]) {
+      if (word.end > word.start)
+        intervals.push({ start: word.start + offset, end: word.end + offset });
+    }
+  }
+  return mergeIntervals(intervals, Number.isFinite(merge) && merge >= 0 ? merge : 0.6);
+}
+
+export function duckKeyframes(
+  spans,
+  { duck = 0.25, attack = 0.15, release = 0.4, baseVolume = 1 } = {},
+) {
+  const base = finiteOr(baseVolume, 1);
+  const ducked = round3(base * finiteOr(duck, 0.25));
+  const keyframes = [];
+  for (const span of spans) {
+    keyframes.push({
+      time: round3(Math.max(0, finiteOr(span.start, 0))),
+      volume: ducked,
+      duration: round3(finiteOr(attack, 0.15)),
+    });
+    keyframes.push({
+      time: round3(Math.max(0, finiteOr(span.end, 0))),
+      volume: round3(base),
+      duration: round3(finiteOr(release, 0.4)),
+    });
+  }
+  return keyframes.sort((a, b) => a.time - b.time);
+}
+
+/** Volume lane for `data-automation`: composition-time keyframes as clip-local ramps. */
+export function duckLane(keyframes, { clipStart = 0, baseVolume = 1 } = {}) {
+  const start = finiteOr(clipStart, 0);
+  const points = [{ t: 0, v: round3(finiteOr(baseVolume, 1)) }];
+  const push = (t, v) => {
+    if (t > points.at(-1).t) points.push({ t: round3(t), v });
+  };
+  for (const kf of keyframes) {
+    const t = Math.max(0, kf.time - start);
+    push(t, points.at(-1).v);
+    push(t + kf.duration, kf.volume);
+  }
+  return { version: 1, lanes: [{ target: "volume", points }] };
+}
+
+function mergeIntervals(intervals, mergeGap) {
+  const sorted = intervals
+    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const range of sorted) {
+    const prev = merged.at(-1);
+    if (prev && (range.start <= prev.end || range.start - prev.end < mergeGap)) {
+      prev.end = Math.max(prev.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function finiteOr(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}

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

@@ -0,0 +1,153 @@
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { duckKeyframes, duckLane, speechSpans } from "./duck.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Keep the skill-owned wrapper path under test until the compatibility layer
+// is removed in a later release.
+const SCRIPT = join(
+  HERE,
+  "..",
+  "..",
+  "..",
+  "..",
+  "..",
+  "skills",
+  "media-use",
+  "scripts",
+  "audio-duck.mjs",
+);
+
+test("speechSpans bridges gaps smaller than mergeGap", () => {
+  const meta = {
+    words: [word("w0", "one", 0, 0.5), word("w1", "two", 0.8, 1), word("w2", "three", 2, 2.2)],
+  };
+
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.4 }), [
+    { start: 0, end: 1 },
+    { start: 2, end: 2.2 },
+  ]);
+});
+
+test("speechSpans refuses multi-line meta without placement (file-relative times)", () => {
+  const meta = {
+    voices: [
+      { id: "a", words: [word("w0", "one", 0, 1)] },
+      { id: "b", words: [word("w1", "two", 0, 1)] },
+    ],
+  };
+  assert.throws(() => speechSpans(meta, { mergeGap: 0.2 }), /--sequential or --offsets/);
+});
+
+test("speechSpans sequential stacks lines by duration plus gap", () => {
+  const meta = {
+    voices: [
+      { id: "a", duration_s: 2, words: [word("w0", "one", 0.1, 1.9)] },
+      { id: "b", duration_s: 1, words: [word("w1", "two", 0.1, 0.9)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.2, sequential: true, gap: 0.5 }), [
+    { start: 0.1, end: 1.9 },
+    { start: 2.6, end: 3.4 },
+  ]);
+});
+
+test("speechSpans explicit offsets place each line at composition time", () => {
+  const meta = {
+    voices: [
+      { id: "a", words: [word("w0", "one", 0, 1)] },
+      { id: "b", words: [word("w1", "two", 0, 1)] },
+    ],
+  };
+  assert.deepEqual(speechSpans(meta, { mergeGap: 0.2, offsets: { a: 0, b: 4 } }), [
+    { start: 0, end: 1 },
+    { start: 4, end: 5 },
+  ]);
+  assert.throws(() => speechSpans(meta, { offsets: { a: 0 } }), /missing voice "b"/);
+});
+
+test("speechSpans returns empty spans for empty input", () => {
+  assert.deepEqual(speechSpans({ voices: [] }, { mergeGap: 0.6 }), []);
+});
+
+test("duckKeyframes shapes attack and release from base volume", () => {
+  assert.deepEqual(
+    duckKeyframes([{ start: 3, end: 5 }], {
+      duck: 0.25,
+      attack: 0.15,
+      release: 0.4,
+      baseVolume: 0.6,
+    }),
+    [
+      { time: 3, volume: 0.15, duration: 0.15 },
+      { time: 5, volume: 0.6, duration: 0.4 },
+    ],
+  );
+});
+
+test("duckLane turns composition-time keyframes into clip-local ramps", () => {
+  const keyframes = [
+    { time: 3, volume: 0.15, duration: 0.15 },
+    { time: 5, volume: 0.6, duration: 0.4 },
+  ];
+  assert.deepEqual(duckLane(keyframes, { clipStart: 1, baseVolume: 0.6 }), {
+    version: 1,
+    lanes: [
+      {
+        target: "volume",
+        points: [
+          { t: 0, v: 0.6 },
+          { t: 2, v: 0.6 },
+          { t: 2.15, v: 0.15 },
+          { t: 4, v: 0.15 },
+          { t: 4.4, v: 0.6 },
+        ],
+      },
+    ],
+  });
+});
+
+test("--json spans match --merge-gap semantics exactly", () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-duck-"));
+  try {
+    const metaPath = join(dir, "audio_meta.json");
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        voices: [
+          {
+            id: "narration",
+            words: [
+              word("w0", "one", 0, 0.4),
+              word("w1", "two", 0.9, 1.2),
+              word("w2", "three", 1.8, 2.1),
+            ],
+          },
+        ],
+      }),
+    );
+
+    const out = execFileSync(
+      process.execPath,
+      [SCRIPT, "--meta", metaPath, "--target", "#bgm", "--merge-gap", "0.6", "--json"],
+      { encoding: "utf8" },
+    );
+
+    const parsed = JSON.parse(out);
+    assert.deepEqual(parsed.spans, [
+      { start: 0, end: 1.2 },
+      { start: 1.8, end: 2.1 },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function word(id, text, start, end) {
+  return { id, text, start, end };
+}

package/dist/skills/media-use/scripts/lib/error-diffusion.mjs

@@ -0,0 +1,230 @@
+export const ERROR_DIFFUSION_ALGORITHMS = {
+  "floyd-steinberg": {
+    kernel: [
+      [1, 0, 7],
+      [-1, 1, 3],
+      [0, 1, 5],
+      [1, 1, 1],
+    ],
+    divisor: 16,
+  },
+  atkinson: {
+    kernel: [
+      [1, 0, 1],
+      [2, 0, 1],
+      [-1, 1, 1],
+      [0, 1, 1],
+      [1, 1, 1],
+      [0, 2, 1],
+    ],
+    divisor: 8,
+  },
+  "jarvis-judice-ninke": {
+    kernel: [
+      [1, 0, 7],
+      [2, 0, 5],
+      [-2, 1, 3],
+      [-1, 1, 5],
+      [0, 1, 7],
+      [1, 1, 5],
+      [2, 1, 3],
+      [-2, 2, 1],
+      [-1, 2, 3],
+      [0, 2, 5],
+      [1, 2, 3],
+      [2, 2, 1],
+    ],
+    divisor: 48,
+  },
+  stucki: {
+    kernel: [
+      [1, 0, 8],
+      [2, 0, 4],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 8],
+      [1, 1, 4],
+      [2, 1, 2],
+      [-2, 2, 1],
+      [-1, 2, 2],
+      [0, 2, 4],
+      [1, 2, 2],
+      [2, 2, 1],
+    ],
+    divisor: 42,
+  },
+  burkes: {
+    kernel: [
+      [1, 0, 8],
+      [2, 0, 4],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 8],
+      [1, 1, 4],
+      [2, 1, 2],
+    ],
+    divisor: 32,
+  },
+  sierra: {
+    kernel: [
+      [1, 0, 5],
+      [2, 0, 3],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 5],
+      [1, 1, 4],
+      [2, 1, 2],
+      [-1, 2, 2],
+      [0, 2, 3],
+      [1, 2, 2],
+    ],
+    divisor: 32,
+  },
+  "sierra-lite": {
+    kernel: [
+      [1, 0, 2],
+      [-1, 1, 1],
+      [0, 1, 1],
+    ],
+    divisor: 4,
+  },
+  "two-row-sierra": {
+    kernel: [
+      [1, 0, 4],
+      [2, 0, 3],
+      [-2, 1, 1],
+      [-1, 1, 2],
+      [0, 1, 3],
+      [1, 1, 2],
+      [2, 1, 1],
+    ],
+    divisor: 16,
+  },
+};
+
+const DEFAULTS = {
+  algorithm: "floyd-steinberg",
+  brightness: 1,
+  contrast: 1.2,
+  detail: 1,
+  palette: ["#000000", "#ffffff"],
+  pointSize: 3,
+};
+
+export function errorDiffusionBufferLength(width, height, pointSize) {
+  return Math.ceil(width / pointSize) * Math.ceil(height / pointSize) * 3;
+}
+
+export function applyErrorDiffusionRgba(data, width, height, options = {}, errorBuffer) {
+  if (!Number.isInteger(width) || width < 1 || !Number.isInteger(height) || height < 1) {
+    throw new Error("width and height must be positive integers");
+  }
+  if (!data || data.length !== width * height * 4) {
+    throw new Error(`RGBA data must contain ${width * height * 4} bytes`);
+  }
+
+  const algorithm = options.algorithm ?? DEFAULTS.algorithm;
+  const diffusion = ERROR_DIFFUSION_ALGORITHMS[algorithm];
+  if (!diffusion) throw new Error(`unknown error-diffusion algorithm: ${algorithm}`);
+
+  const pointSize = integerInRange(options.pointSize ?? DEFAULTS.pointSize, 1, 20, "pointSize");
+  const brightness = numberInRange(options.brightness ?? DEFAULTS.brightness, 0.5, 2, "brightness");
+  const contrast = numberInRange(options.contrast ?? DEFAULTS.contrast, 0.5, 2, "contrast");
+  const detail = numberInRange(options.detail ?? DEFAULTS.detail, 0.1, 1, "detail");
+  const palette = parsePalette(options.palette ?? DEFAULTS.palette);
+  const blockColumns = Math.ceil(width / pointSize);
+  const blockRows = Math.ceil(height / pointSize);
+  const errorLength = errorDiffusionBufferLength(width, height, pointSize);
+  const errors = errorBuffer ?? new Float32Array(errorLength);
+  if (!(errors instanceof Float32Array) || errors.length !== errorLength) {
+    throw new Error(`errorBuffer must be a Float32Array of length ${errorLength}`);
+  }
+  errors.fill(0);
+
+  const centerOffset = Math.floor(pointSize / 2);
+  for (let blockRow = 0; blockRow < blockRows; blockRow++) {
+    const blockY = blockRow * pointSize;
+    for (let blockColumn = 0; blockColumn < blockColumns; blockColumn++) {
+      const blockX = blockColumn * pointSize;
+      const centerX = Math.min(blockX + centerOffset, width - 1);
+      const centerY = Math.min(blockY + centerOffset, height - 1);
+      const rgbaIndex = (centerY * width + centerX) * 4;
+      const errorIndex = (blockRow * blockColumns + blockColumn) * 3;
+      const red = correctedChannel(data[rgbaIndex], errors[errorIndex], brightness, contrast);
+      const green = correctedChannel(
+        data[rgbaIndex + 1],
+        errors[errorIndex + 1],
+        brightness,
+        contrast,
+      );
+      const blue = correctedChannel(
+        data[rgbaIndex + 2],
+        errors[errorIndex + 2],
+        brightness,
+        contrast,
+      );
+      const luminance = 0.299 * red + 0.587 * green + 0.114 * blue;
+      const output = palette[Math.min(palette.length - 1, Math.floor(luminance * palette.length))];
+
+      for (let y = blockY; y < Math.min(blockY + pointSize, height); y++) {
+        for (let x = blockX; x < Math.min(blockX + pointSize, width); x++) {
+          const outputIndex = (y * width + x) * 4;
+          data[outputIndex] = Math.round(output[0] * 255);
+          data[outputIndex + 1] = Math.round(output[1] * 255);
+          data[outputIndex + 2] = Math.round(output[2] * 255);
+        }
+      }
+
+      for (const [dx, dy, weight] of diffusion.kernel) {
+        const targetColumn = blockColumn + dx;
+        const targetRow = blockRow + dy;
+        if (
+          targetColumn < 0 ||
+          targetColumn >= blockColumns ||
+          targetRow < 0 ||
+          targetRow >= blockRows
+        ) {
+          continue;
+        }
+        const target = (targetRow * blockColumns + targetColumn) * 3;
+        const scale = (weight / diffusion.divisor) * detail;
+        errors[target] += (red - output[0]) * scale;
+        errors[target + 1] += (green - output[1]) * scale;
+        errors[target + 2] += (blue - output[2]) * scale;
+      }
+    }
+  }
+  return data;
+}
+
+function correctedChannel(byte, error, brightness, contrast) {
+  return Math.min(1, Math.max(0, ((byte / 255 - 0.5) * contrast + 0.5) * brightness + error));
+}
+
+function parsePalette(colors) {
+  if (!Array.isArray(colors) || colors.length < 2 || colors.length > 6) {
+    throw new Error("palette must contain 2 to 6 colors");
+  }
+  return colors.map((color) => {
+    const match = /^#([0-9a-f]{6})$/i.exec(color);
+    if (!match) throw new Error(`palette color must use #rrggbb: ${color}`);
+    const value = Number.parseInt(match[1], 16);
+    return [(value >> 16) / 255, ((value >> 8) & 255) / 255, (value & 255) / 255];
+  });
+}
+
+function numberInRange(value, min, max, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < min || number > max) {
+    throw new Error(`${name} must be between ${min} and ${max}`);
+  }
+  return number;
+}
+
+function integerInRange(value, min, max, name) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return number;
+}

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

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ERROR_DIFFUSION_ALGORITHMS, applyErrorDiffusionRgba } from "./error-diffusion.mjs";
+
+const EXPECTED_GRADIENTS = {
+  "floyd-steinberg": "00000101/00010101/00100101/00010111/01010101/01011011",
+  atkinson: "00000011/00001100/00010011/00010111/01001101/00111011",
+  "jarvis-judice-ninke": "00000011/00001011/00011001/00101111/00100111/01011011",
+  stucki: "00000011/00010101/00010110/00101011/00101101/01010111",
+  burkes: "00000101/00010011/00010110/00101011/01010111/00101011",
+  sierra: "00000011/00010101/00010110/00100111/00110111/00101101",
+  "sierra-lite": "00000101/00010101/00100101/00010110/01010111/01010101",
+  "two-row-sierra": "00000101/00010011/00010110/00101011/00101101/01011011",
+};
+
+test("exposes the eight article error-diffusion algorithms", () => {
+  assert.deepEqual(Object.keys(ERROR_DIFFUSION_ALGORITHMS), Object.keys(EXPECTED_GRADIENTS));
+});
+
+test("matches deterministic golden patterns for every diffusion kernel", () => {
+  const width = 8;
+  const height = 6;
+  const source = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const value = Math.round((255 * (x + y * 0.7)) / (width - 1 + (height - 1) * 0.7));
+      const offset = (y * width + x) * 4;
+      source[offset] = value;
+      source[offset + 1] = Math.round(value * 0.8);
+      source[offset + 2] = Math.round(value * 0.55);
+      source[offset + 3] = 17 + x + y;
+    }
+  }
+
+  for (const [algorithm, expected] of Object.entries(EXPECTED_GRADIENTS)) {
+    const output = source.slice();
+    applyErrorDiffusionRgba(output, width, height, {
+      algorithm,
+      brightness: 1,
+      contrast: 1,
+      detail: 1,
+      palette: ["#000000", "#ffffff"],
+      pointSize: 1,
+    });
+    const rows = [];
+    for (let y = 0; y < height; y++) {
+      let row = "";
+      for (let x = 0; x < width; x++) row += output[(y * width + x) * 4] ? "1" : "0";
+      rows.push(row);
+    }
+    assert.equal(rows.join("/"), expected, algorithm);
+    for (let i = 0; i < width * height; i++) assert.equal(output[i * 4 + 3], source[i * 4 + 3]);
+  }
+});
+
+test("fills point-size blocks from their center sample", () => {
+  const data = new Uint8ClampedArray([
+    0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0, 5, 255, 255, 255, 6, 0, 0, 0, 7, 255,
+    255, 255, 8,
+  ]);
+  applyErrorDiffusionRgba(
+    data,
+    4,
+    2,
+    {
+      algorithm: "floyd-steinberg",
+      brightness: 1,
+      contrast: 1,
+      detail: 1,
+      palette: ["#000000", "#ffffff"],
+      pointSize: 2,
+    },
+    new Float32Array(6),
+  );
+  assert.deepEqual(
+    [...data],
+    [
+      255, 255, 255, 1, 255, 255, 255, 2, 255, 255, 255, 3, 255, 255, 255, 4, 255, 255, 255, 5, 255,
+      255, 255, 6, 255, 255, 255, 7, 255, 255, 255, 8,
+    ],
+  );
+});
+
+test("preserves authored palette order and validates the public contract", () => {
+  const reversed = new Uint8ClampedArray([0, 0, 0, 255]);
+  applyErrorDiffusionRgba(reversed, 1, 1, {
+    palette: ["#ffffff", "#000000"],
+  });
+  assert.deepEqual([...reversed], [255, 255, 255, 255]);
+
+  assert.throws(
+    () => applyErrorDiffusionRgba(new Uint8ClampedArray(4), 1, 1, { palette: ["#000000"] }),
+    /2 to 6 colors/,
+  );
+  assert.throws(
+    () =>
+      applyErrorDiffusionRgba(new Uint8ClampedArray(4), 1, 1, {
+        algorithm: "ordered-bayer",
+      }),
+    /unknown error-diffusion algorithm/,
+  );
+});

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

@@ -0,0 +1,62 @@
+import { fetchMedia, isPublicMediaUrl } from "./media-fetch.mjs";
+import { writeFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// ponytail: bound the download so a hostile/runaway URL can't fill the disk.
+// 256MB covers any real media asset; raise if 4K video sources ever exceed it.
+const MAX_FREEZE_BYTES = 256 * 1024 * 1024;
+
+export async function freezeUrl(url, destPath) {
+  const where = String(url).slice(0, 80);
+  const res = await fetchMedia(url);
+  if (!res.ok) throw new Error(`freeze failed: HTTP ${res.status} for ${where}`);
+
+  // Fail fast on an advertised oversize body before reading a single byte.
+  const declared = Number(res.headers.get("content-length"));
+  if (declared > MAX_FREEZE_BYTES)
+    throw new Error(
+      `freeze failed: ${declared} bytes exceeds ${MAX_FREEZE_BYTES} cap for ${where}`,
+    );
+
+  // Stream and abort once the cap is crossed, so a lying/chunked hostile URL
+  // can't buffer the whole payload into memory before the check (M1).
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    total += chunk.length;
+    if (total > MAX_FREEZE_BYTES)
+      throw new Error(`freeze failed: stream exceeds ${MAX_FREEZE_BYTES} cap for ${where}`);
+    chunks.push(chunk);
+  }
+  if (total === 0) throw new Error(`freeze failed: empty response for ${where}`);
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, Buffer.concat(chunks, total));
+  return total;
+}
+
+export function freezeLocalFile(srcPath, destPath) {
+  mkdirSync(dirname(destPath), { recursive: true });
+  copyFileSync(srcPath, destPath);
+}
+
+// Ingest accepts a DIRECT public media URL only — not a platform page. yt-dlp is
+// deliberately out (cloud IPs get blocked, and it's brittle); the supported case
+// is "user points at their own file or a direct asset link". A direct URL is a
+// non-platform host whose path ends in a known media extension.
+const PLATFORM_HOSTS =
+  /(^|\.)(youtube\.com|youtu\.be|vimeo\.com|tiktok\.com|instagram\.com|twitter\.com|x\.com|facebook\.com|dailymotion\.com)$/i;
+const MEDIA_EXT = /\.(mp3|wav|m4a|aac|ogg|flac|mp4|mov|webm|mkv|png|jpe?g|webp|gif|svg|avif)$/i;
+
+export function isDirectMediaUrl(u) {
+  let url;
+  try {
+    url = new URL(u);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (PLATFORM_HOSTS.test(url.hostname)) return false;
+  if (!isPublicMediaUrl(url)) return false;
+  return MEDIA_EXT.test(url.pathname);
+}

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

@@ -0,0 +1,46 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { isDirectMediaUrl } from "./freeze.mjs";
+
+test("accepts direct public media URLs", () => {
+  assert.equal(isDirectMediaUrl("https://cdn.example.com/clip.mp4"), true);
+  assert.equal(isDirectMediaUrl("https://example.com/a/b/track.mp3"), true);
+  assert.equal(isDirectMediaUrl("http://example.com/logo.svg"), true);
+});
+
+test("rejects platform pages (no yt-dlp)", () => {
+  assert.equal(isDirectMediaUrl("https://www.youtube.com/watch?v=abc"), false);
+  assert.equal(isDirectMediaUrl("https://youtu.be/abc"), false);
+  assert.equal(isDirectMediaUrl("https://vimeo.com/12345"), false);
+  assert.equal(isDirectMediaUrl("https://x.com/u/status/1"), false);
+});
+
+test("rejects non-direct / non-media URLs", () => {
+  assert.equal(isDirectMediaUrl("https://example.com/page"), false, "no media extension");
+  assert.equal(isDirectMediaUrl("ftp://example.com/a.mp4"), false, "non-http(s)");
+  assert.equal(isDirectMediaUrl("not a url"), false);
+});
+
+test("rejects local / private hosts (SSRF guard, m11)", () => {
+  for (const u of [
+    "http://localhost/a.mp4",
+    "http://127.0.0.1/a.mp4",
+    "http://127.1.2.3/a.mp4",
+    "http://0.0.0.0/a.mp4",
+    "http://10.0.0.5/a.mp4",
+    "http://192.168.1.1/a.mp4",
+    "http://172.16.0.1/a.mp4",
+    "http://172.31.255.255/a.mp4",
+    "http://169.254.169.254/a.mp4", // cloud metadata endpoint
+    "http://printer.local/a.mp4",
+    "http://svc.internal/a.mp4",
+    "http://[::1]/a.mp4",
+    "http://[fe80::1]/a.mp4",
+    "http://[fd00::1]/a.mp4",
+  ]) {
+    assert.equal(isDirectMediaUrl(u), false, `should block ${u}`);
+  }
+  // A public host that merely starts with similar digits is still allowed.
+  assert.equal(isDirectMediaUrl("https://172.40.0.1/a.mp4"), true, "172.40 is public");
+  assert.equal(isDirectMediaUrl("https://11.example.com/a.mp4"), true);
+});