From 4d3cdc3e4bb952a926b466561ed9c96540e10f20 Mon Sep 17 00:00:00 2001 From: WaterrrForever Date: Wed, 8 Jul 2026 23:58:41 +0800 Subject: [PATCH] feat(media-use): resolve official brand logos via a four-tier cascade (#2061) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(media-use): resolve official brand logos via a four-tier cascade Third-party brand logos (the meeting's 'credibility signals lost' gap) had no acquisition path: capture only grabs the product's own site assets, and HeyGen asset search returns generic look-alike icons for brand queries (0/3 in testing — an X-in-a-circle for LinkedIn). Workers could only fake a mark or drop it. New resolve type 'logo', four tiers verified by a 54-brand stress test (100% cascade hit across dev tools / big tech / non-tech / CN brands): - svgl — official full-color vector SVGs + wordmark variants (40/54 first-hits); search is substring-based, so entities pass through alias normalization (nextjs → 'next.js', aws → 'amazon web services') - simple-icons (pinned CDN build) — official monochrome glyphs; catches the long tail (nike, visa, toyota, wechat, bytedance) - github org avatar — known-org map only; a brand name is not a GitHub login, guessing risks same-named personal accounts - domain favicon (DuckDuckGo ip3) — small-raster last resort; sub-500B responses are DDG's placeholder and rejected; frozen with a low_res provenance flag (chip-size use only) logo joins the icon/image equivalence group (typesMatch) and the images/ subdir, so entity cache hits interop with figma-imported marks. A total miss falls through resolve's normal failure path — no special casing. HeyGen search stays the icon provider; it is deliberately absent from the logo cascade. Docs: media-use gap/types/providers tables + example; the five workflow banners now cover logos (catalog claim kept for media, 'from their official sources' added for logos); product-launch story-design and motion-graphics logo-reveal point at the new type; catalog surfaces (CLAUDE.md / README / docs) updated in lockstep. Verified: 19 unit tests + coverage row green; live smoke across all four tiers (linkedin→svgl, nike→simple-icons, heygen→github.avatar, amazon→favicon) plus a fabricated brand exiting 1 on the default miss path. oxlint + oxfmt clean. * test(media-use): sanction the four logo providers in the registry allowlist svgl / simple-icons / github.avatar / favicon.ddg join the sanctioned list — the logo cascade added in the previous commit. Full lib suite 95/95 green. * test(media-use): gate the logo cascade behavior in CI + single-fetch favicon tier Review follow-ups (miga-heygen, jrusso1020 on #2061): - Eight mocked-network tests pin what the manual 54-brand stress test only asserted: descriptor shape, alias retry (svgl non-array payload → next query, simple-icons 404 → next slug), network-error → null fallthrough, the sub-500B placeholder rejection, github's no-guessing (zero fetches for unmapped entities), and the real cascade order landing tier by tier under a mocked network. - faviconSearch now hands its verified bytes over as a local file, so the freeze step copies instead of re-downloading — one round-trip, and the size check is authoritative over what gets frozen. - The header's hit counts are labeled as a stress-test snapshot, not a live invariant. Full lib suite 103/103; live smoke re-verified (amazon → favicon.ddg, frozen .ico). --- CLAUDE.md | 2 +- README.md | 20 +- docs/guides/skills.mdx | 2 +- skills-manifest.json | 18 +- skills/faceless-explainer/SKILL.md | 2 +- skills/general-video/SKILL.md | 2 +- skills/hyperframes/SKILL.md | 2 +- skills/media-use/SKILL.md | 25 +- .../media-use/scripts/lib/coverage.test.mjs | 5 + .../media-use/scripts/lib/logo-provider.mjs | 222 ++++++++++++++++++ .../scripts/lib/logo-provider.test.mjs | 137 +++++++++++ skills/media-use/scripts/lib/manifest.mjs | 1 + skills/media-use/scripts/lib/match.mjs | 7 +- skills/media-use/scripts/lib/registry.mjs | 16 ++ .../media-use/scripts/lib/registry.test.mjs | 5 +- skills/media-use/scripts/resolve.mjs | 1 + .../categories/logo-reveal/module.md | 2 +- skills/pr-to-video/SKILL.md | 2 +- skills/product-launch-video/SKILL.md | 2 +- .../references/story-design.md | 2 +- skills/website-to-video/SKILL.md | 2 +- 21 files changed, 434 insertions(+), 43 deletions(-) create mode 100644 skills/media-use/scripts/lib/logo-provider.mjs create mode 100644 skills/media-use/scripts/lib/logo-provider.test.mjs diff --git a/CLAUDE.md b/CLAUDE.md index 09071ad7b..d4778bef5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,7 +38,7 @@ Atomic capabilities the creation workflows compose against — pull one when you - `/hyperframes-animation` — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). - `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion. - `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. -- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk. +- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk. - `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering). - `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream. - `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. diff --git a/README.md b/README.md index 9884e241d..4b2e805f6 100644 --- a/README.md +++ b/README.md @@ -81,16 +81,16 @@ Run `npx skills add heygen-com/hyperframes --full-depth` for the interactive pic Atomic capabilities the creation workflows compose against — pull one when you need that specific layer. -| Skill | Covers | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. | -| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | -| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | -| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | -| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). | -| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | -| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | +| Skill | Covers | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/hyperframes-core` | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules. | +| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | +| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | +| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | +| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | +| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). | +| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | +| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | For visual design handoff workflows, see the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design) and [Open Design guide](https://hyperframes.heygen.com/guides/open-design). diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index da5c8dd2f..84037c192 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -80,7 +80,7 @@ Atomic capabilities the creation workflows compose against — pull one when you | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | | `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | +| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | | `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). | | `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | | `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. | diff --git a/skills-manifest.json b/skills-manifest.json index 2d2e78e05..93ac09a6e 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,7 +6,7 @@ "files": 144 }, "faceless-explainer": { - "hash": "80882d8135b2aeac", + "hash": "58b1901b8ef7a84e", "files": 18 }, "figma": { @@ -14,11 +14,11 @@ "files": 1 }, "general-video": { - "hash": "6cb3fbdf9b860ba6", + "hash": "a4d2b4ed6d8a0643", "files": 1 }, "hyperframes": { - "hash": "4e0795ead8c8bfa3", + "hash": "547fd3b432a028bb", "files": 1 }, "hyperframes-animation": { @@ -46,11 +46,11 @@ "files": 10 }, "media-use": { - "hash": "b982d0f7c710bf23", - "files": 101 + "hash": "22d8da57c4af6ddd", + "files": 103 }, "motion-graphics": { - "hash": "f5a432862116b39a", + "hash": "7452272d8da8934d", "files": 23 }, "music-to-video": { @@ -58,11 +58,11 @@ "files": 132 }, "pr-to-video": { - "hash": "71dce61cff0233f2", + "hash": "30a91ac16fae4737", "files": 22 }, "product-launch-video": { - "hash": "ac4e1e4aa671fe27", + "hash": "8499a01e77b41c6c", "files": 20 }, "remotion-to-hyperframes": { @@ -78,7 +78,7 @@ "files": 27 }, "website-to-video": { - "hash": "d81ede8e9cabd09b", + "hash": "76c4bae653b29e2f", "files": 32 } } diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md index 895f57592..8c065ebe6 100644 --- a/skills/faceless-explainer/SKILL.md +++ b/skills/faceless-explainer/SKILL.md @@ -3,7 +3,7 @@ name: faceless-explainer description: "Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a product promo (/product-launch-video) or a site tour (/website-to-video). Unclear → /hyperframes." --- -> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill. +> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill. # Faceless Explainer to HyperFrames diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md index 7fde74fb3..3a44c2947 100644 --- a/skills/general-video/SKILL.md +++ b/skills/general-video/SKILL.md @@ -8,7 +8,7 @@ description: > metadata: { "tags": "orchestrator, general-video, fallback, freeform, composition-authoring" } --- -> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill. +> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill. # general-video — general video workflow diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 0995faeb9..2f2302a03 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -31,7 +31,7 @@ Atomic capabilities you load **on demand** — not full workflows; they never ow | **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | `/hyperframes-animation` | | **Author seek-safe keyframes** — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth, plus `hyperframes keyframes` diagnostics | `/hyperframes-keyframes` | | **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive | `/hyperframes-creative` | -| **Media** — resolve/generate BGM, SFX, image, icon, voice; TTS voiceover, transcription, background removal, captions; cross-project reuse | `/media-use` | +| **Media** — resolve/generate BGM, SFX, image, icon, brand logo, voice; TTS voiceover, transcription, background removal, captions; cross-project reuse | `/media-use` | | **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor | `/hyperframes-cli` | | **Install registry blocks / components** (`hyperframes add`) | `/hyperframes-registry` | | **Import Figma content** — assets, tokens, components, storyboards→reconstructed motion (REST/CLI); Motion (MCP), shaders (MCP source / native export) | `/figma` | diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md index c2bcc174f..40e94fcc7 100644 --- a/skills/media-use/SKILL.md +++ b/skills/media-use/SKILL.md @@ -1,6 +1,6 @@ --- name: media-use -description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, or voice into a frozen local file + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent a path. Use for any audio, image, icon, voiceover, caption, or media-asset need. +description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, or voice into a frozen local file + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent a path. Use for any audio, image, icon, voiceover, caption, or media-asset need. --- # media-use @@ -14,6 +14,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 voice / audio generation | `resolve --type voice` + 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 | @@ -26,7 +27,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e ## When to use -Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, or voice. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first, freezes the best match locally, registers it in a manifest, and hands the agent one line; all search noise stays on disk. +Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, brand logos, or voice. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first, freezes the best match locally, registers it in a manifest, and hands the agent one line; all search noise stays on disk. ## Resolve @@ -38,13 +39,14 @@ Returns one line: `resolved → (, )` ### Types -| Type | What it finds | Provider | -| ------- | ------------------- | ---------------------------------------- | -| `bgm` | Background music | HeyGen audio catalog (10k+ tracks) | -| `sfx` | Sound effects | Bundled 19-file library + HeyGen catalog | -| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors) | -| `icon` | Icons, logos | HeyGen asset search (type=icon) | -| `voice` | TTS voiceover | Local Kokoro (free); HeyGen TTS upsell | +| Type | What it finds | Provider | +| ------- | -------------------- | -------------------------------------------------------- | +| `bgm` | Background music | HeyGen audio catalog (10k+ tracks) | +| `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 | +| `voice` | TTS voiceover | Local Kokoro (free); HeyGen TTS upsell | ### Examples @@ -64,6 +66,10 @@ node /scripts/resolve.mjs --type image --intent "gradient tech backgr # Icon node /scripts/resolve.mjs --type icon --intent "rocket" --project . # → resolved icon_001 → .media/images/icon_001.png (icon, transparent) + +# Brand logo (official mark — never redrawn by hand) +node /scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project . +# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark) ``` ### Flags @@ -117,6 +123,7 @@ ladder, `describeModelLadder`); the agent can see the ladder and override. | image | heygen search, then local mflux (best FLUX for your RAM), then codex `image_gen` upsell | | voice | local **Kokoro** (free, on-device), then **heygen tts** paid upsell | | icon | heygen asset search | +| logo | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free) | | video (local) | local LTX (`videogen` ladder); `heygen video create` avatar upsell | Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free, diff --git a/skills/media-use/scripts/lib/coverage.test.mjs b/skills/media-use/scripts/lib/coverage.test.mjs index ab293d8ea..c1267f80c 100644 --- a/skills/media-use/scripts/lib/coverage.test.mjs +++ b/skills/media-use/scripts/lib/coverage.test.mjs @@ -18,6 +18,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"); +}); + 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)"); diff --git a/skills/media-use/scripts/lib/logo-provider.mjs b/skills/media-use/scripts/lib/logo-provider.mjs new file mode 100644 index 000000000..d4028af94 --- /dev/null +++ b/skills/media-use/scripts/lib/logo-provider.mjs @@ -0,0 +1,222 @@ +// 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. +// +// 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. +// +// 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 +// falls through to resolve's normal failure path (`no provider could resolve +// logo`, exit 1). + +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"; +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", +}; + +// 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. +const GITHUB_ORGS = { + slack: "slackhq", + meta: "facebook", + google: "google", + microsoft: "microsoft", + aws: "aws", + vercel: "vercel", + nextjs: "vercel", + alibaba: "alibaba", + heygen: "heygen-com", +}; + +// Favicon domains that aren't `.com`. +const FAVICON_DOMAINS = { + cocacola: "coca-cola.com", + aws: "aws.amazon.com", + nextjs: "nextjs.org", +}; + +const norm = (s) => + String(s) + .toLowerCase() + .replace(/[^a-z0-9]/g, ""); + +/** The brand entity for a query: --entity wins; else the intent minus filler. */ +export function entityFrom(intent, entity) { + if (entity) return entity.toLowerCase().trim(); + return String(intent) + .toLowerCase() + .replace(/\b(logo|logos|icon|brand|official|mark)\b/g, "") + .trim() + .replace(/\s+/g, " "); +} + +/** Exact match after stripping case/spacing/punctuation — "Next.js" ≡ "nextjs". */ +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; +} + +export function githubOrgFor(entity) { + return GITHUB_ORGS[norm(entity)] || null; +} + +export function faviconDomainFor(entity) { + return FAVICON_DOMAINS[norm(entity)] || `${norm(entity)}.com`; +} + +async function fetchJson(url) { + const res = await fetch(url, { signal: AbortSignal.timeout(10_000) }); + if (!res.ok) return null; + return res.json(); +} + +async function urlExists(url) { + const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(10_000) }); + 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) }, + }, + }; + } + return null; +} + +export async function simpleIconsSearch(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" }, + }, + }; + } + return null; +} + +export async function githubAvatarSearch(intent, ctx = {}) { + const entity = entityFrom(intent, ctx.entity); + const org = githubOrgFor(entity); + if (!org) return null; + const url = `https://github.com/${org}.png?size=460`; + try { + if (!(await urlExists(url))) return null; + } catch { + return null; + } + return { + url, + ext: ".png", + source: "search", + metadata: { + description: `${entity} logo (GitHub org avatar)`, + provider: "github.avatar", + provenance: { entity, org }, + }, + }; +} + +export async function faviconSearch(intent, ctx = {}) { + const entity = entityFrom(intent, ctx.entity); + const domain = faviconDomainFor(entity); + const url = `https://icons.duckduckgo.com/ip3/${domain}.ico`; + let body; + try { + const res = await fetch(url, { signal: AbortSignal.timeout(10_000) }); + if (!res.ok) return null; + body = Buffer.from(await res.arrayBuffer()); + } catch { + return null; + } + if (body.byteLength < FAVICON_MIN_BYTES) return null; // DDG placeholder, not a logo + // Hand the verified bytes over as a local file: the freeze step copies it + // instead of re-downloading, so the size check is authoritative over what + // gets frozen and the favicon tier costs one network round-trip, not two. + const bytes = body.byteLength; + const tmp = join(mkdtempSync(join(tmpdir(), "media-use-logo-")), `${domain}.ico`); + writeFileSync(tmp, body); + return { + localPath: tmp, + ext: ".ico", + source: "search", + metadata: { + description: `${entity} favicon (small raster — chip-size use only)`, + provider: "favicon.ddg", + provenance: { entity, domain, bytes, low_res: true }, + }, + }; +} diff --git a/skills/media-use/scripts/lib/logo-provider.test.mjs b/skills/media-use/scripts/lib/logo-provider.test.mjs new file mode 100644 index 000000000..5863d409b --- /dev/null +++ b/skills/media-use/scripts/lib/logo-provider.test.mjs @@ -0,0 +1,137 @@ +import test from "node:test"; +import assert from "node:assert"; +import { readFileSync } from "node:fs"; +import { + entityFrom, + titleMatches, + svglQueriesFor, + simpleIconSlugsFor, + githubOrgFor, + faviconDomainFor, + svglSearch, + simpleIconsSearch, + githubAvatarSearch, + faviconSearch, +} from "./logo-provider.mjs"; +import { getProviders, runProviders } from "./registry.mjs"; + +test("entityFrom strips filler words from the intent; --entity wins", () => { + assert.equal(entityFrom("LinkedIn logo"), "linkedin"); + assert.equal(entityFrom("official Slack brand mark"), "slack"); + assert.equal(entityFrom("anything", "Notion"), "notion"); +}); + +test("titleMatches ignores case, spacing, punctuation — and rejects lookalikes", () => { + assert.ok(titleMatches("Next.js", "nextjs")); + assert.ok(titleMatches("Coca-Cola", "coca cola")); + assert.ok(!titleMatches("Slackware", "slack")); +}); + +test("svgl queries include the alias forms the raw entity can't match", () => { + assert.ok(svglQueriesFor("nextjs").includes("next.js")); + assert.ok(svglQueriesFor("aws").includes("amazon web services")); + assert.deepEqual(svglQueriesFor("figma"), ["figma"]); +}); + +test("simple-icons slugs cover the renamed entries", () => { + assert.ok(simpleIconSlugsFor("nextjs").includes("nextdotjs")); + assert.ok(simpleIconSlugsFor("aws").includes("amazonwebservices")); + assert.deepEqual(simpleIconSlugsFor("nike"), ["nike"]); +}); + +test("github avatar tier never guesses an org", () => { + assert.equal(githubOrgFor("slack"), "slackhq"); + assert.equal(githubOrgFor("heygen"), "heygen-com"); + assert.equal(githubOrgFor("some-random-startup"), null); +}); + +test("favicon domain defaults to .com with explicit overrides", () => { + assert.equal(faviconDomainFor("cocacola"), "coca-cola.com"); + assert.equal(faviconDomainFor("stripe"), "stripe.com"); +}); + +// --- async tiers, network mocked ------------------------------------------- +// The 54-brand stress test is a manual snapshot; these pin the same behavior +// as CI gates: descriptor shape, alias retry, error→null fallthrough, the +// placeholder filter, and the real cascade order under a mocked network. + +const json = (data) => new Response(JSON.stringify(data), { status: 200 }); +const status = (code) => new Response(null, { status: code }); +const bin = (n) => new Response(new Uint8Array(n), { status: 200 }); + +test("svglSearch returns the descriptor shape on an exact title hit", async (t) => { + t.mock.method(globalThis, "fetch", async () => + json([{ title: "Figma", route: "https://svgl.app/library/figma.svg" }]), + ); + const res = await svglSearch("Figma logo", {}); + assert.equal(res.url, "https://svgl.app/library/figma.svg"); + assert.equal(res.ext, ".svg"); + assert.equal(res.metadata.provider, "svgl"); +}); + +test("svglSearch skips a non-array payload and retries with the alias query", async (t) => { + const seen = []; + t.mock.method(globalThis, "fetch", async (url) => { + seen.push(decodeURIComponent(String(url))); + return seen.length === 1 + ? json({ error: "unexpected shape" }) + : json([{ title: "Next.js", route: "https://svgl.app/library/nextjs.svg" }]); + }); + const res = await svglSearch("nextjs logo", {}); + assert.equal(res.metadata.provenance.query, "next.js", "hit came from the alias query"); + assert.ok(seen.length >= 2, "raw query then alias"); +}); + +test("svglSearch returns null when the network is down — the cascade falls through", async (t) => { + t.mock.method(globalThis, "fetch", async () => { + throw new Error("network down"); + }); + assert.equal(await svglSearch("figma logo", {}), null); +}); + +test("simpleIconsSearch falls to the next slug on a 404", async (t) => { + const seen = []; + t.mock.method(globalThis, "fetch", async (url) => { + seen.push(String(url)); + return String(url).includes("amazonwebservices") ? status(200) : status(404); + }); + const res = await simpleIconsSearch("aws logo", {}); + assert.ok(res.url.endsWith("amazonwebservices.svg")); + assert.equal(seen.length, 2, "plain slug 404s first, alias slug hits"); +}); + +test("faviconSearch rejects DDG's sub-500B placeholder with null", async (t) => { + t.mock.method(globalThis, "fetch", async () => bin(120)); + assert.equal(await faviconSearch("someco logo", {}), null); +}); + +test("faviconSearch hands verified bytes over as a local file — one fetch, no re-download", async (t) => { + const fetchMock = t.mock.method(globalThis, "fetch", async () => bin(600)); + const res = await faviconSearch("someco logo", {}); + assert.ok(res.localPath, "returns a localPath, not a url"); + assert.equal(readFileSync(res.localPath).byteLength, 600, "frozen bytes are the verified bytes"); + assert.equal(fetchMock.mock.callCount(), 1, "single network round-trip"); + assert.equal(res.metadata.provenance.low_res, true); +}); + +test("githubAvatarSearch never touches the network for an unmapped entity", async (t) => { + const fetchMock = t.mock.method(globalThis, "fetch", async () => status(200)); + assert.equal(await githubAvatarSearch("some-random-startup logo", {}), null); + assert.equal(fetchMock.mock.callCount(), 0); +}); + +test("the real logo cascade falls through tier by tier to the first hit", async (t) => { + t.mock.method(globalThis, "fetch", async (url) => { + const u = String(url); + if (u.includes("api.svgl.app")) return json([]); // tier 1: no hit + if (u.includes("jsdelivr")) return status(404); // tier 2: no such slug + // tier 3 (github) is never called: entity is unmapped + if (u.includes("duckduckgo")) return bin(600); // tier 4: real favicon + throw new Error(`unexpected fetch: ${u}`); + }); + const res = await runProviders(getProviders("logo"), "search", "zzzbrand logo", { + entity: "zzzbrand", + }); + assert.ok(res, "cascade must land on the favicon tier"); + assert.equal(res.metadata.provider, "favicon.ddg"); +}); diff --git a/skills/media-use/scripts/lib/manifest.mjs b/skills/media-use/scripts/lib/manifest.mjs index f06861052..70ac936dd 100644 --- a/skills/media-use/scripts/lib/manifest.mjs +++ b/skills/media-use/scripts/lib/manifest.mjs @@ -21,6 +21,7 @@ const TYPE_DIRS = { voice: "audio/voice", image: "images", icon: "images", + logo: "images", brand: "images", video: "video", }; diff --git a/skills/media-use/scripts/lib/match.mjs b/skills/media-use/scripts/lib/match.mjs index b56e2c484..b9e8859a9 100644 --- a/skills/media-use/scripts/lib/match.mjs +++ b/skills/media-use/scripts/lib/match.mjs @@ -37,10 +37,11 @@ export function tokenOverlap(a, b) { return n; } -// icon and image are interchangeable: both live in images/, and figma-imported -// brand marks are recorded as type image while agents ask for logos as icon. +// icon, image, and logo are interchangeable: all live in images/, and +// figma-imported brand marks are recorded as type image while agents ask for +// logos as icon or logo. export function typesMatch(a, b) { if (a === b) return true; - const visual = new Set(["icon", "image"]); + const visual = new Set(["icon", "image", "logo"]); return visual.has(a) && visual.has(b); } diff --git a/skills/media-use/scripts/lib/registry.mjs b/skills/media-use/scripts/lib/registry.mjs index 8a9a40190..207b5a397 100644 --- a/skills/media-use/scripts/lib/registry.mjs +++ b/skills/media-use/scripts/lib/registry.mjs @@ -23,6 +23,12 @@ import { bgmProvider } from "./bgm-provider.mjs"; import { sfxProvider } from "./sfx-provider.mjs"; import { imageProvider, iconProvider } from "./image-provider.mjs"; import { brandProvider } from "./brand-provider.mjs"; +import { + svglSearch, + simpleIconsSearch, + githubAvatarSearch, + faviconSearch, +} from "./logo-provider.mjs"; import { heygenTtsGenerate } from "./voice-provider.mjs"; import { localTtsGenerate } from "./tts-local-provider.mjs"; import { codexImageGenerate } from "./codex-provider.mjs"; @@ -50,6 +56,16 @@ const REGISTRY = { N("codex.image_gen", { generate: codexImageGenerate }), ], icon: [N("heygen.asset.search", { search: iconProvider.search })], + logo: [ + // Official brand marks. Tiers verified by a 54-brand stress test (100% + // cascade hit); HeyGen asset search is deliberately absent — it returns + // generic look-alike icons for brand queries. All free, all network → + // --local-only leaves only the cache rungs. + N("svgl", { search: svglSearch }), + N("simple-icons", { search: simpleIconsSearch }), + N("github.avatar", { search: githubAvatarSearch }), + N("favicon.ddg", { search: faviconSearch }), + ], voice: [ // Local Kokoro first (free, private, on-device via the hyperframes CLI, kept // under --local-only), then HeyGen TTS as the higher-quality paid upsell and diff --git a/skills/media-use/scripts/lib/registry.test.mjs b/skills/media-use/scripts/lib/registry.test.mjs index 609c0978c..d7b8f5e4b 100644 --- a/skills/media-use/scripts/lib/registry.test.mjs +++ b/skills/media-use/scripts/lib/registry.test.mjs @@ -19,8 +19,9 @@ test("heygen provider is first for every type it serves", () => { } }); -test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec", () => { - const allowed = /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$/; +test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec, logo tiers", () => { + const allowed = + /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$/; for (const t of listTypes()) { for (const p of getProviders(t)) { assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`); diff --git a/skills/media-use/scripts/resolve.mjs b/skills/media-use/scripts/resolve.mjs index edc7b764c..b366c7d85 100644 --- a/skills/media-use/scripts/resolve.mjs +++ b/skills/media-use/scripts/resolve.mjs @@ -462,6 +462,7 @@ const DEFAULT_EXT = { voice: ".wav", image: ".jpg", icon: ".svg", + logo: ".svg", brand: ".png", }; diff --git a/skills/motion-graphics/categories/logo-reveal/module.md b/skills/motion-graphics/categories/logo-reveal/module.md index 9459db0d4..11f7536d5 100644 --- a/skills/motion-graphics/categories/logo-reveal/module.md +++ b/skills/motion-graphics/categories/logo-reveal/module.md @@ -1,6 +1,6 @@ # logo-reveal — category module -A **logo sting / brand lockup**. The logo is user-supplied (`asset_needs` = one logo `source`, not a search). ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage). +A **logo sting / brand lockup**. The logo is user-supplied, or resolved for a known brand (`resolve --type logo --entity `); `asset_needs` = one logo `source`. ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage). ## Plan (Director) diff --git a/skills/pr-to-video/SKILL.md b/skills/pr-to-video/SKILL.md index 38d25dcf7..9a514ec39 100644 --- a/skills/pr-to-video/SKILL.md +++ b/skills/pr-to-video/SKILL.md @@ -3,7 +3,7 @@ name: pr-to-video description: "Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes." --- -> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill. +> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill. # PR to HyperFrames diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md index f8bda08b7..c7d93ff08 100644 --- a/skills/product-launch-video/SKILL.md +++ b/skills/product-launch-video/SKILL.md @@ -3,7 +3,7 @@ name: product-launch-video description: "Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Not a general site tour (/website-to-video). Unclear → /hyperframes." --- -> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill. +> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill. # Product Launch to HyperFrames diff --git a/skills/product-launch-video/references/story-design.md b/skills/product-launch-video/references/story-design.md index 8180025ef..7d692c8c3 100644 --- a/skills/product-launch-video/references/story-design.md +++ b/skills/product-launch-video/references/story-design.md @@ -309,7 +309,7 @@ Step 3 only TAGS the candidate id and writes the shaped VO. Step 4 (visual desig 2. Use only filenames listed there; write as `assets/`. 3. One line, candidates separated by semicolons, a short description after `—`. 4. Prefer `[video]` assets when motion proves the product better than a still. -5. Use content assets (UI, screenshots, product photos, charts, demos). Skip tiny icons, favicons, badges, decorative chrome, repeated logo variants — unless the beat needs them. +5. Use content assets (UI, screenshots, product photos, charts, demos). Skip tiny icons, favicons, badges, decorative chrome, repeated logo variants — unless the beat needs them. Partner / third-party logos come from `/media-use` (`resolve --type logo --entity `) — never redrawn by hand. 6. Pure-typography beats may use an empty asset list. Do not use nested lists. Example: diff --git a/skills/website-to-video/SKILL.md b/skills/website-to-video/SKILL.md index d7231b13c..eabf33009 100644 --- a/skills/website-to-video/SKILL.md +++ b/skills/website-to-video/SKILL.md @@ -3,7 +3,7 @@ name: website-to-video description: "Capture a general website/URL and turn it into a video OF the site — tour, showcase, or social clip built from captured screenshots and the site's own brand assets. Use for portfolio / blog / docs / landing-page showcases. Not a product launch or promo, even from a URL (/product-launch-video). Unclear → /hyperframes." --- -> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill. +> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill. # Website to HyperFrames