aeon-ui-engine 1.0.2 → 1.1.0

package/scripts/vite-aliases.mjs

@@ -0,0 +1,179 @@
+/**
+ * Vite + TypeScript wiring for apps that install `aeon-ui-engine` from npm.
+ *
+ * @example
+ * // vite.config.ts — one call, done
+ * import { aeonUiVitePlugin } from 'aeon-ui-engine/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [react(), aeonUiVitePlugin()],
+ * })
+ *
+ * // tsconfig.json — spread the base config
+ * {
+ *   "extends": "aeon-ui-engine/tsconfig",
+ *   "compilerOptions": { "jsx": "react-jsx" }
+ * }
+ */
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+
+/** Absolute path to `aeon-ui-engine/packages` (npm install or monorepo checkout). */
+export function resolveAeonPackagesRoot(opts = {}) {
+  if (opts.packagesRoot) return path.resolve(opts.packagesRoot)
+  if (process.env.AEON_UI_ROOT) {
+    return path.join(path.resolve(process.env.AEON_UI_ROOT), 'packages')
+  }
+  try {
+    const require = createRequire(import.meta.url)
+    const engineRoot = path.dirname(require.resolve('aeon-ui-engine/package.json'))
+    return path.join(engineRoot, 'packages')
+  } catch {
+    return path.resolve(scriptDir, '../packages')
+  }
+}
+
+/** Vite `resolve.alias` entries — `@aeon-ui/*` is not published separately. */
+export function aeonUiViteAliases(opts = {}) {
+  const packages = resolveAeonPackagesRoot(opts)
+  const extra = opts.extraAliases ?? []
+
+  return [
+    ...extra,
+    {
+      find: 'aeon-ui-engine/aeon.css',
+      replacement: path.join(packages, 'panda/aeon.css'),
+    },
+    {
+      find: '@aeon-ui/panda/styles.css',
+      replacement: path.join(packages, 'panda/styled-system/styles.css'),
+    },
+    {
+      find: '@aeon-ui/panda/theme-runtime.css',
+      replacement: path.join(packages, 'panda/theme-runtime.css'),
+    },
+    {
+      find: '@aeon-ui/panda/scrollbars.css',
+      replacement: path.join(packages, 'panda/src/theme/scrollbars.css'),
+    },
+    {
+      find: '@aeon-ui/panda/chrome.css',
+      replacement: path.join(packages, 'panda/src/theme/chrome.css'),
+    },
+    {
+      find: '@aeon-ui/panda/styled-system/css',
+      replacement: path.join(packages, 'panda/styled-system/css/index.mjs'),
+    },
+    {
+      find: '@aeon-ui/panda/styled-system/recipes',
+      replacement: path.join(packages, 'panda/styled-system/recipes/index.mjs'),
+    },
+    {
+      find: '@aeon-ui/panda/themes',
+      replacement: path.join(packages, 'panda/src/theme/index.ts'),
+    },
+    {
+      find: '@aeon-ui/ui/styles.css',
+      replacement: path.join(packages, 'ui/src/styles.css'),
+    },
+    {
+      find: '@aeon-ui/surface/surface.css',
+      replacement: path.join(packages, 'surface/surface.css'),
+    },
+    {
+      find: '@aeon-ui/core/theme-transition.css',
+      replacement: path.join(packages, 'core/theme-transition.css'),
+    },
+    { find: '@aeon-ui/surface', replacement: path.join(packages, 'surface/src/index.ts') },
+    { find: '@aeon-ui/core', replacement: path.join(packages, 'core/src/index.ts') },
+    { find: '@aeon-ui/primitives', replacement: path.join(packages, 'primitives/src/index.ts') },
+    { find: '@aeon-ui/react', replacement: path.join(packages, 'react/src/index.ts') },
+    { find: '@aeon-ui/ui', replacement: path.join(packages, 'ui/src/index.ts') },
+    { find: '@aeon-ui/schemas', replacement: path.join(packages, 'schemas/src/index.ts') },
+    { find: '@aeon-ui/panda', replacement: path.join(packages, 'panda') },
+  ]
+}
+
+/** Recommended Vite `optimizeDeps` for Aeon + XState apps. */
+export function aeonUiOptimizeDeps(opts = {}) {
+  const excludeWorkspace = opts.excludeWorkspace ?? true
+  return {
+    include: [
+      'react',
+      'react-dom',
+      '@xstate/react',
+      'xstate',
+      ...(opts.include ?? []),
+    ],
+    exclude: excludeWorkspace
+      ? [
+          '@aeon-ui/core',
+          '@aeon-ui/primitives',
+          '@aeon-ui/react',
+          '@aeon-ui/ui',
+          '@aeon-ui/panda/styled-system/css',
+          '@aeon-ui/panda/styled-system/recipes',
+          ...(opts.exclude ?? []),
+        ]
+      : (opts.exclude ?? []),
+  }
+}
+
+/**
+ * `compilerOptions.paths` fragment for a consumer tsconfig.
+ * Paths are relative to the app tsconfig file location.
+ */
+export function aeonUiTsconfigPaths(opts = {}) {
+  const prefix = opts.prefix ?? '../node_modules/aeon-ui-engine/packages'
+  return {
+    '@aeon-ui/core': [`${prefix}/core/src/index.ts`],
+    '@aeon-ui/primitives': [`${prefix}/primitives/src/index.ts`],
+    '@aeon-ui/react': [`${prefix}/react/src/index.ts`],
+    '@aeon-ui/ui': [`${prefix}/ui/src/index.ts`],
+    '@aeon-ui/surface': [`${prefix}/surface/src/index.ts`],
+    '@aeon-ui/panda/styled-system/css': [`${prefix}/panda/styled-system/css/index.d.ts`],
+    '@aeon-ui/panda/styled-system/recipes': [`${prefix}/panda/styled-system/recipes/index.d.ts`],
+  }
+}
+
+/**
+ * All-in-one Vite plugin — aliases + optimizeDeps in one call.
+ *
+ * @example
+ * import { aeonUiVitePlugin } from 'aeon-ui-engine/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [react(), aeonUiVitePlugin()],
+ * })
+ */
+export function aeonUiVitePlugin(opts = {}) {
+  const alias = aeonUiViteAliases(opts)
+  const optimizeDeps = aeonUiOptimizeDeps(opts)
+
+  return {
+    name: 'aeon-ui',
+    enforce: 'pre',
+    config(userConfig) {
+      return {
+        resolve: {
+          alias: [...(userConfig.resolve?.alias ?? []), ...alias],
+        },
+        optimizeDeps: {
+          ...userConfig.optimizeDeps,
+          ...optimizeDeps,
+          include: [
+            ...(optimizeDeps.include ?? []),
+            ...(userConfig.optimizeDeps?.include ?? []),
+          ],
+          exclude: [
+            ...(optimizeDeps.exclude ?? []),
+            ...(userConfig.optimizeDeps?.exclude ?? []),
+          ],
+        },
+      }
+    },
+  }
+}

