aeon-ui-engine 1.3.1 → 1.4.0

package/packages/schemas/scripts/emit.ts

@@ -2,10 +2,23 @@ import { mkdirSync, writeFileSync, cpSync, existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
+  accordionMachine,
+  appNavMachine,
+  appShellMachine,
   asyncMachine,
   buttonLifecycleMachine,
+  contentRegionMachine,
   dialogMachine,
   fieldMachine,
+  panelMachine,
+  popoverMachine,
+  sliderMachine,
+  rangeSliderMachine,
+  fileUploadMachine,
+  stickyBarMachine,
+  tabsMachine,
+  toastMachine,
+  toggleMachine,
 } from '@aeon-ui/primitives'
 import { catalog, componentSchemas } from '../src/components.js'
 import { AEON_SYSTEM_PROMPT, CURSOR_RULES_SNIPPET, STATECHART_PROMPTS } from '../src/prompts.js'
@@ -30,11 +43,25 @@ for (const [id, schema] of Object.entries(componentSchemas)) {
   writeFileSync(join(registryDir, 'components', `${id}.json`), `${JSON.stringify(schema, null, 2)}\n`)
 }
 
+/** Every primitives machine agents may fetch for validEvents / state trees. */
 const machines = {
   async: asyncMachine,
   buttonLifecycle: buttonLifecycleMachine,
   dialog: dialogMachine,
   field: fieldMachine,
+  popover: popoverMachine,
+  toggle: toggleMachine,
+  tabs: tabsMachine,
+  accordion: accordionMachine,
+  toast: toastMachine,
+  slider: sliderMachine,
+  rangeSlider: rangeSliderMachine,
+  fileUpload: fileUploadMachine,
+  panel: panelMachine,
+  appShell: appShellMachine,
+  appNav: appNavMachine,
+  stickyBar: stickyBarMachine,
+  contentRegion: contentRegionMachine,
 } as const
 
 for (const [id, machine] of Object.entries(machines)) {

package/packages/schemas/src/components.ts

@@ -21,10 +21,15 @@ export const componentSchemas = {
       variant: { type: 'string', enum: ['solid', 'outline', 'ghost', 'link'] },
       size: { type: 'string', enum: ['sm', 'md', 'lg'] },
       disabled: { type: 'boolean' },
+      asChild: {
+        type: 'boolean',
+        description: 'Merge button attrs onto a single child element (Link, a).',
+      },
     },
     slots: { Root: 'button.root', Group: 'button.group', Label: 'button.label', Icon: 'button.icon' },
     examples: [
       '<Button.Root status="pending" aria-busy>Saving…</Button.Root>',
+      '<Button.Root asChild variant="solid"><a href="/upload">Upload</a></Button.Root>',
       "const [snap, send] = useAeonMachine(buttonLifecycleMachine)\n<Button.Root status={snap.value as ButtonStatus} onClick={() => send({ type: 'PRESS' })} />",
     ],
   }),
@@ -222,24 +227,28 @@ export const componentSchemas = {
   combobox: componentSchema({
     id: 'https://aeon-ui.com/schemas/combobox.json',
     title: 'Combobox',
-    description: 'Typeahead — React useState for open/query/highlight today. Do not add a duplicate floating machine without COMPONENT_CHECKLIST.',
+    description:
+      'Open/closed via popoverMachine (same family as Select/Menu/Popover). Query, highlight, and item registry stay React-local for typeahead.',
     scope: 'combobox',
     parts: ['root', 'input', 'icon', 'content', 'item', 'empty'],
     states: ['open', 'closed'],
-    machine: null,
-    runtime: 'useState',
+    machine: 'popoverMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE', 'ESCAPE', 'POINTER_DOWN_OUTSIDE'],
     slots: { Root: 'combobox.root', Input: 'combobox.input', Content: 'combobox.content', Item: 'combobox.item' },
   }),
 
   tooltip: componentSchema({
     id: 'https://aeon-ui.com/schemas/tooltip.json',
     title: 'Tooltip',
-    description: 'Open via React useState. Touch tap toggles.',
+    description:
+      'Open/closed via popoverMachine (same family as Popover/Select/Combobox). openDelay / closeDelay / touchDuration stay React-local.',
     scope: 'tooltip',
     parts: ['root', 'trigger', 'positioner', 'content', 'arrow'],
     states: ['open', 'closed'],
-    machine: null,
-    runtime: 'useState',
+    machine: 'popoverMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE', 'SET_OPEN', 'ESCAPE', 'POINTER_DOWN_OUTSIDE'],
     slots: { Root: 'tooltip.root', Trigger: 'tooltip.trigger', Content: 'tooltip.content' },
   }),
 
