mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-11 14:50:02 +00:00
feat(media-use): resolve official brand logos via a four-tier cascade (#2061)
* 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).
This commit is contained in:
WaterrrForever
@@ -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 `<entity>.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 },
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user