aeon-ui-engine 1.0.0

package/docs/INDEX.md

@@ -0,0 +1,53 @@
+# Aeon UI documentation index
+
+Use this map to pick the right doc. **Agents should start at [AGENTS.md](../AGENTS.md).**
+
+## For coding agents (LLMs)
+
+| Document | Use when |
+|----------|----------|
+| [AGENTS.md](../AGENTS.md) | **Start here** — rules, workflows, naming |
+| [MACHINES.md](./MACHINES.md) | Machine vs prop vs `useState`; events |
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | Monorepo layout, layers, dependencies |
+| [COMPONENT_CHECKLIST.md](./COMPONENT_CHECKLIST.md) | Add or change a component (ordered steps) |
+| [FILE_MAP.md](./FILE_MAP.md) | Where to find every artifact |
+| [GLOSSARY.md](./GLOSSARY.md) | Terms (anatomy, snapshot, totality, …) |
+| [LAYOUT_COORDINATES.md](./LAYOUT_COORDINATES.md) | Normalized plane, split/stack/overlay, game layouts |
+| [API_PATTERNS.md](./API_PATTERNS.md) | Copy-paste snippets by layer |
+
+## Philosophy & contracts
+
+| Document | Use when |
+|----------|----------|
+| [PHILOSOPHY.md](../PHILOSOPHY.md) | Why statecharts; north star |
+| [STATES.md](../STATES.md) | `data-aeon-*`; async, button, field, scroll |
+| [COMPONENTS.md](../COMPONENTS.md) | What ships vs planned |
+
+## Integration & shipping
+
+| Document | Use when |
+|----------|----------|
+| [INTEGRATION.md](../INTEGRATION.md) | Headless vs Panda vs `@aeon-ui/ui` |
+| [MIGRATION_FROM_ARK.md](./MIGRATION_FROM_ARK.md) | Replace `@ark-ui/react` with `@aeon-ui/react` (Vite, Next.js) |
+| [VITE_CONSUMER.md](./VITE_CONSUMER.md) | Vite aliases + local clone |
+| [FRAMEWORKS.md](../FRAMEWORKS.md) | Vue / Solid / Svelte adapters |
+| [ACCESSIBILITY.md](../ACCESSIBILITY.md) | Roles, focus, keyboard |
+| [PUBLISHING.md](../PUBLISHING.md) | Changesets, npm release |
+| [SCENE.md](../SCENE.md) | Scene plane (signal, geometry, surface) |
+
+## Package READMEs
+
+| Package | README |
+|---------|--------|
+| `@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) |
+| Scene / adapters | `packages/signal`, `geometry`, `surface`, `scene`, `react-scene`, `vue`, `solid`, `svelte` |
+
+## Live reference
+
+- Demo app: `apps/demo` — run `pnpm dev`
+- Diagrams: `apps/demo/src/aeonDiagrams.ts` (Mermaid ↔ machines)
+- Ground truth config: `packages/panda/panda.config.ts`

package/docs/LAYOUT_COORDINATES.md

@@ -0,0 +1,178 @@
+# Layout coordinates (responsive play surfaces)
+
+**Problem:** Games and rich apps need the same **logical** interaction space on desktop (split columns) and mobile (stacked lanes or overlays). CSS alone does not give you stable pointer math when regions move.
+
+**Aeon answer:** Separate three concerns — same pattern as `UI = f(state)`:
+
+| Layer | Owns | Package |
+|-------|------|---------|
+| **Behavior** | Statecharts, rounds, bets | `@aeon-ui/primitives` + app |
+| **Composition** | *Where* regions sit (split / stack / overlay) | CSS + `ResponsiveLayoutSpec` |
+| **Coordinates** | *Where* the user points inside a region | `@aeon-ui/core` `layout` module |
+
+Pointer logic uses a **normalized plane** (0–100 per axis) inside a measured `DOMRect`, not raw pixels.
+
+---
+
+## North star
+
+**Layout mode is explicit. Coordinates are normalized. CSS projects mode to pixels.**
+
+- `data-aeon-layout-mode="compact" | "wide"`
+- `data-aeon-layout-composition="split" | "stack" | "overlay"`
+- Anatomy: `playSurfaceAnatomy` → `mat`, `table`, `dice`, `bank`
+
+Agents: [AGENTS.md](../AGENTS.md) · API: `packages/core/src/layout.ts`
+
+---
+
+## Normalized plane
+
+```ts
+import {
+  normFromClient,
+  clientFromNorm,
+  clampNorm,
+  NORM_PLANE,
+} from '@aeon-ui/core'
+
+const rect = bowlEl.getBoundingClientRect()
+const aim = normFromClient(rect, e.clientX, e.clientY, {
+  origin: NORM_PLANE.bottomLeft, // y up — throws, dice
+  bounds: { xMin: 10, xMax: 90, yMin: 26, yMax: 74 },
+})
+```
+
+| Origin | Y direction | Use |
+|--------|-------------|-----|
+| `bottom-left` | Up | Dice throw, spatial games, scene aim |
+| `top-left` | Down | HUD-aligned hit targets (optional) |
+
+**Rule:** Pick one origin per region and keep it in the spec. Do not mix origins in one gesture pipeline.
+
+---
+
+## Responsive layout spec
+
+Declare **composition per mode**, not ad hoc media queries in TS:
+
+```ts
+import type { ResponsiveLayoutSpec } from '@aeon-ui/core'
+
+export const ceeLoPlayLayout: ResponsiveLayoutSpec = {
+  compactMq: '(max-width: 39.99rem)',
+  modes: {
+    wide: {
+      id: 'ceelo-wide',
+      composition: 'split',
+      regions: [
+        { region: 'dice', slot: 'bowl', zIndex: 1 },
+        { region: 'table', slot: 'felt', zIndex: 1 },
+      ],
+      bounds: {
+        dice: { xMin: 8, xMax: 40, yMin: 8, yMax: 92 },
+        table: { xMin: 0, xMax: 100, yMin: 0, yMax: 100 },
+      },
+    },
+    compact: {
+      id: 'ceelo-compact',
+      composition: 'stack',
+      regions: [
+        { region: 'table', slot: 'felt', zIndex: 2 },
+        { region: 'dice', slot: 'dice', zIndex: 4 },
+      ],
+      bounds: {
+        dice: { xMin: 10, xMax: 90, yMin: 26, yMax: 74 },
+      },
+    },
+  },
+}
+```
+
+| Composition | Meaning | CSS strategy |
+|-------------|---------|--------------|
+| `split` | Regions side by side | `grid-template-columns: col + 1fr` |
+| `stack` | Regions in rows | `grid-template-rows: auto + lane` |
+| `overlay` | Same cell, z-index | Single `mat` area + absolute children |
+
+**Do not** encode `overlay` until stack/split is stable — Casino-games reverted overlay for this reason.
+
+---
+
+## React
+
+```ts
+import { useLayoutMode } from '@aeon-ui/react'
+import { layoutModeAttrs, regionBoundsForMode } from '@aeon-ui/core'
+
+const { mode, composition } = useLayoutMode(ceeLoPlayLayout)
+const diceBounds = regionBoundsForMode(ceeLoPlayLayout, mode, 'dice')
+
+<div
+  data-aeon-scope="play"
+  data-aeon-part="mat"
+  {...layoutModeAttrs(mode, composition.composition)}
+>
+```
+
+Measure the **dice region** element for `normFromClient`, not the full mat, when bounds are defined per region.
+
+```ts
+import { measureElement, resolveRegionRect, normFromClient } from '@aeon-ui/core'
+
+const diceRect = resolveRegionRect(
+  measureElement(bowlRef.current),
+  measureElement(matRef.current),
+)
+```
+
+---
+
+## CSS contract
+
+1. Map `composition.regions[].slot` → `grid-template-areas` per `data-aeon-layout-mode`.
+2. Never drive throw math from `grid-template-columns` percentages — measure DOM.
+3. Optional Panda conditions:
+
+```css
+[data-aeon-scope='play'][data-aeon-layout-mode='compact'][data-aeon-layout-composition='stack'] {
+  /* stack rules */
+}
+```
+
+---
+
+## Checklist (new game surface)
+
+- [ ] List logical regions (`table`, `dice`, `bank`, …).
+- [ ] Add `ResponsiveLayoutSpec` with `wide` + `compact` compositions.
+- [ ] Add per-mode `bounds` for any region that receives drag/aim.
+- [ ] CSS: two layouts keyed on `data-aeon-layout-mode` (no overlay until tested).
+- [ ] TS: `useLayoutMode` + `normFromClient` on measured region rects.
+- [ ] Demo or story: resize across breakpoint; aim stays inside bounds.
+
+---
+
+## Relation to scene plane
+
+| Package | Role |
+|---------|------|
+| `@aeon-ui/core` `layout` | App/play surface, pointer norm, breakpoints |
+| `@aeon-ui/geometry` | Decorative scene grids, SVG, `sceneAttrs` |
+| `@aeon-ui/scene` | CSS 3D presentation |
+
+Scene coordinates are visual; **layout coordinates** are for input and game logic.
+
+---
+
+## Reference implementation
+
+[Casino-games](https://github.com/GenericCPU/Casino-games) `shared/game/dicePlayLayout.ts` and `diceAim.ts` already use this model informally (`AimBounds` = `NormRect`). Migrating to `@aeon-ui/core` keeps one API across products.
+
+---
+
+## See also
+
+- [STATES.md](../STATES.md) — scroll snapshot (derived spatial state, same idea)
+- [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
+- [packages/core/README.md](../packages/core/README.md)

package/docs/MACHINES.md

@@ -0,0 +1,166 @@
+# Machines truth table
+
+**Purpose:** Prevent agents from wiring the wrong state layer. This table reflects **current implementation**, not aspirational catalog rows.
+
+---
+
+## Summary table
+
+| Component | `@aeon-ui/primitives` machine | Headless runtime | `data-aeon-state` source |
+|-----------|------------------------------|------------------|--------------------------|
+| **Async** | `createAsyncMachine()` | `useAeonMachine` in `Async` context | Snapshot value (+ `stale` flag on readout) |
+| **Field** | `fieldMachine` (parallel) | `useAeonMachine` | `stateToAttr(snapshot.value)` |
+| **Button** | `buttonLifecycleMachine` | **`status` prop** on `Button.Root` | Prop string, not machine by default |
+| **Switch** | `toggleMachine` | `useAeonMachine` | Snapshot |
+| **Checkbox** | `toggleMachine` | `useAeonMachine` | Snapshot |
+| **Dialog** | `dialogMachine` | `useAeonMachine` | `open` / `closed` |
+| **Tabs** | `tabsMachine` | `useAeonMachine` | Selected tab value |
+| **Accordion** | `accordionMachine` | `useAeonMachine` | Per-item open |
+| **Menu** | `popoverMachine` | `useAeonMachine` | `open` / `closed` |
+| **Popover** | `popoverMachine` | `useAeonMachine` | `open` / `closed` |
+| **Toast** (item) | `toastMachine` | `useAeonMachine` | visible / hidden |
+| **Select** | `popoverMachine` | `useAeonMachine` | `open` / `closed`; highlight in React |
+| **Combobox** | — | **`useState`** (open, query, highlight) | `open` / `closed` + highlight attrs |
+| **Tooltip** | — | **`useState(open)`** | `open` / `closed` |
+| **Scroll** | — | **`getScrollSnapshot()`** | Derived overflow/edge tokens |
+
+---
+
+## Button: prop vs machine (critical)
+
+Two valid patterns — **do not conflate them**:
+
+### Pattern A — Headless / styled (default)
+
+```tsx
+<Button.Root status="pending" aria-busy>
+  Saving…
+</Button.Root>
+```
+
+- File: `packages/react/src/button/index.tsx`
+- `status` ∈ `idle` | `pending` | `success` | `failure` | `disabled`
+- Sets `data-aeon-state` via `partAttrs`
+- **No** `useAeonMachine` inside Button
+
+### Pattern B — Chart-driven (app / demo)
+
+```tsx
+const [snapshot, send] = useAeonMachine(buttonLifecycleMachine)
+const status = snapshot.value as ButtonStatus
+<Button.Root status={status} onClick={() => send({ type: 'PRESS' })} />
+```
+
+- Machine: `packages/primitives/src/machines/button.ts`
+- Demo: playground **Button lifecycle**
+
+---
+
+## Async events
+
+Machine: `packages/primitives/src/machines/async.ts`  
+Factory: `createAsyncMachine<T>()` — use per-region instance in context.
+
+| Event | Effect |
+|-------|--------|
+| `FETCH` | → `loading` |
+| `RESOLVE` `{ data }` | → `success` or `empty` if `isEmptyAsyncData(data)` |
+| `REJECT` `{ error }` | → `failure` |
+| `RESET` | → `idle`, clear context |
+| `STALE` | Context flag while staying in `success` |
+| `REFRESH` | Re-fetch from success/empty/failure |
+
+Constants: `ASYNC_LIFECYCLE_STATES`, `isEmptyAsyncData()`.
+
+React: `Async.Root` provides context; children call `send` via `useAsyncContext()`.
+
+---
+
+## Field events (orthogonal)
+
+Machine: `packages/primitives/src/machines/field.ts` — **parallel** regions.
+
+| Region | States |
+|--------|--------|
+| `interaction` | `pristine` · `dirty` |
+| `validation` | `valid` · `invalid` |
+| `submission` | `idle` · `pending` |
+
+| Event | Typical use |
+|-------|-------------|
+| `INPUT` | User typed |
+| `BLUR` | Left control |
+| `VALIDATE` `{ valid: boolean }` | After rule run |
+| `SUBMIT` | Form submit started |
+| `SUBMIT_DONE` / `SUBMIT_FAIL` | End pending |
+| `RESET` | Clear field |
+
+Flatten for DOM:
+
+```ts
+import { stateToAttr } from '@aeon-ui/core'
+stateToAttr(snapshot.value) // "interaction:dirty validation:invalid submission:idle"
+```
+
+---
+
+## Button lifecycle events
+
+Machine: `buttonLifecycleMachine` in `packages/primitives/src/machines/button.ts`
+
+| Event | From → To (simplified) |
+|-------|------------------------|
+| `PRESS` | idle → pending |
+| `SUCCEED` | pending → success |
+| `FAIL` | pending → failure |
+| `DISABLE` / `ENABLE` | ↔ disabled |
+| `RESET` | → idle |
+
+---
+
+## Dialog / toggle / tabs / accordion
+
+| Machine | File | Notes |
+|---------|------|-------|
+| `dialogMachine` | `machines/dialog.ts` | open/closed; Escape handled in React |
+| `toggleMachine` | `machines/toggle.ts` | Switch + Checkbox |
+| `tabsMachine` | `machines/tabs.ts` | Single active value |
+| `accordionMachine` | `machines/accordion.ts` | Multiple items |
+| `popoverMachine` | `machines/popover.ts` | Menu, Popover, Select |
+| `toastMachine` | `machines/toast.ts` | Auto-dismiss input |
+
+Inspect each file for full transition tables. Diagrams: `apps/demo/src/aeonDiagrams.ts`.
+
+---
+
+## Combobox / Tooltip
+
+**No primitives machine.** Open/query/highlight live in:
+
+- `packages/react/src/combobox/index.tsx` (item registry for filtering)
+- `packages/react/src/tooltip/index.tsx`
+
+**Select** reuses `popoverMachine` for open/closed; option order comes from DOM (`role="option"` ids), not a registry.
+
+---
+
+## Scroll
+
+```ts
+import { getScrollSnapshot } from '@aeon-ui/core'
+```
+
+Hook: `packages/react/src/scroll/use-scroll-state.ts` — listens to scroll/resize on viewport.
+
+States: `idle`, `overflow-y`, `overflow-x`, `overflow-both`, `at-start-y`, `between-y`, `at-end-y`, … (see [STATES.md](../STATES.md) §5).
+
+---
+
+## Diagram sync
+
+When you change transitions in `packages/primitives/src/machines/`:
+
+1. Update matching diagram string in `apps/demo/src/aeonDiagrams.ts`
+2. Mention in PR / commit that diagrams were synced
+
+No automated test enforces sync yet — **manual discipline required**.

package/docs/MIGRATION_FROM_ARK.md

@@ -0,0 +1,295 @@
+# Migrating from Ark UI to Aeon UI
+
+Step-by-step guide for apps that use **`@ark-ui/react`** headless primitives with your own CSS (Tailwind, CSS modules, etc.). Chakra-wrapped Ark recipes are out of scope here—migrate the headless boundary first, then revisit styling.
+
+**Reference consumers**
+
+| App | Stack | Notes |
+|-----|-------|--------|
+| [spidercorp.xyz](https://github.com/GenericCPU/spydercorp.xyz) | Vite + React | Field, Select, Dialog, Toast |
+| [soundbase.click](https://github.com/GenericCPU/soundbase) | Next.js + React | Avatar (Chakra remains for other widgets) |
+
+---
+
+## 1. Inventory Ark usage
+
+```bash
+rg "@ark-ui" --glob '*.{ts,tsx}' .
+```
+
+Group imports by component (`dialog`, `select`, `field`, `avatar`, `toast`, `portal`, `collection`, …). Migrate in this order when possible:
+
+1. **Leaf primitives** with a direct Aeon equivalent (Avatar, Switch, Checkbox).
+2. **Forms** — Field, Select, Combobox.
+3. **Overlays** — Dialog, Menu, Popover, Tooltip.
+4. **Toasts** — replace `createToaster` with `Toast.Provider` + `useToast()`.
+
+Components with **no** Aeon headless yet (Slider, Number Input, Steps, …): keep Ark for that file until Aeon ships them, or replace with a minimal local implementation.
+
+---
+
+## 2. Install Aeon runtime deps
+
+Aeon headless peers:
+
+```bash
+npm install @xstate/react xstate
+```
+
+When `@aeon-ui/*` is on npm:
+
+```bash
+npm install @aeon-ui/react @aeon-ui/core @aeon-ui/primitives
+```
+
+Until publish, point the bundler at a built clone (sections 3–4).
+
+---
+
+## 3. Build Aeon once
+
+From the Aeon UI repo:
+
+```bash
+pnpm run build:headless
+```
+
+In the consumer `package.json`:
+
+```json
+{
+  "scripts": {
+    "aeon:ensure": "node <path-to-AeonUI>/scripts/ensure-headless-built.mjs",
+    "prebuild": "npm run aeon:ensure"
+  }
+}
+```
+
+CI: set `AEON_UI_ROOT` to the checkout path.
+
+---
+
+## 4. Wire the bundler
+
+### Vite
+
+See [VITE_CONSUMER.md](./VITE_CONSUMER.md) for full `resolve.alias`, `optimizeDeps.include`, and TypeScript `paths`.
+
+### Next.js (recommended: `file:` links)
+
+Turbopack often **cannot** import files outside the app root via `resolveAlias`. Link the built packages into `node_modules` instead:
+
+```json
+{
+  "dependencies": {
+    "@aeon-ui/core": "file:../../../AeonUI/packages/core",
+    "@aeon-ui/primitives": "file:../../../AeonUI/packages/primitives",
+    "@aeon-ui/react": "file:../../../AeonUI/packages/react",
+    "@xstate/react": "^5.0.3",
+    "xstate": "^5.19.2"
+  }
+}
+```
+
+Run `npm install` after `pnpm run build:headless` in Aeon UI (or `npm run aeon:ensure` in the consumer).
+
+`next.config.mjs`:
+
+```js
+export default {
+  transpilePackages: ['@aeon-ui/react', '@aeon-ui/core', '@aeon-ui/primitives'],
+}
+```
+
+Optional: `next build --webpack` if you hit Turbopack edge cases.
+
+`tsconfig.json` paths (optional; `file:` installs usually typecheck via package `types`):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@aeon-ui/core": ["../../../AeonUI/packages/core/dist/index.d.ts"],
+      "@aeon-ui/primitives": ["../../../AeonUI/packages/primitives/dist/index.d.ts"],
+      "@aeon-ui/react": ["../../../AeonUI/packages/react/dist/index.d.ts"]
+    }
+  }
+}
+```
+
+Mark client boundaries: `'use client'` on files that import `@aeon-ui/react`.
+
+---
+
+## 5. API mapping (Ark → Aeon)
+
+| Ark | Aeon |
+|-----|------|
+| `data-scope` / `data-part` | `data-aeon-scope` / `data-aeon-part` |
+| `data-state` | `data-aeon-state` |
+| `Field.Input` | `Field.Control` |
+| `Field.Textarea` | `Field.Textarea` |
+| `createListCollection` + `Select.*` | `Select.Root` → `Trigger` + `ValueText` → `Positioner` → `Content` → `Item` |
+| `Portal` + `Dialog.*` | `Dialog.Portal` wraps `Backdrop`, `Positioner`, `Content` |
+| `Avatar.Root` / `Image` / `Fallback` | Same part names under `@aeon-ui/react` |
+| `createToaster` + `Toaster` | `Toast.Provider`, `Toast.Viewport`, `useToast().publish()` |
+
+### Select (required structure)
+
+```tsx
+import { Select } from '@aeon-ui/react'
+
+<Select.Root value={value} onValueChange={setValue}>
+  <Select.Trigger>
+    <Select.ValueText>{label}</Select.ValueText>
+  </Select.Trigger>
+  <Select.Positioner>
+    <Select.Content>
+      <Select.Item value="a">Option A</Select.Item>
+    </Select.Content>
+  </Select.Positioner>
+</Select.Root>
+```
+
+Use `portalled={false}` in tests or fixed-height containers.
+
+### Dialog
+
+```tsx
+<Dialog.Root open={open} onOpenChange={setOpen}>
+  <Dialog.Trigger>Open</Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Backdrop />
+    <Dialog.Positioner>
+      <Dialog.Content>
+        <Dialog.Title>Title</Dialog.Title>
+        <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+      </Dialog.Content>
+    </Dialog.Positioner>
+  </Dialog.Portal>
+</Dialog.Root>
+```
+
+### Avatar (shadcn-style wrapper)
+
+Keep your `components/ui/avatar.tsx` as a thin Tailwind wrapper over Aeon parts so call sites stay unchanged:
+
+```tsx
+import { Avatar as AeonAvatar } from '@aeon-ui/react'
+
+function Avatar({ className, ...props }) {
+  return <AeonAvatar.Root className={cn('relative flex size-8 ...', className)} {...props} />
+}
+```
+
+Aeon does not force width/height recipes—Tailwind `size-*` on `Root` works.
+
+### Toasts
+
+```tsx
+// layout.tsx
+import { Toast } from '@aeon-ui/react'
+
+<Toast.Provider>
+  {children}
+  <Toast.Viewport placement="bottom-end" />
+</Toast.Provider>
+
+// anywhere
+const { publish } = useToast()
+publish({ title: 'Saved' })
+```
+
+---
+
+## 6. Restyle with `data-aeon-*`
+
+Ark CSS often targets `[data-part=trigger]`. Rename selectors:
+
+```css
+/* was: [data-scope='select'][data-part='content'] */
+[data-aeon-scope='select'][data-aeon-part='content'] {
+  /* ... */
+}
+```
+
+State:
+
+```css
+[data-aeon-scope='select'][data-aeon-part='item'][data-aeon-state='highlighted'] {
+  background: var(--accent);
+}
+```
+
+See [STATES.md](../STATES.md) and [INTEGRATION.md](../INTEGRATION.md).
+
+---
+
+## 7. Remove Ark
+
+```bash
+npm uninstall @ark-ui/react
+```
+
+Re-run build and grep for stragglers:
+
+```bash
+rg "@ark-ui" .
+```
+
+---
+
+## 8. Verify
+
+| Check | Command / action |
+|-------|------------------|
+| Aeon tests | `cd AeonUI && pnpm test:headless` |
+| Consumer build | `npm run build` / `vite build` |
+| Select | Open list, keyboard, pick option, Escape |
+| Dialog | Open, focus trap, Escape, scroll lock |
+| Avatar | Image load, fallback when missing/broken |
+| Toasts | `publish` after provider mount |
+
+---
+
+## 9. Chakra + Ark stacks
+
+Many HandCash templates use **Chakra v3 recipes** built on Ark. Migrating “off Ark” does not require removing Chakra in one pass:
+
+1. Replace **direct** `@ark-ui/react` imports (e.g. `components/ui/avatar.tsx`).
+2. Later, swap Chakra widgets for `@aeon-ui/react` or `@aeon-ui/ui` per component.
+
+soundbase.click keeps Chakra for Button, Dialog, Select, etc.; only Avatar uses Aeon headless today.
+
+---
+
+## Light / dark transitions (Tailwind + next-themes)
+
+Import Aeon’s transition stylesheet and bridge `data-aeon-mode` to your existing theme toggle:
+
+```css
+/* globals.css */
+@import '@aeon-ui/core/theme-transition.css';
+```
+
+```tsx
+import { AeonThemeBridge } from '@/components/aeon-theme-bridge' // syncs next-themes → data-aeon-mode
+import { runAeonThemeTransition } from '@aeon-ui/core'
+
+// layout: inside <ThemeProvider>
+<AeonThemeBridge />
+
+// theme menu
+runAeonThemeTransition(() => setTheme('dark'))
+```
+
+Reference: **soundbase.click** (`components/aeon-theme-bridge.tsx`).
+
+---
+
+## Related docs
+
+- [VITE_CONSUMER.md](./VITE_CONSUMER.md) — Vite-specific aliases
+- [MACHINES.md](./MACHINES.md) — which components use XState
+- [ACCESSIBILITY.md](../ACCESSIBILITY.md) — roles and keyboard
+- [API_PATTERNS.md](./API_PATTERNS.md) — copy-paste snippets