package/scripts/xstate-introspect.mjs

@@ -0,0 +1,68 @@
+import { asyncMachine } from '../packages/primitives/dist/index.js';
+import { createActor, getStateNodes } from 'xstate';
+import { getStateNodes as graphGetStateNodes } from 'xstate/graph';
+
+const machine = asyncMachine;
+
+console.log('=== machine keys ===');
+console.log(Object.keys(machine).sort().join(', '));
+
+console.log('\n=== machine.states keys ===');
+console.log(Object.keys(machine.states));
+
+const idle = machine.states.idle;
+console.log('\n=== idle state node keys ===');
+console.log(Object.keys(idle).sort().join(', '));
+
+console.log('\n=== idle.events ===');
+console.log(idle.events);
+
+console.log('\n=== idle.config.on ===');
+console.log(idle.config?.on ?? idle.config);
+
+const actor = createActor(machine);
+actor.start();
+const snap = actor.getSnapshot();
+
+console.log('\n=== snapshot.value ===');
+console.log(snap.value);
+
+console.log("\n=== snapshot.can({ type: 'FETCH' }) ===");
+console.log(snap.can({ type: 'FETCH' }));
+
+console.log('\n=== snapshot keys (sorted) ===');
+console.log(Object.keys(snap).sort().join(', '));
+
+if (typeof snap.getNextEvents === 'function') {
+  console.log('\n=== snap.getNextEvents() ===');
+  console.log(snap.getNextEvents());
+}
+
+// _nodes internal?
+if (snap._nodes) {
+  console.log('\n=== snap._nodes ids ===');
+  console.log([...snap._nodes].map((n) => n.id));
+}
+
+const nodes = getStateNodes(machine.root, snap.value);
+console.log('\n=== getStateNodes(root, value) ===');
+console.log(nodes.map((n) => n.id));
+console.log('active node .events:', nodes.map((n) => ({ id: n.id, events: n.events })));
+
+const allNodes = graphGetStateNodes(machine);
+console.log('\n=== graph.getStateNodes(machine) ===');
+for (const n of allNodes) {
+  console.log({ id: n.id, events: n.events, on: n.config?.on ? Object.keys(n.config.on) : [] });
+}
+
+const eventTypes = ['FETCH', 'RESOLVE', 'REJECT', 'RESET', 'STALE', 'REFRESH'];
+console.log('\n=== idle snapshot: can() per event ===');
+for (const type of eventTypes) {
+  const ev =
+    type === 'RESOLVE'
+      ? { type, data: { x: 1 } }
+      : type === 'REJECT'
+        ? { type, error: 'e' }
+        : { type };
+  console.log(type, snap.can(ev));
+}

