hyperframes 0.8.67 → 0.8.69

package/dist/skills/hyperframes/scripts/lib/frame-packets-core.mjs

@@ -1,20 +1,6 @@
-// Shared frame-packet builder — the script half of the frame-worker core/delta split.
-//
-// Each narrative workflow ships a thin `scripts/frame-packets.mjs` wrapper that pins
-// its own paths (animation skill, role delta, design-truth resolution, extra packet
-// sections) and delegates everything else here, exactly as the markdown half already
-// does with `references/frame-worker-core.md` + each workflow's delta. One owner for
-// the packet-building logic; the wrappers own only what genuinely differs per workflow.
-//
-// Packet (<frame_id>.md) = project inputs + the frame's exact `## Frame N` block
-// + the blueprint body + every cited rule recipe, inlined — so a worker never opens
-// the shared STORYBOARD.md or any skill document. Cited motions are found
-// mechanically: the explicit `- rules:` field when present, plus every valid rule id
-// (a filename under the animation skill's rules/) mentioned in the block.
-//
-// _role.md = frame-worker-core.md + the workflow's sub-agents/frame-worker.md,
-// concatenated verbatim — the complete worker role, assembled from the two source
-// documents so nothing is hand-maintained twice.
+// Frame packets inline the storyboard frame, blueprint and cited recipes.
+// Workflow wrappers supply resource paths and workflow-specific sections.
+// The role combines the shared worker contract with the workflow delta.
 
 import {
   existsSync,
@@ -100,12 +86,8 @@ export function resourceSections(block, { animationDir, ruleIds, frameId }) {
   if (blueprint) {
     const blueprintsDir = join(animationDir, "blueprints");
     const path = join(blueprintsDir, `${blueprint}.md`);
-    // A blueprint that resolved to nothing used to inline an empty string, so the
-    // packet shipped without the one document the frame was designed against and
-    // the run still reported success. Name it instead — but only when the library
-    // is actually there to be named against. The animation skill installs on
-    // demand, so an absent blueprints/ is a missing install, not a bad id, and it
-    // degrades with a warning exactly like an absent rules/ (see knownRuleIds).
+    // An installed library must contain the named blueprint.
+    // An absent on-demand library warns, like missing motion rules.
     if (!existsSync(blueprintsDir)) {
       console.warn(
         `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,

package/dist/skills/media-use/SKILL.md

@@ -17,16 +17,16 @@ npx hyperframes media-use resolve --type <type> --intent "<description>" --proje
 
 Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.
 
-| Type    | One-line intent                                                                     |
-| ------- | ----------------------------------------------------------------------------------- |
-| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                      |
-| `sfx`   | sound effects (bundled 19-file library + catalog)                                   |
-| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                             |
-| `icon`  | icons, symbols (transparent)                                                        |
-| `logo`  | official brand marks (svgl → simple-icons → GitHub avatar → favicon; never redrawn) |
-| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                       |
-| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments    |
-| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file                  |
+| Type    | One-line intent                                                                  |
+| ------- | -------------------------------------------------------------------------------- |
+| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                   |
+| `sfx`   | sound effects (bundled 19-file library + catalog)                                |
+| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
+| `icon`  | icons, symbols (transparent)                                                     |
+| `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |
+| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                    |
+| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments |
+| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file               |
 
 Before resolving fresh, list reusable candidates with `--candidates` and judge fit yourself — reuse rules, all flags, ingest (`--from`), and adopt are in `references/resolve.md`.
 

package/dist/skills/media-use/audio/scripts/lib/bgm-volume.mjs

@@ -0,0 +1,4 @@
+// Music sits under narration; a silent film brings music forward.
+export const BGM_BED_VOLUME = 0.12;
+export const BGM_SILENT_VOLUME = 0.9;
+export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);

package/dist/skills/media-use/audio/scripts/lib/bgm.mjs

@@ -20,12 +20,8 @@ import { pythonInvocation } from "./python.mjs";
 const r3 = (x) => Number(x.toFixed(3));
 const lyriaKey = () => process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "";
 
-// Default BGM level. Under narration music is a bed that must stay under the
-// voice — 0.12 linear ≈ -18 dB. A silent film (no voice) has no voice to duck
-// beneath, so BGM sits forward at 0.9. Callers may override per composition.
-export const BGM_BED_VOLUME = 0.12;
-export const BGM_SILENT_VOLUME = 0.9;
-export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);
+import { bgmDefaultVolume } from "./bgm-volume.mjs";
+export { BGM_BED_VOLUME, BGM_SILENT_VOLUME, bgmDefaultVolume } from "./bgm-volume.mjs";
 
 const BGM_PY_DEPS = ["transformers", "torch", "soundfile", "numpy"];
 const BGM_PY_PROBE =

package/dist/skills/media-use/references/meta.md

@@ -9,7 +9,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e
 | HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                                               |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                                                  |
-| No third-party brand logos                 | `resolve --type logo` (svgl → simple-icons → GitHub org avatar → domain favicon)                                                                                                                                                                                                    |
+| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                                                 |
 | No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                                           |
 | Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                                                  |
 | No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                                                   |

package/dist/skills/media-use/references/resolve.md

@@ -14,7 +14,7 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 | `sfx`   | Sound effects                    | Bundled 19-file library + HeyGen catalog                     |
 | `image` | Photos, backgrounds              | HeyGen asset search (75k+ vectors)                           |
 | `icon`  | Icons, symbols                   | HeyGen asset search (type=icon)                              |
-| `logo`  | Official brand marks             | svgl → simple-icons → GitHub org avatar → domain favicon     |
+| `logo`  | Official brand marks             | theSVG → GitHub org avatar → domain favicon                  |
 | `voice` | TTS voiceover                    | HeyGen TTS free-usage path; optional local Kokoro            |
 | `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |
 | `lut`   | Reusable `.cube` LUT files       | Look index params/CDN LUT → deterministic cube               |

package/dist/skills/media-use/references/setup-providers.md

@@ -31,7 +31,7 @@ see the ladder and override.
 | image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
 | voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
 | icon      | heygen asset search free-usage path                                                                                                                                           |
-| logo      | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free)                                                                                               |
+| logo      | theSVG (thesvg.org), then GitHub org avatar, then domain favicon (all free)                                                                                                   |
 | grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback                                                                                              |
 | video     | heygen avatar video free-usage path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |
 

package/dist/skills/media-use/scripts/compatibility.test.mjs

@@ -1,8 +1,10 @@
-import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import assert from "node:assert/strict";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import test from "node:test";
+import { pathToFileURL } from "node:url";
 
 function run(scriptsDir, script, args) {
   return execFileSync(process.execPath, [join(scriptsDir, script), ...args], {
@@ -25,3 +27,68 @@ test("published memory scripts run without reaching outside the skill", () => {
     rmSync(scratchDir, { recursive: true, force: true });
   }
 });
+
+test("published audio helpers import without the CLI package tree", () => {
+  const root = mkdtempSync(join(tmpdir(), "media-use-audio-"));
+  const skill = join(root, "media-use");
+  try {
+    cpSync(new URL("..", import.meta.url), skill, { recursive: true });
+    for (const helper of ["heygen.mjs", "tts.mjs"])
+      run(join(skill, "audio/scripts/lib"), helper, []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+for (const name of ["faceless-explainer", "pr-to-video", "product-launch-video"]) {
+  test(name + " assembles from its installed directory alone", () => {
+    const root = mkdtempSync(join(tmpdir(), "installed-workflow-"));
+    try {
+      const skill = join(root, name);
+      cpSync(new URL("../../" + name, import.meta.url), skill, { recursive: true });
+      const project = join(root, "project");
+      mkdirSync(join(project, "compositions/frames"), { recursive: true });
+      writeFileSync(
+        join(project, "STORYBOARD.md"),
+        "---\nformat: 1920x1080\nmessage: Test\n---\n\n## Frame 1\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
+      );
+      writeFileSync(
+        join(project, "compositions/frames/01-a.html"),
+        '<template><div data-composition-id="01-a" data-duration="3" data-width="1920" data-height="1080"><section class="clip" data-start="0" data-duration="3"></section></div></template>',
+      );
+      run(join(skill, "scripts"), "assemble-index.mjs", [
+        "--hyperframes",
+        project,
+        "--storyboard",
+        join(project, "STORYBOARD.md"),
+      ]);
+      assert.match(readFileSync(join(project, "index.html"), "utf8"), /01-a/);
+      importPacketBuilder(join(skill, "scripts/frame-packets.mjs"));
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+}
+
+test("general-video packet builder starts from its installed directory alone", () => {
+  const root = mkdtempSync(join(tmpdir(), "installed-packets-"));
+  try {
+    cpSync(new URL("../../general-video", import.meta.url), root, { recursive: true });
+    importPacketBuilder(join(root, "scripts/frame-packets.mjs"));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+function importPacketBuilder(path) {
+  execFileSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "-e",
+      'const m = await import(process.argv[1]); if (typeof m.buildFramePackets !== "function") throw new Error("missing builder");',
+      pathToFileURL(path).href,
+    ],
+    { stdio: "pipe" },
+  );
+}

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

@@ -29,7 +29,11 @@ test("weakness: audio-only → media-use resolves image + icon", () => {
 
 test("weakness: no third-party brand logos → media-use resolves logo", () => {
   assert.ok(listTypes().includes("logo"), "logo type missing");
-  assert.ok(getProviders("logo").length >= 4, "logo cascade incomplete");
+  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", () => {

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

@@ -1,41 +1,51 @@
-import { fetchMedia, isPublicMediaUrl } from "./media-fetch.mjs";
-import { writeFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { fetchMedia, isPublicMediaUrl, readCappedBody } from "./media-fetch.mjs";
+import { sanitizeSvg } from "./svg-sanitize.mjs";
+import { writeFileSync, copyFileSync, mkdirSync, readFileSync } 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;
+// Bounds only the wait for response headers; a large video body may stream for minutes.
+const FREEZE_HEADERS_TIMEOUT_MS = 10_000;
+
+const isSvgPath = (destPath) => /\.svg$/i.test(destPath);
+
+// Every logo/icon SVG comes from a third-party host (theSVG, a --from URL, a local file), so it
+// passes the Figma import's sanitizeSvg allowlist before it touches disk.
+function writeFrozen(destPath, buffer) {
+  mkdirSync(dirname(destPath), { recursive: true });
+  const bytes = isSvgPath(destPath) ? Buffer.from(sanitizeSvg(buffer.toString("utf8"))) : buffer;
+  writeFileSync(destPath, bytes);
+  return bytes.byteLength;
+}
 
 export async function freezeUrl(url, destPath) {
   const where = String(url).slice(0, 80);
-  const res = await fetchMedia(url);
+  const headerWait = new AbortController();
+  const timer = setTimeout(
+    () =>
+      headerWait.abort(
+        new Error(`freeze failed: no response within ${FREEZE_HEADERS_TIMEOUT_MS} ms for ${where}`),
+      ),
+    FREEZE_HEADERS_TIMEOUT_MS,
+  );
+  const res = await fetchMedia(url, { signal: headerWait.signal }).finally(() =>
+    clearTimeout(timer),
+  );
   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}`);
+  const body = await readCappedBody(res, MAX_FREEZE_BYTES, `freeze failed for ${where}`);
+  if (body.byteLength === 0) throw new Error(`freeze failed: empty response for ${where}`);
 
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, Buffer.concat(chunks, total));
-  return total;
+  return writeFrozen(destPath, body);
 }
 
 export function freezeLocalFile(srcPath, destPath) {
+  if (isSvgPath(destPath)) {
+    writeFrozen(destPath, readFileSync(srcPath));
+    return;
+  }
   mkdirSync(dirname(destPath), { recursive: true });
   copyFileSync(srcPath, destPath);
 }

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