@@ -289,6 +298,490 @@ export const componentSchemas = {
     },
     slots: { Root: 'progress.root', Track: 'progress.track', Range: 'progress.range', Label: 'progress.label' },
   }),
+
+  radioGroup: componentSchema({
+    id: 'https://aeon-ui.com/schemas/radioGroup.json',
+    title: 'RadioGroup',
+    description: 'Single selection via tabsMachine (same chart family as Tabs/Nav).',
+    scope: 'radioGroup',
+    parts: ['root', 'item', 'itemControl', 'itemIndicator', 'itemLabel'],
+    states: ['selected'],
+    machine: 'tabsMachine',
+    runtime: 'useAeonMachine',
+    events: ['SELECT'],
+    slots: {
+      Root: 'radioGroup.root',
+      Item: 'radioGroup.item',
+      ItemControl: 'radioGroup.itemControl',
+      ItemLabel: 'radioGroup.itemLabel',
+    },
+  }),
+
+  slider: componentSchema({
+    id: 'https://aeon-ui.com/schemas/slider.json',
+    title: 'Slider',
+    description: 'Range control via sliderMachine — idle | dragging plus numeric value in context.',
+    scope: 'slider',
+    parts: ['root', 'track', 'range', 'thumb', 'valueText'],
+    states: ['idle', 'dragging'],
+    machine: 'sliderMachine',
+    runtime: 'useAeonMachine',
+    events: ['SET_VALUE', 'STEP', 'POINTER_DOWN', 'POINTER_UP', 'HOME', 'END'],
+    slots: {
+      Root: 'slider.root',
+      Track: 'slider.track',
+      Range: 'slider.range',
+      Thumb: 'slider.thumb',
+      ValueText: 'slider.valueText',
+    },
+  }),
+
+  rangeSlider: componentSchema({
+    id: 'https://aeon-ui.com/schemas/rangeSlider.json',
+    title: 'RangeSlider',
+    description:
+      'Two-thumb range via rangeSliderMachine — idle | dragging with values pair and minStepsBetween gap.',
+    scope: 'rangeSlider',
+    parts: ['root', 'track', 'range', 'thumb', 'valueText'],
+    states: ['idle', 'dragging'],
+    machine: 'rangeSliderMachine',
+    runtime: 'useAeonMachine',
+    events: [
+      'SET_VALUES',
+      'SET_BOUNDS',
+      'SET_DISABLED',
+      'POINTER_DOWN',
+      'POINTER_MOVE',
+      'POINTER_UP',
+      'STEP',
+      'HOME',
+      'END',
+    ],
+    slots: {
+      Root: 'rangeSlider.root',
+      Track: 'rangeSlider.track',
+      Range: 'rangeSlider.range',
+      Thumb: 'rangeSlider.thumb',
+      ValueText: 'rangeSlider.valueText',
+    },
+    examples: [
+      '<RangeSlider.Root defaultValue={[20, 80]} minStepsBetween={1}>\n  <RangeSlider.Track /><RangeSlider.Range />\n  <RangeSlider.Thumb index={0} /><RangeSlider.Thumb index={1} />\n</RangeSlider.Root>',
+    ],
+  }),
+
+  fileUpload: componentSchema({
+    id: 'https://aeon-ui.com/schemas/fileUpload.json',
+    title: 'FileUpload',
+    description:
+      'Drag-drop surface via fileUploadMachine — idle | dragging | rejected. File bytes stay in React callbacks.',
+    scope: 'fileUpload',
+    parts: [
+      'root',
+      'dropzone',
+      'input',
+      'label',
+      'hint',
+      'preview',
+      'clearTrigger',
+      'rejectionMessage',
+    ],
+    states: ['idle', 'dragging', 'rejected'],
+    machine: 'fileUploadMachine',
+    runtime: 'useAeonMachine',
+    events: ['DRAG_OVER', 'DRAG_LEAVE', 'DROP_ACCEPT', 'DROP_REJECT', 'RESET'],
+    slots: {
+      Root: 'fileUpload.root',
+      Dropzone: 'fileUpload.dropzone',
+      Input: 'fileUpload.input',
+      Label: 'fileUpload.label',
+      Hint: 'fileUpload.hint',
+      Preview: 'fileUpload.preview',
+      ClearTrigger: 'fileUpload.clearTrigger',
+      RejectionMessage: 'fileUpload.rejectionMessage',
+    },
+  }),
+
+  pinInput: componentSchema({
+    id: 'https://aeon-ui.com/schemas/pinInput.json',
+    title: 'PinInput',
+    description: 'OTP / PIN cells — React state for digit buffer; projects idle | complete on root.',
+    scope: 'pinInput',
+    parts: ['root', 'input'],
+    states: ['idle', 'complete'],
+    machine: null,
+    runtime: 'useState',
+    slots: { Root: 'pinInput.root', Input: 'pinInput.input' },
+  }),
+
+  avatar: componentSchema({
+    id: 'https://aeon-ui.com/schemas/avatar.json',
+    title: 'Avatar',
+    description: 'Image load lifecycle in React; badge presence is a prop projection.',
+    scope: 'avatar',
+    parts: ['root', 'image', 'fallback', 'badge'],
+    states: ['idle', 'loading', 'loaded', 'error'],
+    machine: null,
+    runtime: 'useState',
+    slots: {
+      Root: 'avatar.root',
+      Image: 'avatar.image',
+      Fallback: 'avatar.fallback',
+      Badge: 'avatar.badge',
+    },
+  }),
+
+  content: componentSchema({
+    id: 'https://aeon-ui.com/schemas/content.json',
+    title: 'Content',
+    description:
+      'Status-slotted body via contentRegionMachine (or Root state prop projection). Pair with Async for fetch.',
+    scope: 'content',
+    parts: ['root', 'toolbar', 'body', 'pending', 'empty', 'error', 'success', 'sentinel'],
+    states: ['idle', 'pending', 'empty', 'error', 'ready', 'loadingMore', 'success'],
+    machine: 'contentRegionMachine',
+    runtime: 'useAeonMachine',
+    events: ['LOAD', 'RESOLVE', 'REJECT', 'RETRY', 'LOAD_MORE', 'MORE_DONE', 'SUCCEED', 'RESET'],
+    slots: {
+      Root: 'content.root',
+      Pending: 'content.pending',
+      Empty: 'content.empty',
+      Error: 'content.error',
+      Success: 'content.success',
+    },
+  }),
+
+  panel: componentSchema({
+    id: 'https://aeon-ui.com/schemas/panel.json',
+    title: 'Panel',
+    description: 'Collapsible layout region via panelMachine — expanded | collapsed.',
+    scope: 'panel',
+    parts: ['group', 'root', 'trigger', 'label', 'content'],
+    states: ['expanded', 'collapsed'],
+    machine: 'panelMachine',
+    runtime: 'useAeonMachine',
+    events: ['EXPAND', 'COLLAPSE', 'TOGGLE', 'SET_EXPANDED'],
+    slots: {
+      Group: 'panel.group',
+      Root: 'panel.root',
+      Trigger: 'panel.trigger',
+      Label: 'panel.label',
+      Content: 'panel.content',
+    },
+  }),
+
+  appShell: componentSchema({
+    id: 'https://aeon-ui.com/schemas/appShell.json',
+    title: 'AppShell',
+    description: 'Application chrome frame via appShellMachine — idle | overlayOpen (+ dockVisible).',
+    scope: 'appShell',
+    parts: ['root', 'header', 'subheader', 'content', 'aside', 'footer', 'dock', 'scrim'],
+    states: ['idle', 'overlayOpen'],
+    machine: 'appShellMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN_OVERLAY', 'CLOSE_OVERLAY', 'SHOW_DOCK', 'HIDE_DOCK', 'SET_DOCK'],
+    slots: {
+      Root: 'appShell.root',
+      Header: 'appShell.header',
+      Content: 'appShell.content',
+      Dock: 'appShell.dock',
+      Scrim: 'appShell.scrim',
+    },
+  }),
+
+  stickyBar: componentSchema({
+    id: 'https://aeon-ui.com/schemas/stickyBar.json',
+    title: 'StickyBar',
+    description:
+      'Sticky/fixed chrome band via stickyBarMachine. DOM scope is bar (reuses bar anatomy zones).',
+    scope: 'bar',
+    parts: ['root', 'leading', 'center', 'trailing', 'seam'],
+    states: ['floating', 'docked', 'collapsed', 'hidden'],
+    machine: 'stickyBarMachine',
+    runtime: 'useAeonMachine',
+    events: ['DOCK', 'FLOAT', 'COLLAPSE', 'EXPAND', 'HIDE', 'SHOW', 'SET_OFFSET'],
+    slots: {
+      Root: 'bar.root',
+      Leading: 'bar.leading',
+      Center: 'bar.center',
+      Trailing: 'bar.trailing',
+      Seam: 'bar.seam',
+    },
+  }),
+
+  bar: componentSchema({
+    id: 'https://aeon-ui.com/schemas/bar.json',
+    title: 'Bar',
+    description: 'Three-zone toolbar layout (leading / center / trailing / seam). Sticky lifecycle uses StickyBar + stickyBarMachine.',
+    scope: 'bar',
+    parts: ['root', 'leading', 'center', 'trailing', 'seam'],
+    states: ['idle'],
+    machine: null,
+    runtime: 'layout',
+    slots: {
+      Root: 'bar.root',
+      Leading: 'bar.leading',
+      Center: 'bar.center',
+      Trailing: 'bar.trailing',
+    },
+  }),
+
+  nav: componentSchema({
+    id: 'https://aeon-ui.com/schemas/nav.json',
+    title: 'Nav',
+    description: 'Navigational collection via tabsMachine; items project inactive | active | disabled.',
+    scope: 'nav',
+    parts: ['root', 'item', 'indicator', 'label', 'icon', 'badge'],
+    states: ['inactive', 'active', 'disabled'],
+    machine: 'tabsMachine',
+    runtime: 'useAeonMachine',
+    events: ['SELECT'],
+    slots: { Root: 'nav.root', Item: 'nav.item', Label: 'nav.label', Icon: 'nav.icon' },
+  }),
+
+  appNav: componentSchema({
+    id: 'https://aeon-ui.com/schemas/appNav.json',
+    title: 'AppNav',
+    description: 'Section + detail stack via appNavMachine — list→detail, settings drill-in.',
+    scope: 'appNav',
+    parts: ['root', 'rail', 'section', 'stage', 'breadcrumb', 'crumb', 'back'],
+    states: ['section'],
+    machine: 'appNavMachine',
+    runtime: 'useAeonMachine',
+    events: ['SET_SECTION', 'PUSH', 'REPLACE', 'POP', 'POP_TO', 'CLEAR', 'RESET'],
+    slots: {
+      Root: 'appNav.root',
+      Rail: 'appNav.rail',
+      Stage: 'appNav.stage',
+      Back: 'appNav.back',
+    },
+  }),
+
+  prompt: componentSchema({
+    id: 'https://aeon-ui.com/schemas/prompt.json',
+    title: 'Prompt',
+    description:
+      'Confirm / permission dialog composed on Dialog. Open/closed via dialogMachine; face via status prop.',
+    scope: 'prompt',
+    parts: ['root', 'eyebrow', 'meta', 'amount', 'actions', 'primary', 'secondary'],
+    states: ['pending', 'confirming', 'dismissed', 'confirmed'],
+    machine: 'dialogMachine',
+    runtime: 'status prop',
+    events: ['OPEN', 'CLOSE', 'TOGGLE'],
+    props: {
+      status: {
+        type: 'string',
+        enum: ['pending', 'confirming', 'dismissed', 'confirmed'],
+        default: 'pending',
+      },
+    },
+    slots: {
+      Root: 'prompt.root',
+      Primary: 'prompt.primary',
+      Secondary: 'prompt.secondary',
+      Actions: 'prompt.actions',
+    },
+  }),
+
+  statusBanner: componentSchema({
+    id: 'https://aeon-ui.com/schemas/statusBanner.json',
+    title: 'StatusBanner',
+    description: 'Non-blocking top-of-app notice — tone + optional status props project to data-aeon-state.',
+    scope: 'statusBanner',
+    parts: ['root', 'copy', 'title', 'body', 'actions'],
+    states: ['info', 'success', 'warning', 'danger', 'neutral'],
+    machine: null,
+    runtime: 'props',
+    props: {
+      tone: { type: 'string', enum: ['info', 'success', 'warning', 'danger', 'neutral'] },
+      status: { type: 'string', description: 'Optional secondary token appended to data-aeon-state' },
+    },
+    slots: {
+      Root: 'statusBanner.root',
+      Title: 'statusBanner.title',
+      Body: 'statusBanner.body',
+      Actions: 'statusBanner.actions',
+    },
+  }),
+
+  separator: componentSchema({
+    id: 'https://aeon-ui.com/schemas/separator.json',
+    title: 'Separator',
+    description: 'Static divider — orientation prop only.',
+    scope: 'separator',
+    parts: ['root'],
+    states: ['horizontal', 'vertical'],
+    machine: null,
+    runtime: 'props',
+    slots: { Root: 'separator.root' },
+  }),
+
+  composer: componentSchema({
+    id: 'https://aeon-ui.com/schemas/composer.json',
+    title: 'Composer',
+    description: 'Compose chrome — root state prop idle | sending | disabled | error.',
+    scope: 'composer',
+    parts: ['root', 'input', 'actions', 'send'],
+    states: ['idle', 'sending', 'disabled', 'error'],
+    machine: null,
+    runtime: 'props',
+    slots: { Root: 'composer.root', Input: 'composer.input', Send: 'composer.send' },
+  }),
+
+  thread: componentSchema({
+    id: 'https://aeon-ui.com/schemas/thread.json',
+    title: 'Thread',
+    description: 'Message stream — item state prop mine | theirs | pending | failed.',
+    scope: 'thread',
+    parts: ['root', 'list', 'item', 'bubble', 'meta', 'day'],
+    states: ['mine', 'theirs', 'pending', 'failed'],
+    machine: null,
+    runtime: 'props',
+    slots: { Root: 'thread.root', Item: 'thread.item', Bubble: 'thread.bubble' },
+  }),
+
+  identity: componentSchema({
+    id: 'https://aeon-ui.com/schemas/identity.json',
+    title: 'Identity',
+    description: 'Avatar + title + subtitle strip — presentational layout, not a niche product scope.',
+    scope: 'identity',
+    parts: ['root', 'avatar', 'title', 'subtitle', 'meta', 'trailing'],
+    states: ['idle'],
+    machine: null,
+    runtime: 'layout',
+    props: {
+      size: { type: 'string', enum: ['sm', 'md', 'lg'] },
+    },
+    slots: {
+      Root: 'identity.root',
+      Avatar: 'identity.avatar',
+      Title: 'identity.title',
+      Subtitle: 'identity.subtitle',
+      Meta: 'identity.meta',
+      Trailing: 'identity.trailing',
+    },
+  }),
+
+  profileHeader: componentSchema({
+    id: 'https://aeon-ui.com/schemas/profileHeader.json',
+    title: 'ProfileHeader',
+    description: 'Dense account header — identity · metrics · actions. Universal people chrome.',
+    scope: 'profileHeader',
+    parts: ['root', 'media', 'identity', 'metrics', 'actions', 'body'],
+    states: ['idle'],
+    machine: null,
+    runtime: 'layout',
+    slots: {
+      Root: 'profileHeader.root',
+      Media: 'profileHeader.media',
+      Identity: 'profileHeader.identity',
+      Metrics: 'profileHeader.metrics',
+      Actions: 'profileHeader.actions',
+      Body: 'profileHeader.body',
+    },
+  }),
+
+  metricStrip: componentSchema({
+    id: 'https://aeon-ui.com/schemas/metricStrip.json',
+    title: 'MetricStrip',
+    description: 'Dense value|label chips — cluster or loose density. Generic stats only.',
+    scope: 'metricStrip',
+    parts: ['root', 'chip', 'value', 'label'],
+    states: ['idle'],
+    machine: null,
+    runtime: 'layout',
+    props: {
+      density: { type: 'string', enum: ['cluster', 'loose'] },
+    },
+    slots: {
+      Root: 'metricStrip.root',
+      Chip: 'metricStrip.chip',
+      Value: 'metricStrip.value',
+      Label: 'metricStrip.label',
+    },
+  }),
+
+  listRow: componentSchema({
+    id: 'https://aeon-ui.com/schemas/listRow.json',
+    title: 'ListRow',
+    description: 'Settings / menu row — leading · label · trailing. Layout only.',
+    scope: 'listRow',
+    parts: ['root', 'leading', 'label', 'description', 'trailing'],
+    states: ['idle'],
+    machine: null,
+    runtime: 'layout',
+    slots: {
+      Root: 'listRow.root',
+      Leading: 'listRow.leading',
+      Label: 'listRow.label',
+      Description: 'listRow.description',
+      Trailing: 'listRow.trailing',
+    },
+  }),
+
+  entry: componentSchema({
+    id: 'https://aeon-ui.com/schemas/entry.json',
+    title: 'Entry',
+    description:
+      'Universal multi-value card (feed stack or listing split). Root state idle | selected | muted — never invent niche scopes.',
+    scope: 'entry',
+    parts: [
+      'list',
+      'root',
+      'header',
+      'leading',
+      'heading',
+      'title',
+      'subtitle',
+      'meta',
+      'media',
+      'body',
+      'values',
+      'value',
+      'actions',
+      'footer',
+    ],
+    states: ['idle', 'selected', 'muted'],
+    machine: null,
+    runtime: 'props',
+    props: {
+      state: { type: 'string', enum: ['idle', 'selected', 'muted'], default: 'idle' },
+      density: { type: 'string', enum: ['compact', 'cozy'] },
+      layout: { type: 'string', enum: ['stack', 'split'] },
+    },
+    slots: {
+      List: 'entry.list',
+      Root: 'entry.root',
+      Header: 'entry.header',
+      Body: 'entry.body',
+      Actions: 'entry.actions',
+      Footer: 'entry.footer',
+    },
+  }),
+
+  conversation: componentSchema({
+    id: 'https://aeon-ui.com/schemas/conversation.json',
+    title: 'Conversation',
+    description:
+      'Inbox / DM list — item state prop idle | unread | selected. Universal messaging chrome.',
+    scope: 'conversation',
+    parts: ['root', 'item', 'leading', 'body', 'title', 'preview', 'meta', 'badge'],
+    states: ['idle', 'unread', 'selected'],
+    machine: null,
+    runtime: 'props',
+    props: {
+      state: { type: 'string', enum: ['idle', 'unread', 'selected'], default: 'idle' },
+    },
+    slots: {
+      Root: 'conversation.root',
+      Item: 'conversation.item',
+      Leading: 'conversation.leading',
+      Body: 'conversation.body',
+      Title: 'conversation.title',
+      Preview: 'conversation.preview',
+      Meta: 'conversation.meta',
+      Badge: 'conversation.badge',
+    },
+  }),
 } as const satisfies Record<string, JsonSchema>
 
 export type ComponentSchemaId = keyof typeof componentSchemas