package/.changeset/README.md

@@ -1,23 +0,0 @@
-# Changesets
-
-This monorepo uses [Changesets](https://github.com/changesets/changesets) to version and publish `@aeon-ui/*` packages together.
-
-## Add a changeset
-
-After a meaningful change:
-
-```bash
-pnpm changeset
-```
-
-Choose affected packages (usually all five public packages) and bump type (`patch` / `minor` / `major`).
-
-## Release flow (maintainers)
-
-```bash
-pnpm version-packages   # apply changesets → bump versions + CHANGELOGs
-pnpm build
-pnpm release            # publish to npm (requires npm login + scope access)
-```
-
-See [PUBLISHING.md](../PUBLISHING.md) for manual publish order and first-time setup.

package/.changeset/combobox-and-changesets.md

@@ -1,9 +0,0 @@
----
-"@aeon-ui/core": minor
-"@aeon-ui/primitives": minor
-"@aeon-ui/react": minor
-"@aeon-ui/panda": minor
-"@aeon-ui/ui": minor
----
-
-Add **Combobox** (typeahead listbox extending Select) and **Changesets** for fixed-version npm releases before 0.1.0.

package/.changeset/config.json

@@ -1,31 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [
-    ["aeon-ui-engine"],
-    [
-      "@aeon-ui/core",
-      "@aeon-ui/primitives",
-      "@aeon-ui/react",
-      "@aeon-ui/panda",
-      "@aeon-ui/ui",
-      "@aeon-ui/vue",
-      "@aeon-ui/solid",
-      "@aeon-ui/svelte"
-    ],
-    [
-      "@aeon-ui/signal",
-      "@aeon-ui/geometry",
-      "@aeon-ui/surface",
-      "@aeon-ui/scene",
-      "@aeon-ui/react-scene",
-      "@aeon-ui/site"
-    ]
-  ],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": ["@aeon-ui/demo"]
-}

package/.changeset/framework-adapters.md

@@ -1,12 +0,0 @@
----
-"@aeon-ui/core": minor
-"@aeon-ui/primitives": minor
-"@aeon-ui/react": minor
-"@aeon-ui/panda": minor
-"@aeon-ui/ui": minor
-"@aeon-ui/vue": minor
-"@aeon-ui/solid": minor
-"@aeon-ui/svelte": minor
----
-
-Add Vue, Solid, and Svelte adapter packages (`useAeonMachine` + reference Switch port). Document publish and framework roadmap.

package/.changeset/scene-3d.md

@@ -1,6 +0,0 @@
----
-"@aeon-ui/scene": minor
-"@aeon-ui/react-scene": minor
----
-
-Add CSS 3D scene construction: `@aeon-ui/scene` transforms, `SceneStage` / `SceneLayer` / `ScenePlane` / `SceneSlot`, and demo alley preview.

package/.changeset/scene-plane.md

@@ -1,8 +0,0 @@
----
-"@aeon-ui/signal": minor
-"@aeon-ui/geometry": minor
-"@aeon-ui/surface": minor
-"@aeon-ui/react-scene": minor
----
-
-Add optional Scene plane: signal, geometry, procedural surface materials (pavement, kraft, brick), react-scene bindings, and SCENE.md.

package/.changeset/site-og.md

@@ -1,5 +0,0 @@
----
-"@aeon-ui/site": minor
----
-
-Add `@aeon-ui/site` Open Graph meta helpers for marketing apps and demos.

