aeon-ui-engine 1.3.1 → 1.3.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [1.3.5] - 2026-07-31
+
+### Added
+
+- Layout schemas for Instant/agent surfaces: identity, profileHeader, metricStrip, listRow, entry, conversation (38 total schemas).
+
+### Fixed
+
+- **Tooltip open/closed** — uses `popoverMachine` like Popover/Select/Combobox; openDelay / closeDelay / touchDuration stay React-local.
+- Agent prompts and MACHINES/COMPONENTS/FILE_MAP now treat Tooltip as popover-family.
+
+## [1.3.4] - 2026-07-31
+
+### Fixed
+
+- Instant/Build no longer shows chart-only stubs like “States: idle · discover · … Project faces in a second pass.” — projects concept/prompt faces while keeping the authored chart.
+
+## [1.3.3] - 2026-07-31
+
+### Fixed
+
+- **Agent registry lag** — runtime `registry/catalog.json` now derives from `componentSchemas` (was stuck at 4 entries while schemas existed).
+- **Machine emit coverage** — schema emit writes all 15 primitives machines (was only async/button/dialog/field), unlocking `validEvents` trees for popover family, slider, shells, etc.
+- **Combobox open/closed** — uses `popoverMachine` like Select; query/highlight stay React-local.
+- Stale docs claiming Select/Combobox were pure `useState`; checklist now requires schema + emit steps.
+
+### Added
+
+- Component schemas for machine-backed and high-traffic surfaces: radioGroup, slider, content, panel, appShell, stickyBar, nav, appNav, prompt, statusBanner, pinInput, avatar, bar, separator, composer, thread (32 total).
+
+## [1.3.2] - 2026-07-31
+
+### Changed
+
+- Restore state-first landing messaging (remove BETA chrome from hero, meta, and builder).
+
 ## [1.3.1] - 2026-07-30
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeon-ui-engine",
-  "version": "1.3.1",
+  "version": "1.3.5",
   "private": false,
   "type": "module",
   "bin": {

package/packages/react/src/combobox/index.tsx

@@ -1,4 +1,5 @@
 import { comboboxAnatomy, partAttrs, partOnlyAttrs } from '@aeon-ui/core'
+import { popoverMachine } from '@aeon-ui/primitives'
 import {
   createContext,
   forwardRef,
@@ -18,6 +19,7 @@ import {
   type MouseEvent,
   type ReactNode,
 } from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
 import { mergeProps } from '../utils/merge-props.js'
 
 interface RegisteredItem {
@@ -73,23 +75,27 @@ const Root = forwardRef<HTMLDivElement, ComboboxRootProps>(function ComboboxRoot
   { value, onValueChange, children, className, disabled },
   ref,
 ) {
-  const [open, setOpenState] = useState(false)
+  const [snapshot, send] = useAeonMachine(popoverMachine, { input: { open: false } })
   const [query, setQuery] = useState('')
   const [highlightedValue, setHighlightedValue] = useState<string | null>(null)
   const [itemsVersion, setItemsVersion] = useState(0)
   const itemsRef = useRef<RegisteredItem[]>([])
   const listboxId = useId()
 
+  const open = disabled ? false : snapshot.matches('open')
+
   const setOpen = useCallback(
     (next: boolean) => {
       if (disabled) return
-      setOpenState(next)
-      if (!next) {
-        setQuery('')
-        setHighlightedValue(null)
+      if (next) {
+        send({ type: 'OPEN' })
+        return
       }
+      send({ type: 'CLOSE' })
+      setQuery('')
+      setHighlightedValue(null)
     },
-    [disabled],
+    [disabled, send],
   )
 
   const registerItem = useCallback((item: RegisteredItem) => {
@@ -107,7 +113,7 @@ const Root = forwardRef<HTMLDivElement, ComboboxRootProps>(function ComboboxRoot
   const ctx = useMemo(
     () => ({
       value,
-      open: disabled ? false : open,
+      open,
       query,
       listboxId,
       highlightedValue,
@@ -132,7 +138,6 @@ const Root = forwardRef<HTMLDivElement, ComboboxRootProps>(function ComboboxRoot
       registerItem,
       unregisterItem,
       getItems,
-      disabled,
     ],
   )
 

package/packages/react/src/tooltip/index.tsx

@@ -1,7 +1,9 @@
 import { tooltipAnatomy, partAttrs } from '@aeon-ui/core'
+import { popoverMachine } from '@aeon-ui/primitives'
 import {
   createContext,
   forwardRef,
+  useCallback,
   useContext,
   useEffect,
   useId,
@@ -15,6 +17,7 @@ import {
   type ReactNode,
 } from 'react'
 import { FloatingPositioner } from '../floating/FloatingPositioner.js'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
 import { useOutsideClick } from '../hooks/use-outside-click.js'
 import { usePrefersHover } from '../hooks/use-prefers-hover.js'
 import { mergeProps } from '../utils/merge-props.js'
@@ -76,8 +79,10 @@ const Root = forwardRef<HTMLDivElement, TooltipRootProps>(function TooltipRoot(
   },
   ref,
 ) {
-  const [uncontrolled, setUncontrolled] = useState(defaultOpen)
-  const resolvedOpen = open ?? uncontrolled
+  const [snapshot, send] = useAeonMachine(popoverMachine, {
+    input: { open: defaultOpen },
+  })
+  const resolvedOpen = open ?? snapshot.matches('open')
   const showTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
   const hideTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
   const triggerRef = useRef<HTMLSpanElement>(null)
@@ -87,6 +92,10 @@ const Root = forwardRef<HTMLDivElement, TooltipRootProps>(function TooltipRoot(
   const prefersHover = usePrefersHover()
   const [outsideClickEnabled, setOutsideClickEnabled] = useState(false)
 
+  useEffect(() => {
+    if (open !== undefined) send({ type: 'SET_OPEN', open })
+  }, [open, send])
+
   useEffect(() => {
     if (!resolvedOpen || prefersHover) {
       setOutsideClickEnabled(false)
@@ -97,52 +106,57 @@ const Root = forwardRef<HTMLDivElement, TooltipRootProps>(function TooltipRoot(
     return () => window.clearTimeout(id)
   }, [resolvedOpen, prefersHover, touchOutsideGraceMs])
 
-  const setOpen = (next: boolean) => {
-    if (open === undefined) setUncontrolled(next)
-    onOpenChange?.(next)
-  }
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (open === undefined) send({ type: next ? 'OPEN' : 'CLOSE' })
+      onOpenChange?.(next)
+    },
+    [open, send, onOpenChange],
+  )
 
   useEffect(() => {
     onOpenChange?.(resolvedOpen)
   }, [resolvedOpen, onOpenChange])
 
-  const hideNow = () => {
+  const hideNow = useCallback(() => {
     if (showTimer.current !== undefined) clearTimeout(showTimer.current)
     if (hideTimer.current !== undefined) clearTimeout(hideTimer.current)
     setOpen(false)
-  }
+  }, [setOpen])
 
-  const showImmediately = () => {
+  const showImmediately = useCallback(() => {
     if (showTimer.current !== undefined) clearTimeout(showTimer.current)
     if (hideTimer.current !== undefined) clearTimeout(hideTimer.current)
     setOpen(true)
-    if (!prefersHover) {
-      if (touchDurationMs > 0) {
-        hideTimer.current = setTimeout(() => hideNow(), touchDurationMs)
-      }
+    if (!prefersHover && touchDurationMs > 0) {
+      hideTimer.current = setTimeout(() => hideNow(), touchDurationMs)
     }
-  }
+  }, [setOpen, prefersHover, touchDurationMs, hideNow])
 
-  const scheduleShow = () => {
+  const scheduleShow = useCallback(() => {
     if (hideTimer.current !== undefined) clearTimeout(hideTimer.current)
     showTimer.current = setTimeout(() => setOpen(true), openDelay)
-  }
+  }, [setOpen, openDelay])
 
-  const scheduleHide = () => {
+  const scheduleHide = useCallback(() => {
     if (showTimer.current !== undefined) clearTimeout(showTimer.current)
     if (closeDelay <= 0) {
       setOpen(false)
       return
     }
     hideTimer.current = setTimeout(() => setOpen(false), closeDelay)
-  }
+  }, [setOpen, closeDelay])
 
-  const toggleTouch = () => {
+  const toggleTouch = useCallback(() => {
     if (resolvedOpen) hideNow()
     else showImmediately()
-  }
+  }, [resolvedOpen, hideNow, showImmediately])
 
-  useOutsideClick([triggerRef, positionerRef], resolvedOpen && !prefersHover && outsideClickEnabled, hideNow)
+  useOutsideClick(
+    [triggerRef, positionerRef],
+    resolvedOpen && !prefersHover && outsideClickEnabled,
+    hideNow,
+  )
 
   const value = useMemo(
     () => ({
@@ -160,7 +174,19 @@ const Root = forwardRef<HTMLDivElement, TooltipRootProps>(function TooltipRoot(
       showOnFocus,
       prefersHover,
     }),
-    [resolvedOpen, triggerId, contentId, openDelay, closeDelay, touchDurationMs, touchOutsideGraceMs, showOnFocus, prefersHover],
+    [
+      resolvedOpen,
+      setOpen,
+      triggerId,
+      contentId,
+      scheduleShow,
+      scheduleHide,
+      showImmediately,
+      hideNow,
+      toggleTouch,
+      showOnFocus,
+      prefersHover,
+    ],
   )
 
   return (

package/packages/schemas/dist/index.d.ts

@@ -35,6 +35,28 @@ declare const componentSchemas: {
     readonly toast: JsonSchema;
     readonly scroll: JsonSchema;
     readonly progress: JsonSchema;
+    readonly radioGroup: JsonSchema;
+    readonly slider: JsonSchema;
+    readonly pinInput: JsonSchema;
+    readonly avatar: JsonSchema;
+    readonly content: JsonSchema;
+    readonly panel: JsonSchema;
+    readonly appShell: JsonSchema;
+    readonly stickyBar: JsonSchema;
+    readonly bar: JsonSchema;
+    readonly nav: JsonSchema;
+    readonly appNav: JsonSchema;
+    readonly prompt: JsonSchema;
+    readonly statusBanner: JsonSchema;
+    readonly separator: JsonSchema;
+    readonly composer: JsonSchema;
+    readonly thread: JsonSchema;
+    readonly identity: JsonSchema;
+    readonly profileHeader: JsonSchema;
+    readonly metricStrip: JsonSchema;
+    readonly listRow: JsonSchema;
+    readonly entry: JsonSchema;
+    readonly conversation: JsonSchema;
 };
 type ComponentSchemaId = keyof typeof componentSchemas;
 declare const catalog: {
@@ -63,6 +85,28 @@ declare const catalog: {
         readonly toast: JsonSchema;
         readonly scroll: JsonSchema;
         readonly progress: JsonSchema;
+        readonly radioGroup: JsonSchema;
+        readonly slider: JsonSchema;
+        readonly pinInput: JsonSchema;
+        readonly avatar: JsonSchema;
+        readonly content: JsonSchema;
+        readonly panel: JsonSchema;
+        readonly appShell: JsonSchema;
+        readonly stickyBar: JsonSchema;
+        readonly bar: JsonSchema;
+        readonly nav: JsonSchema;
+        readonly appNav: JsonSchema;
+        readonly prompt: JsonSchema;
+        readonly statusBanner: JsonSchema;
+        readonly separator: JsonSchema;
+        readonly composer: JsonSchema;
+        readonly thread: JsonSchema;
+        readonly identity: JsonSchema;
+        readonly profileHeader: JsonSchema;
+        readonly metricStrip: JsonSchema;
+        readonly listRow: JsonSchema;
+        readonly entry: JsonSchema;
+        readonly conversation: JsonSchema;
     };
 };
 
@@ -70,14 +114,18 @@ declare const catalog: {
  * Statecharts packaged as system-prompt fragments for AI coding agents.
  * Embed before code generation so agents cannot invent impossible UI states.
  */
-declare const AEON_SYSTEM_PROMPT = "# Aeon UI \u2014 agent system prompt\n\nYou are building UI with **Aeon UI**, a React component library powered by finite statecharts.\n\n## Order of work (mandatory)\n1. **Build the state machines first** \u2014 name every lifecycle the UX needs (states + events). Prefer machines from `@aeon-ui/primitives` (or documented prop projections such as Button `status`).\n2. **Then project UI from those machines** \u2014 compound parts, copy, and layout exist only to reflect the chart. Never invent UI for states that are not in a machine.\n3. **UI = f(state)** \u2014 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.\n\n## Non-negotiable rules\n1. Do not duplicate open/checked/lifecycle in `useState` when a machine exists in `@aeon-ui/primitives`.\n2. **Button `status` is a prop** (`idle|pending|success|failure|disabled`). Optional: drive it from `buttonLifecycleMachine` via `useAeonMachine` in app code.\n3. **Select / Menu / Popover** share `popoverMachine` \u2014 never fork another open/closed chart.\n4. **Combobox** and **Tooltip** use React state today \u2014 do not add floating machines without the component checklist.\n5. **Scroll** uses `getScrollSnapshot()` \u2014 no XState machine.\n6. If a machine lists N stable states, the UI must represent all N (totality).\n7. Prefer `@aeon-ui/react` (headless) or `@aeon-ui/ui` (styled). Relative TS imports use `.js` extensions inside the Aeon monorepo only.\n8. Primitives stay **universal** \u2014 never invent niche components (dating, colour-blind test, pong). Compose from generic parts.\n\n## DOM contract\nEvery interactive surface sets anatomy via `partAttrs` from `@aeon-ui/core`:\n- `data-aeon-scope` \u2014 family (`button`, `async`, `field`, \u2026)\n- `data-aeon-part` \u2014 anatomy key (`root`, `trigger`, \u2026)\n- `data-aeon-state` \u2014 allowed snapshot / prop state only\n\n## Before writing JSX\n1. Enumerate machines (or documented status props) for the flow \u2014 states and events.\n2. Read the component JSON Schema from `@aeon-ui/schemas` (or pasted catalog) and match parts to those charts.\n3. Compose with documented compound parts (`Dialog.Root`, `Field.Control`, \u2026).\n4. Wire events to machine events or documented props \u2014 never invent `isLoading && !isError && hasData` spaghetti when a named state exists.\n";
+declare const AEON_SYSTEM_PROMPT = "# Aeon UI \u2014 agent system prompt\n\nYou are building UI with **Aeon UI**, a React component library powered by finite statecharts.\n\n## Order of work (mandatory)\n1. **Build the state machines first** \u2014 name every lifecycle the UX needs (states + events). Prefer machines from `@aeon-ui/primitives` (or documented prop projections such as Button `status`).\n2. **Then project UI from those machines** \u2014 compound parts, copy, and layout exist only to reflect the chart. Never invent UI for states that are not in a machine.\n3. **UI = f(state)** \u2014 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.\n\n## Non-negotiable rules\n1. Do not duplicate open/checked/lifecycle in `useState` when a machine exists in `@aeon-ui/primitives`.\n2. **Button `status` is a prop** (`idle|pending|success|failure|disabled`). Optional: drive it from `buttonLifecycleMachine` via `useAeonMachine` in app code.\n3. **Select / Menu / Popover / Combobox / Tooltip** share `popoverMachine` for open/closed \u2014 never fork another open/closed chart. Combobox keeps query/highlight in React; Tooltip keeps openDelay/closeDelay/touchDuration in React.\n4. **PinInput** digit buffer is React-local today \u2014 do not invent a pin machine without the component checklist.\n5. **Scroll** uses `getScrollSnapshot()` \u2014 no XState machine.\n6. If a machine lists N stable states, the UI must represent all N (totality).\n7. Prefer `@aeon-ui/react` (headless) or `@aeon-ui/ui` (styled). Relative TS imports use `.js` extensions inside the Aeon monorepo only.\n8. Primitives stay **universal** \u2014 never invent niche components (dating, colour-blind test, pong). Compose from generic parts.\n\n## DOM contract\nEvery interactive surface sets anatomy via `partAttrs` from `@aeon-ui/core`:\n- `data-aeon-scope` \u2014 family (`button`, `async`, `field`, \u2026)\n- `data-aeon-part` \u2014 anatomy key (`root`, `trigger`, \u2026)\n- `data-aeon-state` \u2014 allowed snapshot / prop state only\n\n## Before writing JSX\n1. Enumerate machines (or documented status props) for the flow \u2014 states and events.\n2. Read the component JSON Schema from `@aeon-ui/schemas` (or pasted catalog) and match parts to those charts.\n3. Compose with documented compound parts (`Dialog.Root`, `Field.Control`, \u2026).\n4. Wire events to machine events or documented props \u2014 never invent `isLoading && !isError && hasData` spaghetti when a named state exists.\n";
 declare const STATECHART_PROMPTS: {
     readonly async: "## Async region statechart\nStates: idle → loading → (success | empty | failure); REFRESH from success/empty/failure; STALE flag while success.\nEvents: FETCH, RESOLVE{data}, REJECT{error}, RESET, STALE, REFRESH.\nRule: Render track segments for idle, loading, success, empty, failure. Never hide empty/failure behind a generic spinner.";
     readonly field: "## Field parallel statechart\nRegions:\n- interaction: pristine | dirty\n- validation: valid | invalid\n- submission: idle | pending\nEvents: INPUT, BLUR, VALIDATE{valid}, SUBMIT, SUBMIT_DONE, SUBMIT_FAIL, RESET.\nRule: Do not collapse validation + submission into one `error` boolean. Message UI follows validation region; pending follows submission.";
     readonly button: "## Button lifecycle\nPreferred headless API: `status` prop ∈ idle | pending | success | failure | disabled.\nOptional machine: buttonLifecycleMachine with PRESS / RESOLVE / REJECT / RESET.\nRule: Pending must set aria-busy. Do not use disabled alone to mean \"saving\".";
     readonly dialog: "## Dialog statechart\nStates: open | closed. Events: OPEN, CLOSE, TOGGLE.\nRule: Backdrop click and Escape are CLOSE transitions. Title/Description are required for a11y when open.";
-    readonly popoverFamily: "## Popover family (Popover, Menu, Select open state)\nMachine: popoverMachine — states open | closed.\nRule: Reuse this chart. Never create selectOpenMachine / menuOpenMachine forks.";
+    readonly popoverFamily: "## Popover family (Popover, Menu, Select, Combobox, Tooltip open state)\nMachine: popoverMachine — states open | closed.\nRule: Reuse this chart. Never create selectOpenMachine / menuOpenMachine / comboboxOpenMachine / tooltipOpenMachine forks.\nCombobox: query + highlight stay React-local; open/closed must still be popoverMachine.\nTooltip: openDelay / closeDelay / touchDuration stay React-local; open/closed must still be popoverMachine.";
     readonly toggle: "## Switch / Checkbox\nMachine: toggleMachine — checked | unchecked. Events: TOGGLE, CHECK, UNCHECK.\nRule: Hidden input stays in sync with snapshot for forms.";
+    readonly slider: "## Slider statechart\nMachine: sliderMachine — idle | dragging; value/min/max/step in context.\nEvents: SET_VALUE, STEP, POINTER_DOWN, POINTER_UP, HOME, END.\nRule: Disabled blocks SET_VALUE / drag; project idle vs dragging on data-aeon-state.";
+    readonly contentRegion: "## Content region statechart\nMachine: contentRegionMachine — idle → pending → (empty | error | ready) → loadingMore | success.\nEvents: LOAD, RESOLVE, REJECT, RETRY, LOAD_MORE, MORE_DONE, SUCCEED, RESET.\nRule: Every stable state has a slot. Pair with Async for fetch; do not hide empty/error behind a spinner.";
+    readonly toast: "## Toast item statechart\nMachine: toastMachine — hidden | visible. Events: SHOW, HIDE, DISMISS.\nRule: Provider list orchestration may use React; each toast item uses the machine.";
+    readonly stickyBar: "## StickyBar statechart\nMachine: stickyBarMachine — floating | docked | collapsed | hidden.\nEvents: DOCK, FLOAT, COLLAPSE, EXPAND, HIDE, SHOW, SET_OFFSET.\nRule: DOM scope is bar (bar anatomy zones). Do not invent a parallel sticky useState.";
 };
 /** Checkout-form example used on the landing "AI playground" proof. */
 declare const GENERATIVE_UI_EXAMPLE: {
@@ -247,6 +295,8 @@ type AgentEventBridge = ReturnType<typeof createAgentEventBridge>;
  * 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
+ *
+ * Components are derived from `componentSchemas` — do not hand-maintain a parallel list.
  */
 type RegistryEntry = {
     id: string;
@@ -259,29 +309,24 @@ type RegistryEntry = {
 };
 declare const REGISTRY_BASE: "https://aeon-ui.com/registry";
 declare const registryCatalog: {
-    readonly $id: "https://aeon-ui.com/registry/catalog.json";
-    readonly version: "0.1.0";
-    readonly principle: "UI = f(state)";
-    readonly description: "Lightweight runtime registry — fetch Aeon component schemas and state-tree JSON on demand instead of bundling every primitive.";
-    readonly endpoints: {
-        readonly catalog: "https://aeon-ui.com/registry/catalog.json";
-        readonly component: "https://aeon-ui.com/registry/components/{id}.json";
-        readonly machine: "https://aeon-ui.com/registry/machines/{id}.json";
+    $id: string;
+    version: string;
+    principle: string;
+    description: string;
+    endpoints: {
+        catalog: string;
+        component: string;
+        machine: string;
     };
-    readonly components: {
-        id: string;
-        title: string;
-        scope: string;
-        schemaUrl: string;
-        machineUrl: string;
-        runtime: string;
-        description: string;
-    }[];
-    readonly client: {
-        readonly fetchCatalog: "fetch('https://aeon-ui.com/registry/catalog.json').then(r => r.json())";
-        readonly fetchComponent: "id => fetch(`https://aeon-ui.com/registry/components/${id}.json`).then(r => r.json())";
-        readonly fetchMachine: "id => fetch(`https://aeon-ui.com/registry/machines/${id}.json`).then(r => r.json())";
+    components: RegistryEntry[];
+    client: {
+        fetchCatalog: string;
+        fetchComponent: string;
+        fetchMachine: string;
     };
 };
 
-export { AEON_SYSTEM_PROMPT, type AeonMachineSchema, type AeonSnapshotSchema, type AeonStateTreeNode, type AgentBridgeOptions, type AgentEventBridge, type AgentEventMap, type AgentStreamEvent, CURSOR_RULES_SNIPPET, type ComponentSchemaId, GENERATIVE_UI_EXAMPLE, type JsonSchema, REGISTRY_BASE, type RegistryEntry, STATECHART_PROMPTS, aeonInitialAgentContext, aeonSnapshotSchema, aeonToPrompt, aeonToSchema, catalog, componentSchema, componentSchemas, createAgentEventBridge, registryCatalog };
+/** Map component schema `machine` export names → registry/machines/{id}.json ids. */
+declare function machineRegistryId(machine: string | null | undefined): string | undefined;
+
+export { AEON_SYSTEM_PROMPT, type AeonMachineSchema, type AeonSnapshotSchema, type AeonStateTreeNode, type AgentBridgeOptions, type AgentEventBridge, type AgentEventMap, type AgentStreamEvent, CURSOR_RULES_SNIPPET, type ComponentSchemaId, GENERATIVE_UI_EXAMPLE, type JsonSchema, REGISTRY_BASE, type RegistryEntry, STATECHART_PROMPTS, aeonInitialAgentContext, aeonSnapshotSchema, aeonToPrompt, aeonToSchema, catalog, componentSchema, componentSchemas, createAgentEventBridge, machineRegistryId, registryCatalog };