package/packages/schemas/src/index.test.ts

@@ -1,6 +1,44 @@
 import { describe, expect, it } from 'vitest'
 import { catalog, componentSchemas } from './components.js'
+import { machineRegistryId } from './machine-id.js'
 import { AEON_SYSTEM_PROMPT } from './prompts.js'
+import { registryCatalog } from './registry.js'
+
+/** Machine-backed COMPONENTS / MACHINES rows that must have a schema entry. */
+const MACHINE_BACKED_SCHEMA_IDS = [
+  'async',
+  'field',
+  'button',
+  'switch',
+  'checkbox',
+  'dialog',
+  'tabs',
+  'accordion',
+  'menu',
+  'popover',
+  'select',
+  'combobox',
+  'toast',
+  'radioGroup',
+  'slider',
+  'stickyBar',
+  'appShell',
+  'content',
+  'nav',
+  'panel',
+  'appNav',
+  'prompt',
+  'tooltip',
+] as const
+
+const LAYOUT_SCHEMA_IDS = [
+  'identity',
+  'profileHeader',
+  'metricStrip',
+  'listRow',
+  'entry',
+  'conversation',
+] as const
 
 describe('@aeon-ui/schemas', () => {
   it('exposes a catalog of every component schema', () => {
@@ -22,4 +60,49 @@ describe('@aeon-ui/schemas', () => {
     expect(AEON_SYSTEM_PROMPT).toContain('Build the state machines first')
     expect(AEON_SYSTEM_PROMPT).toContain('data-aeon-state')
   })
+
+  it('derives registry catalog from componentSchemas (no hand list drift)', () => {
+    const schemaIds = Object.keys(componentSchemas).sort()
+    const registryIds = registryCatalog.components.map((c) => c.id).sort()
+    expect(registryIds).toEqual(schemaIds)
+    expect(catalog.components.sort()).toEqual(schemaIds)
+  })
+
+  it('covers machine-backed components in the schema catalog', () => {
+    for (const id of MACHINE_BACKED_SCHEMA_IDS) {
+      expect(componentSchemas).toHaveProperty(id)
+    }
+    expect(componentSchemas.combobox['x-aeon']).toMatchObject({
+      machine: 'popoverMachine',
+      runtime: 'useAeonMachine',
+    })
+    expect(componentSchemas.tooltip['x-aeon']).toMatchObject({
+      machine: 'popoverMachine',
+      runtime: 'useAeonMachine',
+    })
+  })
+
+  it('covers Instant-critical layout schemas', () => {
+    for (const id of LAYOUT_SCHEMA_IDS) {
+      expect(componentSchemas).toHaveProperty(id)
+    }
+    expect(componentSchemas.entry['x-aeon']).toMatchObject({
+      scope: 'entry',
+      runtime: 'props',
+    })
+  })
+
+  it('maps machine export names to registry machine file ids', () => {
+    expect(machineRegistryId('popoverMachine')).toBe('popover')
+    expect(machineRegistryId('createAsyncMachine')).toBe('async')
+    expect(machineRegistryId('buttonLifecycleMachine')).toBe('buttonLifecycle')
+    expect(machineRegistryId(null)).toBeUndefined()
+  })
+
+  it('points registry machineUrl at the mapped machine id when present', () => {
+    const select = registryCatalog.components.find((c) => c.id === 'select')
+    expect(select?.machineUrl).toBe('https://aeon-ui.com/registry/machines/popover.json')
+    const scroll = registryCatalog.components.find((c) => c.id === 'scroll')
+    expect(scroll?.machineUrl).toBeUndefined()
+  })
 })

package/packages/schemas/src/index.ts

@@ -23,3 +23,4 @@ export {
   type AgentEventBridge,
 } from './agent-bridge.js'
 export { registryCatalog, REGISTRY_BASE, type RegistryEntry } from './registry.js'
+export { machineRegistryId } from './machine-id.js'