@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/packages/agentsam-brand/src/core/receipts.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { BrandAssetError } from './errors.js';
+
+export function receiptDir(baseDir, { brand, asset, version }) {
+  return path.join(baseDir, '.agentsam', 'brand', 'assets', brand, asset, version);
+}
+
+export function writePromotionReceipt(dir, receipt) {
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'promotion.json');
+  fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+  return file;
+}
+
+export function loadPromotionReceipt(dir) {
+  const file = path.join(dir, 'promotion.json');
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function listBrandAssetReceipts(cwd = process.cwd()) {
+  const root = path.join(cwd, '.agentsam', 'brand', 'assets');
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const brand of fs.readdirSync(root)) {
+    const brandDir = path.join(root, brand);
+    if (!fs.statSync(brandDir).isDirectory()) continue;
+    for (const asset of fs.readdirSync(brandDir)) {
+      const assetDir = path.join(brandDir, asset);
+      if (!fs.statSync(assetDir).isDirectory()) continue;
+      for (const version of fs.readdirSync(assetDir)) {
+        const receipt = loadPromotionReceipt(path.join(assetDir, version));
+        if (receipt) out.push(receipt);
+      }
+    }
+  }
+  return out;
+}
+
+export function requireReceipt(dir) {
+  const receipt = loadPromotionReceipt(dir);
+  if (!receipt) throw new BrandAssetError('receipt_missing', `Promotion receipt missing: ${dir}`);
+  return receipt;
+}
+
+/**
+ * Human CLI receipt — storage / delivery / registry as separate rows.
+ * Never collapses them into a single "uploaded" checkmark.
+ */
+export function formatPublishReceipt(result = {}) {
+  const lines = [];
+  const overall = result.overall || (result.ok ? 'success' : 'failed');
+  const title = overall === 'planned'
+    ? 'Brand asset plan'
+    : overall === 'partial_success'
+      ? 'Brand asset partially published'
+      : overall === 'success'
+        ? 'Brand asset published'
+        : 'Brand asset publish failed';
+  lines.push(`Agent Sam · ${title}`);
+  lines.push('');
+
+  const storage = result.storage || null;
+  lines.push('Storage');
+  if (!storage) {
+    lines.push('  — not requested');
+  } else {
+    const mark = storage.status === 'published' ? '✓'
+      : storage.status === 'planned' ? '○'
+        : storage.status === 'failed' ? '✗'
+          : '—';
+    const provider = storage.provider || 'unknown';
+    lines.push(`  ${mark} ${labelProvider(provider)}`);
+    if (storage.binding) lines.push(`    ${storage.binding}`);
+    if (storage.bucket) lines.push(`    ${storage.bucket}`);
+    const keys = (storage.objects || result.uploaded || []).map((o) => o.key).filter(Boolean);
+    for (const k of keys.slice(0, 5)) lines.push(`    ${k}`);
+    if (keys.length > 5) lines.push(`    … +${keys.length - 5} more`);
+  }
+
+  lines.push('');
+  lines.push('Delivery');
+  const delivery = result.delivery;
+  if (!delivery) {
+    lines.push('  — Cloudflare Images · not requested');
+  } else {
+    const mark = delivery.status === 'published' ? '✓'
+      : delivery.status === 'planned' ? '○'
+        : delivery.status === 'failed' ? '✗'
+          : delivery.status === 'skipped' ? '—'
+            : '?';
+    const provider = delivery.provider || 'unknown';
+    if (delivery.status === 'published') {
+      const id = delivery.provider_receipt?.provider_asset_id
+        || delivery.provider_receipt?.image_id
+        || delivery.provider_asset_id;
+      const variants = delivery.provider_receipt?.variants || delivery.variants || [];
+      const hash = delivery.provider_receipt?.account_hash || delivery.account_hash;
+      lines.push(`  ${mark} ${labelProvider(provider)}`);
+      if (delivery.provider_receipt?.account_id || delivery.account_id) {
+        lines.push(`    account    ${delivery.provider_receipt?.account_id || delivery.account_id}`);
+      }
+      if (hash) lines.push(`    hash       ${hash}`);
+      if (id) lines.push(`    image id  ${id}`);
+      if (variants.length) {
+        const names = variants.map((v) => {
+          try {
+            const u = new URL(v);
+            return u.pathname.split('/').filter(Boolean).pop() || v;
+          } catch {
+            return String(v);
+          }
+        });
+        lines.push(`    variants  ${names.join(', ')}`);
+      }
+    } else if (delivery.status === 'planned') {
+      lines.push(`  ${mark} ${labelProvider(provider)} · planned`);
+    } else if (delivery.status === 'failed') {
+      lines.push(`  ${mark} ${labelProvider(provider)} · ${delivery.reason || delivery.error || 'failed'}`);
+    } else if (delivery.status === 'skipped') {
+      lines.push(`  ${mark} ${labelProvider(provider)} · ${delivery.reason || 'skipped'}`);
+    } else {
+      lines.push(`  ${mark} ${labelProvider(provider)} · ${delivery.status}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Registry');
+  const registry = result.registry;
+  if (!registry || registry.status === 'skipped') {
+    lines.push('  — not requested');
+  } else {
+    const mark = registry.status === 'published' ? '✓'
+      : registry.status === 'planned' ? '○'
+        : '✗';
+    lines.push(`  ${mark} D1`);
+  }
+
+  if (overall === 'partial_success') {
+    lines.push('');
+    lines.push('Overall: partial_success (layers reported independently)');
+  }
+
+  return lines.join('\n');
+}
+
+function labelProvider(provider) {
+  if (provider === 'cloudflare-r2') return 'Cloudflare R2';
+  if (provider === 'cloudflare-images') return 'Cloudflare Images';
+  if (provider === 'filesystem') return 'Local filesystem';
+  if (provider === 'memory') return 'In-memory';
+  if (provider === 'plan_only') return 'Plan only';
+  return provider;
+}

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

@@ -0,0 +1,280 @@
+/**
+ * Compile brand.pack.json → dist representations (ZIP is an export, not SoT).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assert } from '../errors.js';
+import { deriveBrandAssets } from '../derivatives.js';
+import { writeZipArchive } from '../pack.js';
+import { FORMAT_CAPABILITIES, FORMAT_FAMILIES } from '../capabilities.js';
+import {
+  planSemanticDerivatives,
+  materializedToSharpDerivatives,
+  defaultLogoUsage,
+} from './derivatives-semantic.js';
+import {
+  normalizeBrandPack,
+  touchProvenance,
+  BRAND_PACK_FILENAME,
+} from './schema.js';
+import { applyBrandTemplate } from './templates.js';
+import { loadBrandPack, saveBrandPack } from './ingest-graph.js';
+
+function tokensToCss(tokens = {}) {
+  const lines = [':root {'];
+  for (const [k, v] of Object.entries(tokens.color || {})) {
+    const val = typeof v === 'object' ? v.value : v;
+    const name = k.startsWith('--') ? k : `--${k.replace(/[^a-z0-9-]/gi, '-')}`;
+    lines.push(`  ${name}: ${val};`);
+  }
+  for (const [k, v] of Object.entries(tokens.type || {})) {
+    if (v?.family) lines.push(`  --font-${k.replace(/[^a-z0-9-]/gi, '-')}: ${v.family};`);
+  }
+  lines.push('}');
+  return `${lines.join('\n')}\n`;
+}
+
+function tokensToJson(tokens = {}) {
+  return `${JSON.stringify({ $schema: 'https://agentsam.dev/schemas/brand-tokens/v1.json', ...tokens }, null, 2)}\n`;
+}
+
+function buildStudioHtml(pack) {
+  const brand = pack.brand?.name || pack.brand?.id || 'Brand';
+  const assets = (pack.assets || []).map((a) => `
+    <tr>
+      <td>${a.role}</td>
+      <td>${a.label || a.id}</td>
+      <td>${a.master?.format || '—'}</td>
+      <td>${a.provenance?.confidence != null ? Number(a.provenance.confidence).toFixed(2) : '—'}</td>
+      <td>${a.licensing?.status || '—'}</td>
+    </tr>`).join('');
+  const colors = Object.entries(pack.tokens?.color || {}).slice(0, 24).map(([k, v]) => {
+    const val = typeof v === 'object' ? v.value : v;
+    return `<div class="swatch"><i style="background:${val}"></i><span>${k}<br/><small>${val}</small></span></div>`;
+  }).join('');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${brand} — Brand Studio</title>
+  <style>
+    :root { color-scheme: dark; --bg:#0b0b0e; --fg:#eceae6; --muted:#8b8680; --line:#2a2a32; }
+    * { box-sizing: border-box; }
+    body { margin:0; font-family: ui-sans-serif, system-ui, sans-serif; background:var(--bg); color:var(--fg); }
+    header { padding:28px 32px; border-bottom:1px solid var(--line); display:flex; justify-content:space-between; align-items:center; }
+    h1 { margin:0; font-size:1.35rem; font-weight:560; }
+    nav { display:flex; gap:12px; padding:12px 32px; border-bottom:1px solid var(--line); color:var(--muted); font-size:0.85rem; }
+    main { padding:28px 32px; display:grid; gap:28px; }
+    section h2 { font-size:0.95rem; margin:0 0 12px; letter-spacing:0.04em; text-transform:uppercase; color:var(--muted); }
+    table { width:100%; border-collapse:collapse; font-size:0.88rem; }
+    th, td { text-align:left; padding:8px 10px; border-bottom:1px solid var(--line); }
+    .swatches { display:flex; flex-wrap:wrap; gap:10px; }
+    .swatch { display:flex; gap:8px; align-items:center; min-width:140px; }
+    .swatch i { width:28px; height:28px; border-radius:6px; border:1px solid var(--line); display:block; }
+    .note { color:var(--muted); font-size:0.85rem; }
+    code { font-size:0.8rem; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>${brand}</h1>
+    <span class="note">brand.pack.json · compiled studio</span>
+  </header>
+  <nav>
+    <span>Overview</span><span>Logo</span><span>Color</span><span>Type</span>
+    <span>Imagery</span><span>Motion</span><span>3D</span><span>Tokens</span><span>Delivery</span>
+  </nav>
+  <main>
+    <section>
+      <h2>Assets (${pack.assets?.length || 0})</h2>
+      <table>
+        <thead><tr><th>Role</th><th>Label</th><th>Master</th><th>Confidence</th><th>License</th></tr></thead>
+        <tbody>${assets || '<tr><td colspan="5">No assets</td></tr>'}</tbody>
+      </table>
+    </section>
+    <section>
+      <h2>Color tokens</h2>
+      <div class="swatches">${colors || '<p class="note">No color tokens yet — ingest HTML/CSS or declare tokens.</p>'}</div>
+    </section>
+    <section>
+      <h2>Delivery policy</h2>
+      <p class="note">Images → <code>${pack.delivery?.images}</code> · Video → <code>${pack.delivery?.video}</code> · Objects → <code>${pack.delivery?.objects}</code></p>
+      <p class="note">Policy: <code>${pack.delivery?.policy || 'role_canonical'}</code> (per-role masters; CF negotiates AVIF/WebP)</p>
+    </section>
+    <section>
+      <h2>Source of truth</h2>
+      <p class="note">This page is a <strong>compiled representation</strong>. Edit <code>brand.pack.json</code>, then re-run <code>agentsam brand build</code>.</p>
+    </section>
+  </main>
+</body>
+</html>
+`;
+}
+
+/**
+ * Build compiled dist from brand.pack.json
+ */
+export async function buildBrandPackFromGraph(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  let pack = options.pack;
+  if (!pack && options.from) {
+    pack = await loadBrandPack(options.from, { cwd });
+  }
+  assert(pack, 'pack_required', 'brand.pack.json / pack object required');
+  pack = normalizeBrandPack(pack);
+
+  if (options.template) {
+    pack = applyBrandTemplate(pack, options.template);
+  }
+
+  const brandId = pack.brand.id || 'untitled';
+  const distRoot = path.resolve(
+    options.outDir || path.join(cwd, '.agentsam', 'brand', 'dist', brandId),
+  );
+  fs.rmSync(distRoot, { recursive: true, force: true });
+
+  const dirs = {
+    root: distRoot,
+    web: path.join(distRoot, 'web'),
+    social: path.join(distRoot, 'social'),
+    icons: path.join(distRoot, 'icons'),
+    app: path.join(distRoot, 'app'),
+    media: path.join(distRoot, 'media'),
+    models: path.join(distRoot, 'models'),
+    tokens: path.join(distRoot, 'brand-tokens'),
+    assets: path.join(distRoot, 'assets'),
+  };
+  for (const d of Object.values(dirs)) fs.mkdirSync(d, { recursive: true });
+
+  // Persist SoT at dist root
+  saveBrandPack(pack, distRoot);
+
+  // Tokens compile
+  fs.writeFileSync(path.join(dirs.tokens, 'tokens.json'), tokensToJson(pack.tokens));
+  fs.writeFileSync(path.join(dirs.tokens, 'tokens.css'), tokensToCss(pack.tokens));
+
+  const plans = [];
+  const materialized = [];
+  const warnings = [...(pack.validation?.warnings || [])];
+
+  for (const asset of pack.assets || []) {
+    const plan = planSemanticDerivatives(asset.role, { materializeAll: options.materializeAll });
+    asset.derivatives = plan;
+    if (asset.family === 'logo' || String(asset.role).startsWith('logo.')) {
+      asset.usage = asset.usage || defaultLogoUsage(asset.role);
+      const usageDir = path.join(dirs.assets, 'logo', asset.role.replace(/^logo\./, '') || 'primary');
+      fs.mkdirSync(usageDir, { recursive: true });
+      fs.writeFileSync(path.join(usageDir, 'usage.json'), `${JSON.stringify(asset.usage, null, 2)}\n`);
+    }
+
+    // Copy master when present
+    const masterPath = asset.master?.path;
+    if (masterPath && fs.existsSync(masterPath)) {
+      const familyDir = path.join(dirs.assets, asset.family || 'generic', asset.id);
+      fs.mkdirSync(familyDir, { recursive: true });
+      const dest = path.join(familyDir, path.basename(masterPath));
+      fs.copyFileSync(masterPath, dest);
+      asset.master = { ...asset.master, compiled: path.relative(distRoot, dest) };
+
+      // Materialize sharp derivatives for raster masters only
+      const sharpRows = materializedToSharpDerivatives(plan);
+      if (sharpRows.length && /\.(png|jpe?g|webp|gif|tiff?)$/i.test(masterPath)) {
+        const outDerive = path.join(familyDir, 'derived');
+        const result = await deriveBrandAssets({
+          sourcePath: masterPath,
+          outDir: outDerive,
+          derivatives: sharpRows,
+          asset: asset.id,
+        });
+        for (const art of result.artifacts || []) {
+          if (art.status === 'generated') {
+            materialized.push({
+              asset_id: asset.id,
+              role: asset.role,
+              ...art,
+              relative: path.relative(distRoot, art.path),
+            });
+          }
+        }
+      }
+
+      // Fonts: never copy into redistributable zip unless licensed
+      if (asset.family === 'font' && asset.licensing?.redistributable !== true) {
+        warnings.push({
+          code: 'font_not_redistributable',
+          asset_id: asset.id,
+          message: `${asset.label || asset.id} excluded from redistributable export until licensing.redistributable=true`,
+        });
+      }
+    }
+
+    plans.push({ asset_id: asset.id, role: asset.role, plan });
+  }
+
+  // Studio HTML (interactive guidelines scaffold)
+  fs.writeFileSync(path.join(distRoot, 'studio.html'), buildStudioHtml(pack));
+  fs.writeFileSync(path.join(distRoot, 'gallery.html'), buildStudioHtml(pack));
+
+  // Delivery manifest (compiled)
+  const deliveryManifest = {
+    schema: 'agentsam.brand-delivery.v1',
+    brand: pack.brand,
+    delivery: pack.delivery,
+    format_capabilities: FORMAT_CAPABILITIES,
+    format_families: FORMAT_FAMILIES,
+    assets: (pack.assets || []).map((a) => ({
+      id: a.id,
+      role: a.role,
+      master: a.master?.compiled || a.master?.relative || null,
+      canonical_policy: a.derivatives?.canonical_policy || null,
+      redistributable: a.licensing ? a.licensing.redistributable === true : true,
+    })),
+    materialized_count: materialized.length,
+  };
+  fs.writeFileSync(path.join(distRoot, 'delivery.manifest.json'), `${JSON.stringify(deliveryManifest, null, 2)}\n`);
+
+  pack.validation = { warnings, errors: pack.validation?.errors || [] };
+  pack = touchProvenance(pack, { op: 'build', dist: distRoot, materialized: materialized.length });
+  saveBrandPack(pack, distRoot);
+
+  let zip = null;
+  if (options.zip !== false) {
+    const zipPath = path.resolve(
+      options.zipPath || path.join(cwd, '.agentsam', 'brand', 'packs', `${brandId}-brand.zip`),
+    );
+    const entries = [];
+    const walk = (dir, base = '') => {
+      for (const name of fs.readdirSync(dir)) {
+        const full = path.join(dir, name);
+        const rel = path.join(base, name).replace(/\\/g, '/');
+        if (fs.statSync(full).isDirectory()) walk(full, rel);
+        else {
+          // Skip non-redistributable fonts from zip
+          if (/\.(otf|ttf|woff2?)$/i.test(name)) {
+            const asset = pack.assets.find((a) => a.master?.compiled?.endsWith(name) || a.master?.path?.endsWith(name));
+            if (asset?.licensing && asset.licensing.redistributable !== true) continue;
+          }
+          entries.push({ name: `${brandId}/${rel}`, data: fs.readFileSync(full) });
+        }
+      }
+    };
+    walk(distRoot);
+    writeZipArchive(entries, zipPath);
+    zip = zipPath;
+  }
+
+  return {
+    ok: true,
+    capability: 'brand.build',
+    source_of_truth: path.join(distRoot, BRAND_PACK_FILENAME),
+    dist: distRoot,
+    zip,
+    studio: path.join(distRoot, 'studio.html'),
+    plans,
+    materialized,
+    warnings,
+    pack,
+  };
+}

package/packages/agentsam-brand/src/core/v2/derivatives-semantic.js

@@ -0,0 +1,207 @@
+/**
+ * Semantic derivatives — DERIVABLE vs MATERIALIZED.
+ * Shared responsive ladder is a menu; roles pick what to materialize.
+ */
+
+import { ROLE_CANVAS, getAssetRole } from './roles.js';
+
+/** Shared base ladder for responsive web imagery (materialize subset per role) */
+export const RESPONSIVE_WIDTH_LADDER = Object.freeze([
+  320, 480, 640, 768, 960, 1280, 1600, 1920, 2560,
+]);
+
+/**
+ * @typedef {'derivable'|'materialized'} DerivativeState
+ */
+
+/**
+ * Build semantic derivative plan for a role (does not write files).
+ */
+export function planSemanticDerivatives(role, options = {}) {
+  const meta = getAssetRole(role) || { family: 'generic', canonical_policy: 'inspect' };
+  const family = meta.family;
+  const materializeAll = options.materializeAll === true;
+  const out = {
+    role,
+    family,
+    canonical_policy: meta.canonical_policy,
+    buckets: {
+      master: [],
+      raster_fallbacks: [],
+      delivery: [],
+      platform: [],
+      poster: [],
+      tokens: [],
+    },
+  };
+
+  if (family === 'logo') {
+    out.buckets.master.push(derivable('master.svg', { format: 'svg', semantic: 'master' }));
+    out.buckets.raster_fallbacks.push(
+      ...[256, 512, 1024].map((w) => maybeMaterialize(`raster-${w}.png`, {
+        format: 'png', width: w, height: w, semantic: 'raster-fallback', materialize: true,
+      })),
+    );
+    out.buckets.delivery.push(
+      derivable('header', { semantic: 'delivery.header', note: 'on-demand / CF Images' }),
+      derivable('header-retina', { semantic: 'delivery.header-retina' }),
+      derivable('footer', { semantic: 'delivery.footer' }),
+      derivable('nav-compact', { semantic: 'delivery.nav-compact' }),
+    );
+    out.buckets.platform.push(
+      derivable('social', { semantic: 'platform.social' }),
+      derivable('favicon', { semantic: 'platform.favicon' }),
+      derivable('print', { semantic: 'platform.print' }),
+    );
+  } else if (family === 'favicon') {
+    const sizes = [
+      { name: 'favicon.svg', format: 'svg', materialize: true },
+      { name: 'favicon-16.png', format: 'png', width: 16, height: 16, materialize: true },
+      { name: 'favicon-32.png', format: 'png', width: 32, height: 32, materialize: true },
+      { name: 'favicon-48.png', format: 'png', width: 48, height: 48, materialize: true },
+      { name: 'apple-touch-icon.png', format: 'png', width: 180, height: 180, materialize: true },
+      { name: 'pwa-192.png', format: 'png', width: 192, height: 192, materialize: true },
+      { name: 'pwa-512.png', format: 'png', width: 512, height: 512, materialize: true },
+      { name: 'pwa-maskable-192.png', format: 'png', width: 192, height: 192, semantic: 'maskable', materialize: true, safe_padding: 0.2 },
+      { name: 'pwa-maskable-512.png', format: 'png', width: 512, height: 512, semantic: 'maskable', materialize: true, safe_padding: 0.2 },
+      { name: 'favicon.ico', format: 'ico', materialize: false, note: 'platform tool when available' },
+      { name: 'site.webmanifest', format: 'json', materialize: true },
+    ];
+    for (const s of sizes) {
+      out.buckets.platform.push(maybeMaterialize(s.name, s));
+    }
+  } else if (family === 'app-icon') {
+    const ladder = [1024, 512, 256, 128, 64, 32, 16];
+    out.buckets.master.push(maybeMaterialize('artwork-1024.png', {
+      format: 'png', width: 1024, height: 1024, semantic: 'master', materialize: true,
+    }));
+    for (const w of ladder) {
+      out.buckets.platform.push(maybeMaterialize(`icon-${w}.png`, {
+        format: 'png', width: w, height: w, semantic: 'preview-size', materialize: w >= 128 || materializeAll,
+        warn_detail_loss: w <= 32,
+      }));
+    }
+    out.buckets.platform.push(
+      derivable('icon.icns', { format: 'icns', semantic: 'macos' }),
+      derivable('icon.ico', { format: 'ico', semantic: 'windows' }),
+    );
+  } else if (family === 'hero' || family === 'social' || family === 'product-shot') {
+    const canvas = ROLE_CANVAS[role] || { width: 1920, height: 1080 };
+    out.buckets.master.push(maybeMaterialize('master', {
+      format: 'png',
+      width: canvas.width,
+      height: canvas.height,
+      semantic: 'master',
+      materialize: true,
+    }));
+    const widths = pickResponsiveWidths(family, options.maxWidth || canvas.width);
+    for (const w of widths) {
+      out.buckets.raster_fallbacks.push(maybeMaterialize(`w${w}`, {
+        format: 'webp',
+        width: w,
+        semantic: 'responsive',
+        materialize: materializeAll || w === widths[Math.floor(widths.length / 2)],
+        note: materializeAll ? null : 'often on-demand via Cloudflare Images',
+      }));
+    }
+    out.buckets.delivery.push(
+      derivable('avif', { format: 'avif', semantic: 'delivery', note: 'CF format negotiation preferred' }),
+      derivable('webp', { format: 'webp', semantic: 'delivery' }),
+      derivable('jpeg', { format: 'jpeg', semantic: 'delivery-fallback' }),
+    );
+  } else if (family === 'video') {
+    out.buckets.master.push(derivable('master.mov', { format: 'mov', semantic: 'master', materialize: true }));
+    out.buckets.delivery.push(
+      maybeMaterialize('web-1080.mp4', { format: 'mp4', height: 1080, semantic: 'web', materialize: true }),
+      maybeMaterialize('web-720.mp4', { format: 'mp4', height: 720, semantic: 'web', materialize: false }),
+      maybeMaterialize('mobile.mp4', { format: 'mp4', height: 720, semantic: 'mobile', materialize: false }),
+    );
+    out.buckets.poster.push(
+      maybeMaterialize('poster-1920.webp', { format: 'webp', width: 1920, semantic: 'poster', materialize: true }),
+      maybeMaterialize('poster-mobile.webp', { format: 'webp', width: 1080, semantic: 'poster', materialize: false }),
+    );
+  } else if (family === 'model') {
+    out.buckets.master.push(maybeMaterialize('master.glb', { format: 'glb', semantic: 'master', materialize: true }));
+    out.buckets.platform.push(
+      derivable('model.gltf', { format: 'gltf' }),
+      derivable('model.usdz', { format: 'usdz', semantic: 'ar' }),
+    );
+    out.buckets.poster.push(
+      maybeMaterialize('preview.webp', { format: 'webp', semantic: 'preview', materialize: true }),
+      maybeMaterialize('poster.webp', { format: 'webp', semantic: 'poster', materialize: false }),
+      derivable('turntable.mp4', { format: 'mp4', semantic: 'turntable' }),
+    );
+  } else if (family === 'font') {
+    out.buckets.master.push(derivable('source', { semantic: 'licensed_source', licensing_required: true }));
+    out.buckets.delivery.push(
+      derivable('woff2', { format: 'woff2', note: 'only if licensing.redistributable' }),
+    );
+  } else if (family === 'tokens' || family === 'theme') {
+    out.buckets.tokens.push(
+      maybeMaterialize('tokens.json', { format: 'json', materialize: true }),
+      maybeMaterialize('tokens.css', { format: 'css', materialize: true }),
+      derivable('tokens.ts', { format: 'ts' }),
+      derivable('tailwind.preset.ts', { format: 'ts' }),
+    );
+  }
+
+  return out;
+}
+
+function derivable(id, extra = {}) {
+  return { id, state: 'derivable', ...extra };
+}
+
+function maybeMaterialize(id, { materialize = false, ...extra } = {}) {
+  return {
+    id,
+    state: materialize ? 'materialized' : 'derivable',
+    ...extra,
+  };
+}
+
+export function pickResponsiveWidths(family, maxWidth = 2560) {
+  const max = Number(maxWidth) || 2560;
+  let picks = RESPONSIVE_WIDTH_LADDER.filter((w) => w <= max);
+  if (family === 'product-shot' || family === 'social') {
+    picks = picks.filter((w) => [320, 640, 960, 1280, 1600].includes(w) || w === picks[picks.length - 1]);
+  } else if (family === 'hero') {
+    picks = picks.filter((w) => w >= 640);
+  } else if (family === 'logo') {
+    picks = [];
+  }
+  return picks;
+}
+
+/** Flatten plan into sharp-style derivative rows for MATERIALIZED items only */
+export function materializedToSharpDerivatives(plan) {
+  const rows = [];
+  for (const bucket of Object.values(plan.buckets || {})) {
+    for (const d of bucket) {
+      if (d.state !== 'materialized') continue;
+      if (!d.format || d.format === 'svg' || d.format === 'json' || d.format === 'css') continue;
+      if (!d.width && !d.height) continue;
+      rows.push({
+        id: d.id,
+        role: d.semantic || 'raster',
+        format: d.format,
+        width: d.width || d.height,
+        height: d.height || d.width,
+        quality: d.quality,
+        safe_padding: d.safe_padding,
+      });
+    }
+  }
+  return rows;
+}
+
+/** Default logo usage.json */
+export function defaultLogoUsage(role = 'logo.primary') {
+  return {
+    role,
+    minimumWidth: { digital: 96, printMm: 24 },
+    clearspace: { basis: 'markHeight', multiplier: 0.25 },
+    allowedBackgrounds: ['light', 'dark', 'brand'],
+    forbidden: ['stretch', 'rotate', 'recolor-unapproved', 'add-shadow'],
+  };
+}