@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

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

@@ -0,0 +1,187 @@
+/**
+ * Theme package registry — neutral product identity + donor aliases.
+ *
+ * Storage model (do not flatten or delete built CSS mounts):
+ *   packages/theme-*-site          → package folders (path may keep donor slug)
+ *   packages/theme-scenes          → composition vocabulary
+ *   packages/heuristic-theme       → stock CMS shell
+ *   packages/agentsam-docs-theme   → docs skin
+ *   apps/theme-gallery-preview     → gallery demos only
+ *
+ * Canonical public ids are neutral (cypress/violet/…). Donor names stay private
+ * provenance via aliases[]. Gallery/static URLs can keep old mounts.
+ *
+ * Host typography: apps/local-studio/frontend/src/styles.css
+ * (--font-sans / --font-display / --font-mono).
+ */
+
+/** @typedef {'site-theme'|'scenes'|'storefront-shell'|'docs-skin'|'gallery-preview'} ThemePackageKind */
+
+/**
+ * @typedef {object} ThemePackageEntry
+ * @property {string} id
+ * @property {string} packageName
+ * @property {string} [packageNameLegacy]
+ * @property {string} path
+ * @property {ThemePackageKind} kind
+ * @property {string} label
+ * @property {string} [siteSlug]
+ * @property {string} [donor]
+ * @property {string[]} [aliases]
+ */
+
+/** @type {readonly ThemePackageEntry[]} */
+export const THEME_PACKAGE_REGISTRY = Object.freeze([
+  {
+    id: "cypress",
+    packageName: "@inneranimalmedia/theme-cypress",
+    packageNameLegacy: "@inneranimalmedia/theme-church-site",
+    path: "packages/theme-church-site",
+    kind: "site-theme",
+    label: "Cypress",
+    siteSlug: "church-site",
+    donor: "new-iberia-church",
+    aliases: ["church-site", "theme-church", "church", "theme-church-site", "nic"],
+  },
+  {
+    id: "violet",
+    packageName: "@inneranimalmedia/theme-violet",
+    packageNameLegacy: "@inneranimalmedia/theme-companions-site",
+    path: "packages/theme-companions-site",
+    kind: "site-theme",
+    label: "Violet",
+    siteSlug: "companions-site",
+    donor: "companions-of-caddo",
+    aliases: ["companions-site", "theme-companions", "companions", "companions-of-caddo", "theme-companions-site", "coc"],
+  },
+  {
+    id: "grove",
+    packageName: "@inneranimalmedia/theme-grove",
+    packageNameLegacy: "@inneranimalmedia/theme-floors-site",
+    path: "packages/theme-floors-site",
+    kind: "site-theme",
+    label: "Grove",
+    siteSlug: "floors-site",
+    donor: "anything-floors",
+    aliases: ["floors-site", "theme-floors", "floors", "anything-floors", "theme-floors-site", "afm"],
+  },
+  {
+    id: "ember",
+    packageName: "@inneranimalmedia/theme-ember",
+    packageNameLegacy: "@inneranimalmedia/theme-fuelnfree-site",
+    path: "packages/theme-fuelnfree-site",
+    kind: "site-theme",
+    label: "Ember",
+    siteSlug: "fuelnfree-site",
+    donor: "fuelnfreetime",
+    aliases: ["fuelnfree-site", "theme-fuelnfree", "fuelnfreetime", "fuel-n-free", "theme-fuelnfree-site", "fnf"],
+  },
+  {
+    id: "forge",
+    packageName: "@inneranimalmedia/theme-forge",
+    packageNameLegacy: "@inneranimalmedia/theme-handyman-site",
+    path: "packages/theme-handyman-site",
+    kind: "site-theme",
+    label: "Forge",
+    siteSlug: "handyman-site",
+    donor: "primeaux-handyman",
+    aliases: ["handyman-site", "theme-handyman", "handyman", "theme-handyman-site", "phs"],
+  },
+  {
+    id: "harbor",
+    packageName: "@inneranimalmedia/theme-harbor",
+    packageNameLegacy: "@inneranimalmedia/theme-insurance-site",
+    path: "packages/theme-insurance-site",
+    kind: "site-theme",
+    label: "Harbor",
+    siteSlug: "insurance-site",
+    donor: "chrystal-clear-insurance",
+    aliases: ["insurance-site", "theme-insurance", "insurance", "theme-insurance-site", "cci"],
+  },
+  {
+    id: "summit",
+    packageName: "@inneranimalmedia/theme-summit",
+    packageNameLegacy: "@inneranimalmedia/theme-shinshu-site",
+    path: "packages/theme-shinshu-site",
+    kind: "site-theme",
+    label: "Summit",
+    siteSlug: "shinshu-site",
+    donor: "shinshu-solutions",
+    aliases: ["shinshu-site", "theme-shinshu", "shinshu", "theme-shinshu-site", "shin"],
+  },
+  {
+    id: "iasf",
+    packageName: "@inneranimalmedia/theme-iasf",
+    path: "packages/theme-iasf",
+    kind: "site-theme",
+    label: "IASF Storefront",
+    siteSlug: "iasf",
+    donor: "inner-animals-storefront",
+    aliases: [
+      "theme-iasf",
+      "inneranimals-site",
+      "theme-inneranimals-site",
+      "inner-animals",
+      "inneranimals",
+      "iasf-storefront",
+    ],
+  },
+  {
+    id: "theme-scenes",
+    packageName: "@inneranimalmedia/theme-scenes",
+    path: "packages/theme-scenes",
+    kind: "scenes",
+    label: "Theme Scenes",
+    aliases: ["scenes", "composition"],
+  },
+  {
+    id: "heuristic",
+    packageName: "@inneranimalmedia/theme-heuristic",
+    path: "packages/heuristic-theme",
+    kind: "storefront-shell",
+    label: "Heuristic storefront shell",
+    aliases: ["heuristic-theme", "storefront"],
+  },
+  {
+    id: "docs",
+    packageName: "@inneranimalmedia/agentsam-docs-theme",
+    path: "packages/agentsam-docs-theme",
+    kind: "docs-skin",
+    label: "AgentSam docs skin",
+    aliases: ["agentsam-docs-theme", "docs-theme"],
+  },
+]);
+
+/**
+ * @param {string} query
+ * @returns {ThemePackageEntry | null}
+ */
+export function resolveThemePackage(query) {
+  const needle = String(query || "").trim().toLowerCase();
+  if (!needle) return null;
+  for (const entry of THEME_PACKAGE_REGISTRY) {
+    const names = [
+      entry.id,
+      entry.packageName,
+      entry.packageNameLegacy,
+      entry.path,
+      entry.siteSlug,
+      entry.donor,
+      ...(entry.aliases || []),
+    ]
+      .filter(Boolean)
+      .map((v) => String(v).toLowerCase());
+    if (names.includes(needle)) return entry;
+    if (names.some((n) => n.endsWith("/" + needle) || n.endsWith(needle))) return entry;
+  }
+  return null;
+}
+
+/**
+ * @param {ThemePackageKind} [kind]
+ * @returns {ThemePackageEntry[]}
+ */
+export function listThemePackages(kind) {
+  if (!kind) return [...THEME_PACKAGE_REGISTRY];
+  return THEME_PACKAGE_REGISTRY.filter((entry) => entry.kind === kind);
+}

