aeon-ui-engine 1.0.3 → 1.2.0

package/packages/schemas/registry/machines/field.json

@@ -0,0 +1,275 @@
+{
+  "id": "field",
+  "events": [
+    "INPUT",
+    "BLUR",
+    "RESET",
+    "VALIDATE",
+    "SUBMIT",
+    "SUBMIT_DONE",
+    "SUBMIT_FAIL"
+  ],
+  "tree": {
+    "key": "field",
+    "id": "field",
+    "type": "parallel",
+    "events": [
+      "INPUT",
+      "BLUR",
+      "RESET",
+      "VALIDATE",
+      "SUBMIT",
+      "SUBMIT_DONE",
+      "SUBMIT_FAIL"
+    ],
+    "transitions": [],
+    "children": [
+      {
+        "key": "interaction",
+        "id": "field.interaction",
+        "type": "compound",
+        "events": [
+          "INPUT",
+          "BLUR",
+          "RESET"
+        ],
+        "transitions": [],
+        "children": [
+          {
+            "key": "pristine",
+            "id": "field.interaction.pristine",
+            "type": "atomic",
+            "events": [
+              "INPUT",
+              "BLUR"
+            ],
+            "transitions": [
+              {
+                "event": "INPUT",
+                "target": [
+                  "dirty"
+                ],
+                "guarded": false
+              },
+              {
+                "event": "BLUR",
+                "target": [
+                  "dirty"
+                ],
+                "guarded": false
+              }
+            ],
+            "children": []
+          },
+          {
+            "key": "dirty",
+            "id": "field.interaction.dirty",
+            "type": "atomic",
+            "events": [
+              "RESET"
+            ],
+            "transitions": [
+              {
+                "event": "RESET",
+                "target": [
+                  "pristine"
+                ],
+                "guarded": false
+              }
+            ],
+            "children": []
+          }
+        ]
+      },
+      {
+        "key": "validation",
+        "id": "field.validation",
+        "type": "compound",
+        "events": [
+          "VALIDATE",
+          "RESET"
+        ],
+        "transitions": [],
+        "children": [
+          {
+            "key": "valid",
+            "id": "field.validation.valid",
+            "type": "atomic",
+            "events": [
+              "VALIDATE"
+            ],
+            "transitions": [
+              {
+                "event": "VALIDATE",
+                "target": [
+                  "invalid"
+                ],
+                "guarded": true
+              }
+            ],
+            "children": []
+          },
+          {
+            "key": "invalid",
+            "id": "field.validation.invalid",
+            "type": "atomic",
+            "events": [
+              "VALIDATE",
+              "RESET"
+            ],
+            "transitions": [
+              {
+                "event": "VALIDATE",
+                "target": [
+                  "valid"
+                ],
+                "guarded": true
+              },
+              {
+                "event": "RESET",
+                "target": [
+                  "valid"
+                ],
+                "guarded": false
+              }
+            ],
+            "children": []
+          }
+        ]
+      },
+      {
+        "key": "submission",
+        "id": "field.submission",
+        "type": "compound",
+        "events": [
+          "SUBMIT",
+          "SUBMIT_DONE",
+          "SUBMIT_FAIL"
+        ],
+        "transitions": [],
+        "children": [
+          {
+            "key": "idle",
+            "id": "field.submission.idle",
+            "type": "atomic",
+            "events": [
+              "SUBMIT"
+            ],
+            "transitions": [
+              {
+                "event": "SUBMIT",
+                "target": [
+                  "pending"
+                ],
+                "guarded": false
+              }
+            ],
+            "children": []
+          },
+          {
+            "key": "pending",
+            "id": "field.submission.pending",
+            "type": "atomic",
+            "events": [
+              "SUBMIT_DONE",
+              "SUBMIT_FAIL"
+            ],
+            "transitions": [
+              {
+                "event": "SUBMIT_DONE",
+                "target": [
+                  "idle"
+                ],
+                "guarded": false
+              },
+              {
+                "event": "SUBMIT_FAIL",
+                "target": [
+                  "idle"
+                ],
+                "guarded": false
+              }
+            ],
+            "children": []
+          }
+        ]
+      }
+    ]
+  },
+  "states": {
+    "field": {
+      "events": [
+        "INPUT",
+        "BLUR",
+        "RESET",
+        "VALIDATE",
+        "SUBMIT",
+        "SUBMIT_DONE",
+        "SUBMIT_FAIL"
+      ],
+      "type": "parallel"
+    },
+    "field.interaction": {
+      "events": [
+        "INPUT",
+        "BLUR",
+        "RESET"
+      ],
+      "type": "compound"
+    },
+    "field.interaction.pristine": {
+      "events": [
+        "INPUT",
+        "BLUR"
+      ],
+      "type": "atomic"
+    },
+    "field.interaction.dirty": {
+      "events": [
+        "RESET"
+      ],
+      "type": "atomic"
+    },
+    "field.validation": {
+      "events": [
+        "VALIDATE",
+        "RESET"
+      ],
+      "type": "compound"
+    },
+    "field.validation.valid": {
+      "events": [
+        "VALIDATE"
+      ],
+      "type": "atomic"
+    },
+    "field.validation.invalid": {
+      "events": [
+        "VALIDATE",
+        "RESET"
+      ],
+      "type": "atomic"
+    },
+    "field.submission": {
+      "events": [
+        "SUBMIT",
+        "SUBMIT_DONE",
+        "SUBMIT_FAIL"
+      ],
+      "type": "compound"
+    },
+    "field.submission.idle": {
+      "events": [
+        "SUBMIT"
+      ],
+      "type": "atomic"
+    },
+    "field.submission.pending": {
+      "events": [
+        "SUBMIT_DONE",
+        "SUBMIT_FAIL"
+      ],
+      "type": "atomic"
+    }
+  }
+}

