aeon-ui-engine 1.0.2 → 1.1.0

package/packages/schemas/src/components.ts

@@ -0,0 +1,307 @@
+import { componentSchema, type JsonSchema } from './schema-builder.js'
+
+/** Deterministic component contracts for LLM / Generative UI consumption. */
+export const componentSchemas = {
+  button: componentSchema({
+    id: 'https://aeon-ui.com/schemas/button.json',
+    title: 'Button',
+    description:
+      'Action control. status is a prop projection (not an in-tree machine). Never invent parallel useState for lifecycle.',
+    scope: 'button',
+    parts: ['root', 'group', 'label', 'icon'],
+    states: ['idle', 'pending', 'success', 'failure', 'disabled'],
+    machine: 'buttonLifecycleMachine',
+    runtime: 'status prop',
+    props: {
+      status: {
+        type: 'string',
+        enum: ['idle', 'pending', 'success', 'failure', 'disabled'],
+        default: 'idle',
+      },
+      variant: { type: 'string', enum: ['solid', 'outline', 'ghost', 'link'] },
+      size: { type: 'string', enum: ['sm', 'md', 'lg'] },
+      disabled: { type: 'boolean' },
+    },
+    slots: { Root: 'button.root', Group: 'button.group', Label: 'button.label', Icon: 'button.icon' },
+    examples: [
+      '<Button.Root status="pending" aria-busy>Saving…</Button.Root>',
+      "const [snap, send] = useAeonMachine(buttonLifecycleMachine)\n<Button.Root status={snap.value as ButtonStatus} onClick={() => send({ type: 'PRESS' })} />",
+    ],
+  }),
+
+  async: componentSchema({
+    id: 'https://aeon-ui.com/schemas/async.json',
+    title: 'Async',
+    description:
+      'Fetch region with full lifecycle totality: idle → loading → success|empty|failure. Always render every stable state in demos.',
+    scope: 'async',
+    parts: ['root', 'track', 'segment', 'readout', 'readoutRail', 'readoutBody', 'actions'],
+    states: ['idle', 'loading', 'success', 'empty', 'failure'],
+    machine: 'createAsyncMachine',
+    runtime: 'useAeonMachine',
+    events: ['FETCH', 'RESOLVE', 'REJECT', 'RESET', 'STALE', 'REFRESH'],
+    slots: {
+      Root: 'async.root',
+      Track: 'async.track',
+      Segment: 'async.segment',
+      Readout: 'async.readout',
+      Actions: 'async.actions',
+    },
+    examples: [
+      '<Async.Root>\n  {/* Content faces via asyncStatusToContentState — not Track */}\n  <Async.Actions />\n</Async.Root>',
+    ],
+  }),
+
+  field: componentSchema({
+    id: 'https://aeon-ui.com/schemas/field.json',
+    title: 'Field',
+    description:
+      'Parallel regions: interaction × validation × submission. Do not collapse into a single error boolean.',
+    scope: 'field',
+    parts: ['root', 'label', 'control', 'textarea', 'message', 'hint'],
+    states: [
+      'pristine',
+      'dirty',
+      'valid',
+      'invalid',
+      'idle',
+      'pending',
+      'interaction.pristine',
+      'interaction.dirty',
+      'validation.valid',
+      'validation.invalid',
+      'submission.idle',
+      'submission.pending',
+    ],
+    machine: 'fieldMachine',
+    runtime: 'useAeonMachine',
+    events: ['INPUT', 'BLUR', 'VALIDATE', 'SUBMIT', 'SUBMIT_DONE', 'SUBMIT_FAIL', 'RESET'],
+    slots: {
+      Root: 'field.root',
+      Label: 'field.label',
+      Control: 'field.control',
+      Message: 'field.message',
+      Hint: 'field.hint',
+    },
+  }),
+
+  dialog: componentSchema({
+    id: 'https://aeon-ui.com/schemas/dialog.json',
+    title: 'Dialog',
+    description: 'Modal open/closed via dialogMachine. Dismissal is a transition, not ad hoc flags.',
+    scope: 'dialog',
+    parts: [
+      'root',
+      'trigger',
+      'portal',
+      'backdrop',
+      'positioner',
+      'content',
+      'title',
+      'description',
+      'closeTrigger',
+    ],
+    states: ['open', 'closed'],
+    machine: 'dialogMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE'],
+    slots: {
+      Root: 'dialog.root',
+      Trigger: 'dialog.trigger',
+      Content: 'dialog.content',
+      Title: 'dialog.title',
+      Description: 'dialog.description',
+      CloseTrigger: 'dialog.closeTrigger',
+    },
+  }),
+
+  switch: componentSchema({
+    id: 'https://aeon-ui.com/schemas/switch.json',
+    title: 'Switch',
+    description: 'Binary toggle via toggleMachine.',
+    scope: 'switch',
+    parts: ['root', 'control', 'thumb', 'label', 'hiddenInput'],
+    states: ['checked', 'unchecked'],
+    machine: 'toggleMachine',
+    runtime: 'useAeonMachine',
+    events: ['TOGGLE', 'CHECK', 'UNCHECK'],
+    slots: { Root: 'switch.root', Control: 'switch.control', Thumb: 'switch.thumb', Label: 'switch.label' },
+  }),
+
+  checkbox: componentSchema({
+    id: 'https://aeon-ui.com/schemas/checkbox.json',
+    title: 'Checkbox',
+    description: 'Binary toggle via toggleMachine (same chart family as Switch).',
+    scope: 'checkbox',
+    parts: ['root', 'control', 'indicator', 'label', 'hiddenInput'],
+    states: ['checked', 'unchecked'],
+    machine: 'toggleMachine',
+    runtime: 'useAeonMachine',
+    events: ['TOGGLE', 'CHECK', 'UNCHECK'],
+    slots: {
+      Root: 'checkbox.root',
+      Control: 'checkbox.control',
+      Indicator: 'checkbox.indicator',
+      Label: 'checkbox.label',
+    },
+  }),
+
+  tabs: componentSchema({
+    id: 'https://aeon-ui.com/schemas/tabs.json',
+    title: 'Tabs',
+    description: 'Selected tab value from tabsMachine.',
+    scope: 'tabs',
+    parts: ['root', 'list', 'trigger', 'content', 'indicator'],
+    states: ['selected'],
+    machine: 'tabsMachine',
+    runtime: 'useAeonMachine',
+    events: ['SELECT'],
+    props: {
+      value: { type: 'string', description: 'Selected tab id — becomes data-aeon-state' },
+    },
+    slots: { Root: 'tabs.root', List: 'tabs.list', Trigger: 'tabs.trigger', Content: 'tabs.content' },
+  }),
+
+  accordion: componentSchema({
+    id: 'https://aeon-ui.com/schemas/accordion.json',
+    title: 'Accordion',
+    description: 'Per-item open state via accordionMachine.',
+    scope: 'accordion',
+    parts: ['root', 'item', 'itemTrigger', 'itemContent', 'itemIndicator'],
+    states: ['open', 'closed'],
+    machine: 'accordionMachine',
+    runtime: 'useAeonMachine',
+    events: ['TOGGLE'],
+    slots: {
+      Root: 'accordion.root',
+      Item: 'accordion.item',
+      ItemTrigger: 'accordion.itemTrigger',
+      ItemContent: 'accordion.itemContent',
+    },
+  }),
+
+  popover: componentSchema({
+    id: 'https://aeon-ui.com/schemas/popover.json',
+    title: 'Popover',
+    description: 'Floating surface — shares popoverMachine. Do not fork a duplicate open/closed chart.',
+    scope: 'popover',
+    parts: ['root', 'trigger', 'positioner', 'content', 'arrow', 'closeTrigger'],
+    states: ['open', 'closed'],
+    machine: 'popoverMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE'],
+    slots: { Root: 'popover.root', Trigger: 'popover.trigger', Content: 'popover.content' },
+  }),
+
+  menu: componentSchema({
+    id: 'https://aeon-ui.com/schemas/menu.json',
+    title: 'Menu',
+    description: 'Shares popoverMachine with Popover/Select open state.',
+    scope: 'menu',
+    parts: ['root', 'trigger', 'positioner', 'content', 'item', 'separator'],
+    states: ['open', 'closed'],
+    machine: 'popoverMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE'],
+    slots: { Root: 'menu.root', Trigger: 'menu.trigger', Content: 'menu.content', Item: 'menu.item' },
+  }),
+
+  select: componentSchema({
+    id: 'https://aeon-ui.com/schemas/select.json',
+    title: 'Select',
+    description: 'Open/closed via popoverMachine; highlight may be React-local. Do not invent a new open machine.',
+    scope: 'select',
+    parts: ['root', 'trigger', 'value', 'icon', 'positioner', 'content', 'item'],
+    states: ['open', 'closed'],
+    machine: 'popoverMachine',
+    runtime: 'useAeonMachine',
+    events: ['OPEN', 'CLOSE', 'TOGGLE'],
+    slots: { Root: 'select.root', Trigger: 'select.trigger', Content: 'select.content', Item: 'select.item' },
+  }),
+
+  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.',
+    scope: 'combobox',
+    parts: ['root', 'input', 'icon', 'content', 'item', 'empty'],
+    states: ['open', 'closed'],
+    machine: null,
+    runtime: 'useState',
+    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.',
+    scope: 'tooltip',
+    parts: ['root', 'trigger', 'positioner', 'content', 'arrow'],
+    states: ['open', 'closed'],
+    machine: null,
+    runtime: 'useState',
+    slots: { Root: 'tooltip.root', Trigger: 'tooltip.trigger', Content: 'tooltip.content' },
+  }),
+
+  toast: componentSchema({
+    id: 'https://aeon-ui.com/schemas/toast.json',
+    title: 'Toast',
+    description: 'Per-item visibility via toastMachine.',
+    scope: 'toast',
+    parts: ['viewport', 'root', 'title', 'description', 'closeTrigger'],
+    states: ['visible', 'hidden'],
+    machine: 'toastMachine',
+    runtime: 'useAeonMachine',
+    events: ['SHOW', 'HIDE', 'DISMISS'],
+    slots: {
+      Provider: 'toast.provider',
+      Viewport: 'toast.viewport',
+      Root: 'toast.root',
+      Title: 'toast.title',
+      Description: 'toast.description',
+    },
+  }),
+
+  scroll: componentSchema({
+    id: 'https://aeon-ui.com/schemas/scroll.json',
+    title: 'Scroll',
+    description: 'Derived overflow/edge snapshot via getScrollSnapshot() — no XState machine.',
+    scope: 'scroll',
+    parts: ['root', 'viewport', 'content'],
+    states: ['idle', 'start', 'middle', 'end', 'overflow-x', 'overflow-y', 'overflow-both'],
+    machine: null,
+    runtime: 'getScrollSnapshot',
+    slots: { Root: 'scroll.root', Viewport: 'scroll.viewport', Content: 'scroll.content' },
+  }),
+
+  progress: componentSchema({
+    id: 'https://aeon-ui.com/schemas/progress.json',
+    title: 'Progress',
+    description: 'Prop-driven progress: value + indeterminate → idle | loading | complete.',
+    scope: 'progress',
+    parts: ['root', 'track', 'range', 'label'],
+    states: ['idle', 'loading', 'complete'],
+    machine: null,
+    runtime: 'props',
+    props: {
+      value: { type: 'number', minimum: 0, maximum: 100 },
+      indeterminate: { type: 'boolean' },
+    },
+    slots: { Root: 'progress.root', Track: 'progress.track', Range: 'progress.range', Label: 'progress.label' },
+  }),
+} as const satisfies Record<string, JsonSchema>
+
+export type ComponentSchemaId = keyof typeof componentSchemas
+
+export const catalog = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://aeon-ui.com/schemas/catalog.json',
+  title: 'Aeon UI Component Catalog',
+  description:
+    'Machine-legible index of Aeon UI components. Prefer these schemas over inventing props, states, or boolean UI flags.',
+  version: '0.1.0',
+  principle: 'UI = f(state)',
+  attributes: ['data-aeon-scope', 'data-aeon-part', 'data-aeon-state'],
+  components: Object.keys(componentSchemas),
+  schemas: componentSchemas,
+} as const

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { catalog, componentSchemas } from './components.js'
+import { AEON_SYSTEM_PROMPT } from './prompts.js'
+
+describe('@aeon-ui/schemas', () => {
+  it('exposes a catalog of every component schema', () => {
+    expect(catalog.components.length).toBeGreaterThan(10)
+    expect(catalog.components).toContain('button')
+    expect(componentSchemas.button['x-aeon']).toMatchObject({
+      scope: 'button',
+      runtime: 'status prop',
+    })
+  })
+
+  it('keeps button statuses exhaustive for agents', () => {
+    const states = (componentSchemas.button['x-aeon'] as { states: string[] }).states
+    expect(states).toEqual(['idle', 'pending', 'success', 'failure', 'disabled'])
+  })
+
+  it('ships a non-empty system prompt', () => {
+    expect(AEON_SYSTEM_PROMPT).toContain('UI = f(state)')
+    expect(AEON_SYSTEM_PROMPT).toContain('Build the state machines first')
+    expect(AEON_SYSTEM_PROMPT).toContain('data-aeon-state')
+  })
+})

