@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/packages/theme-scenes/src/contracts/index.js

@@ -0,0 +1,286 @@
+/**
+ * Content contracts — PAGE → SECTION → GROUP → BLOCK.
+ * Scenes never hardcode URLs, CDN hosts, or product copy.
+ */
+
+/** @typedef {'route'|'url'|'action'|'mailto'|'tel'} ActionTargetType */
+
+/**
+ * @typedef {object} RouteRef
+ * @property {'route'} type
+ * @property {string} ref  // e.g. "product.agentsam" — host resolves
+ */
+
+/**
+ * @typedef {object} UrlRef
+ * @property {'url'} type
+ * @property {string} href
+ */
+
+/**
+ * @typedef {object} ActionTarget
+ * @property {ActionTargetType} type
+ * @property {string} [ref]
+ * @property {string} [href]
+ */
+
+/**
+ * @typedef {object} MediaRef
+ * @property {string} [assetRole]  // BrandPack role / asset id
+ * @property {string} [provider]   // cloudflare-images | r2 | url | local
+ * @property {string} [ref]
+ * @property {string} [alt]
+ * @property {[number, number]} [focalPoint] // 0–1
+ * @property {string} [fit] // cover | contain
+ */
+
+/**
+ * @typedef {object} CopyBlock
+ * @property {'copy'} kind
+ * @property {string} [id]
+ * @property {'eyebrow'|'display'|'heading'|'body'|'caption'|'label'} [variant]
+ * @property {string} [eyebrow]
+ * @property {string} [title]
+ * @property {string} [body]
+ * @property {string[]} [bullets]
+ * @property {number} [level]
+ */
+
+/**
+ * @typedef {object} MediaBlock
+ * @property {'media'} kind
+ * @property {string} [id]
+ * @property {MediaRef} media
+ * @property {'image'|'video'|'model'|'svg'} [mediaKind]
+ */
+
+/**
+ * @typedef {object} ActionBlock
+ * @property {'action'} kind
+ * @property {string} [id]
+ * @property {string} label
+ * @property {ActionTarget} target
+ * @property {'primary'|'secondary'|'ghost'|'link'} [variant]
+ */
+
+/**
+ * @typedef {object} CardItem
+ * @property {string} [id]
+ * @property {string} [title]
+ * @property {string} [body]
+ * @property {string} [tag]
+ * @property {MediaRef} [media]
+ * @property {ActionTarget} [target]
+ * @property {string} [category]
+ */
+
+/**
+ * @typedef {object} CardCollectionBlock
+ * @property {'cards'} kind
+ * @property {string} [id]
+ * @property {CardItem[]} items
+ * @property {{ strategy?: 'adaptive'|'rail'|'bento'|'stack', minWidth?: number, maxColumns?: number }} [layout]
+ */
+
+/**
+ * @typedef {object} DemoBlock
+ * @property {'demo'} kind
+ * @property {string} [id]
+ * @property {string} adapter  // e.g. agentsam-mini-composer | database-editor
+ * @property {Record<string, unknown>} [props]
+ * @property {'demo'|'interactive'|'static'} [mode]
+ */
+
+/**
+ * @typedef {object} MetricBlock
+ * @property {'metric'} kind
+ * @property {string} [id]
+ * @property {string} label
+ * @property {string} value
+ * @property {string} [hint]
+ */
+
+/**
+ * @typedef {object} QuoteBlock
+ * @property {'quote'} kind
+ * @property {string} [id]
+ * @property {string} text
+ * @property {string} [attribution]
+ */
+
+/** @typedef {CopyBlock|MediaBlock|ActionBlock|CardCollectionBlock|DemoBlock|MetricBlock|QuoteBlock} ContentBlock */
+
+/**
+ * @typedef {object} SectionGroup
+ * @property {string} [id]
+ * @property {'stack'|'split'|'grid'|'feature'|'asymmetric'} [layout]
+ * @property {ContentBlock[]} blocks
+ */
+
+/**
+ * @typedef {object} SceneTheme
+ * @property {'auto'|'light'|'dark'|'inverse'|'canvas'} [mode]
+ * @property {'canvas'|'raised'|'inverse'|'bridge'|'transparent'} [surface]
+ * @property {'primary'|'muted'|'inverse'} [text]
+ * @property {'brand'|'teal'|'neutral'} [accent]
+ * @property {'auto'|'light'|'dark'|'inverse'} [headerTone]
+ */
+
+/**
+ * @typedef {object} ScrollStage
+ * @property {number} at  // 0–1
+ * @property {string} id
+ */
+
+/**
+ * @typedef {object} SceneMotion
+ * @property {'none'|'reveal'|'scrub'|'ken-burns'|'story'} [profile]
+ * @property {number} [intensity] // 0–1
+ * @property {boolean} [reducedMotionCrossfade]
+ */
+
+/**
+ * @typedef {object} ScrollBehavior
+ * @property {'natural'|'viewport'|'linger'|'sticky-story'|'cinematic'|'bridge'} mode
+ * @property {number} [length] // vh units when not natural
+ * @property {number} [pin]
+ * @property {ScrollStage[]} [stages]
+ */
+
+/**
+ * @typedef {object} SectionContent
+ * @property {string} id
+ * @property {string} scene  // SceneKind id
+ * @property {SceneTheme} [theme]
+ * @property {SceneMotion} [motion]
+ * @property {ScrollBehavior} [scroll]
+ * @property {string} [visual]  // visual primitive id
+ * @property {string} [demo]    // demo adapter id
+ * @property {SectionGroup[]} [groups]
+ * @property {string} [contentRef] // optional external content pointer
+ */
+
+/**
+ * @typedef {object} ShellContent
+ * @property {'adaptive'|'minimal'|'none'} [header]
+ * @property {'default'|'compact'|'none'} [footer]
+ * @property {boolean} [filterRail]
+ * @property {ActionTarget[]} [nav]
+ * @property {MediaRef} [logo]
+ * @property {MediaRef} [logoInverse]
+ * @property {MediaRef} [avatar]
+ */
+
+/**
+ * @typedef {object} PageContent
+ * @property {string} id
+ * @property {string} theme  // theme id
+ * @property {ShellContent} [shell]
+ * @property {SectionContent[]} sections
+ * @property {Record<string, string>} [routes] // optional page-local route map
+ * @property {object} [seo]
+ */
+
+export const BLOCK_KINDS = Object.freeze([
+  'copy', 'media', 'action', 'cards', 'demo', 'metric', 'quote',
+]);
+
+export const SCROLL_MODES = Object.freeze([
+  'natural', 'viewport', 'linger', 'sticky-story', 'cinematic', 'bridge',
+]);
+
+export const SCROLL_PRESETS = Object.freeze({
+  natural: { mode: 'natural' },
+  viewport: { mode: 'viewport', length: 100 },
+  linger: { mode: 'linger', length: 140 },
+  'sticky-story': { mode: 'sticky-story', length: 220, pin: 100 },
+  cinematic: { mode: 'cinematic', length: 280, pin: 100 },
+  bridge: { mode: 'bridge', length: 60 },
+});
+
+export function createCopyBlock(partial = {}) {
+  return { kind: 'copy', variant: 'body', ...partial };
+}
+
+export function createMediaBlock(partial = {}) {
+  return { kind: 'media', mediaKind: 'image', media: {}, ...partial };
+}
+
+export function createActionBlock(partial = {}) {
+  return {
+    kind: 'action',
+    variant: 'primary',
+    label: '',
+    target: { type: 'route', ref: 'home' },
+    ...partial,
+  };
+}
+
+export function createCardsBlock(items = [], layout = {}) {
+  return {
+    kind: 'cards',
+    items: Array.isArray(items) ? items : [],
+    layout: {
+      strategy: 'adaptive',
+      minWidth: 280,
+      maxColumns: 4,
+      ...layout,
+    },
+  };
+}
+
+export function createDemoBlock(adapter, props = {}) {
+  return { kind: 'demo', adapter, mode: 'demo', props };
+}
+
+/** Adaptive card composition — never invent filler cards. */
+export function composeCardCollection(items = [], layout = {}) {
+  const list = Array.isArray(items) ? items.filter(Boolean) : [];
+  if (list.length === 0) return null;
+  const strategy = layout.strategy || 'adaptive';
+  let resolved = strategy;
+  if (strategy === 'adaptive') {
+    if (list.length === 1) resolved = 'feature';
+    else if (list.length === 2) resolved = 'split';
+    else if (list.length === 3) resolved = 'asymmetric';
+    else if (list.length <= 4) resolved = 'grid';
+    else resolved = 'rail';
+  }
+  return createCardsBlock(list, { ...layout, strategy: resolved });
+}
+
+export function resolveRoute(target, routeMap = {}) {
+  if (!target) return null;
+  if (target.type === 'url' || target.type === 'mailto' || target.type === 'tel') {
+    return target.href || null;
+  }
+  if (target.type === 'route') {
+    return routeMap[target.ref] || null;
+  }
+  return null;
+}
+
+export function validatePageContent(page) {
+  const errors = [];
+  const warnings = [];
+  if (!page?.id) errors.push({ code: 'page_id_required' });
+  if (!page?.theme) warnings.push({ code: 'theme_missing', message: 'theme defaults to foundation' });
+  if (!Array.isArray(page?.sections) || !page.sections.length) {
+    warnings.push({ code: 'no_sections' });
+  }
+  for (const section of page?.sections || []) {
+    if (!section.id) errors.push({ code: 'section_id_required' });
+    if (!section.scene) errors.push({ code: 'scene_required', section: section.id });
+    for (const group of section.groups || []) {
+      for (const block of group.blocks || []) {
+        if (!BLOCK_KINDS.includes(block.kind)) {
+          errors.push({ code: 'unknown_block', kind: block.kind, section: section.id });
+        }
+        if (block.kind === 'cards' && (!block.items || !block.items.length)) {
+          warnings.push({ code: 'empty_cards', section: section.id });
+        }
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}

package/packages/theme-scenes/src/demos/index.js

@@ -0,0 +1,65 @@
+/**
+ * Demo adapters — marketing scenes consume real product surfaces.
+ * Adapters are contracts; hosts inject implementations.
+ */
+
+export const DEMO_ADAPTERS = Object.freeze({
+  'agentsam-mini-composer': {
+    id: 'agentsam-mini-composer',
+    label: 'AgentSam MiniComposer',
+    description: 'Real AgentSam / MiniComposer workspace with optional marketingDemoProvider.',
+    product: 'agentsam',
+    modes: ['demo', 'interactive'],
+    storyStages: ['intro', 'prompt', 'plan', 'edit', 'runtime', 'receipt', 'exit'],
+  },
+  'database-editor': {
+    id: 'database-editor',
+    label: 'Database Editor',
+    description: 'Lightweight D1/SQLite editor preview (schema, grid, query).',
+    product: 'database',
+    modes: ['demo', 'interactive'],
+    capabilities: ['schema', 'query', 'crud', 'metrics'],
+  },
+  'cad-viewer': {
+    id: 'cad-viewer',
+    label: 'CAD / Model Viewer',
+    description: 'GLB/glTF turntable + poster; BrandPack model role.',
+    product: 'cad',
+    modes: ['demo', 'interactive'],
+  },
+  'generic-iframe': {
+    id: 'generic-iframe',
+    label: 'Generic Iframe',
+    description: 'Escape hatch for hosted demos (games, embeds). Prefer real adapters.',
+    product: null,
+    modes: ['static', 'interactive'],
+  },
+});
+
+export function getDemoAdapter(id) {
+  return DEMO_ADAPTERS[id] || null;
+}
+
+export function listDemoAdapters() {
+  return Object.values(DEMO_ADAPTERS);
+}
+
+/**
+ * DemoHost descriptor — host apps bind adapter → component.
+ * @param {string} adapter
+ * @param {object} [options]
+ */
+export function createDemoHost(adapter, options = {}) {
+  const meta = DEMO_ADAPTERS[adapter];
+  if (!meta) {
+    throw new Error(`Unknown demo adapter: ${adapter}`);
+  }
+  return {
+    kind: 'demo-host',
+    adapter,
+    mode: options.mode || 'demo',
+    props: options.props || {},
+    provider: options.provider || 'marketingDemoProvider',
+    meta,
+  };
+}

package/packages/theme-scenes/src/index.js

@@ -0,0 +1,75 @@
+export {
+  BLOCK_KINDS,
+  SCROLL_MODES,
+  SCROLL_PRESETS,
+  createCopyBlock,
+  createMediaBlock,
+  createActionBlock,
+  createCardsBlock,
+  createDemoBlock,
+  composeCardCollection,
+  resolveRoute,
+  validatePageContent,
+} from './contracts/index.js';
+
+export {
+  SCENE_KINDS,
+  SCENE_ORIGIN,
+  getSceneKind,
+  listSceneKinds,
+  normalizeSection,
+  createSection,
+} from './scenes/index.js';
+
+export {
+  SHELL_KINDS,
+  createShellContent,
+  listShellKinds,
+} from './shell/index.js';
+
+export {
+  shouldRenderBlock,
+  filterRenderableBlocks,
+} from './blocks/index.js';
+
+export {
+  VISUAL_KINDS,
+  getVisual,
+  listVisuals,
+} from './visuals/index.js';
+
+export {
+  DEMO_ADAPTERS,
+  getDemoAdapter,
+  listDemoAdapters,
+  createDemoHost,
+} from './demos/index.js';
+
+export {
+  FOUNDATION_THEME,
+  INNERANIMAL_THEME,
+  AGENTSAM_THEME,
+  AUTODIDACT_THEME,
+  getTheme,
+  listThemes,
+  resolveTheme,
+  themeToCssVars,
+} from './themes/index.js';
+
+export {
+  createAgencyHomePreset,
+  createWorkPreset,
+  createProductPreset,
+  createServicesPreset,
+  createBrandStoryPreset,
+  createPreset,
+  listPresets,
+  PRESET_BUILDERS,
+} from './presets/index.js';
+
+export {
+  compilePage,
+  resolveMedia,
+  computeScrollProgress,
+  stageAtProgress,
+} from './runtime/compile.js';

package/packages/theme-scenes/src/presets/index.js

@@ -0,0 +1,263 @@
+/**
+ * Page presets — composition only. Content is injected via SECTION_CONTENT.
+ */
+
+import { SCROLL_PRESETS } from '../contracts/index.js';
+import { createSection } from '../scenes/index.js';
+import { createShellContent } from '../shell/index.js';
+
+const DEFAULT_ROUTES = Object.freeze({
+  home: '/',
+  'work.index': '/work',
+  about: '/about',
+  services: '/services',
+  contact: '/contact',
+  'product.agentsam': '/agentsam',
+  'product.database': '/database',
+  'product.cad': '/cad',
+  'product.cloud': '/cloud',
+  learn: '/learn',
+});
+
+/**
+ * Agency / institutional home: quiet hero → product demo → bridge → gallery → capabilities.
+ */
+export function createAgencyHomePreset(content = {}) {
+  const c = content;
+  return {
+    id: c.id || 'agency-home',
+    theme: c.theme || 'inneranimal',
+    routes: { ...DEFAULT_ROUTES, ...(c.routes || {}) },
+    shell: createShellContent(c.shell || { header: 'adaptive', footer: 'default' }),
+    sections: [
+      createSection({
+        id: 'intro',
+        scene: 'hero.scroll-product',
+        visual: 'visual.orbital-field',
+        theme: { surface: 'inverse', headerTone: 'auto' },
+        scroll: { ...SCROLL_PRESETS['sticky-story'], length: 210 },
+        motion: { profile: 'story', intensity: 0.34 },
+        groups: c.heroGroups || [],
+        contentRef: c.heroRef || 'home.hero',
+      }),
+      createSection({
+        id: 'flagship-demo',
+        scene: 'product.demo',
+        demo: 'agentsam-mini-composer',
+        theme: { surface: 'inverse' },
+        scroll: SCROLL_PRESETS['sticky-story'],
+        groups: c.demoGroups || [],
+        contentRef: c.demoRef || 'products.agentsam',
+      }),
+      createSection({
+        id: 'bridge',
+        scene: 'bridge.theme',
+        scroll: SCROLL_PRESETS.bridge,
+        groups: c.bridgeGroups || [],
+        contentRef: c.bridgeRef || 'home.bridge',
+      }),
+      createSection({
+        id: 'selected-work',
+        scene: 'work.gallery',
+        theme: { surface: 'canvas' },
+        groups: c.workGroups || [],
+        contentRef: c.workRef || 'work.selected',
+      }),
+      createSection({
+        id: 'capabilities',
+        scene: 'capability.grid',
+        theme: { surface: 'inverse' },
+        groups: c.capabilityGroups || [],
+        contentRef: c.capabilityRef || 'home.capabilities',
+      }),
+    ],
+  };
+}
+
+/**
+ * Work page: editorial/scroll hero → product demos → stack → interactive stage.
+ */
+export function createWorkPreset(content = {}) {
+  const c = content;
+  return {
+    id: c.id || 'work',
+    theme: c.theme || 'inneranimal',
+    routes: { ...DEFAULT_ROUTES, ...(c.routes || {}) },
+    shell: createShellContent({
+      header: 'adaptive',
+      footer: 'default',
+      filterRail: c.filterRail !== false,
+      ...(c.shell || {}),
+    }),
+    sections: [
+      createSection({
+        id: 'intro',
+        scene: c.heroScene || 'hero.scroll-product',
+        visual: c.visual || 'visual.orbital-field',
+        theme: c.heroTone === 'canvas'
+          ? { surface: 'canvas', headerTone: 'light' }
+          : { surface: 'inverse', headerTone: 'auto' },
+        scroll: c.heroTone === 'canvas'
+          ? SCROLL_PRESETS.viewport
+          : { ...SCROLL_PRESETS['sticky-story'], length: 210 },
+        groups: c.heroGroups || [],
+        contentRef: c.heroRef || 'work.hero',
+      }),
+      createSection({
+        id: 'agentsam',
+        scene: 'product.demo',
+        demo: 'agentsam-mini-composer',
+        theme: { surface: 'inverse' },
+        scroll: SCROLL_PRESETS['sticky-story'],
+        groups: c.agentsamGroups || [],
+        contentRef: 'products.agentsam',
+      }),
+      createSection({
+        id: 'products',
+        scene: 'product.stack',
+        theme: { surface: 'canvas' },
+        groups: c.productGroups || [],
+        contentRef: 'products.featured',
+      }),
+      createSection({
+        id: 'database',
+        scene: 'product.demo',
+        demo: 'database-editor',
+        theme: { surface: 'canvas' },
+        scroll: SCROLL_PRESETS.linger,
+        groups: c.databaseGroups || [],
+        contentRef: 'products.database',
+      }),
+      createSection({
+        id: 'interactive',
+        scene: 'interactive.stage',
+        demo: 'generic-iframe',
+        visual: 'visual.atmosphere',
+        groups: c.interactiveGroups || [],
+        contentRef: 'products.interactive',
+      }),
+    ],
+  };
+}
+
+/**
+ * Product landing — single flagship demo focus.
+ */
+export function createProductPreset(content = {}) {
+  const c = content;
+  return {
+    id: c.id || 'product',
+    theme: c.theme || 'agentsam',
+    routes: { ...DEFAULT_ROUTES, ...(c.routes || {}) },
+    shell: createShellContent(c.shell || { header: 'adaptive', footer: 'compact' }),
+    sections: [
+      createSection({
+        id: 'intro',
+        scene: 'hero.editorial',
+        theme: { surface: 'canvas' },
+        scroll: SCROLL_PRESETS.viewport,
+        groups: c.heroGroups || [],
+        contentRef: c.heroRef || 'product.hero',
+      }),
+      createSection({
+        id: 'demo',
+        scene: 'product.demo',
+        demo: c.demo || 'agentsam-mini-composer',
+        scroll: SCROLL_PRESETS.cinematic,
+        motion: { profile: 'story', intensity: 0.35 },
+        groups: c.demoGroups || [],
+        contentRef: c.demoRef || 'product.demo',
+      }),
+      createSection({
+        id: 'gallery',
+        scene: 'gallery.storyboard',
+        groups: c.galleryGroups || [],
+        contentRef: c.galleryRef || 'product.gallery',
+      }),
+    ],
+  };
+}
+
+/**
+ * Services / capabilities page.
+ */
+export function createServicesPreset(content = {}) {
+  const c = content;
+  return {
+    id: c.id || 'services',
+    theme: c.theme || 'inneranimal',
+    routes: { ...DEFAULT_ROUTES, ...(c.routes || {}) },
+    shell: createShellContent(c.shell || {}),
+    sections: [
+      createSection({
+        id: 'intro',
+        scene: 'hero.editorial',
+        theme: { surface: 'canvas' },
+        scroll: SCROLL_PRESETS.viewport,
+        groups: c.heroGroups || [],
+        contentRef: 'services.hero',
+      }),
+      createSection({
+        id: 'capabilities',
+        scene: 'capability.grid',
+        theme: { surface: 'inverse' },
+        groups: c.capabilityGroups || [],
+        contentRef: 'services.capabilities',
+      }),
+      createSection({
+        id: 'rail',
+        scene: 'gallery.rail',
+        groups: c.railGroups || [],
+        contentRef: 'services.partners',
+      }),
+    ],
+  };
+}
+
+/**
+ * Brand / Create storyboard page (guideline lanes, not static PDF).
+ */
+export function createBrandStoryPreset(content = {}) {
+  const c = content;
+  return {
+    id: c.id || 'brand-story',
+    theme: c.theme || 'inneranimal',
+    routes: { ...DEFAULT_ROUTES, ...(c.routes || {}) },
+    shell: createShellContent(c.shell || {}),
+    sections: [
+      createSection({
+        id: 'system',
+        scene: 'gallery.storyboard',
+        theme: { surface: 'canvas' },
+        scroll: SCROLL_PRESETS.linger,
+        groups: c.storyGroups || [],
+        contentRef: 'brand.system',
+      }),
+      createSection({
+        id: 'capabilities',
+        scene: 'capability.grid',
+        theme: { surface: 'inverse' },
+        groups: c.capabilityGroups || [],
+        contentRef: 'brand.capabilities',
+      }),
+    ],
+  };
+}
+
+export const PRESET_BUILDERS = Object.freeze({
+  'agency-home': createAgencyHomePreset,
+  work: createWorkPreset,
+  product: createProductPreset,
+  services: createServicesPreset,
+  'brand-story': createBrandStoryPreset,
+});
+
+export function createPreset(name, content = {}) {
+  const builder = PRESET_BUILDERS[name];
+  if (!builder) throw new Error(`Unknown preset: ${name}`);
+  return builder(content);
+}
+
+export function listPresets() {
+  return Object.keys(PRESET_BUILDERS);
+}