package/packages/schemas/scripts/emit.ts

@@ -0,0 +1,61 @@
+import { mkdirSync, writeFileSync, cpSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  asyncMachine,
+  buttonLifecycleMachine,
+  dialogMachine,
+  fieldMachine,
+} from '@aeon-ui/primitives'
+import { catalog, componentSchemas } from '../src/components.js'
+import { AEON_SYSTEM_PROMPT, CURSOR_RULES_SNIPPET, STATECHART_PROMPTS } from '../src/prompts.js'
+import { aeonToSchema } from '../src/aeon-to-schema.js'
+import { registryCatalog } from '../src/registry.js'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const jsonDir = join(root, 'json')
+const promptsDir = join(root, 'prompts')
+const registryDir = join(root, 'registry')
+const demoRegistry = join(root, '../../apps/demo/public/registry')
+
+mkdirSync(jsonDir, { recursive: true })
+mkdirSync(promptsDir, { recursive: true })
+mkdirSync(join(registryDir, 'components'), { recursive: true })
+mkdirSync(join(registryDir, 'machines'), { recursive: true })
+
+writeFileSync(join(jsonDir, 'catalog.json'), `${JSON.stringify(catalog, null, 2)}\n`)
+
+for (const [id, schema] of Object.entries(componentSchemas)) {
+  writeFileSync(join(jsonDir, `${id}.json`), `${JSON.stringify(schema, null, 2)}\n`)
+  writeFileSync(join(registryDir, 'components', `${id}.json`), `${JSON.stringify(schema, null, 2)}\n`)
+}
+
+const machines = {
+  async: asyncMachine,
+  buttonLifecycle: buttonLifecycleMachine,
+  dialog: dialogMachine,
+  field: fieldMachine,
+} as const
+
+for (const [id, machine] of Object.entries(machines)) {
+  const schema = aeonToSchema(machine)
+  writeFileSync(join(registryDir, 'machines', `${id}.json`), `${JSON.stringify(schema, null, 2)}\n`)
+}
+
+writeFileSync(join(registryDir, 'catalog.json'), `${JSON.stringify(registryCatalog, null, 2)}\n`)
+
+writeFileSync(join(promptsDir, 'system.md'), `${AEON_SYSTEM_PROMPT.trim()}\n`)
+writeFileSync(join(promptsDir, 'cursorrules.md'), `${CURSOR_RULES_SNIPPET.trim()}\n`)
+writeFileSync(
+  join(promptsDir, 'statecharts.md'),
+  `# Aeon UI statecharts (agent prompts)\n\n${Object.values(STATECHART_PROMPTS).join('\n\n')}\n`,
+)
+
+mkdirSync(demoRegistry, { recursive: true })
+if (existsSync(registryDir)) {
+  cpSync(registryDir, demoRegistry, { recursive: true })
+}
+
+console.log(
+  `Emitted ${Object.keys(componentSchemas).length} schemas + ${Object.keys(machines).length} machines → registry/ (+ demo public)`,
+)

