@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/packages/agentsam-brand/src/core/v2/ingest-graph.js

@@ -0,0 +1,387 @@
+/**
+ * BrandPack v2 ingest — folders, archives (zip/tar/gz), HTML/CSS/code extraction.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { spawnSync } from 'node:child_process';
+import { BrandAssetError } from '../errors.js';
+import { expandHome, isImagePath } from '../ingest.js';
+import { INGEST_EXTENSIONS, formatCapabilities } from '../capabilities.js';
+import { classifyAssetRole } from './roles.js';
+import {
+  createEmptyBrandPack,
+  normalizeBrandPack,
+  normalizeAssetNode,
+  touchProvenance,
+  BRAND_PACK_FILENAME,
+} from './schema.js';
+import { sha256File } from '../inspect.js';
+
+const ARCHIVE_EXTS = new Set(['.zip', '.tar', '.gz', '.tgz', '.tar.gz']);
+const CODE_EXTS = new Set(['.html', '.htm', '.css', '.scss', '.js', '.ts', '.tsx', '.jsx', '.vue', '.svelte', '.json', '.md', '.yaml', '.yml']);
+
+function extOf(filePath) {
+  const lower = String(filePath || '').toLowerCase();
+  if (lower.endsWith('.tar.gz')) return '.tar.gz';
+  return path.extname(lower);
+}
+
+export function isArchivePath(filePath) {
+  return ARCHIVE_EXTS.has(extOf(filePath));
+}
+
+export function isIngestiblePath(filePath) {
+  const ext = extOf(filePath);
+  if (ARCHIVE_EXTS.has(ext)) return true;
+  if (INGEST_EXTENSIONS.includes(ext)) return true;
+  if (CODE_EXTS.has(ext)) return true;
+  return isImagePath(filePath);
+}
+
+/**
+ * Extract archive to a work directory (uses system unzip/tar).
+ */
+export function extractArchive(archivePath, destDir) {
+  const abs = path.resolve(archivePath);
+  const ext = extOf(abs);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  if (ext === '.zip') {
+    const r = spawnSync('unzip', ['-q', '-o', abs, '-d', destDir], { encoding: 'utf8' });
+    if (r.status !== 0) {
+      throw new BrandAssetError('unzip_failed', r.stderr || 'unzip failed');
+    }
+    return destDir;
+  }
+  if (ext === '.tar' || ext === '.tgz' || ext === '.tar.gz') {
+    const args = ext === '.tar' ? ['-xf', abs, '-C', destDir] : ['-xzf', abs, '-C', destDir];
+    const r = spawnSync('tar', args, { encoding: 'utf8' });
+    if (r.status !== 0) {
+      throw new BrandAssetError('tar_failed', r.stderr || 'tar failed');
+    }
+    return destDir;
+  }
+  if (ext === '.gz' && !abs.endsWith('.tar.gz')) {
+    const outName = path.basename(abs, '.gz');
+    const outPath = path.join(destDir, outName);
+    fs.writeFileSync(outPath, zlib.gunzipSync(fs.readFileSync(abs)));
+    return destDir;
+  }
+  throw new BrandAssetError('archive_unsupported', `Unsupported archive: ${ext}`);
+}
+
+/**
+ * Extract colors, font-families, image urls from HTML/CSS/JS text.
+ */
+export function extractFromCode(sourceText, { filePath = '' } = {}) {
+  const text = String(sourceText || '');
+  const colors = new Set();
+  const fonts = new Set();
+  const urls = new Set();
+  const cssVars = {};
+
+  const hexRe = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+  const rgbRe = /rgba?\(\s*[\d.]+\s*,\s*[\d.]+\s*,\s*[\d.]+(?:\s*,\s*[\d.]+)?\s*\)/gi;
+  const oklchRe = /oklch\(\s*[^)]+\)/gi;
+  const fontRe = /font-family\s*:\s*([^;!}{]+)/gi;
+  const urlRe = /url\(\s*['"]?([^'")\s]+)['"]?\s*\)/gi;
+  const srcRe = /(?:src|href)=['"]([^'"]+\.(?:png|jpe?g|webp|avif|svg|gif|woff2?|ttf|otf|mp4|webm|glb))['"]/gi;
+  const varRe = /--([a-zA-Z0-9-_]+)\s*:\s*([^;]+);/g;
+
+  for (const m of text.matchAll(hexRe)) colors.add(m[0].toLowerCase());
+  for (const m of text.matchAll(rgbRe)) colors.add(m[0].replace(/\s+/g, ''));
+  for (const m of text.matchAll(oklchRe)) colors.add(m[0].replace(/\s+/g, ' '));
+  for (const m of text.matchAll(fontRe)) {
+    const raw = m[1].split(',')[0].replace(/['"]/g, '').trim();
+    if (raw && !/^(inherit|initial|sans-serif|serif|monospace|system-ui)$/i.test(raw)) {
+      fonts.add(raw);
+    }
+  }
+  for (const m of text.matchAll(urlRe)) urls.add(m[1]);
+  for (const m of text.matchAll(srcRe)) urls.add(m[1]);
+  for (const m of text.matchAll(varRe)) {
+    cssVars[`--${m[1]}`] = m[2].trim();
+  }
+
+  return {
+    file: filePath || null,
+    colors: [...colors].slice(0, 64),
+    fonts: [...fonts].slice(0, 32),
+    asset_urls: [...urls].slice(0, 128),
+    css_variables: cssVars,
+  };
+}
+
+function walkFiles(root, { maxFiles = 5000 } = {}) {
+  const out = [];
+  const stack = [root];
+  while (stack.length && out.length < maxFiles) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      if (ent.name.startsWith('.') || ent.name === 'node_modules' || ent.name === '__MACOSX') continue;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) stack.push(full);
+      else if (ent.isFile()) out.push(full);
+    }
+  }
+  return out;
+}
+
+function classifyFile(filePath, rootDir) {
+  const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+  const ext = extOf(filePath).replace(/^\./, '');
+  const caps = formatCapabilities(ext);
+  const classification = classifyAssetRole({ path: filePath, contentType: null });
+  let bytes = 0;
+  try { bytes = fs.statSync(filePath).size; } catch { /* ignore */ }
+
+  const node = normalizeAssetNode({
+    id: `asset_${rel.replace(/[^a-z0-9]+/gi, '_').slice(0, 64)}`,
+    role: classification.role,
+    family: classification.family,
+    label: path.basename(filePath),
+    master: {
+      path: filePath,
+      relative: rel,
+      format: ext || null,
+      bytes,
+      sha256: bytes < 50_000_000 ? safeSha(filePath) : null,
+    },
+    provenance: {
+      source: 'ingest',
+      confidence: classification.confidence,
+      needs_review: classification.needs_review,
+    },
+    licensing: caps.licensing_required
+      ? { redistributable: false, status: 'unknown', note: 'Font licensing must be confirmed before ZIP export' }
+      : null,
+  });
+
+  return {
+    asset: node,
+    classification,
+    caps,
+  };
+}
+
+function safeSha(filePath) {
+  try { return sha256File(filePath); } catch { return null; }
+}
+
+/**
+ * Ingest a path (file, folder, or archive) into a brand.pack.json graph.
+ */
+export async function ingestBrandSources(inputPath, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const abs = expandHome(inputPath);
+  if (!abs || !fs.existsSync(abs)) {
+    throw new BrandAssetError('ingest_missing', `Not found: ${inputPath}`);
+  }
+
+  const workRoot = options.workDir
+    || path.join(cwd, '.agentsam', 'brand', 'ingest', `run-${Date.now()}`);
+  fs.mkdirSync(workRoot, { recursive: true });
+
+  let scanRoot = abs;
+  const extracted = [];
+
+  if (fs.statSync(abs).isFile() && isArchivePath(abs)) {
+    const dest = path.join(workRoot, 'extracted');
+    extractArchive(abs, dest);
+    scanRoot = dest;
+    extracted.push(abs);
+  } else if (fs.statSync(abs).isFile()) {
+    scanRoot = path.dirname(abs);
+  }
+
+  // Also expand nested archives one level
+  if (fs.statSync(scanRoot).isDirectory()) {
+    for (const f of walkFiles(scanRoot, { maxFiles: 200 })) {
+      if (isArchivePath(f) && f !== abs) {
+        const nested = path.join(workRoot, 'nested', path.basename(f, extOf(f)));
+        try {
+          extractArchive(f, nested);
+          extracted.push(f);
+        } catch {
+          /* keep going */
+        }
+      }
+    }
+  }
+
+  const roots = [scanRoot];
+  if (fs.existsSync(path.join(workRoot, 'nested'))) {
+    roots.push(...fs.readdirSync(path.join(workRoot, 'nested')).map((n) => path.join(workRoot, 'nested', n)));
+  }
+
+  let pack = options.pack
+    ? normalizeBrandPack(options.pack)
+    : createEmptyBrandPack({ brandId: options.brandId || '', brandName: options.brandName || '' });
+
+  if (!pack.brand.id && options.brandId) pack.brand.id = String(options.brandId).toLowerCase();
+
+  const detections = [];
+  const codeExtractions = [];
+  const recommendations = [];
+  const seenSha = new Map();
+
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const files = fs.statSync(root).isFile()
+      ? [root]
+      : walkFiles(root).filter(isIngestiblePath);
+
+    // Single-file ingest when user pointed at one file
+    if (fs.statSync(abs).isFile() && !isArchivePath(abs)) {
+      files.length = 0;
+      files.push(abs);
+    }
+
+    for (const file of files) {
+      const ext = extOf(file);
+      if (ARCHIVE_EXTS.has(ext)) continue;
+
+      if (CODE_EXTS.has(ext) || ext === '.html' || ext === '.htm') {
+        try {
+          const text = fs.readFileSync(file, 'utf8');
+          const extractedCode = extractFromCode(text, { filePath: file });
+          codeExtractions.push(extractedCode);
+          // Merge CSS vars / colors into tokens (soft)
+          for (const [k, v] of Object.entries(extractedCode.css_variables || {})) {
+            if (!pack.tokens.color[k]) {
+              pack.tokens.color[k] = { value: v, source: path.basename(file), inferred: true };
+            }
+          }
+          let fi = 0;
+          for (const font of extractedCode.fonts) {
+            const key = `font.inferred.${fi++}`;
+            if (!pack.tokens.type[key]) {
+              pack.tokens.type[key] = { family: font, source: path.basename(file), inferred: true };
+            }
+          }
+        } catch {
+          /* binary masquerading */
+        }
+      }
+
+      if (!isIngestiblePath(file)) continue;
+      // Skip pure code from asset list unless it's tokens/docs
+      if (['.js', '.ts', '.tsx', '.jsx', '.vue', '.svelte'].includes(ext)) continue;
+
+      const { asset, classification } = classifyFile(file, root);
+      const sha = asset.master?.sha256;
+      if (sha && seenSha.has(sha)) {
+        recommendations.push({
+          type: 'duplicate',
+          message: `${path.basename(file)} duplicates ${seenSha.get(sha)}`,
+          path: file,
+        });
+        continue;
+      }
+      if (sha) seenSha.set(sha, asset.master.relative || file);
+
+      pack.assets.push(asset);
+      detections.push({
+        path: asset.master?.relative || file,
+        role: classification.role,
+        confidence: classification.confidence,
+        ok: classification.confidence >= 0.7,
+        label: classification.label,
+      });
+    }
+  }
+
+  // Recommendations
+  const roles = new Set(pack.assets.map((a) => a.role));
+  if (roles.has('logo.primary') === false && pack.assets.some((a) => a.family === 'logo')) {
+    /* ok */
+  }
+  if (!roles.has('logo.primary') && !roles.has('logo.mark')) {
+    recommendations.push({ type: 'missing', message: 'No primary logo / mark detected' });
+  }
+  if (!roles.has('favicon') && !roles.has('icon.app')) {
+    recommendations.push({ type: 'missing', message: 'No favicon or app icon detected' });
+  }
+  if (roles.has('hero.landscape') && !roles.has('hero.mobile')) {
+    recommendations.push({ type: 'missing', message: 'Desktop hero found but no mobile hero — consider art-direction crop' });
+  }
+  for (const a of pack.assets) {
+    if (a.provenance?.needs_review) {
+      recommendations.push({
+        type: 'review',
+        message: `Low-confidence classification for ${a.label || a.id} → ${a.role}`,
+        asset_id: a.id,
+      });
+    }
+    if (a.licensing?.status === 'unknown') {
+      recommendations.push({
+        type: 'licensing',
+        message: `Font ${a.label} cannot be redistributed until licensing is confirmed`,
+        asset_id: a.id,
+      });
+    }
+  }
+
+  pack = touchProvenance(pack, {
+    op: 'ingest',
+    input: abs,
+    asset_count: pack.assets.length,
+    archives: extracted.map((p) => path.basename(p)),
+  });
+
+  const outDir = options.outDir || path.join(cwd, '.agentsam', 'brand', 'packs', pack.brand.id || 'untitled');
+  fs.mkdirSync(outDir, { recursive: true });
+  const packPath = path.join(outDir, BRAND_PACK_FILENAME);
+  if (options.write !== false) {
+    fs.writeFileSync(packPath, `${JSON.stringify(pack, null, 2)}\n`);
+  }
+
+  return {
+    ok: true,
+    capability: 'brand.ingest',
+    pack,
+    pack_path: packPath,
+    detections,
+    code_extractions: codeExtractions,
+    recommendations,
+    stats: {
+      assets: pack.assets.length,
+      high_confidence: detections.filter((d) => d.ok).length,
+      needs_review: detections.filter((d) => !d.ok).length,
+      archives_expanded: extracted.length,
+      tokens_color: Object.keys(pack.tokens.color).length,
+      tokens_type: Object.keys(pack.tokens.type).length,
+    },
+  };
+}
+
+export async function loadBrandPack(fromPath, { cwd = process.cwd() } = {}) {
+  const abs = path.resolve(cwd, fromPath);
+  if (fs.statSync(abs).isDirectory()) {
+    const candidate = path.join(abs, BRAND_PACK_FILENAME);
+    if (fs.existsSync(candidate)) {
+      return normalizeBrandPack(JSON.parse(fs.readFileSync(candidate, 'utf8')));
+    }
+    throw new BrandAssetError('pack_missing', `No ${BRAND_PACK_FILENAME} in ${fromPath}`);
+  }
+  return normalizeBrandPack(JSON.parse(fs.readFileSync(abs, 'utf8')));
+}
+
+export function saveBrandPack(pack, outDir) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const file = path.join(outDir, BRAND_PACK_FILENAME);
+  const normalized = normalizeBrandPack(pack);
+  normalized.provenance = {
+    ...normalized.provenance,
+    updated_at: new Date().toISOString(),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(normalized, null, 2)}\n`);
+  return file;
+}

package/packages/agentsam-brand/src/core/v2/roles.js

@@ -0,0 +1,180 @@
+/**
+ * Asset roles — semantic identity, not dimensions.
+ * A 512px logo and a 512px app icon are different assets.
+ */
+
+export const ASSET_ROLES = Object.freeze({
+  // Logo system
+  'logo.primary': {
+    family: 'logo',
+    label: 'Primary logo',
+    canonical_policy: 'vector_preferred',
+    master_prefers: ['svg', 'pdf'],
+  },
+  'logo.secondary': { family: 'logo', label: 'Secondary logo', canonical_policy: 'vector_preferred', master_prefers: ['svg'] },
+  'logo.mark': { family: 'logo', label: 'Mark / monogram', canonical_policy: 'vector_preferred', master_prefers: ['svg'] },
+  'logo.wordmark': { family: 'logo', label: 'Wordmark', canonical_policy: 'vector_preferred', master_prefers: ['svg'] },
+  'logo.black': { family: 'logo', label: 'Logo black', canonical_policy: 'vector_preferred', master_prefers: ['svg'] },
+  'logo.white': { family: 'logo', label: 'Logo white', canonical_policy: 'vector_preferred', master_prefers: ['svg'] },
+
+  // Icons / platform
+  favicon: { family: 'favicon', label: 'Favicon', canonical_policy: 'svg_plus_png', master_prefers: ['svg', 'png'] },
+  'icon.app': { family: 'app-icon', label: 'App icon', canonical_policy: 'artwork_1024', master_prefers: ['png', 'svg'] },
+  'icon.ios': { family: 'app-icon', label: 'iOS icon set', canonical_policy: 'artwork_1024', master_prefers: ['png'] },
+  'icon.macos': { family: 'app-icon', label: 'macOS icon', canonical_policy: 'artwork_1024', master_prefers: ['png', 'icns'] },
+  'icon.android': { family: 'app-icon', label: 'Android icon', canonical_policy: 'artwork_1024', master_prefers: ['png', 'svg'] },
+  'icon.maskable': { family: 'app-icon', label: 'Maskable / adaptive', canonical_policy: 'artwork_1024', master_prefers: ['png'] },
+  'icon.windows': { family: 'app-icon', label: 'Windows icon', canonical_policy: 'artwork_1024', master_prefers: ['png', 'ico'] },
+
+  // Heroes / imagery
+  'hero.landscape': { family: 'hero', label: 'Desktop hero', canonical_policy: 'photographic', master_prefers: ['jpg', 'png', 'tiff'] },
+  'hero.ultrawide': { family: 'hero', label: 'Ultrawide hero', canonical_policy: 'photographic', master_prefers: ['jpg', 'png'] },
+  'hero.mobile': { family: 'hero', label: 'Mobile hero', canonical_policy: 'photographic', master_prefers: ['jpg', 'png'] },
+  'hero.poster': { family: 'hero', label: 'Poster / still', canonical_policy: 'photographic', master_prefers: ['jpg', 'png'] },
+  'hero.background': { family: 'hero', label: 'Background hero', canonical_policy: 'photographic', master_prefers: ['jpg', 'png'] },
+  'hero.product': { family: 'hero', label: 'Product hero', canonical_policy: 'photographic', master_prefers: ['png', 'jpg'] },
+
+  // Social
+  'social.og': { family: 'social', label: 'Open Graph', canonical_policy: 'composition', master_prefers: ['png', 'jpg'] },
+  'social.square': { family: 'social', label: 'Square social', canonical_policy: 'composition', master_prefers: ['png', 'jpg'] },
+  'social.portrait': { family: 'social', label: 'Portrait social', canonical_policy: 'composition', master_prefers: ['png', 'jpg'] },
+  'social.story': { family: 'social', label: 'Story / reel poster', canonical_policy: 'composition', master_prefers: ['png', 'jpg'] },
+
+  // Product shots
+  'product.raw': { family: 'product-shot', label: 'Raw screenshot', canonical_policy: 'png_transparency', master_prefers: ['png'] },
+  'product.framed': { family: 'product-shot', label: 'Device-framed shot', canonical_policy: 'png_transparency', master_prefers: ['png'] },
+  'product.marketing': { family: 'product-shot', label: 'Marketing composition', canonical_policy: 'composition', master_prefers: ['png', 'jpg'] },
+  'product.thumb': { family: 'product-shot', label: 'Thumbnail', canonical_policy: 'png_transparency', master_prefers: ['png', 'webp'] },
+  'product.docs': { family: 'product-shot', label: 'Documentation shot', canonical_policy: 'png_transparency', master_prefers: ['png'] },
+
+  // Motion
+  'motion.hero': { family: 'video', label: 'Hero video', canonical_policy: 'video_master', master_prefers: ['mov', 'mp4'] },
+  'motion.loop': { family: 'video', label: 'UI loop (silent)', canonical_policy: 'video_loop', master_prefers: ['mp4', 'webm'] },
+  'motion.lottie': { family: 'motion-graphics', label: 'Lottie', canonical_policy: 'source_preserve', master_prefers: ['json'] },
+  'motion.rive': { family: 'motion-graphics', label: 'Rive', canonical_policy: 'source_preserve', master_prefers: ['riv'] },
+
+  // 3D
+  'model.product': { family: 'model', label: 'Product model', canonical_policy: 'glb', master_prefers: ['glb', 'gltf'] },
+  'model.brand': { family: 'model', label: 'Brand render model', canonical_policy: 'glb', master_prefers: ['glb'] },
+  'model.ar': { family: 'model', label: 'AR model', canonical_policy: 'glb_usdz', master_prefers: ['glb', 'usdz'] },
+  'model.engineering': { family: 'model', label: 'Engineering model', canonical_policy: 'source_preserve', master_prefers: ['glb', 'fbx', 'obj'] },
+
+  // Type + tokens + docs
+  'type.display': { family: 'font', label: 'Display font', canonical_policy: 'licensed_source', master_prefers: ['otf', 'ttf'] },
+  'type.heading': { family: 'font', label: 'Heading font', canonical_policy: 'licensed_source', master_prefers: ['otf', 'ttf', 'woff2'] },
+  'type.body': { family: 'font', label: 'Body font', canonical_policy: 'licensed_source', master_prefers: ['otf', 'ttf', 'woff2'] },
+  'type.mono': { family: 'font', label: 'Mono font', canonical_policy: 'licensed_source', master_prefers: ['otf', 'ttf', 'woff2'] },
+  'type.ui': { family: 'font', label: 'UI font', canonical_policy: 'licensed_source', master_prefers: ['otf', 'ttf', 'woff2'] },
+  'token.color': { family: 'tokens', label: 'Color tokens', canonical_policy: 'dtcg_json', master_prefers: ['json', 'yaml'] },
+  'token.type': { family: 'tokens', label: 'Type tokens', canonical_policy: 'dtcg_json', master_prefers: ['json'] },
+  'token.theme': { family: 'tokens', label: 'Theme / CSS', canonical_policy: 'token_source', master_prefers: ['css', 'json'] },
+  'doc.guideline': { family: 'docs', label: 'Brand guideline', canonical_policy: 'structured', master_prefers: ['md', 'html', 'json'] },
+  'doc.markdown': { family: 'docs', label: 'Markdown doc', canonical_policy: 'structured', master_prefers: ['md'] },
+
+  'asset.generic': { family: 'generic', label: 'Unclassified asset', canonical_policy: 'inspect', master_prefers: [] },
+});
+
+export function listAssetRoles() {
+  return Object.entries(ASSET_ROLES).map(([id, meta]) => ({ id, ...meta }));
+}
+
+export function getAssetRole(id) {
+  return ASSET_ROLES[String(id || '').trim()] || null;
+}
+
+/** Composition / canvas targets for hero & social roles */
+export const ROLE_CANVAS = Object.freeze({
+  'hero.landscape': { width: 1920, height: 1080 },
+  'hero.ultrawide': { width: 2560, height: 1080 },
+  'hero.mobile': { width: 1080, height: 1350 },
+  'hero.poster': { width: 1080, height: 1920 },
+  'hero.product': { width: 1920, height: 1080 },
+  'social.og': { width: 1200, height: 630 },
+  'social.square': { width: 1080, height: 1080 },
+  'social.portrait': { width: 1080, height: 1350 },
+  'social.story': { width: 1080, height: 1920 },
+  'icon.app': { width: 1024, height: 1024 },
+  'icon.maskable': { width: 512, height: 512, safe_padding: 0.2 },
+});
+
+/**
+ * Heuristic role classification from filename + extension + optional dims.
+ */
+export function classifyAssetRole({ path: filePath, contentType, width, height, textHint } = {}) {
+  const name = String(filePath || '').toLowerCase();
+  const base = name.split('/').pop() || '';
+  const ext = (base.includes('.') ? base.split('.').pop() : '') || '';
+  const hints = `${base} ${textHint || ''}`.toLowerCase();
+
+  let role = 'asset.generic';
+  let confidence = 0.35;
+
+  if (/\.(otf|ttf|woff2?)$/i.test(name) || ['otf', 'ttf', 'woff', 'woff2'].includes(ext)) {
+    role = hints.includes('mono') || hints.includes('code')
+      ? 'type.mono'
+      : hints.includes('display')
+        ? 'type.display'
+        : hints.includes('heading') || hints.includes('title')
+          ? 'type.heading'
+          : 'type.body';
+    confidence = 0.95;
+  } else if (/\.(glb|gltf|usdz|obj|fbx)$/i.test(name)) {
+    role = hints.includes('ar') || ext === 'usdz' ? 'model.ar' : 'model.product';
+    confidence = 0.88;
+  } else if (/\.(mp4|mov|webm|mkv)$/i.test(name)) {
+    role = hints.includes('loop') || hints.includes('ui') ? 'motion.loop' : 'motion.hero';
+    confidence = 0.9;
+  } else if (/\.json$/i.test(name) && (hints.includes('lottie') || hints.includes('animation'))) {
+    role = 'motion.lottie';
+    confidence = 0.85;
+  } else if (/\.riv$/i.test(name)) {
+    role = 'motion.rive';
+    confidence = 0.9;
+  } else if (/\.(css|scss)$/i.test(name) || (/\.json$/i.test(name) && hints.includes('token'))) {
+    role = hints.includes('token') || hints.includes('theme') ? 'token.theme' : 'token.color';
+    confidence = 0.8;
+  } else if (/\.(md|markdown)$/i.test(name)) {
+    role = hints.includes('brand') || hints.includes('guideline') ? 'doc.guideline' : 'doc.markdown';
+    confidence = 0.75;
+  } else if (/favicon|apple-touch|site\.webmanifest/i.test(hints)) {
+    role = 'favicon';
+    confidence = 0.96;
+  } else if (/maskable|adaptive/i.test(hints)) {
+    role = 'icon.maskable';
+    confidence = 0.92;
+  } else if (/app[-_]?icon|icon[-_]?1024|icns/i.test(hints)) {
+    role = 'icon.app';
+    confidence = 0.93;
+  } else if (/logo|wordmark|mark[-_]/i.test(hints) || ext === 'svg') {
+    if (/mark|mono|glyph/i.test(hints)) role = 'logo.mark';
+    else if (/word/i.test(hints)) role = 'logo.wordmark';
+    else if (/white/i.test(hints)) role = 'logo.white';
+    else if (/black/i.test(hints)) role = 'logo.black';
+    else role = 'logo.primary';
+    confidence = ext === 'svg' ? 0.96 : 0.85;
+  } else if (/og[-_]?image|open[-_]?graph|twitter[-_]?card|social/i.test(hints)) {
+    role = 'social.og';
+    confidence = 0.91;
+  } else if (/hero|banner|masthead/i.test(hints)) {
+    if (width && height && height > width) role = 'hero.mobile';
+    else if (width && height && width / height > 2) role = 'hero.ultrawide';
+    else role = 'hero.landscape';
+    confidence = 0.88;
+  } else if (/screenshot|product[-_]?shot|ui[-_]?shot/i.test(hints)) {
+    role = 'product.raw';
+    confidence = 0.86;
+  } else if (ext === 'html' || ext === 'htm') {
+    role = 'doc.guideline';
+    confidence = 0.55;
+  }
+
+  const meta = getAssetRole(role) || ASSET_ROLES['asset.generic'];
+  return {
+    role,
+    family: meta.family,
+    confidence,
+    label: meta.label,
+    canonical_policy: meta.canonical_policy,
+    needs_review: confidence < 0.7,
+  };
+}