package/packages/schemas/src/index.ts

@@ -0,0 +1,25 @@
+export { componentSchema, type JsonSchema } from './schema-builder.js'
+export { catalog, componentSchemas, type ComponentSchemaId } from './components.js'
+export {
+  AEON_SYSTEM_PROMPT,
+  CURSOR_RULES_SNIPPET,
+  GENERATIVE_UI_EXAMPLE,
+  STATECHART_PROMPTS,
+} from './prompts.js'
+export {
+  aeonToSchema,
+  aeonToPrompt,
+  aeonSnapshotSchema,
+  aeonInitialAgentContext,
+  type AeonMachineSchema,
+  type AeonSnapshotSchema,
+  type AeonStateTreeNode,
+} from './aeon-to-schema.js'
+export {
+  createAgentEventBridge,
+  type AgentStreamEvent,
+  type AgentEventMap,
+  type AgentBridgeOptions,
+  type AgentEventBridge,
+} from './agent-bridge.js'
+export { registryCatalog, REGISTRY_BASE, type RegistryEntry } from './registry.js'

package/packages/schemas/src/prompts.ts

@@ -0,0 +1,121 @@
+/**
+ * Statecharts packaged as system-prompt fragments for AI coding agents.
+ * Embed before code generation so agents cannot invent impossible UI states.
+ */
+
+export const AEON_SYSTEM_PROMPT = `# Aeon UI — agent system prompt
+
+You are building UI with **Aeon UI**, a React component library powered by finite statecharts.
+
+## Order of work (mandatory)
+1. **Build the state machines first** — name every lifecycle the UX needs (states + events). Prefer machines from \`@aeon-ui/primitives\` (or documented prop projections such as Button \`status\`).
+2. **Then project UI from those machines** — compound parts, copy, and layout exist only to reflect the chart. Never invent UI for states that are not in a machine.
+3. **UI = f(state)** — the DOM exposes \`data-aeon-scope\`, \`data-aeon-part\`, \`data-aeon-state\`. Style targets those attributes. Do not drive the same concern with parallel React \`useState\` flags.
+
+## Non-negotiable rules
+1. Do not duplicate open/checked/lifecycle in \`useState\` when a machine exists in \`@aeon-ui/primitives\`.
+2. **Button \`status\` is a prop** (\`idle|pending|success|failure|disabled\`). Optional: drive it from \`buttonLifecycleMachine\` via \`useAeonMachine\` in app code.
+3. **Select / Menu / Popover** share \`popoverMachine\` — never fork another open/closed chart.
+4. **Combobox** and **Tooltip** use React state today — do not add floating machines without the component checklist.
+5. **Scroll** uses \`getScrollSnapshot()\` — no XState machine.
+6. If a machine lists N stable states, the UI must represent all N (totality).
+7. Prefer \`@aeon-ui/react\` (headless) or \`@aeon-ui/ui\` (styled). Relative TS imports use \`.js\` extensions inside the Aeon monorepo only.
+8. Primitives stay **universal** — never invent niche components (dating, colour-blind test, pong). Compose from generic parts.
+
+## DOM contract
+Every interactive surface sets anatomy via \`partAttrs\` from \`@aeon-ui/core\`:
+- \`data-aeon-scope\` — family (\`button\`, \`async\`, \`field\`, …)
+- \`data-aeon-part\` — anatomy key (\`root\`, \`trigger\`, …)
+- \`data-aeon-state\` — allowed snapshot / prop state only
+
+## Before writing JSX
+1. Enumerate machines (or documented status props) for the flow — states and events.
+2. Read the component JSON Schema from \`@aeon-ui/schemas\` (or pasted catalog) and match parts to those charts.
+3. Compose with documented compound parts (\`Dialog.Root\`, \`Field.Control\`, …).
+4. Wire events to machine events or documented props — never invent \`isLoading && !isError && hasData\` spaghetti when a named state exists.
+`
+
+export const STATECHART_PROMPTS = {
+  async: `## Async region statechart
+States: idle → loading → (success | empty | failure); REFRESH from success/empty/failure; STALE flag while success.
+Events: FETCH, RESOLVE{data}, REJECT{error}, RESET, STALE, REFRESH.
+Rule: Render track segments for idle, loading, success, empty, failure. Never hide empty/failure behind a generic spinner.`,
+
+  field: `## Field parallel statechart
+Regions:
+- interaction: pristine | dirty
+- validation: valid | invalid
+- submission: idle | pending
+Events: INPUT, BLUR, VALIDATE{valid}, SUBMIT, SUBMIT_DONE, SUBMIT_FAIL, RESET.
+Rule: Do not collapse validation + submission into one \`error\` boolean. Message UI follows validation region; pending follows submission.`,
+
+  button: `## Button lifecycle
+Preferred headless API: \`status\` prop ∈ idle | pending | success | failure | disabled.
+Optional machine: buttonLifecycleMachine with PRESS / RESOLVE / REJECT / RESET.
+Rule: Pending must set aria-busy. Do not use disabled alone to mean "saving".`,
+
+  dialog: `## Dialog statechart
+States: open | closed. Events: OPEN, CLOSE, TOGGLE.
+Rule: Backdrop click and Escape are CLOSE transitions. Title/Description are required for a11y when open.`,
+
+  popoverFamily: `## Popover family (Popover, Menu, Select open state)
+Machine: popoverMachine — states open | closed.
+Rule: Reuse this chart. Never create selectOpenMachine / menuOpenMachine forks.`,
+
+  toggle: `## Switch / Checkbox
+Machine: toggleMachine — checked | unchecked. Events: TOGGLE, CHECK, UNCHECK.
+Rule: Hidden input stays in sync with snapshot for forms.`,
+} as const
+
+/** Checkout-form example used on the landing "AI playground" proof. */
+export const GENERATIVE_UI_EXAMPLE = {
+  prompt: 'Create a multi-step checkout form with error handling.',
+  schemaOutput: {
+    component: 'CheckoutFlow',
+    steps: [
+      {
+        id: 'shipping',
+        fields: [
+          { component: 'Field', name: 'email', states: ['interaction', 'validation', 'submission'] },
+          { component: 'Field', name: 'address', states: ['interaction', 'validation', 'submission'] },
+        ],
+      },
+      {
+        id: 'payment',
+        fields: [{ component: 'Field', name: 'card', states: ['interaction', 'validation', 'submission'] }],
+      },
+    ],
+    submit: {
+      component: 'Button',
+      statusMachine: 'buttonLifecycleMachine',
+      allowedStatuses: ['idle', 'pending', 'success', 'failure'],
+    },
+    asyncRegion: {
+      component: 'Async',
+      allowedStates: ['idle', 'loading', 'success', 'empty', 'failure'],
+      onFailure: 'show Field.message + Button status=failure',
+    },
+  },
+  renderedHint:
+    'Aeon maps each step to Field (parallel regions) + Button status + Async lifecycle — named states throughout.',
+} as const
+
+export const CURSOR_RULES_SNIPPET = `${AEON_SYSTEM_PROMPT}
+
+## Schemas
+When generating Aeon UI, constrain props/parts/states to @aeon-ui/schemas catalog.
+Import headless from @aeon-ui/react or styled from @aeon-ui/ui.
+Install: npm install aeon-ui-engine react react-dom xstate @xstate/react
+CSS: import 'aeon-ui-engine/aeon.css'
+Vite: aeonUiVitePlugin() from aeon-ui-engine/vite
+
+${STATECHART_PROMPTS.async}
+
+${STATECHART_PROMPTS.field}
+
+${STATECHART_PROMPTS.button}
+
+${STATECHART_PROMPTS.dialog}
+
+${STATECHART_PROMPTS.popoverFamily}
+`