package/packages/schemas/src/aeon-to-schema.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { createActor } from 'xstate'
+import { asyncMachine, buttonLifecycleMachine } from '@aeon-ui/primitives'
+import { aeonSnapshotSchema, aeonToPrompt, aeonToSchema } from './aeon-to-schema.js'
+import { createAgentEventBridge } from './agent-bridge.js'
+
+describe('aeonToSchema', () => {
+  it('builds a hierarchical state tree for async', () => {
+    const schema = aeonToSchema(asyncMachine)
+    expect(schema.id).toBe('async')
+    expect(schema.events).toEqual(expect.arrayContaining(['FETCH', 'RESOLVE', 'REJECT', 'RESET']))
+    expect(schema.tree.children.map((c) => c.key)).toEqual(
+      expect.arrayContaining(['idle', 'loading', 'success', 'failure', 'empty']),
+    )
+    const idle = schema.tree.children.find((c) => c.key === 'idle')
+    expect(idle?.events).toEqual(expect.arrayContaining(['FETCH', 'RESET']))
+  })
+
+  it('omits internal xstate.* events from the public tree', () => {
+    const schema = aeonToSchema(asyncMachine)
+    expect(schema.events.every((e) => !e.startsWith('xstate.'))).toBe(true)
+  })
+
+  it('lists only valid events for the live snapshot', () => {
+    const actor = createActor(asyncMachine)
+    actor.start()
+    const live = aeonSnapshotSchema(asyncMachine, actor.getSnapshot())
+    expect(live.value).toBe('idle')
+    expect(live.validEvents).toEqual(expect.arrayContaining(['FETCH', 'RESET']))
+    expect(live.validEvents).not.toContain('RESOLVE')
+    actor.stop()
+  })
+
+  it('produces a prompt with JSON tree', () => {
+    const prompt = aeonToPrompt(buttonLifecycleMachine)
+    expect(prompt).toContain('buttonLifecycle')
+    expect(prompt).toContain('```json')
+    expect(prompt).toContain('PRESS')
+  })
+})
+
+describe('createAgentEventBridge', () => {
+  it('maps AGENT_STREAM_START → FETCH and blocks illegal events', () => {
+    const actor = createActor(asyncMachine)
+    actor.start()
+    const illegal: string[] = []
+    const bridge = createAgentEventBridge(actor, {
+      map: {
+        AGENT_STREAM_START: 'FETCH',
+        AGENT_STREAM_ERROR: (e) =>
+          e.type === 'AGENT_STREAM_ERROR' ? { type: 'REJECT', error: e.error } : null,
+      },
+      onIllegal: (ev, reason) => illegal.push(`${ev.type}:${reason}`),
+    })
+
+    expect(bridge.push({ type: 'AGENT_STREAM_START' })).toBe(true)
+    expect(actor.getSnapshot().value).toBe('loading')
+
+    // RESOLVE is valid in loading — but AGENT_STREAM_ERROR maps to REJECT which is also valid
+    expect(bridge.push({ type: 'AGENT_STREAM_ERROR', error: 'boom' })).toBe(true)
+    expect(actor.getSnapshot().value).toBe('failure')
+
+    // FETCH is valid from failure
+    expect(bridge.push({ type: 'AGENT_STREAM_START' })).toBe(true)
+    expect(actor.getSnapshot().value).toBe('loading')
+
+    actor.stop()
+    expect(illegal).toEqual([])
+  })
+})

package/packages/schemas/src/aeon-to-schema.ts