package/packages/theme-scenes/src/runtime/compile.js

@@ -0,0 +1,119 @@
+/**
+ * Runtime helpers — host-agnostic. React/DOM hosts bind later.
+ */
+
+import { resolveRoute, validatePageContent, SCROLL_PRESETS } from '../contracts/index.js';
+import { normalizeSection, getSceneKind } from '../scenes/index.js';
+import { filterRenderableBlocks } from '../blocks/index.js';
+import { resolveTheme, themeToCssVars } from '../themes/index.js';
+import { getDemoAdapter, createDemoHost } from '../demos/index.js';
+import { getVisual } from '../visuals/index.js';
+
+/**
+ * Compile a PageContent into a render plan (no DOM).
+ */
+export function compilePage(page, options = {}) {
+  const validation = validatePageContent(page);
+  const theme = resolveTheme(page?.theme || 'foundation');
+  const routes = { ...(options.routes || {}), ...(page?.routes || {}) };
+  const cssVars = themeToCssVars(theme);
+
+  const sections = (page?.sections || []).map((raw) => {
+    const section = normalizeSection(raw, { scrollPresets: SCROLL_PRESETS });
+    const kind = getSceneKind(section.scene);
+    const groups = (section.groups || []).map((g) => ({
+      ...g,
+      blocks: filterRenderableBlocks(g.blocks || []).map((block) => enrichBlock(block, routes)),
+    })).filter((g) => g.blocks.length > 0);
+
+    let demoHost = null;
+    if (section.demo) {
+      try {
+        demoHost = createDemoHost(section.demo, { mode: 'demo' });
+      } catch {
+        demoHost = null;
+      }
+    }
+
+    return {
+      ...section,
+      groups,
+      sceneMeta: kind,
+      visualMeta: section.visual ? getVisual(section.visual) : null,
+      demoHost,
+      adapterMeta: section.demo ? getDemoAdapter(section.demo) : null,
+    };
+  });
+
+  return {
+    id: page?.id,
+    theme,
+    cssVars,
+    routes,
+    shell: page?.shell || null,
+    sections,
+    validation,
+    seo: page?.seo || null,
+  };
+}
+
+function enrichBlock(block, routes) {
+  if (block.kind === 'action') {
+    return {
+      ...block,
+      href: resolveRoute(block.target, routes),
+    };
+  }
+  if (block.kind === 'cards') {
+    return {
+      ...block,
+      items: (block.items || []).map((item) => ({
+        ...item,
+        href: item.target ? resolveRoute(item.target, routes) : null,
+      })),
+    };
+  }
+  return block;
+}
+
+/**
+ * Map media refs through a BrandPack / delivery resolver.
+ * @param {object} media
+ * @param {(role: string) => string|null} resolveAsset
+ */
+export function resolveMedia(media, resolveAsset) {
+  if (!media) return null;
+  if (media.assetRole && typeof resolveAsset === 'function') {
+    const url = resolveAsset(media.assetRole);
+    return { ...media, url: url || null };
+  }
+  if (media.ref && media.provider === 'url') {
+    return { ...media, url: media.ref };
+  }
+  return { ...media, url: media.ref || null };
+}
+
+/**
+ * Normalized scroll progress helper for hosts.
+ * @param {number} scrollY
+ * @param {DOMRect|object} sectionRect — { top, height }
+ * @param {object} scroll — ScrollBehavior
+ */
+export function computeScrollProgress(scrollY, sectionRect, scroll = {}) {
+  if (!sectionRect || scroll.mode === 'natural') return 0;
+  const start = (sectionRect.top ?? 0) + scrollY;
+  const lengthPx = ((scroll.length || 100) / 100) * (typeof window !== 'undefined' ? window.innerHeight : 800);
+  const pin = ((scroll.pin || 0) / 100) * (typeof window !== 'undefined' ? window.innerHeight : 800);
+  const local = scrollY - start + pin;
+  if (lengthPx <= 0) return 0;
+  return Math.min(1, Math.max(0, local / lengthPx));
+}
+
+export function stageAtProgress(progress, stages = []) {
+  if (!stages.length) return null;
+  let current = stages[0];
+  for (const s of stages) {
+    if (progress >= s.at) current = s;
+  }
+  return current;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Scene kinds — reusable narrative units.
+ * Source inventory (Work / Create HTML) → scene mapping lives in SCENE_ORIGIN.
+ */
+
+export const SCENE_KINDS = Object.freeze({
+  'hero.editorial': {
+    id: 'hero.editorial',
+    label: 'Editorial Hero',
+    description: 'Quiet statement + optional visual. Light/canvas tone.',
+    slots: ['copy', 'actions', 'visual'],
+    defaultScroll: 'viewport',
+  },
+  'hero.scroll-product': {
+    id: 'hero.scroll-product',
+    label: 'Scroll Product Hero',
+    description: 'Cinematic intro with scrub-linked product/visual.',
+    slots: ['copy', 'actions', 'visual', 'demo'],
+    defaultScroll: 'sticky-story',
+  },
+  'bridge.theme': {
+    id: 'bridge.theme',
+    label: 'Theme Bridge',
+    description: 'Narrative transition between visual worlds (light→dark).',
+    slots: ['copy', 'media'],
+    defaultScroll: 'bridge',
+  },
+  'gallery.storyboard': {
+    id: 'gallery.storyboard',
+    label: 'Storyboard Gallery',
+    description: 'Brand/guideline lanes: mixed cards, iconography, action.',
+    slots: ['copy', 'cards', 'actions'],
+    defaultScroll: 'linger',
+  },
+  'gallery.rail': {
+    id: 'gallery.rail',
+    label: 'Gallery Rail',
+    description: 'Asset/product rail — static, drag, snap, loop, or scroll-linked.',
+    slots: ['cards', 'media'],
+    defaultScroll: 'natural',
+    behaviors: ['static', 'drag', 'snap', 'loop', 'scroll-linked'],
+  },
+  'product.demo': {
+    id: 'product.demo',
+    label: 'Product Demo',
+    description: 'Live product surface via DemoAdapter (never a fake mockup).',
+    slots: ['copy', 'demo', 'actions'],
+    defaultScroll: 'sticky-story',
+  },
+  'product.stack': {
+    id: 'product.stack',
+    label: 'Product Stack',
+    description: 'Staggered product/work catalog; item count drives layout.',
+    slots: ['copy', 'cards'],
+    defaultScroll: 'natural',
+  },
+  'capability.grid': {
+    id: 'capability.grid',
+    label: 'Capability Grid',
+    description: 'Services/features bento — adaptive to card count.',
+    slots: ['copy', 'cards', 'actions'],
+    defaultScroll: 'natural',
+  },
+  'work.gallery': {
+    id: 'work.gallery',
+    label: 'Work Gallery',
+    description: 'Selected work / case studies with optional filter rail.',
+    slots: ['copy', 'cards', 'actions'],
+    defaultScroll: 'natural',
+  },
+  'interactive.stage': {
+    id: 'interactive.stage',
+    label: 'Interactive Stage',
+    description: '3D / game / CAD / model stage.',
+    slots: ['copy', 'demo', 'visual', 'actions'],
+    defaultScroll: 'viewport',
+  },
+});
+
+/** Provenance: harvested Work/Create HTML → scene (do not ship as page HTML). */
+export const SCENE_ORIGIN = Object.freeze({
+  'sticky-glass-header': { becomes: 'shell.adaptive-header', sources: ['create', 'work-dark', 'work-light'] },
+  'mobile-menu': { becomes: 'shell.mobile-navigation', sources: ['create', 'work-dark'] },
+  'work-filter-rail': { becomes: 'shell.work-filter-rail', sources: ['work-dark'] },
+  'hero-dark-globe': { becomes: 'hero.scroll-product', tone: 'inverse', sources: ['work-dark'] },
+  'hero-light-globe': { becomes: 'hero.editorial', tone: 'canvas', visual: 'orbital', sources: ['work-light'] },
+  'galaxy-atmosphere': { becomes: 'visual.atmosphere', sources: ['work-dark', 'work-light', 'create'] },
+  'three-globe': { becomes: 'visual.orbital-field', sources: ['work-dark', 'work-light'] },
+  'vibe-shift-transition': { becomes: 'bridge.theme', sources: ['work-light'] },
+  'brand-storyboard-marquee': { becomes: 'gallery.storyboard', sources: ['create'] },
+  'icon-marquee': { becomes: 'gallery.rail', behavior: 'loop', sources: ['work-dark'] },
+  'service-bento': { becomes: 'capability.grid', sources: ['create'] },
+  'meauxide-block': { becomes: 'product.demo', adapter: 'agentsam-mini-composer', sources: ['work-dark', 'work-light'] },
+  'meauxsql-card': { becomes: 'product.demo', adapter: 'database-editor', sources: ['work-dark', 'work-light'] },
+  'staggered-tools': { becomes: 'product.stack', sources: ['work-dark', 'work-light'] },
+  'chess-stage': { becomes: 'interactive.stage', adapter: 'generic-iframe', sources: ['work-dark'] },
+  'site-footer': { becomes: 'shell.site-footer', sources: ['create', 'work-dark', 'work-light'] },
+});
+
+export function getSceneKind(id) {
+  return SCENE_KINDS[id] || null;
+}
+
+export function listSceneKinds() {
+  return Object.values(SCENE_KINDS);
+}
+
+/**
+ * Normalize a section against its scene contract.
+ * Drops empty card groups; fills scroll defaults.
+ */
+export function normalizeSection(section, { scrollPresets } = {}) {
+  if (!section?.scene) return section;
+  const kind = SCENE_KINDS[section.scene];
+  const next = { ...section };
+  if (!next.scroll && kind?.defaultScroll) {
+    const presets = scrollPresets || {};
+    next.scroll = presets[kind.defaultScroll] || { mode: kind.defaultScroll };
+  }
+  if (Array.isArray(next.groups)) {
+    next.groups = next.groups
+      .map((g) => ({
+        ...g,
+        blocks: (g.blocks || []).filter((b) => {
+          if (b.kind === 'cards' && (!b.items || !b.items.length)) return false;
+          return true;
+        }),
+      }))
+      .filter((g) => (g.blocks || []).length > 0);
+  }
+  return next;
+}
+
+export function createSection(partial) {
+  return normalizeSection({
+    id: partial.id || `section_${Math.random().toString(36).slice(2, 8)}`,
+    scene: partial.scene,
+    theme: partial.theme,
+    motion: partial.motion,
+    scroll: partial.scroll,
+    visual: partial.visual,
+    demo: partial.demo,
+    groups: partial.groups || [],
+    contentRef: partial.contentRef,
+  });
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Shell modules — site chrome shared across pages.
+ */
+
+export const SHELL_KINDS = Object.freeze({
+  'shell.adaptive-header': {
+    id: 'shell.adaptive-header',
+    label: 'Adaptive Header',
+    description: 'Glass sticky header; tone follows scene headerTone / scroll.',
+    props: ['logo', 'logoInverse', 'nav', 'avatar', 'height'],
+  },
+  'shell.mobile-navigation': {
+    id: 'shell.mobile-navigation',
+    label: 'Mobile Navigation',
+    description: 'Full-screen overlay nav driven by shell.nav.',
+  },
+  'shell.work-filter-rail': {
+    id: 'shell.work-filter-rail',
+    label: 'Work Filter Rail',
+    description: 'Optional sticky category filter for work/product galleries.',
+    props: ['filters', 'active'],
+  },
+  'shell.site-footer': {
+    id: 'shell.site-footer',
+    label: 'Site Footer',
+    description: 'Data-driven columns; no hardcoded product links.',
+    props: ['brand', 'columns', 'legal', 'version'],
+  },
+});
+
+export function createShellContent(partial = {}) {
+  return {
+    header: partial.header ?? 'adaptive',
+    footer: partial.footer ?? 'default',
+    filterRail: Boolean(partial.filterRail),
+    nav: Array.isArray(partial.nav) ? partial.nav : [],
+    logo: partial.logo || null,
+    logoInverse: partial.logoInverse || null,
+    avatar: partial.avatar || null,
+    footerColumns: partial.footerColumns || [],
+    tagline: partial.tagline || null,
+  };
+}
+
+export function listShellKinds() {
+  return Object.values(SHELL_KINDS);
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Theme tokens — semantic only. Scenes consume CSS vars / token keys, never raw hex in components.
+ */
+
+export const FOUNDATION_THEME = Object.freeze({
+  id: 'foundation',
+  label: 'Foundation',
+  description: 'Neutral multi-brand base. Customer brands extend this.',
+  tokens: {
+    color: {
+      'color.surface.canvas': { css: '--scene-surface', value: '#FFFFFF' },
+      'color.surface.raised': { css: '--scene-surface-raised', value: '#F8FAFC' },
+      'color.surface.inverse': { css: '--scene-surface-inverse', value: '#0F172A' },
+      'color.text.primary': { css: '--scene-text', value: '#1E293B' },
+      'color.text.muted': { css: '--scene-text-muted', value: '#64748B' },
+      'color.text.inverse': { css: '--scene-text-inverse', value: '#F8FAFC' },
+      'color.border.subtle': { css: '--scene-border', value: '#E2E8F0' },
+      'color.brand.primary': { css: '--scene-accent', value: '#2563EB' },
+      'color.brand.secondary': { css: '--scene-accent-secondary', value: '#1FAAAD' },
+      'color.focus.ring': { css: '--scene-focus', value: '#2563EB' },
+    },
+    type: {
+      'type.display.xl': { size: 'clamp(3.5rem, 8vw, 7rem)', lineHeight: 1.05, tracking: '-0.04em' },
+      'type.display.lg': { size: 'clamp(2.75rem, 5vw, 5rem)', lineHeight: 1.08, tracking: '-0.03em' },
+      'type.section': { size: 'clamp(2rem, 3.5vw, 3.5rem)', lineHeight: 1.15, tracking: '-0.02em' },
+      'type.body.lg': { size: 'clamp(1.05rem, 1.3vw, 1.25rem)', lineHeight: 1.6 },
+      'type.mono': { family: 'ui-monospace, monospace' },
+    },
+    space: {
+      'space.section.y.desktop': '144px',
+      'space.section.y.mobile': '80px',
+      'space.scene.gap': '80px',
+      'space.content.max': '1280px',
+    },
+    motion: {
+      'motion.intensity.default': 0.35,
+      'motion.reveal.duration': '800ms',
+      'motion.reduce': 'crossfade',
+    },
+  },
+});
+
+export const INNERANIMAL_THEME = Object.freeze({
+  id: 'inneranimal',
+  extends: 'foundation',
+  label: 'InnerAnimal Media',
+  description: 'Quiet institutional parent — navy / blue / teal discipline.',
+  tokens: {
+    color: {
+      'color.brand.primary': { css: '--scene-accent', value: '#2563EB' },
+      'color.brand.secondary': { css: '--scene-accent-secondary', value: '#1FAAAD' },
+      'color.surface.inverse': { css: '--scene-surface-inverse', value: '#0F172A' },
+      'color.text.primary': { css: '--scene-text', value: '#1E293B' },
+    },
+  },
+});
+
+export const AGENTSAM_THEME = Object.freeze({
+  id: 'agentsam',
+  extends: 'inneranimal',
+  label: 'AgentSam',
+  description: 'Technical product skin on InnerAnimal spacing/type discipline.',
+  tokens: {
+    color: {
+      'color.brand.primary': { css: '--scene-accent', value: '#4F8CFF' },
+      'color.brand.secondary': { css: '--scene-accent-secondary', value: '#8FD7FF' },
+      'color.surface.inverse': { css: '--scene-surface-inverse', value: '#0A0F18' },
+      'color.surface.raised': { css: '--scene-surface-raised', value: '#172333' },
+    },
+  },
+});
+
+export const AUTODIDACT_THEME = Object.freeze({
+  id: 'autodidact',
+  extends: 'inneranimal',
+  label: 'InnerAutodidact',
+  description: 'Learning surface — same grid/motion, softer accent.',
+  tokens: {
+    color: {
+      'color.brand.primary': { css: '--scene-accent', value: '#1FAAAD' },
+      'color.brand.secondary': { css: '--scene-accent-secondary', value: '#2563EB' },
+    },
+  },
+});
+
+const REGISTRY = Object.freeze({
+  foundation: FOUNDATION_THEME,
+  inneranimal: INNERANIMAL_THEME,
+  agentsam: AGENTSAM_THEME,
+  autodidact: AUTODIDACT_THEME,
+});
+
+export function getTheme(id) {
+  return REGISTRY[id] || null;
+}
+
+export function listThemes() {
+  return Object.values(REGISTRY);
+}
+
+/** Deep-merge token maps along extends chain. */
+export function resolveTheme(id) {
+  const theme = REGISTRY[id];
+  if (!theme) return resolveTheme('foundation');
+  if (!theme.extends) {
+    return structuredClone(theme);
+  }
+  const parent = resolveTheme(theme.extends);
+  return {
+    ...parent,
+    ...theme,
+    tokens: {
+      color: { ...parent.tokens?.color, ...theme.tokens?.color },
+      type: { ...parent.tokens?.type, ...theme.tokens?.type },
+      space: { ...parent.tokens?.space, ...theme.tokens?.space },
+      motion: { ...parent.tokens?.motion, ...theme.tokens?.motion },
+    },
+  };
+}
+
+/** Emit CSS custom properties for a resolved theme. */
+export function themeToCssVars(themeOrId) {
+  const theme = typeof themeOrId === 'string' ? resolveTheme(themeOrId) : themeOrId;
+  const vars = {};
+  for (const token of Object.values(theme.tokens?.color || {})) {
+    if (token.css && token.value) vars[token.css] = token.value;
+  }
+  return vars;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Visual primitives — not scenes. Plugged into hero / stage slots.
+ */
+
+export const VISUAL_KINDS = Object.freeze({
+  'visual.orbital-field': {
+    id: 'visual.orbital-field',
+    label: 'Orbital Field',
+    description: 'Three.js (or WebGL) globe / lattice; scroll can scrub rotation.',
+    runtime: 'webgl',
+    props: ['tone', 'intensity', 'scrub'],
+  },
+  'visual.atmosphere': {
+    id: 'visual.atmosphere',
+    label: 'Atmosphere Layer',
+    description: 'Galaxy / stars / soft gradient bleed — optional underlay.',
+    runtime: 'css',
+    props: ['density', 'tone'],
+  },
+  'visual.grid-field': {
+    id: 'visual.grid-field',
+    label: 'Grid Field',
+    description: 'Quiet structural grid for editorial surfaces.',
+    runtime: 'css',
+  },
+  'visual.product-window': {
+    id: 'visual.product-window',
+    label: 'Product Window Frame',
+    description: 'Chrome frame around a DemoHost — not a fake IDE.',
+    runtime: 'dom',
+    props: ['title', 'chrome'],
+  },
+});
+
+export function getVisual(id) {
+  return VISUAL_KINDS[id] || null;
+}
+
+export function listVisuals() {
+  return Object.values(VISUAL_KINDS);
+}