package/packages/schemas/src/registry.ts

@@ -0,0 +1,73 @@
+/**
+ * Aeon UI agent registry — machine-legible component contracts for Generative UI.
+ * Fetch at runtime: GET https://aeon-ui.com/registry/catalog.json
+ * Per component: GET https://aeon-ui.com/registry/components/{id}.json
+ * Machines: GET https://aeon-ui.com/registry/machines/{id}.json
+ */
+export type RegistryEntry = {
+  id: string
+  title: string
+  scope: string
+  schemaUrl: string
+  machineUrl?: string
+  runtime: string
+  description: string
+}
+
+export const REGISTRY_BASE = 'https://aeon-ui.com/registry' as const
+
+export const registryCatalog = {
+  $id: `${REGISTRY_BASE}/catalog.json`,
+  version: '0.1.0',
+  principle: 'UI = f(state)',
+  description:
+    'Lightweight runtime registry — fetch Aeon component schemas and state-tree JSON on demand instead of bundling every primitive.',
+  endpoints: {
+    catalog: `${REGISTRY_BASE}/catalog.json`,
+    component: `${REGISTRY_BASE}/components/{id}.json`,
+    machine: `${REGISTRY_BASE}/machines/{id}.json`,
+  },
+  components: [
+    {
+      id: 'button',
+      title: 'Button',
+      scope: 'button',
+      schemaUrl: `${REGISTRY_BASE}/components/button.json`,
+      machineUrl: `${REGISTRY_BASE}/machines/buttonLifecycle.json`,
+      runtime: 'status prop',
+      description: 'Action control with idle|pending|success|failure|disabled',
+    },
+    {
+      id: 'async',
+      title: 'Async',
+      scope: 'async',
+      schemaUrl: `${REGISTRY_BASE}/components/async.json`,
+      machineUrl: `${REGISTRY_BASE}/machines/async.json`,
+      runtime: 'useAeonMachine',
+      description: 'Fetch lifecycle region with full totality',
+    },
+    {
+      id: 'field',
+      title: 'Field',
+      scope: 'field',
+      schemaUrl: `${REGISTRY_BASE}/components/field.json`,
+      machineUrl: `${REGISTRY_BASE}/machines/field.json`,
+      runtime: 'useAeonMachine',
+      description: 'Parallel interaction × validation × submission',
+    },
+    {
+      id: 'dialog',
+      title: 'Dialog',
+      scope: 'dialog',
+      schemaUrl: `${REGISTRY_BASE}/components/dialog.json`,
+      machineUrl: `${REGISTRY_BASE}/machines/dialog.json`,
+      runtime: 'useAeonMachine',
+      description: 'Modal open/closed',
+    },
+  ] satisfies RegistryEntry[],
+  client: {
+    fetchCatalog: `fetch('${REGISTRY_BASE}/catalog.json').then(r => r.json())`,
+    fetchComponent: `id => fetch(\`${REGISTRY_BASE}/components/\${id}.json\`).then(r => r.json())`,
+    fetchMachine: `id => fetch(\`${REGISTRY_BASE}/machines/\${id}.json\`).then(r => r.json())`,
+  },
+} as const