@@ -0,0 +1,206 @@
+import type { AnyStateMachine, AnyStateNode, SnapshotFrom } from 'xstate'
+import {
+  createActor,
+  getNextTransitions,
+  getStateNodes,
+  __unsafe_getAllOwnEventDescriptors,
+} from 'xstate'
+
+/** Hierarchical state-tree node for LLM / Generative UI consumption. */
+export type AeonStateTreeNode = {
+  key: string
+  id: string
+  type: string
+  events: string[]
+  transitions: Array<{
+    event: string
+    target: string[]
+    guarded: boolean
+  }>
+  children: AeonStateTreeNode[]
+}
+
+/** Deterministic statechart JSON an agent can read at any micro-moment. */
+export type AeonMachineSchema = {
+  id: string
+  initial: string | undefined
+  events: string[]
+  tree: AeonStateTreeNode
+  /** Flat map: state id → events defined on that node */
+  states: Record<string, { events: string[]; type: string }>
+}
+
+export type AeonSnapshotSchema = {
+  machineId: string
+  value: unknown
+  /** Event types valid from the active configuration (no getNextEvents in XState v5). */
+  validEvents: string[]
+  /** Transition rows including guard presence — agents should prefer unguarded or known payloads. */
+  nextTransitions: Array<{
+    event: string
+    target: string[]
+    guarded: boolean
+  }>
+  activeStateIds: string[]
+}
+
+function isPublicEvent(event: string): boolean {
+  return !event.startsWith('xstate.')
+}
+
+function filterPublicEvents(events: readonly string[]): string[] {
+  return events.filter(isPublicEvent)
+}
+
+function walkNode(node: AnyStateNode): AeonStateTreeNode {
+  const on = node.config.on ?? {}
+  const transitionEntries = Object.entries(on as Record<string, unknown>)
+    .filter(([event]) => isPublicEvent(event))
+    .map(([event, def]) => {
+      const targets: string[] = []
+      const list = Array.isArray(def) ? def : [def]
+      let guarded = false
+      for (const item of list) {
+        if (item == null) continue
+        if (typeof item === 'string') {
+          targets.push(item)
+          continue
+        }
+        if (typeof item === 'object') {
+          const row = item as { target?: string | string[]; guard?: unknown }
+          if (row.guard != null) guarded = true
+          if (typeof row.target === 'string') targets.push(row.target)
+          else if (Array.isArray(row.target)) targets.push(...row.target)
+        }
+      }
+      return { event, target: targets, guarded }
+    })
+
+  return {
+    key: node.key,
+    id: node.id,
+    type: node.type,
+    events: filterPublicEvents([...(node.events ?? [])]),
+    transitions: transitionEntries,
+    children: Object.values(node.states ?? {}).map(walkNode),
+  }
+}
+
+function flattenNodes(node: AnyStateNode, out: AeonMachineSchema['states']) {
+  out[node.id] = {
+    events: filterPublicEvents([...(node.events ?? [])]),
+    type: node.type,
+  }
+  for (const child of Object.values(node.states ?? {})) {
+    flattenNodes(child, out)
+  }
+}
+
+/**
+ * Stringify an XState machine into a clean hierarchical state-tree JSON.
+ * Use this as the runtime contract for agents that must know which events
+ * (TOGGLE, SUBMIT, FETCH, …) are legal before calling `send`.
+ * Internal timers (`xstate.after.*`) are omitted — agents send public events only.
+ */
+export function aeonToSchema(machine: AnyStateMachine): AeonMachineSchema {
+  const tree = walkNode(machine.root)
+  const flat: AeonMachineSchema['states'] = {}
+  flattenNodes(machine.root, flat)
+
+  const initial =
+    typeof machine.config.initial === 'string' ? machine.config.initial : undefined
+
+  return {
+    id: machine.id,
+    initial,
+    events: filterPublicEvents([...(machine.events ?? [])]),
+    tree,
+    states: flat,
+  }
+}
+
+/**
+ * Snapshot-aware companion to `aeonToSchema`.
+ * Call whenever the actor advances so the LLM only proposes legal next events.
+ */
+export function aeonSnapshotSchema(
+  machine: AnyStateMachine,
+  snapshot: SnapshotFrom<AnyStateMachine>,
+): AeonSnapshotSchema {
+  const active = getStateNodes(machine.root, snapshot.value)
+  const next = getNextTransitions(snapshot)
+
+  return {
+    machineId: machine.id,
+    value: snapshot.value,
+    validEvents: [...__unsafe_getAllOwnEventDescriptors(snapshot)].filter(
+      (e) => !e.startsWith('xstate.'),
+    ),
+    nextTransitions: next
+      .filter((t) => !t.eventType.startsWith('xstate.'))
+      .map((t) => ({
+        event: t.eventType,
+        target: (t.target ?? []).map((n) => n.id),
+        guarded: Boolean(t.guard),
+      })),
+    activeStateIds: active.map((n) => n.id),
+  }
+}
+
+/**
+ * Turn a machine (+ optional live snapshot) into a deterministic system-prompt fragment.
+ */
+export function aeonToPrompt(
+  machine: AnyStateMachine,
+  snapshot?: SnapshotFrom<AnyStateMachine>,
+): string {
+  const schema = aeonToSchema(machine)
+  const lines = [
+    `## Aeon statechart: ${schema.id}`,
+    `Initial: ${schema.initial ?? '(none)'}`,
+    `All events: ${schema.events.join(', ') || '(none)'}`,
+    '',
+    '### State tree (JSON)',
+    '```json',
+    JSON.stringify(schema.tree, null, 2),
+    '```',
+    '',
+    'Rules for agents:',
+    '- Only send event types listed under the *active* configuration.',
+    '- Never invent events or targets not present in this tree.',
+    '- Prefer events with guarded:false unless you can satisfy the guard payload.',
+  ]
+
+  if (snapshot) {
+    const live = aeonSnapshotSchema(machine, snapshot)
+    lines.push(
+      '',
+      '### Live snapshot',
+      `- value: ${JSON.stringify(live.value)}`,
+      `- validEvents now: ${live.validEvents.join(', ') || '(none)'}`,
+      `- nextTransitions: ${JSON.stringify(live.nextTransitions)}`,
+    )
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Convenience: start a throwaway actor at the initial state and return both
+ * static schema + snapshot schema for prompt injection.
+ */
+export function aeonInitialAgentContext(machine: AnyStateMachine): {
+  schema: AeonMachineSchema
+  snapshot: AeonSnapshotSchema
+  prompt: string
+} {
+  const actor = createActor(machine)
+  actor.start()
+  const snap = actor.getSnapshot()
+  actor.stop()
+  return {
+    schema: aeonToSchema(machine),
+    snapshot: aeonSnapshotSchema(machine, snap),
+    prompt: aeonToPrompt(machine, snap),
+  }
+}

package/packages/schemas/src/agent-bridge.ts

@@ -0,0 +1,82 @@
+import type { AnyEventObject, AnyActorRef } from 'xstate'
+
+/** Streaming / tool-loop events from an LLM or automation. */
+export type AgentStreamEvent =
+  | { type: 'AGENT_STREAM_START'; taskId?: string }
+  | { type: 'AGENT_STREAM_CHUNK'; taskId?: string; data?: unknown }
+  | { type: 'AGENT_STREAM_END'; taskId?: string; data?: unknown }
+  | { type: 'AGENT_STREAM_ERROR'; taskId?: string; error: string }
+  | { type: 'AGENT_TOOL_CALL'; name: string; args?: unknown }
+  | { type: 'AGENT_TOOL_RESULT'; name: string; result?: unknown }
+  | { type: string; [key: string]: unknown }
+
+export type AgentEventMap = Record<string, string | ((event: AgentStreamEvent) => AnyEventObject | null)>
+
+export type AgentBridgeOptions = {
+  /**
+   * Map inbound agent event types → machine event types or transformers.
+   * Example: `{ AGENT_STREAM_START: 'FETCH', AGENT_STREAM_ERROR: (e) => ({ type: 'REJECT', error: e.error }) }`
+   */
+  map: AgentEventMap
+  /** Optional filter — return false to drop the event. */
+  accept?: (event: AgentStreamEvent) => boolean
+  /** Called when a mapped event is not allowed by `snapshot.can` (if actor exposes getSnapshot). */
+  onIllegal?: (event: AnyEventObject, reason: string) => void
+}
+
+type Sendable = {
+  send: (event: AnyEventObject) => void
+  getSnapshot?: () => { can: (event: AnyEventObject) => boolean }
+}
+
+/**
+ * Bind streaming LLM / tool-loop events to an Aeon machine actor.
+ * Prevents agents from firing transitions the chart will reject.
+ */
+export function createAgentEventBridge(actor: Sendable | AnyActorRef, options: AgentBridgeOptions) {
+  const { map, accept, onIllegal } = options
+
+  const resolve = (incoming: AgentStreamEvent): AnyEventObject | null => {
+    if (accept && !accept(incoming)) return null
+    const binding = map[incoming.type]
+    if (binding == null) return null
+    if (typeof binding === 'function') return binding(incoming)
+    return { type: binding }
+  }
+
+  const push = (incoming: AgentStreamEvent): boolean => {
+    const event = resolve(incoming)
+    if (!event) return false
+
+    const snap = typeof actor.getSnapshot === 'function' ? actor.getSnapshot() : undefined
+    if (snap && !snap.can(event)) {
+      onIllegal?.(event, `Event ${event.type} is not valid in the current configuration`)
+      return false
+    }
+
+    actor.send(event)
+    return true
+  }
+
+  return {
+    /** Push one agent/stream event through the map into `machine.send`. */
+    push,
+    /** Map of known agent → machine bindings (for prompts / docs). */
+    map,
+    /** Describe the bridge for system prompts. */
+    toPrompt(): string {
+      const rows = Object.entries(map).map(([from, to]) => {
+        const dest = typeof to === 'string' ? to : '(transform)'
+        return `- ${from} → ${dest}`
+      })
+      return [
+        '## Agent event bridge',
+        'Inbound stream events map to machine events:',
+        ...rows,
+        'Illegal events (rejected by snapshot.can) are dropped.',
+      ].join('\n')
+    },
+  }
+}
+
+export type AgentEventBridge = ReturnType<typeof createAgentEventBridge>