package/.cursor/rules/aeon-ui.mdc

@@ -1,22 +0,0 @@
----
-description: Aeon UI conventions — read AGENTS.md before editing this repo
-alwaysApply: true
----
-
-# Aeon UI (agent rules)
-
-**Read [AGENTS.md](../../AGENTS.md) before any change.** Full map: [docs/INDEX.md](../../docs/INDEX.md).
-
-## Must follow
-
-- **UI = f(state)** — project snapshots to `data-aeon-scope`, `data-aeon-part`, `data-aeon-state` via `partAttrs` from `@aeon-ui/core`.
-- **Machine truth:** [docs/MACHINES.md](../../docs/MACHINES.md) — Button uses `status` prop; Select/Menu/Popover share `popoverMachine`; Combobox/Tooltip use React state; Scroll uses `getScrollSnapshot`.
-- **New components:** [docs/COMPONENT_CHECKLIST.md](../../docs/COMPONENT_CHECKLIST.md) (all steps).
-- **Panda changes:** run `pnpm codegen` from repo root.
-- **Imports:** `.js` extension in TypeScript relative imports.
-
-## Do not
-
-- Duplicate state in `useState` and XState for the same concern.
-- Fork duplicate open/closed machines (use `popoverMachine` / `dialogMachine`).
-- Hand-edit `packages/panda/styled-system/` (generated).

package/ACCESSIBILITY.md

@@ -1,32 +0,0 @@
-# Accessibility
-
-Aeon targets **WCAG-minded** behavior on headless parts. Styled layers must not remove semantics.
-
-## Patterns in place
-
-| Component | Roles / ARIA |
-|-----------|----------------|
-| Dialog | `role="dialog"`, `aria-modal`, `aria-labelledby` / `aria-describedby`, Escape |
-| Avatar | `img` + `hidden` when loaded; fallback `hidden` when image shown; pass `alt` on `Avatar.Image` |
-| Menu | `aria-haspopup="menu"`, `role="menu"`, `role="menuitem"`, Escape, outside click |
-| Popover | `aria-expanded`, `role="dialog"` (non-modal) |
-| Tooltip | `aria-describedby`, `role="tooltip"` |
-| Toast | `role="status"`, `aria-live="polite"` |
-| Select | `aria-haspopup="listbox"`, `aria-expanded`, `aria-activedescendant`, arrow keys + Enter |
-| Dialog | focus trap + body scroll lock when open via `Dialog.Portal` |
-| Combobox | `role="combobox"`, `aria-autocomplete="list"`, `aria-activedescendant`, arrow keys + Enter |
-| Switch / Checkbox | native input + label association |
-
-## Focus
-
-- `@aeon-ui/panda` `chrome.css`: focus rings on **keyboard** (`:focus-visible`) only.
-- Selected / pressed / open states use surface tint, not conflated with focus.
-
-## Your checklist when adopting
-
-1. Every `Dialog` includes `Title` (and `Description` when copy is long).
-2. Menu items are `<button type="button">`, not `<div onClick>`.
-3. Custom colors meet contrast on `data-aeon-state` variants you add.
-4. Async regions expose status text in `Readout`, not color alone.
-
-Report gaps in GitHub issues with expected keyboard / screen reader steps.

package/AGENTS.md