package/packages/schemas/src/schema-builder.ts

@@ -0,0 +1,87 @@
+/** JSON Schema 2020-12 helpers for Aeon component contracts. */
+
+export type JsonSchema = Record<string, unknown>
+
+export function componentSchema(opts: {
+  id: string
+  title: string
+  description: string
+  scope: string
+  parts: readonly string[]
+  states: readonly string[]
+  props?: Record<string, JsonSchema>
+  slots?: Record<string, string>
+  machine?: string | null
+  runtime?: string
+  events?: readonly string[]
+  examples?: readonly string[]
+}): JsonSchema {
+  const props = opts.props ?? {}
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: opts.id,
+    title: opts.title,
+    description: opts.description,
+    type: 'object',
+    additionalProperties: false,
+    required: ['component', 'scope'],
+    properties: {
+      component: { const: opts.title.replace(/\s+/g, '') },
+      scope: { const: opts.scope },
+      parts: {
+        type: 'array',
+        description: 'Anatomy part keys — map to data-aeon-part',
+        items: { type: 'string', enum: [...opts.parts] },
+        uniqueItems: true,
+      },
+      states: {
+        type: 'array',
+        description: 'Allowed data-aeon-state values (stable states only)',
+        items: { type: 'string', enum: [...opts.states] },
+        uniqueItems: true,
+      },
+      props: {
+        type: 'object',
+        additionalProperties: false,
+        properties: props,
+      },
+      slots: {
+        type: 'object',
+        description: 'Named composition slots / compound parts',
+        additionalProperties: { type: 'string' },
+        properties: Object.fromEntries(
+          Object.entries(opts.slots ?? {}).map(([k, v]) => [k, { const: v, description: v }]),
+        ),
+      },
+      machine: {
+        type: ['string', 'null'],
+        description: 'XState machine export from @aeon-ui/primitives, or null if prop/React driven',
+        const: opts.machine ?? null,
+      },
+      runtime: {
+        type: 'string',
+        description: 'How headless state is driven at runtime',
+        const: opts.runtime ?? 'useAeonMachine',
+      },
+      events: {
+        type: 'array',
+        items: { type: 'string', enum: [...(opts.events ?? [])] },
+      },
+      examples: {
+        type: 'array',
+        items: { type: 'string' },
+        default: opts.examples ?? [],
+      },
+    },
+    'x-aeon': {
+      scope: opts.scope,
+      parts: [...opts.parts],
+      states: [...opts.states],
+      machine: opts.machine ?? null,
+      runtime: opts.runtime ?? 'useAeonMachine',
+      events: [...(opts.events ?? [])],
+      slots: opts.slots ?? {},
+      examples: [...(opts.examples ?? [])],
+    },
+  }
+}

package/packages/schemas/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "noEmit": true
+  },
+  "include": ["src", "scripts"]
+}