@@ -1,6 +1,14 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
-import { isDirectMediaUrl } from "./freeze.mjs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isDirectMediaUrl, freezeUrl, freezeLocalFile } from "./freeze.mjs";
+
+const HOSTILE_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script>' +
+  '<rect onload="alert(2)" width="1" height="1"/>' +
+  '<a href="javascript:alert(3)"><circle r="1"/></a></svg>';
 
 test("accepts direct public media URLs", () => {
   assert.equal(isDirectMediaUrl("https://cdn.example.com/clip.mp4"), true);
@@ -44,3 +52,87 @@ test("rejects local / private hosts (SSRF guard, m11)", () => {
   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);
 });
+
+test("freezeUrl strips <script>, on* handlers and javascript: hrefs from a fetched SVG", async (t) => {
+  t.mock.method(
+    globalThis,
+    "fetch",
+    async () =>
+      new Response(HOSTILE_SVG, { status: 200, headers: { "content-type": "image/svg+xml" } }),
+  );
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "logo.svg");
+  await freezeUrl("https://example.com/hostile.svg", dest);
+  const out = readFileSync(dest, "utf8");
+  assert.ok(!out.includes("<script"), "script element stripped");
+  assert.ok(!out.includes("onload="), "event handler stripped");
+  assert.ok(!out.includes("javascript:"), "javascript: href stripped");
+  assert.ok(out.includes("<circle"), "benign markup survives");
+});
+
+// Puts setTimeout and AbortSignal.timeout on node:test's fake clock.
+function fakeClock(t) {
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  t.mock.method(AbortSignal, "timeout", (ms) => {
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(new DOMException("timed out", "TimeoutError")), ms);
+    return controller.signal;
+  });
+}
+
+test("freezeUrl keeps streaming a slow body past the header timeout", async (t) => {
+  fakeClock(t);
+  let body;
+  t.mock.method(globalThis, "fetch", async (_url, { signal }) => {
+    const stream = new ReadableStream({
+      start(controller) {
+        body = controller;
+        // undici aborts the body stream too when the request signal fires.
+        signal.addEventListener("abort", () => controller.error(signal.reason));
+        controller.enqueue(new Uint8Array([1, 2, 3]));
+      },
+    });
+    return new Response(stream, { status: 200 });
+  });
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "clip.mp4");
+  const frozen = freezeUrl("https://cdn.example.com/clip.mp4", dest);
+  await new Promise(setImmediate);
+  t.mock.timers.tick(60_000);
+  body.enqueue(new Uint8Array([4, 5]));
+  body.close();
+  assert.equal(await frozen, 5);
+  assert.deepEqual([...readFileSync(dest)], [1, 2, 3, 4, 5]);
+});
+
+test("freezeUrl times out when no response headers arrive", { timeout: 5_000 }, async (t) => {
+  fakeClock(t);
+  t.mock.method(
+    globalThis,
+    "fetch",
+    (_url, { signal }) =>
+      new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason))),
+  );
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-")), "clip.mp4");
+  const frozen = freezeUrl("https://cdn.example.com/clip.mp4", dest);
+  t.mock.timers.tick(10_000);
+  await assert.rejects(frozen, /no response within 10000 ms/);
+});
+
+test("freezeLocalFile strips the same hostile SVG content from a local source", () => {
+  const srcDir = mkdtempSync(join(tmpdir(), "media-use-freeze-src-"));
+  const src = join(srcDir, "in.svg");
+  writeFileSync(src, HOSTILE_SVG);
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-dest-")), "logo.svg");
+  freezeLocalFile(src, dest);
+  const out = readFileSync(dest, "utf8");
+  assert.ok(!out.includes("<script"));
+  assert.ok(!out.includes("onload="));
+});
+
+test("freezeLocalFile still byte-copies a non-SVG file untouched", () => {
+  const srcDir = mkdtempSync(join(tmpdir(), "media-use-freeze-src-"));
+  const src = join(srcDir, "in.png");
+  writeFileSync(src, Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+  const dest = join(mkdtempSync(join(tmpdir(), "media-use-freeze-dest-")), "logo.png");
+  freezeLocalFile(src, dest);
+  assert.deepEqual(readFileSync(dest), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+});

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

@@ -1,21 +1,11 @@
-import { fetchMedia } from "./media-fetch.mjs";
+import { fetchMedia, readCappedBody } from "./media-fetch.mjs";
 // Official brand marks — the `logo` type's provider tiers, tried in registry
-// order. Every tier was verified against a 54-brand stress test (2026-07,
-// 100% cascade hit). Hit counts below are a snapshot of that run — they
-// drift as the alias/org maps grow; re-run the stress test to refresh them.
+// order.
 //
-//   1. svgl          — official full-color vector SVGs (+ wordmark variants);
-//                      40/54 first-hits. Search is substring-based, so
-//                      entities go through alias normalization first
-//                      ("nextjs" never matches "Next.js" raw).
-//   2. simple-icons  — monochrome official glyphs; caught the long tail the
-//                      others miss (nike, visa, toyota, wechat, bytedance).
-//                      Pinned CDN build for determinism.
-//   3. github avatar — the org's official logo for brands with a GitHub
-//                      presence. Known orgs only: guessing a login risks a
-//                      same-named personal account.
-//   4. domain favicon — small-raster last resort (DuckDuckGo ip3). Responses
-//                      under ~500B are DDG's globe placeholder, not a hit.
+//   1. thesvg: one pinned manifest matched locally ("Next.js", "nextjs", "next js" hit one
+//      entry); default full-color mark; skips licenses outside THESVG_ACCEPTED_LICENSES.
+//   2. github avatar: known orgs only; guessing a login risks a same-named personal account.
+//   3. domain favicon: DuckDuckGo ip3 last resort; under ~500B is its globe placeholder.
 //
 // HeyGen asset search is deliberately absent: for brand queries it returns
 // generic look-alike icons (0/3 in testing) — worse than a miss. A total miss
@@ -26,24 +16,36 @@ import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const SVGL_API = "https://api.svgl.app";
-const SIMPLE_ICONS_CDN = "https://cdn.jsdelivr.net/npm/simple-icons@16.25.0/icons";
+// Bump by pointing at a newer glincker/thesvg commit; the manifest and every
+// icon URL resolve against the same pin, so a resolve is reproducible.
+const THESVG_REV = "e5957fa742c1ebf6da07ac40665bdd01d8add35f";
+const THESVG_CDN = `https://cdn.jsdelivr.net/gh/glincker/thesvg@${THESVG_REV}`;
+const THESVG_MANIFEST = `${THESVG_CDN}/src/data/icons.json`;
 const FAVICON_MIN_BYTES = 500;
-
-// svgl search queries per entity, tried in order after the raw entity.
-const SVGL_ALIASES = {
-  nextjs: ["next.js", "next"],
-  aws: ["amazon web services"],
-  huggingface: ["hugging face"],
-  cocacola: ["coca-cola"],
-  mcdonalds: ["mcdonald's"],
-};
-
-// simple-icons slugs that differ from the normalized entity.
-const SIMPLE_ICON_SLUGS = {
-  nextjs: "nextdotjs",
-  aws: "amazonwebservices",
-};
+// ponytail: the manifest is ~3.3MB today; 20MB leaves headroom without trusting an
+// unbounded body from a CDN edge.
+const MAX_MANIFEST_BYTES = 20 * 1024 * 1024;
+
+// When several entries share a normalized name (e.g. "slack" and the
+// "slack-badge" auth button), the brand mark wins over cloud/infra and badge
+// collections.
+const THESVG_COLLECTION_RANK = ["brands", "community", "aws", "azure", "gcp", "k8s", "auth-badges"];
+
+// The ten SPDX ids theSVG's submission form accepts and verifies before merge
+// (thesvg.org LICENSING.md §5); anything else routes through their unaudited
+// "Other/custom" path.
+const THESVG_ACCEPTED_LICENSES = new Set([
+  "CC0-1.0",
+  "Unlicense",
+  "MIT",
+  "Apache-2.0",
+  "BSD-3-Clause",
+  "ISC",
+  "CC-BY-4.0",
+  "CC-BY-SA-4.0",
+  "CC-BY-ND-4.0",
+  "MPL-2.0",
+]);
 
 // Known GitHub orgs. Only mapped entities resolve at this tier — a brand name
 // is NOT a GitHub login, and guessing hits same-named personal accounts.
@@ -86,15 +88,32 @@ export function titleMatches(title, entity) {
   return norm(title) === norm(entity);
 }
 
-export function svglQueriesFor(entity) {
-  return [entity, ...(SVGL_ALIASES[norm(entity)] || [])];
-}
-
-export function simpleIconSlugsFor(entity) {
-  const slugs = [norm(entity)];
-  const alias = SIMPLE_ICON_SLUGS[norm(entity)];
-  if (alias) slugs.push(alias);
-  return slugs;
+/** Best theSVG entry for an entity, or null: slug > title > alias, ties to the brands
+ * collection; entries outside THESVG_ACCEPTED_LICENSES are never returned. */
+export function thesvgMatch(icons, entity) {
+  const want = norm(entity);
+  if (!want || !Array.isArray(icons)) return null;
+  const collectionRank = (icon) => {
+    const i = THESVG_COLLECTION_RANK.indexOf(icon.collection);
+    return i === -1 ? THESVG_COLLECTION_RANK.length : i;
+  };
+  let best = null;
+  let bestScore = Infinity;
+  for (const icon of icons) {
+    if (!icon || typeof icon.slug !== "string" || !icon.variants?.default) continue;
+    if (!THESVG_ACCEPTED_LICENSES.has(icon.license)) continue;
+    let field;
+    if (norm(icon.slug) === want) field = 0;
+    else if (titleMatches(icon.title, want)) field = 1;
+    else if ((icon.aliases || []).some((a) => titleMatches(a, want))) field = 2;
+    else continue;
+    const score = field * 100 + collectionRank(icon);
+    if (score < bestScore) {
+      best = icon;
+      bestScore = score;
+    }
+  }
+  return best;
 }
 
 export function githubOrgFor(entity) {
@@ -108,7 +127,8 @@ export function faviconDomainFor(entity) {
 async function fetchJson(url) {
   const res = await fetchMedia(url, { signal: AbortSignal.timeout(10_000) });
   if (!res.ok) return null;
-  return res.json();
+  const body = await readCappedBody(res, MAX_MANIFEST_BYTES, "fetchJson");
+  return JSON.parse(body.toString("utf8"));
 }
 
 async function urlExists(url) {
@@ -116,57 +136,58 @@ async function urlExists(url) {
   return res.ok;
 }
 
-export async function svglSearch(intent, ctx = {}) {
-  const entity = entityFrom(intent, ctx.entity);
-  for (const q of svglQueriesFor(entity)) {
-    let items;
-    try {
-      items = await fetchJson(`${SVGL_API}?search=${encodeURIComponent(q)}`);
-    } catch {
-      return null; // network down — let the next tier try its own host
-    }
-    if (!Array.isArray(items)) continue;
-    const hit = items.find((it) => titleMatches(it.title, q) || titleMatches(it.title, entity));
-    if (!hit) continue;
-    const route = typeof hit.route === "string" ? hit.route : hit.route?.light;
-    if (!route) continue;
-    return {
-      url: route,
-      ext: ".svg",
-      source: "search",
-      metadata: {
-        description: `${hit.title} logo (official mark)`,
-        provider: "svgl",
-        provenance: { entity, query: q, route, wordmark: Boolean(hit.wordmark) },
-      },
-    };
+// One manifest per process: a multi-logo resolve pays the download once. A
+// failed load is not cached, so the next call retries.
+let thesvgManifest = null;
+
+async function loadThesvgManifest() {
+  if (!thesvgManifest) {
+    thesvgManifest = fetchJson(THESVG_MANIFEST).then((icons) => {
+      if (!Array.isArray(icons)) throw new Error("theSVG manifest: unexpected shape");
+      return icons;
+    });
+    thesvgManifest.catch(() => {
+      thesvgManifest = null;
+    });
   }
-  return null;
+  return thesvgManifest;
 }
 
-export async function simpleIconsSearch(intent, ctx = {}) {
+/** Test hook: drop the memoized manifest. */
+export function resetThesvgManifest() {
+  thesvgManifest = null;
+}
+
+export async function thesvgSearch(intent, ctx = {}) {
   const entity = entityFrom(intent, ctx.entity);
-  for (const slug of simpleIconSlugsFor(entity)) {
-    const url = `${SIMPLE_ICONS_CDN}/${slug}.svg`;
-    let ok;
-    try {
-      ok = await urlExists(url);
-    } catch {
-      return null;
-    }
-    if (!ok) continue;
-    return {
-      url,
-      ext: ".svg",
-      source: "search",
-      metadata: {
-        description: `${entity} logo (official monochrome glyph)`,
-        provider: "simple-icons",
-        provenance: { entity, slug, pinned: "simple-icons@16.25.0" },
-      },
-    };
+  let icons;
+  try {
+    icons = await loadThesvgManifest();
+  } catch {
+    return null; // network down or bad payload — let the next tier try its own host
   }
-  return null;
+  const hit = thesvgMatch(icons, entity);
+  if (!hit) return null;
+  // theSVG also ships mono, light/dark and wordmark variants; default is the full-color mark.
+  const route = hit.variants.default;
+  return {
+    url: `${THESVG_CDN}/public${route.startsWith("/") ? "" : "/"}${route}`,
+    ext: ".svg",
+    source: "search",
+    metadata: {
+      description: `${hit.title} logo (official mark)`,
+      provider: "thesvg",
+      provenance: {
+        entity,
+        slug: hit.slug,
+        variant: "default",
+        variants: Object.keys(hit.variants),
+        collection: hit.collection,
+        license: hit.license,
+        pinned: `glincker/thesvg@${THESVG_REV}`,
+      },
+    },
+  };
 }
 
 export async function githubAvatarSearch(intent, ctx = {}) {