@@ -1,226 +0,0 @@
-# Aeon UI — agent instructions
-
-**Audience:** Cursor, Copilot, Claude, or any coding agent working in this repo.  
-**Goal:** Follow Aeon conventions without guessing. When in doubt, read the linked doc — do not invent patterns.
-
----
-
-## North star (memorize this)
-
-**State is defined first. UI represents the totality of that definition.**
-
-- Behavior → XState snapshot (or explicit derived state like Scroll).
-- DOM → `data-aeon-scope`, `data-aeon-part`, `data-aeon-state` from `@aeon-ui/core`.
-- Style → Panda slot recipes keyed on those attributes.
-- **UI = f(snapshot)** — not f(ad hoc React flags).
-
-Source: [PHILOSOPHY.md](./PHILOSOPHY.md) · Code: `packages/core/src/philosophy.ts`
-
----
-
-## Read order (first time in repo)
-
-| Order | File | Why |
-|-------|------|-----|
-| 1 | This file (`AGENTS.md`) | Rules, maps, workflows |
-| 2 | [docs/MACHINES.md](./docs/MACHINES.md) | **Which components use machines vs props** — avoid wrong wiring |
-| 3 | [STATES.md](./STATES.md) | Attribute contract, async/button/field/scroll |
-| 4 | [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Packages, layers, build |
-| 5 | [docs/COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md) | Adding or changing a component |
-| 6 | [COMPONENTS.md](./COMPONENTS.md) | Shipped catalog |
-| 7 | [INTEGRATION.md](./INTEGRATION.md) | Headless / Panda / styled |
-| 8 | [FRAMEWORKS.md](./FRAMEWORKS.md) | Vue / Solid / Svelte porting |
-| — | [docs/LAYOUT_COORDINATES.md](./docs/LAYOUT_COORDINATES.md) | **Responsive play surfaces — norm coords + layout modes** |
-| — | [docs/API_PATTERNS.md](./docs/API_PATTERNS.md) | Copy-paste snippets |
-
-Scene plane (optional): [SCENE.md](./SCENE.md). Publishing: [PUBLISHING.md](./PUBLISHING.md). A11y: [ACCESSIBILITY.md](./ACCESSIBILITY.md).
-
-Full index: [docs/INDEX.md](./docs/INDEX.md).
-
----
-
-## Non-negotiable rules
-
-1. **Do not add `useState` for open/checked/lifecycle** on components that already have a machine in `@aeon-ui/primitives` unless you are intentionally replacing the headless layer (rare).
-2. **Button `status` is a prop projection**, not the machine. `buttonLifecycleMachine` exists for demos and app logic via `useAeonMachine`; headless `Button.Root` sets `data-aeon-state` from the `status` prop. Wire chart → prop yourself when needed.
-3. **Select** shares `popoverMachine` (do not fork another open/closed chart). **Combobox** and **Tooltip** still use React state — do not add duplicate floating-surface machines without [COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md).
-4. **Scroll** uses `getScrollSnapshot()` from core — **no** XState machine.
-5. **Every new scope** needs anatomy in `packages/core/src/anatomy.ts`, headless in `packages/react/src/<name>/`, recipe in `packages/panda/src/recipes/`, styled in `packages/ui/src/<name>.tsx`, demo in `apps/demo`.
-6. **After any Panda recipe or token change**, run from repo root: `pnpm codegen` (then build if verifying).
-7. **ESM**: TypeScript sources use **`.js` extensions** in relative imports (`import { x } from './foo.js'`).
-8. **Panda package is private** — apps consume CSS via `@aeon-ui/ui` or direct `@aeon-ui/panda/styles.css` imports; do not publish `@aeon-ui/panda` as a separate product without maintainer intent.
-9. **Totality**: If the machine lists N stable states, the demo must show all N (e.g. `Async.Track` segments).
-10. **Do not style with ad hoc class names for state** in product code inside this repo — use `data-aeon-state` + recipes or documented `globalCss`.
-
----
-
-## Decision tree: which package to edit?
-
-```
-Changing behavior / transitions?
-  └─> packages/primitives/src/machines/<topic>.ts
-      └─> Update apps/demo/src/aeonDiagrams.ts if diagram exists
-
-Changing DOM contract / part names?
-  └─> packages/core/src/anatomy.ts
-  └─> packages/core/src/attrs.ts (partAttrs, stateToAttr)
-
-Changing React API / a11y / events?
-  └─> packages/react/src/<component>/
-
-Changing default look?
-  └─> packages/panda/src/recipes/<component>.ts
-  └─> pnpm codegen
-
-Shipping styled export?
-  └─> packages/ui/src/<component>.tsx
-
-Showing behavior to humans?
-  └─> apps/demo/src/ (playground sections)
-```
-
----
-
-## Decision tree: which layer should the user import?
-
-```
-Need full Aeon styling + themes?
-  └─> @aeon-ui/ui (+ panda CSS imports — see INTEGRATION.md)
-
-Custom design system, same behavior?
-  └─> @aeon-ui/react + CSS on [data-aeon-*]
-
-Own XState app machines?
-  └─> useAeonMachine from @aeon-ui/react + primitives machines or app machines
-
-Only tokens/recipes?
-  └─> @aeon-ui/panda/styled-system/recipes (workspace/private; codegen required)
-```
-
----
-
-## Repo map (high signal paths)
-
-| Path | Contents |
-|------|----------|
-| `packages/core/src/anatomy.ts` | All `*Anatomy` scopes and part keys |
-| `packages/core/src/attrs.ts` | `partAttrs`, `scopeAttrs`, `stateToAttr` |
-| `packages/primitives/src/machines/` | XState machines |
-| `packages/react/src/<component>/` | Headless compound components |
-| `packages/react/src/hooks/use-aeon-machine.ts` | `useAeonMachine` wrapper |
-| `packages/panda/panda.config.ts` | Recipe registration, `aeon*` conditions |
-| `packages/panda/src/recipes/` | Slot + plain recipes |
-| `packages/ui/src/*.tsx` | Styled wrappers (`aeon*` + `cn`) |
-| `apps/demo/src/` | Marketing + playgrounds |
-| `apps/demo/src/aeonDiagrams.ts` | Mermaid ↔ machines (keep in sync) |
-
-Detailed map: [docs/FILE_MAP.md](./docs/FILE_MAP.md).
-
----
-
-## Naming conventions (copy exactly)
-
-| Artifact | Pattern | Example |
-|----------|---------|---------|
-| npm package | `@aeon-ui/<name>` | `@aeon-ui/react` |
-| Anatomy export | `{scope}Anatomy` | `asyncAnatomy` |
-| Scope string | lowercase family | `'async'`, `'button'` |
-| Machine export | `{name}Machine` or `create{Name}Machine` | `fieldMachine`, `createAsyncMachine` |
-| Panda recipe key | `aeon{Pascal}` | `aeonAsync`, `aeonButton` |
-| Recipe export | `{name}Recipe` | `asyncRegionRecipe` |
-| React folder | `packages/react/src/<component>/` | `async/`, `dialog/` |
-| Styled file | `packages/ui/src/<component>.tsx` | `button.tsx` |
-| Compound parts | `Root`, `Trigger`, `Content`, … | `Dialog.Root` |
-| Data attrs | `data-aeon-scope`, `data-aeon-part`, `data-aeon-state` | always via `partAttrs` |
-
----
-
-## Common workflows
-
-### Fix a styling bug on a component
-
-1. Inspect DOM for `data-aeon-scope`, `data-aeon-part`, `data-aeon-state`.
-2. Find slot recipe: `packages/panda/src/recipes/<component>.ts`.
-3. Check conditions in `packages/panda/panda.config.ts` (`aeonOpen`, `aeonPending`, …).
-4. `pnpm codegen` → verify in `apps/demo`.
-
-### Add a new primitive component
-
-Follow **[docs/COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md)** — all 10 steps. Do not skip anatomy or demo rail.
-
-### Port to Vue / Solid / Svelte
-
-Follow **[FRAMEWORKS.md](./FRAMEWORKS.md)** — copy React `partAttrs` usage; use `useAeonMachine` equivalent per adapter.
-
-### Change async / field / button lifecycle
-
-1. Machine in `packages/primitives/src/machines/`.
-2. React projection in `packages/react/src/<async|field|button>/`.
-3. Mermaid in `apps/demo/src/aeonDiagrams.ts`.
-4. STATES.md section if user-facing contract changes.
-
----
-
-## Machine vs implementation (cheat sheet)
-
-See full table and events in **[docs/MACHINES.md](./docs/MACHINES.md)**.
-
-| Component | Runtime driver |
-|-----------|----------------|
-| Dialog, Tabs, Accordion, Switch, Checkbox | `useAeonMachine` + primitives |
-| Async, Field | `useAeonMachine` + primitives |
-| Menu, Popover | `popoverMachine` |
-| Toast (item) | `toastMachine` |
-| Button | **`status` prop** (machine optional in app) |
-| Select, Combobox, Tooltip | **React `useState`** |
-| Scroll | **`getScrollSnapshot()`** |
-
----
-
-## Build & verify
-
-```bash
-pnpm install          # from repo root
-pnpm codegen          # after panda changes
-pnpm dev              # demo app
-pnpm build            # codegen + all packages
-pnpm typecheck        # all packages
-```
-
-Node ≥ 20. Package manager: **pnpm** (workspace: `packages/*`, `apps/*`).
-
----
-
-## What not to do
-
-- Do not duplicate state in React and XState for the same concern.
-- Do not add Tailwind inside `@aeon-ui/ui` — Panda recipes only.
-- Do not export unstyled components from `@aeon-ui/ui`.
-- Do not change `data-aeon-*` names without updating panda conditions and STATES.md.
-- Do not assume COMPONENTS.md “Machine” column is accurate for Select/Combobox — see [docs/MACHINES.md](./docs/MACHINES.md).
-
----
-
-## Package READMEs (API entry points)
-
-| Package | Doc |
-|---------|-----|
-| `@aeon-ui/core` | [packages/core/README.md](./packages/core/README.md) |
-| `@aeon-ui/primitives` | [packages/primitives/README.md](./packages/primitives/README.md) |
-| `@aeon-ui/react` | [packages/react/README.md](./packages/react/README.md) |
-| `@aeon-ui/panda` | [packages/panda/README.md](./packages/panda/README.md) |
-| `@aeon-ui/ui` | [packages/ui/README.md](./packages/ui/README.md) |
-
----
-
-## Glossary
-
-[docs/GLOSSARY.md](./docs/GLOSSARY.md)
-
----
-
-## Human docs (same truth)
-
-[README.md](./README.md) · [PHILOSOPHY.md](./PHILOSOPHY.md) · [STATES.md](./STATES.md) · [COMPONENTS.md](./COMPONENTS.md)
-
-When agents and human docs disagree, **source code wins** — then fix the doc in the same PR.

package/COMPONENTS.md

@@ -1,41 +0,0 @@
-# Component catalog
-
-Status key: **Headless** (`@aeon-ui/react`) · **Styled** (`@aeon-ui/ui`) · **State driver** (how runtime state is chosen)
-
-**Agents:** authoritative wiring table → [docs/MACHINES.md](./docs/MACHINES.md).
-
-| Component | Headless | Styled | State driver | Stable states / notes |
-|-----------|----------|--------|--------------|------------------------|
-| Button | ✓ | ✓ | **`status` prop** (machine optional in app) | idle, pending, success, failure, disabled |
-| Switch | ✓ | ✓ | `toggleMachine` | checked / unchecked |
-| Checkbox | ✓ | ✓ | `toggleMachine` | checked / unchecked |
-| Dialog | ✓ | ✓ | `dialogMachine` | open / closed |
-| Tabs | ✓ | ✓ | `tabsMachine` | per-tab selected |
-| Accordion | ✓ | ✓ | `accordionMachine` | per-item open / closed |
-| Select | ✓ | ✓ | `popoverMachine` | open / closed listbox; keyboard highlight in React |
-| Combobox | ✓ | ✓ | **React state** | open / closed + filter |
-| Async | ✓ | ✓ | `createAsyncMachine` | idle, loading, success, failure, empty + stale |
-| Field | ✓ | ✓ | `fieldMachine` (parallel) | interaction × validation × submission; `Control` + `Textarea` |
-| Scroll | ✓ | ✓ | **`getScrollSnapshot`** | overflow axis + edge position |
-| Menu | ✓ | ✓ | `popoverMachine` | open / closed |
-| Popover | ✓ | ✓ | `popoverMachine` | open / closed |
-| Tooltip | ✓ | ✓ | **React state** | open / closed; tap-to-toggle on touch |
-| Toast | ✓ | ✓ | `toastMachine` | hidden / visible |
-| Avatar | ✓ | — | **React state** | idle / loading / loaded / error |
-| Separator | ✓ | ✓ | **static** | horizontal / vertical orientation |
-| Progress | ✓ | ✓ | **props** | idle / loading / complete |
-| RadioGroup | ✓ | ✓ | `tabsMachine` | one selected item |
-| Slider | ✓ | ✓ | `sliderMachine` | idle / dragging + value |
-| PinInput | ✓ | ✓ | **React state** | idle / complete |
-
-## Planned (not shipped)
-
-Number Input, Date Picker, Tree View, File Upload, Carousel, Toggle Group — tracked as the catalog grows; prefer explicit machines per component.
-
-## Choosing a layer
-
-- **App logic & tests** → define or extend machines in `@aeon-ui/primitives`, or app-level XState.
-- **Custom design system** → `@aeon-ui/react` + your CSS targeting `data-aeon-*`.
-- **Ship fast with Aeon look** → `@aeon-ui/ui` + `@aeon-ui/panda` themes.
-
-See [INTEGRATION.md](./INTEGRATION.md) for styling without Panda.