@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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

@@ -0,0 +1,209 @@
+/**
+ * BrandPack v2 — brand.pack.json is the source of truth.
+ * ZIP / localhost preview / production publish are compiled representations.
+ *
+ * Schema id: agentsam.brand-pack.v2
+ */
+
+export const BRAND_PACK_SCHEMA = 'agentsam.brand-pack.v2';
+export const BRAND_PACK_SCHEMA_URL = 'https://agentsam.dev/schemas/brand-pack/v2.json';
+export const BRAND_PACK_FILENAME = 'brand.pack.json';
+
+/** Empty brand graph — never seeds product identity. */
+export function createEmptyBrandPack({ brandId = '', brandName = '' } = {}) {
+  const id = String(brandId || '').trim().toLowerCase();
+  return {
+    $schema: BRAND_PACK_SCHEMA_URL,
+    schema: BRAND_PACK_SCHEMA,
+    brand: {
+      id: id || null,
+      name: brandName || null,
+    },
+    concept: {
+      position: null,
+      personality: [],
+      principles: [],
+    },
+    assets: [],
+    tokens: {
+      color: {},
+      type: {},
+      space: {},
+      radius: {},
+      motion: {},
+    },
+    rules: {
+      logo: {},
+      color: {},
+      type: {},
+      imagery: {},
+    },
+    delivery: {
+      images: 'cloudflare-images',
+      video: 'cloudflare-stream',
+      objects: 'r2',
+      policy: 'role_canonical', // replaces flat canonical_png — chosen per role
+    },
+    platforms: {
+      web: {},
+      pwa: {},
+      ios: {},
+      android: {},
+      macos: {},
+    },
+    validation: {
+      warnings: [],
+      errors: [],
+    },
+    provenance: {
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      sources: [],
+      operations: [],
+    },
+  };
+}
+
+/**
+ * Normalize / migrate a pack document (v1 folder manifests → v2 graph).
+ */
+export function normalizeBrandPack(input = {}) {
+  if (!input || typeof input !== 'object') {
+    return createEmptyBrandPack();
+  }
+
+  // v1 pack manifest (single-asset) → wrap into graph
+  const isV1 = input.schema === 'agentsam.brand-pack.v1'
+    || (typeof input.brand === 'string' && input.asset && !Array.isArray(input.assets));
+  if (isV1) {
+    const pack = createEmptyBrandPack({
+      brandId: typeof input.brand === 'string' ? input.brand : input.brand?.id,
+      brandName: typeof input.brand === 'object' ? input.brand?.name : null,
+    });
+    if (input.asset) {
+      pack.assets.push({
+        id: `asset_${input.asset}`,
+        role: inferRoleFromAssetId(input.asset),
+        version: input.version || 'v1',
+        master: null,
+        derivatives: [],
+        seo: input.seo || null,
+        provenance: { migrated_from: 'agentsam.brand-pack.v1' },
+      });
+    }
+    if (input.format_capabilities) {
+      pack.provenance.migrated_capabilities = true;
+    }
+    return pack;
+  }
+
+  const pack = createEmptyBrandPack({
+    brandId: input.brand?.id || (typeof input.brand === 'string' ? input.brand : ''),
+    brandName: input.brand?.name || '',
+  });
+
+  Object.assign(pack.brand, input.brand || {});
+  if (typeof input.brand === 'string') {
+    pack.brand.id = input.brand;
+  }
+  Object.assign(pack.concept, input.concept || {});
+  pack.assets = Array.isArray(input.assets) ? input.assets.map(normalizeAssetNode) : [];
+  pack.tokens = {
+    color: { ...(input.tokens?.color || {}) },
+    type: { ...(input.tokens?.type || {}) },
+    space: { ...(input.tokens?.space || {}) },
+    radius: { ...(input.tokens?.radius || {}) },
+    motion: { ...(input.tokens?.motion || {}) },
+  };
+  pack.rules = { ...pack.rules, ...(input.rules || {}) };
+  pack.delivery = { ...pack.delivery, ...(input.delivery || {}) };
+  pack.platforms = { ...pack.platforms, ...(input.platforms || {}) };
+  pack.validation = {
+    warnings: [...(input.validation?.warnings || [])],
+    errors: [...(input.validation?.errors || [])],
+  };
+  pack.provenance = {
+    ...pack.provenance,
+    ...(input.provenance || {}),
+    updated_at: new Date().toISOString(),
+  };
+  pack.schema = BRAND_PACK_SCHEMA;
+  pack.$schema = BRAND_PACK_SCHEMA_URL;
+  return pack;
+}
+
+function inferRoleFromAssetId(asset) {
+  const a = String(asset || '').toLowerCase();
+  if (a.includes('favicon')) return 'favicon';
+  if (a.includes('logo')) return 'logo.primary';
+  if (a.includes('og') || a.includes('social')) return 'social.og';
+  if (a.includes('icon') || a.includes('app-icon')) return 'icon.app';
+  if (a.includes('hero')) return 'hero.landscape';
+  return 'asset.generic';
+}
+
+export function normalizeAssetNode(row = {}) {
+  return {
+    id: row.id || `asset_${Date.now().toString(36)}`,
+    role: row.role || 'asset.generic',
+    family: row.family || null,
+    version: row.version || 'v1',
+    label: row.label || null,
+    master: row.master || null,
+    // Semantic buckets — not a flat size ladder
+    variants: row.variants || {
+      master: null,
+      raster_fallbacks: [],
+      delivery: [],
+      platform: [],
+    },
+    derivatives: Array.isArray(row.derivatives) ? row.derivatives : [],
+    // Content / CMS graph context (machine identity ≠ delivery filename)
+    semantic: row.semantic || {
+      subject: [],
+      page: null,
+      section: null,
+      locale: null,
+      intent: null,
+    },
+    naming: row.naming || {
+      slug: null,
+      strategy: 'semantic',
+      aliases: [],
+    },
+    usage: row.usage || null,
+    seo: row.seo || {
+      alt: null,
+      title: null,
+      caption: null,
+    },
+    focalPoint: row.focalPoint || null,
+    safeArea: row.safeArea || null,
+    artDirection: row.artDirection || null,
+    licensing: row.licensing || null, // critical for fonts
+    delivery: row.delivery || null,
+    providerMetadata: row.providerMetadata || {},
+    provenance: row.provenance || null,
+    validation: row.validation || null,
+  };
+}
+
+export function touchProvenance(pack, operation) {
+  const next = { ...pack };
+  next.provenance = {
+    ...next.provenance,
+    updated_at: new Date().toISOString(),
+    operations: [
+      ...(next.provenance?.operations || []),
+      {
+        at: new Date().toISOString(),
+        ...operation,
+      },
+    ].slice(-200),
+  };
+  return next;
+}
+
+export function findAssetsByRole(pack, role) {
+  return (pack.assets || []).filter((a) => a.role === role || String(a.role || '').startsWith(`${role}.`));
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Uniform brand pack templates — orchestrated starter graphs per build type.
+ */
+import { createEmptyBrandPack, normalizeBrandPack } from './schema.js';
+import { defaultLogoUsage } from './derivatives-semantic.js';
+
+export const BRAND_TEMPLATES = Object.freeze({
+  'web-app': {
+    id: 'web-app',
+    label: 'Web / PWA app',
+    description: 'Logo, favicon+PWA icons, OG card, color+type tokens, web delivery',
+    required_roles: ['logo.primary', 'favicon', 'social.og'],
+    optional_roles: ['icon.app', 'hero.landscape', 'type.body'],
+    delivery: { images: 'cloudflare-images', video: 'cloudflare-stream', objects: 'r2', policy: 'role_canonical' },
+    platforms: { web: { enabled: true }, pwa: { enabled: true } },
+  },
+  'mobile-app': {
+    id: 'mobile-app',
+    label: 'Mobile app (iOS + Android)',
+    description: 'App icons, splash/poster, logo mark, store screenshots',
+    required_roles: ['icon.app', 'icon.ios', 'icon.android', 'logo.mark'],
+    optional_roles: ['product.marketing', 'hero.poster'],
+    delivery: { images: 'cloudflare-images', objects: 'r2', policy: 'role_canonical' },
+    platforms: { ios: { enabled: true }, android: { enabled: true } },
+  },
+  'marketing-site': {
+    id: 'marketing-site',
+    label: 'Marketing site',
+    description: 'Logo system, heroes, social, motion loop, tokens, guidelines',
+    required_roles: ['logo.primary', 'logo.mark', 'hero.landscape', 'hero.mobile', 'social.og'],
+    optional_roles: ['motion.loop', 'motion.hero', 'type.display', 'type.body'],
+    delivery: { images: 'cloudflare-images', video: 'cloudflare-stream', objects: 'r2', policy: 'role_canonical' },
+    platforms: { web: { enabled: true } },
+  },
+  'product-saas': {
+    id: 'product-saas',
+    label: 'SaaS product brand',
+    description: 'Full product visual system: UI shots, icons, tokens, docs',
+    required_roles: ['logo.primary', 'favicon', 'icon.app', 'product.raw', 'social.og', 'token.color'],
+    optional_roles: ['product.framed', 'hero.product', 'type.ui', 'model.product'],
+    delivery: { images: 'cloudflare-images', video: 'cloudflare-stream', objects: 'r2', policy: 'role_canonical' },
+    platforms: { web: { enabled: true }, pwa: { enabled: true }, macos: { enabled: true } },
+  },
+  'spatial-3d': {
+    id: 'spatial-3d',
+    label: 'Spatial / 3D brand',
+    description: 'GLB/USDZ models, posters, turntable stubs, AR export',
+    required_roles: ['model.product', 'model.ar', 'logo.mark'],
+    optional_roles: ['hero.product', 'motion.hero'],
+    delivery: { objects: 'r2', images: 'cloudflare-images', policy: 'role_canonical' },
+    platforms: { web: { enabled: true } },
+  },
+});
+
+export function listBrandTemplates() {
+  return Object.values(BRAND_TEMPLATES);
+}
+
+export function getBrandTemplate(id) {
+  return BRAND_TEMPLATES[String(id || '').trim()] || null;
+}
+
+/**
+ * Seed or merge a template onto a pack (does not invent binary assets).
+ */
+export function applyBrandTemplate(packInput, templateId) {
+  const template = getBrandTemplate(templateId);
+  if (!template) return normalizeBrandPack(packInput);
+
+  const pack = normalizeBrandPack(packInput);
+  pack.delivery = { ...pack.delivery, ...template.delivery };
+  pack.platforms = { ...pack.platforms, ...template.platforms };
+  pack.rules.template = {
+    id: template.id,
+    required_roles: template.required_roles,
+    optional_roles: template.optional_roles,
+  };
+
+  const have = new Set(pack.assets.map((a) => a.role));
+  for (const role of template.required_roles) {
+    if (!have.has(role)) {
+      pack.assets.push({
+        id: `placeholder_${role.replace(/\./g, '_')}`,
+        role,
+        family: role.split('.')[0],
+        label: `${role} (required by ${template.id})`,
+        master: null,
+        variants: { master: null, raster_fallbacks: [], delivery: [], platform: [] },
+        derivatives: [],
+        usage: role.startsWith('logo.') ? defaultLogoUsage(role) : null,
+        provenance: { placeholder: true, template: template.id },
+      });
+    }
+  }
+
+  pack.validation = pack.validation || { warnings: [], errors: [] };
+  const missing = template.required_roles.filter((r) => {
+    const asset = pack.assets.find((a) => a.role === r);
+    return !asset?.master?.path && !asset?.master?.compiled;
+  });
+  for (const role of missing) {
+    pack.validation.warnings.push({
+      code: 'template_role_unfilled',
+      role,
+      message: `Template ${template.id} requires ${role} — ingest a master`,
+    });
+  }
+
+  return pack;
+}
+
+export function createPackFromTemplate(templateId, { brandId, brandName } = {}) {
+  return applyBrandTemplate(createEmptyBrandPack({ brandId, brandName }), templateId);
+}

package/packages/agentsam-brand/src/index.js

@@ -1,3 +1,10 @@
+/**
+ * @inneranimalmedia/agentsam-sdk-brand
+ *
+ * Brand intelligence (scan/resolve/plan) + portable brand-asset promotion SDK.
+ * Product-specific assets (e.g. AgentSam icons) live outside this package.
+ */
+
 export { brandScan } from './scan.js';
 export { brandResolve, parseDeclaredColor } from './resolve.js';
 export { buildBrandContractDraft, writeBrandArtifacts } from './contract.js';
@@ -8,41 +15,191 @@ export {
   brandGoalFromPlan,
 } from './goap-actions.js';
 
+// Core brand-asset SDK
+export { BrandAssetError } from './core/errors.js';
+export {
+  inspectBrandAsset,
+  inspectLocalAsset,
+  validateSvgMark,
+  isExcludedIntermediate,
+  sha256File,
+  sha256Buffer,
+} from './core/inspect.js';
+export {
+  BRAND_ASSETS_SCHEMA,
+  brandAssetPrefix,
+  resolveKeyLayout,
+} from './core/keys.js';
+export {
+  deriveBrandAssets,
+  discoverDerivativeCapabilities,
+  formatBytesKb,
+  hasMagick,
+  hasSharp,
+  hasSquooshBinary,
+} from './core/derivatives.js';
+export {
+  discoverProcessors,
+  listProcessors,
+  getProcessor,
+  resolveProcessor,
+  encodeWithScheduler,
+  optimizeWithScheduler,
+  PROCESSOR_CAPABILITIES,
+  REJECTED_PROCESSORS,
+  planProcessorOrder,
+} from './core/processors/index.js';
+export {
+  optimizeBrandAsset,
+  optimizePolicyForRole,
+} from './core/optimize.js';
+export {
+  slugifySegment,
+  buildSemanticSlug,
+  buildDerivativeFilename,
+  validateDeliveryName,
+  applySemanticNaming,
+} from './core/naming.js';
+export {
+  planBrandAssetPromotion,
+  normalizePromotionSpec,
+  parseDeriveFlag,
+  createBrandAssetManifest,
+} from './core/plan.js';
+export {
+  promoteBrandAssets,
+  publishBrandAssets,
+  verifyBrandAssets,
+} from './core/promote.js';
+export {
+  listBrandAssetReceipts,
+  writePromotionReceipt,
+  loadPromotionReceipt,
+  receiptDir,
+  formatPublishReceipt,
+} from './core/receipts.js';
+
+// Adapters
+export { MemoryStorageAdapter } from './adapters/memory.js';
+export { FilesystemStorageAdapter } from './adapters/filesystem.js';
+export { CloudflareR2StorageAdapter } from './adapters/cloudflare-r2.js';
+export {
+  CloudflareImagesDeliveryAdapter,
+  isCloudflareImagesPublished,
+  resolveCloudflareImagesConfig,
+  resolveCloudflareImagesCredentials,
+  cloudflareImageUrl,
+  cloudflareImagesDeliveryBase,
+  mayUploadToCloudflareImages,
+  CLOUDFLARE_IMAGES_PLATFORM_INPUT_TYPES,
+  CANONICAL_PNG_DELIVERY_POLICY_TYPES,
+  AGENTSAM_IMAGES_DELIVERY_POLICY_TYPES,
+} from './adapters/cloudflare-images.js';
+export { D1BrandRegistryAdapter } from './adapters/d1-registry.js';
+
+export {
+  FORMAT_CAPABILITIES,
+  FORMAT_FAMILIES,
+  formatCapabilities,
+  canResizeFormat,
+  familyCapabilities,
+  INGEST_EXTENSIONS,
+} from './core/capabilities.js';
+export {
+  sniffImageBuffer,
+  readStdinImage,
+  scanDropFolder,
+  waitForDrop,
+  resolveSourceInput,
+  expandHome,
+  isImagePath,
+} from './core/ingest.js';
+export {
+  buildBrandPack,
+  buildGalleryHtml,
+  writeZipArchive,
+} from './core/pack.js';
+export {
+  previewBrandPack,
+  resolvePackRoot,
+} from './core/preview.js';
+
+// BrandPack v2 — brand.pack.json is source of truth
+export {
+  BRAND_PACK_SCHEMA,
+  BRAND_PACK_SCHEMA_URL,
+  BRAND_PACK_FILENAME,
+  createEmptyBrandPack,
+  normalizeBrandPack,
+  normalizeAssetNode,
+  touchProvenance,
+  findAssetsByRole,
+} from './core/v2/schema.js';
+export {
+  ASSET_ROLES,
+  ROLE_CANVAS,
+  listAssetRoles,
+  getAssetRole,
+  classifyAssetRole,
+} from './core/v2/roles.js';
+export {
+  RESPONSIVE_WIDTH_LADDER,
+  planSemanticDerivatives,
+  materializedToSharpDerivatives,
+  pickResponsiveWidths,
+  defaultLogoUsage,
+} from './core/v2/derivatives-semantic.js';
+export {
+  ingestBrandSources,
+  extractArchive,
+  extractFromCode,
+  loadBrandPack,
+  saveBrandPack,
+  isArchivePath,
+  isIngestiblePath,
+} from './core/v2/ingest-graph.js';
+export {
+  buildBrandPackFromGraph,
+} from './core/v2/compile.js';
+export {
+  BRAND_TEMPLATES,
+  listBrandTemplates,
+  getBrandTemplate,
+  applyBrandTemplate,
+  createPackFromTemplate,
+} from './core/v2/templates.js';
+
+// Presets (format strategies — never product/customer identity)
+export {
+  getDerivativePreset,
+  listDerivativePresets,
+  DERIVATIVE_PRESETS,
+} from './presets/index.js';
+
+// CLI controller (shared by agentsam brand + agentsam-brand bin)
+export { runBrandAssetCommand, parseBrandCliArgs } from './cli/controller.js';
+export { runBrandPromoteWizard } from './cli/wizard.js';
+
+/** @deprecated Prefer adapter constructors; kept for soft resolve. */
+export async function resolveBrandAssetStorage(options = {}) {
+  const { FilesystemStorageAdapter } = await import('./adapters/filesystem.js');
+  const { MemoryStorageAdapter } = await import('./adapters/memory.js');
+  if (options.kind === 'memory') return new MemoryStorageAdapter();
+  return new FilesystemStorageAdapter({ rootDir: options.rootDir });
+}
+
 export const BRAND_CAPABILITY_META = Object.freeze({
-  'brand.scan': {
-    id: 'brand.scan',
-    deterministic: true,
-    model_required: false,
-    side_effects: 'none',
-    produces: ['brand.evidence'],
-  },
-  'brand.resolve': {
-    id: 'brand.resolve',
-    deterministic: true,
-    model_required: false,
-    side_effects: 'none',
-    produces: ['brand.resolved'],
-  },
-  'brand.plan': {
-    id: 'brand.plan',
-    deterministic: true,
-    model_required: false,
-    model_assisted_optional: true,
-    side_effects: 'none',
-    produces: ['brand.plan'],
-  },
-  'brand.apply': {
-    id: 'brand.apply',
-    deterministic: true,
-    model_required: false,
-    side_effects: 'repository-write',
-    status: 'stub',
-  },
-  'brand.verify': {
-    id: 'brand.verify',
-    deterministic: true,
-    model_required: false,
-    side_effects: 'none',
-    status: 'stub',
-  },
+  'brand.scan': { id: 'brand.scan', deterministic: true, model_required: false, side_effects: 'none' },
+  'brand.resolve': { id: 'brand.resolve', deterministic: true, model_required: false, side_effects: 'none' },
+  'brand.plan': { id: 'brand.plan', deterministic: true, model_required: false, side_effects: 'none' },
+  'brand.inspect': { id: 'brand.inspect', deterministic: true, model_required: false, side_effects: 'none' },
+  'brand.derive': { id: 'brand.derive', deterministic: true, model_required: false, side_effects: 'filesystem' },
+  'brand.optimize': { id: 'brand.optimize', deterministic: true, model_required: false, side_effects: 'filesystem' },
+  'brand.ingest': { id: 'brand.ingest', deterministic: true, model_required: false, side_effects: 'filesystem' },
+  'brand.build': { id: 'brand.build', deterministic: true, model_required: false, side_effects: 'filesystem' },
+  'brand.pack': { id: 'brand.pack', deterministic: true, model_required: false, side_effects: 'filesystem' },
+  'brand.preview': { id: 'brand.preview', deterministic: true, model_required: false, side_effects: 'localhost' },
+  'brand.promote': { id: 'brand.promote', deterministic: true, model_required: false, side_effects: 'storage-optional' },
+  'brand.publish': { id: 'brand.publish', deterministic: true, model_required: false, side_effects: 'storage-adapter' },
+  'brand.verify': { id: 'brand.verify', deterministic: true, model_required: false, side_effects: 'none' },
 });

package/packages/agentsam-brand/src/presets/app-icon.json

@@ -0,0 +1,16 @@
+{
+  "id": "app-icon",
+  "label": "Standard app icon",
+  "description": "PNG size ladder 1024→16 plus optional WebP/AVIF @1024",
+  "derivatives": [
+    { "id": "png-1024", "role": "raster", "format": "png", "width": 1024, "height": 1024 },
+    { "id": "png-512", "role": "raster", "format": "png", "width": 512, "height": 512 },
+    { "id": "png-256", "role": "raster", "format": "png", "width": 256, "height": 256 },
+    { "id": "png-128", "role": "raster", "format": "png", "width": 128, "height": 128 },
+    { "id": "png-64", "role": "raster", "format": "png", "width": 64, "height": 64 },
+    { "id": "png-32", "role": "raster", "format": "png", "width": 32, "height": 32 },
+    { "id": "png-16", "role": "raster", "format": "png", "width": 16, "height": 16 },
+    { "id": "webp-1024", "role": "web", "format": "webp", "width": 1024, "height": 1024, "quality": 92 },
+    { "id": "avif-1024", "role": "web", "format": "avif", "width": 1024, "height": 1024, "quality": 78 }
+  ]
+}

package/packages/agentsam-brand/src/presets/favicon.json

@@ -0,0 +1,17 @@
+{
+  "id": "favicon",
+  "label": "Favicon + PWA platform set",
+  "description": "SVG/ICO + 16/32/48, apple-touch 180, PWA 192/512 + maskable (safe padding)",
+  "role": "favicon",
+  "semantic": true,
+  "derivatives": [
+    { "id": "favicon-16", "role": "platform", "format": "png", "width": 16, "height": 16 },
+    { "id": "favicon-32", "role": "platform", "format": "png", "width": 32, "height": 32 },
+    { "id": "favicon-48", "role": "platform", "format": "png", "width": 48, "height": 48 },
+    { "id": "apple-touch-icon", "role": "platform", "format": "png", "width": 180, "height": 180 },
+    { "id": "pwa-192", "role": "platform", "format": "png", "width": 192, "height": 192 },
+    { "id": "pwa-512", "role": "platform", "format": "png", "width": 512, "height": 512 },
+    { "id": "pwa-maskable-192", "role": "maskable", "format": "png", "width": 192, "height": 192 },
+    { "id": "pwa-maskable-512", "role": "maskable", "format": "png", "width": 512, "height": 512 }
+  ]
+}

package/packages/agentsam-brand/src/presets/hero.json

@@ -0,0 +1,12 @@
+{
+  "id": "hero",
+  "label": "Hero imagery",
+  "description": "Desktop 1920×1080 master + selective responsive widths (CF Images for the rest)",
+  "role": "hero.landscape",
+  "semantic": true,
+  "derivatives": [
+    { "id": "master-1920", "role": "master", "format": "png", "width": 1920, "height": 1080 },
+    { "id": "w960", "role": "responsive", "format": "webp", "width": 960, "height": 540, "quality": 85 },
+    { "id": "w1600", "role": "responsive", "format": "webp", "width": 1600, "height": 900, "quality": 85 }
+  ]
+}

package/packages/agentsam-brand/src/presets/index.js

@@ -0,0 +1,40 @@
+import appIcon from './app-icon.json' with { type: 'json' };
+import webImage from './web-image.json' with { type: 'json' };
+import socialImage from './social-image.json' with { type: 'json' };
+import favicon from './favicon.json' with { type: 'json' };
+import ogImage from './og-image.json' with { type: 'json' };
+import logo from './logo.json' with { type: 'json' };
+import hero from './hero.json' with { type: 'json' };
+import productShot from './product-shot.json' with { type: 'json' };
+import model from './model.json' with { type: 'json' };
+
+const PRESETS = Object.freeze({
+  'app-icon': appIcon,
+  favicon,
+  logo,
+  hero,
+  'product-shot': productShot,
+  model,
+  'og-image': ogImage,
+  'web-image': webImage,
+  'social-image': socialImage,
+});
+
+export function listDerivativePresets() {
+  return Object.values(PRESETS).map((p) => ({
+    id: p.id,
+    label: p.label,
+    description: p.description,
+    role: p.role || null,
+    semantic: Boolean(p.semantic),
+    derivative_count: (p.derivatives || []).length,
+  }));
+}
+
+export function getDerivativePreset(id) {
+  const row = PRESETS[String(id || '').trim()];
+  if (!row) return null;
+  return structuredClone(row);
+}
+
+export { PRESETS as DERIVATIVE_PRESETS };

package/packages/agentsam-brand/src/presets/logo.json

@@ -0,0 +1,12 @@
+{
+  "id": "logo",
+  "label": "Logo (semantic)",
+  "description": "Raster fallbacks 256/512/1024 — SVG master preferred; delivery variants are derivable not all materialized",
+  "role": "logo.primary",
+  "semantic": true,
+  "derivatives": [
+    { "id": "raster-256", "role": "raster-fallback", "format": "png", "width": 256, "height": 256 },
+    { "id": "raster-512", "role": "raster-fallback", "format": "png", "width": 512, "height": 512 },
+    { "id": "raster-1024", "role": "raster-fallback", "format": "png", "width": 1024, "height": 1024 }
+  ]
+}

package/packages/agentsam-brand/src/presets/model.json

@@ -0,0 +1,8 @@
+{
+  "id": "model",
+  "label": "3D model package",
+  "description": "GLB master preserved; poster/preview are optional materialized derivatives",
+  "role": "model.product",
+  "semantic": true,
+  "derivatives": []
+}

package/packages/agentsam-brand/src/presets/og-image.json

@@ -0,0 +1,10 @@
+{
+  "id": "og-image",
+  "label": "Open Graph image",
+  "description": "1200×630 social/OG share image (PNG + WebP + AVIF)",
+  "derivatives": [
+    { "id": "png-1200x630", "role": "raster", "format": "png", "width": 1200, "height": 630 },
+    { "id": "webp-1200x630", "role": "web", "format": "webp", "width": 1200, "height": 630, "quality": 90 },
+    { "id": "avif-1200x630", "role": "web", "format": "avif", "width": 1200, "height": 630, "quality": 75 }
+  ]
+}