aeon-ui-engine 1.0.0

package/PUBLISHING.md

@@ -0,0 +1,85 @@
+# Publishing to npm
+
+Packages are versioned together at **0.1.0** (pre-release) using [Changesets](https://github.com/changesets/changesets).
+
+## Packages
+
+| npm name | Path |
+|----------|------|
+| `@aeon-ui/core` | `packages/core` |
+| `@aeon-ui/primitives` | `packages/primitives` |
+| `@aeon-ui/react` | `packages/react` |
+| `@aeon-ui/panda` | `packages/panda` |
+| `@aeon-ui/ui` | `packages/ui` |
+| `@aeon-ui/vue` | `packages/vue` |
+| `@aeon-ui/solid` | `packages/solid` |
+| `@aeon-ui/svelte` | `packages/svelte` |
+
+All eight publishable packages are in a **fixed** changeset group — one version bump applies to every package.
+
+## Day-to-day versioning
+
+1. After shipping features or fixes, run `pnpm changeset` and describe the change.
+2. When ready to release, run `pnpm version-packages` (updates `package.json` versions and package CHANGELOGs).
+3. Run `pnpm build` and `pnpm typecheck`.
+4. Run `pnpm release` to publish (requires `npm login` and `@aeon-ui` scope access).
+
+See `.changeset/README.md` for a short maintainer cheat sheet.
+
+## Before first publish (0.1.0)
+
+1. `pnpm install` — includes `@changesets/cli` and adapter deps.
+2. `pnpm build` — codegen + all package builds.
+3. `pnpm typecheck` — workspace clean.
+4. Confirm `files` in each `package.json` includes `dist` (and Panda `styled-system` / CSS assets; Svelte `.svelte` sources where applicable).
+5. Create npm org or scope `@aeon-ui` and login: `npm login`.
+6. Apply pending changesets: `pnpm version-packages`.
+7. Dry-run: `pnpm release --dry-run` (if your Changesets version supports it) or publish one package manually to verify.
+8. `pnpm release`.
+
+### Publish order (manual fallback)
+
+Dependency order is satisfied automatically when all packages share one version and declare `workspace:*` / semver peers. Manual order if needed:
+
+```bash
+pnpm --filter @aeon-ui/core publish --access public
+pnpm --filter @aeon-ui/primitives publish --access public
+pnpm --filter @aeon-ui/react publish --access public
+pnpm --filter @aeon-ui/vue publish --access public
+pnpm --filter @aeon-ui/solid publish --access public
+pnpm --filter @aeon-ui/svelte publish --access public
+pnpm --filter @aeon-ui/panda publish --access public
+pnpm --filter @aeon-ui/ui publish --access public
+```
+
+Prefer `pnpm release` once Changesets is in use.
+
+## Consumer install
+
+**React + styled:**
+
+```bash
+pnpm add @aeon-ui/ui @aeon-ui/react @aeon-ui/panda
+```
+
+**Vue headless:**
+
+```bash
+pnpm add @aeon-ui/vue @aeon-ui/core @aeon-ui/primitives xstate
+```
+
+**Solid headless:**
+
+```bash
+pnpm add @aeon-ui/solid @aeon-ui/core @aeon-ui/primitives xstate solid-js
+```
+
+**Svelte headless:**
+
+```bash
+pnpm add @aeon-ui/svelte @aeon-ui/core @aeon-ui/primitives xstate svelte
+```
+
+## Demo app
+
+The `apps/demo` package stays private and is listed in Changesets `ignore`.

package/README.md

@@ -0,0 +1,154 @@
+# Aeon UI
+
+**Future-proof UI infrastructure for the web.**
+
+**State is defined first. UI represents the totality of that definition.**
+
+> **Coding agents:** read **[AGENTS.md](./AGENTS.md)** first, then [docs/INDEX.md](./docs/INDEX.md). Human overview below.
+
+Aeon UI models interactive behavior as executable [statecharts](https://www.theseus.fi/bitstream/handle/10024/334118/Thanh_Nguyen.pdf?sequence=2&isAllowed=y), exposes production-ready headless compound components, and ships a styled layer powered by **[Panda CSS](https://panda-css.com)** slot recipes aligned with `@aeon-ui/core` anatomy. Every primitive projects a full machine snapshot onto the DOM — structure, copy, and `data-aeon-state` stay in sync.
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `@aeon-ui/core` | Anatomy tokens, `data-aeon-*` attributes, machine helpers |
+| `@aeon-ui/primitives` | XState machines (toggle, dialog, tabs, accordion, async, button lifecycle, field) |
+| `@aeon-ui/react` | React headless bindings |
+| `@aeon-ui/panda` | Design tokens, `defineSlotRecipe` styles, generated `styled-system` |
+| `@aeon-ui/ui` | Styled components (`aeonButton`, `aeonAccordion`, …) |
+| `@aeon-ui/vue` | Vue 3 headless adapter (v0.1: Switch + `useAeonMachine`) |
+| `@aeon-ui/solid` | Solid headless adapter (v0.1: Switch + `useAeonMachine`) |
+| `@aeon-ui/svelte` | Svelte headless adapter (v0.1: Switch + `useAeonMachine`) |
+
+**Catalog (React):** Button, Switch, Checkbox, Dialog, Tabs, Accordion, Select, **Combobox**, Async, Field, Scroll, **Menu**, **Popover**, **Tooltip**, **Toast** — see [COMPONENTS.md](./COMPONENTS.md). **Vue / Solid / Svelte:** reference Switch port; more components follow — [FRAMEWORKS.md](./FRAMEWORKS.md).
+
+## Quick start
+
+**Early access** — DM FOR EARLY ACCESS (npm publish is wired via Changesets; public install docs ship when the scope is live).
+
+Open [https://github.com/GenericCPU/aeon-ui](https://github.com/GenericCPU/aeon-ui) for the repo. The marketing demo lives at [https://aeon-ui.com](https://aeon-ui.com) — set `VITE_SITE_ORIGIN` to that origin in Vercel so Open Graph previews resolve `og.png` correctly.
+
+When published: `pnpm add @aeon-ui/ui @aeon-ui/react @aeon-ui/panda`
+
+After changing recipes or tokens in `packages/panda`:
+
+```bash
+pnpm codegen
+```
+
+## Styling (Panda CSS)
+
+Recipes live in `packages/panda/src/recipes/` and map to core anatomy parts (`accordion`, `dialog`, `tabs`, …). The styled layer applies them:
+
+```tsx
+import { aeonAccordion } from '@aeon-ui/panda/styled-system/recipes'
+
+const styles = aeonAccordion()
+// styles.root, styles.itemTrigger, …
+```
+
+Apps import generated CSS once, then runtime theme overrides (required for light/dark):
+
+```tsx
+import '@aeon-ui/panda/styles.css'
+import '@aeon-ui/panda/theme-runtime.css'
+import '@aeon-ui/panda/scrollbars.css'
+import '@aeon-ui/panda/chrome.css'
+```
+
+Legacy `--aeon-*` CSS variables are still emitted on `:root` for landing layout and gradual migration.
+
+## Themes (light / dark × mood)
+
+Edit **`packages/panda/src/theme/themes.config.ts`** — one entry per mood (`default`, `signal`, `berry`, `slate`, `neon`, …), each with `light` + `dark` palette fields. Run `pnpm codegen` in `packages/panda` to regenerate `theme-runtime.css`.
+
+```ts
+// themes.config.ts — add a mood
+{
+  id: 'brand',
+  label: 'Brand',
+  description: 'Your product',
+  light: { bg: '#f5f5f5', surface: '#fff', border: '#ddd', text: '#111', muted: '#666', accent: '#3366ff' },
+  dark: { bg: '#0a0a0a', surface: '#141414', border: '#333', text: '#eee', muted: '#999', accent: '#6699ff' },
+}
+```
+
+Runtime API:
+
+```ts
+import { applyAeonTheme, AEON_THEMES } from '@aeon-ui/panda/themes'
+
+applyAeonTheme('ocean', 'light')
+```
+
+Built-in moods: **Aeon**, **Signal**, **Dusk**, **Calm**, **Ocean**, **Ember**, **Frost**, **Dawn**, **Forest**, **Noir**. The demo uses a custom **Select** (not the OS dropdown) plus a Light/Dark rail.
+
+**Focus policy:** `chrome.css` shows focus rings only for keyboard (`:focus-visible`). Selected tabs, pressed buttons, and open selects use surface tint — not a focus “circle” on click.
+
+## Docs
+
+| Doc | Purpose |
+|-----|---------|
+| **[AGENTS.md](./AGENTS.md)** | **LLM/agent entry — rules, workflows, naming** |
+| [docs/INDEX.md](./docs/INDEX.md) | Full documentation map |
+| [docs/MACHINES.md](./docs/MACHINES.md) | Machine vs prop vs `useState` (ground truth) |
+| [docs/LAYOUT_COORDINATES.md](./docs/LAYOUT_COORDINATES.md) | Responsive play surfaces — normalized coordinate plane |
+| [docs/COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md) | Add or change a component (ordered steps) |
+| [COMPONENTS.md](./COMPONENTS.md) | What ships today vs planned |
+| [INTEGRATION.md](./INTEGRATION.md) | Headless, Panda, Tailwind |
+| [PUBLISHING.md](./PUBLISHING.md) | npm release checklist |
+| [FRAMEWORKS.md](./FRAMEWORKS.md) | React now; adapter contract |
+| [ACCESSIBILITY.md](./ACCESSIBILITY.md) | Roles, focus, checklist |
+
+## Philosophy & state catalog
+
+Read [PHILOSOPHY.md](./PHILOSOPHY.md) and **[STATES.md](./STATES.md)** — gaps traditional UI leaves implicit (empty vs idle, button pending/success, orthogonal field regions) and how Aeon models them.
+
+**UI = f(state).** Define every stable condition in the chart; build UI that expresses the whole definition, not a fragment of it.
+
+### Async region (totality)
+
+```tsx
+import { Async, Button } from '@aeon-ui/ui'
+
+<Async.Root>
+  <Async.Track />
+  <Async.Readout>Ready when you are</Async.Readout>
+  <Async.Actions>
+    <Button.Root size="sm">Fetch</Button.Root>
+  </Async.Actions>
+</Async.Root>
+```
+
+## Example
+
+```tsx
+import { Dialog, Button, Switch } from '@aeon-ui/ui'
+
+<Switch.Root defaultChecked>
+  <Switch.Control><Switch.Thumb /></Switch.Control>
+  <Switch.Label>Notifications</Switch.Label>
+</Switch.Root>
+
+<Dialog.Root>
+  <Dialog.Trigger><Button.Root>Open</Button.Root></Dialog.Trigger>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content>
+      <Dialog.Title>Title</Dialog.Title>
+      <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+    </Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+```
+
+Headless usage:
+
+```tsx
+import { Dialog } from '@aeon-ui/react'
+```
+
+## License
+
+MIT

package/SCENE.md

@@ -0,0 +1,113 @@
+# Aeon Scene (optional plane)
+
+**Control plane** (`@aeon-ui/primitives`, `@aeon-ui/react`, `@aeon-ui/ui`) models interactive UI with statecharts.
+
+**Scene plane** adds ambient visuals — geometry, materials, and audio-driven motion — without changing that contract.
+
+## Packages
+
+| Package | Role |
+|---------|------|
+| `@aeon-ui/signal` | Web Audio analyser tap, FFT bands, bar motion smoothing |
+| `@aeon-ui/geometry` | Grid/wave patterns, SVG bar layout, `sceneAttrs()` |
+| `@aeon-ui/surface` | Procedural CSS materials (stone, gravel, brick, pavement, kraft) — import `surface.css` once |
+| `@aeon-ui/scene` | CSS 3D transforms, perspective, wall clips (framework-agnostic) |
+| `@aeon-ui/react-scene` | React: backdrops/visualizers + `SceneStage`, `SceneLayer`, `ScenePlane`, `SceneSlot` |
+
+Install only what you need. Sic Bo might use `surface` + `geometry`; a player app might add `signal` + `react-scene`.
+
+## Quick start (React)
+
+```bash
+pnpm add @aeon-ui/react-scene @aeon-ui/signal @aeon-ui/geometry @aeon-ui/surface
+```
+
+```tsx
+import '@aeon-ui/surface/surface.css'
+import { SceneRoot, SceneSurface, SignalBars } from '@aeon-ui/react-scene'
+import { createDemoSignal } from '@aeon-ui/signal'
+
+// Demo oscillator for playgrounds (use attachMediaAnalyser(audio) in production)
+const demo = createDemoSignal()
+demo.start()
+
+<SceneRoot state="active">
+  <SceneSurface material="stone" style={{ minHeight: 120 }} />
+  <SignalBars analyser={demo.analyser} active barCount={7} />
+</SceneRoot>
+```
+
+## Anatomy
+
+Scene regions use the same attribute story as controls:
+
+- `data-aeon-scope="scene"`
+- `data-aeon-part="backdrop" | "grid" | "surface" | "visualizer" | …`
+- `data-aeon-state="idle" | "active" | "paused"` when playback or motion applies
+
+Style with Panda/CSS like any other Aeon part — no requirement to use `@aeon-ui/ui` components.
+
+## Construct a 3D scene from UI elements
+
+Use **CSS 3D** (not WebGL): a `SceneStage` sets perspective; `SceneRoom` builds a box (floor, ceiling, back, left, right) with one shared vanishing point; `SceneLayer` / `ScenePlane` cover ad-hoc layouts; `SceneSlot` mounts interactive UI at a transform. Prefer `SceneRoom` for alley/corridor spaces.
+
+```bash
+pnpm add @aeon-ui/react-scene @aeon-ui/scene @aeon-ui/surface @aeon-ui/geometry
+```
+
+```tsx
+import '@aeon-ui/surface/surface.css'
+import '@aeon-ui/react-scene/scene-3d.css'
+import { SceneStage, SceneRoom, SceneLayer, ScenePlane, SceneSlot } from '@aeon-ui/react-scene'
+
+<SceneStage minHeight={360} perspective={{ distance: 1100, origin: '50% 48%' }}>
+  <SceneRoom
+    size={{ width: 1280, height: 680, depth: 920 }}
+    camera={{ pitch: 11, offsetZ: -60 }}
+    floorMaterial="pavement"
+    wallMaterial="brick"
+    floor={<YourGameBoard />}
+  />
+</SceneStage>
+
+<!-- Or manual layers: -->
+<SceneStage minHeight={360} perspective={{ distance: 1000, origin: '50% 38%' }}>
+  <SceneLayer transform={{ z: -140 }}>
+    <ScenePlane part="sky" style={{ background: 'linear-gradient(180deg, #1a2030, #0d1117)' }} />
+  </SceneLayer>
+
+  <SceneLayer transform={{ z: -70, rotateY: 38 }} origin="0% 100%">
+    <ScenePlane part="wall-left" wall="left" material="brick" fill={false} style={{ width: '52%', height: '72%' }} />
+  </SceneLayer>
+
+  <SceneLayer transform={{ z: -70, rotateY: -38 }} origin="100% 100%">
+    <ScenePlane part="wall-right" wall="right" material="brick" fill={false} style={{ right: 0, width: '52%', height: '72%' }} />
+  </SceneLayer>
+
+  <SceneLayer transform={{ z: 0, rotateX: 58 }} origin="50% 0%">
+    <ScenePlane part="ground" material="gravel">
+      <SceneSlot transform={{ z: 24 }} style={{ left: '12%', right: '12%', top: '18%' }}>
+        {/* Any React UI — table, cards, controls */}
+        <YourGameBoard />
+      </SceneSlot>
+    </ScenePlane>
+  </SceneLayer>
+</SceneStage>
+```
+
+**Image URLs (optional):** pass `texture="…"` on `ScenePlane` when you have art assets. Prefer `@aeon-ui/surface` classes (`aeon-surface--pavement`, `--kraft`, `--brick`, …) for zero-asset materials — see the Sic Bo alley demo.
+
+**Low-level:** import `sceneTransformStyle`, `sceneStageStyle`, `sceneWallClip` from `@aeon-ui/scene` for Vue/Solid/Svelte bindings.
+
+Layers use `data-aeon-scope="scene"` and `data-aeon-part` from `@aeon-ui/geometry` — style in Panda/CSS like controls.
+
+## Soundbase lineage
+
+Bar motion and analyser patterns are adapted from the Soundbase logo visualizer (`logo-visualizer-core`, `logo-audio-analyser`). Product-specific logos stay in the app; the math lives in `@aeon-ui/signal`.
+
+## What not to put here
+
+- Form controls, dialogs, async data — stay in **primitives / ui**
+- Full WebGL/game engines — separate packages or app code; Scene provides CSS/SVG/canvas-friendly building blocks first
+
+Future: `@aeon-ui/vue-scene`, canvas render targets, image-based texture atlases, shared `@aeon-ui/motion` for non-audio springs. WebGL/Three.js stays app-level; Scene 3D is DOM + CSS transforms first.

package/STATES.md

@@ -0,0 +1,243 @@
+# States traditional UI forgets — and how Aeon models them
+
+**Agents:** start at [AGENTS.md](./AGENTS.md) and [docs/MACHINES.md](./docs/MACHINES.md) for which components use machines vs props.
+
+Aeon’s north star: **[state is defined first; UI expresses the totality of that definition](./PHILOSOPHY.md)** (`UI = f(snapshot)`).
+
+Traditional interfaces collapse rich behavior into a few booleans (`disabled`, `loading`, `open`) or hide conditions entirely. This document catalogs common gaps, how Aeon addresses them today, and how to extend the library.
+
+---
+
+## The attribute contract
+
+Every styled surface should be targetable consistently:
+
+| Attribute | Purpose |
+|-----------|---------|
+| `data-aeon-scope` | Component family (`button`, `async`, `field`, …) |
+| `data-aeon-part` | Compound part (`root`, `track`, `control`, …) |
+| `data-aeon-state` | Active condition(s) from the machine snapshot |
+
+Nested parallel regions flatten with `stateToAttr` from `@aeon-ui/core`:
+
+```ts
+import { stateToAttr } from '@aeon-ui/core'
+// e.g. "interaction:dirty validation:invalid submission:idle"
+```
+
+Panda recipes and `globalCss` in `@aeon-ui/panda` key off these attributes — not ad hoc class names in product code.
+
+---
+
+## 1. Async data regions
+
+### What traditional UI skips
+
+| Condition | Typical mistake |
+|-----------|-----------------|
+| **Idle** (never fetched) | Looks like “empty” |
+| **Loading** | Spinner with no named state |
+| **Success** | Only happy path styled |
+| **Failure** | Toast only, easy to miss |
+| **Empty** (success, zero results) | Same UI as idle |
+| **Stale** (success + background refresh) | Silent flicker |
+
+### Aeon model
+
+Machine: `createAsyncMachine()` in `@aeon-ui/primitives`  
+States: `idle` · `loading` · `success` · `failure` · `empty`  
+Context flag: `stale` on success → readout uses `data-aeon-state="success stale"`
+
+Constants: `ASYNC_LIFECYCLE_STATES`, `isEmptyAsyncData()`
+
+### UI kit (totality pattern)
+
+```tsx
+import { Async, Button } from '@aeon-ui/ui'
+
+<Async.Root>
+  <Async.Track />      {/* every lifecycle state visible on the rail */}
+  <Async.Readout>…</Async.Readout>
+  <Async.Actions>
+    <Button.Root>Fetch</Button.Root>
+  </Async.Actions>
+</Async.Root>
+```
+
+Headless: `@aeon-ui/react` → `Async`, `useAsyncContext`  
+Anatomy: `asyncAnatomy` (`track`, `segment`, `readout`, `actions`, …)  
+Styles: `aeonAsync` slot recipe
+
+**Rule:** If the chart lists five states, the track lists five segments — one active, none implicit.
+
+---
+
+## 2. Action button lifecycle
+
+### What traditional UI skips
+
+`disabled` is used for: in-flight submit, success, permission denied, validation blocked, and “busy”.
+
+Missing named states: **pending**, **success**, **failure**, distinct from **disabled**.
+
+### Aeon model
+
+Machine: `buttonLifecycleMachine`  
+States: `idle` · `pending` · `success` · `failure` · `disabled`
+
+### Component API
+
+```tsx
+<Button.Root status="pending" aria-busy>
+  Submitting…
+</Button.Root>
+```
+
+`status` maps to `data-aeon-state`. Global styles adjust cursor/opacity/border per state.
+
+For full chart-driven flows, run `buttonLifecycleMachine` with `useAeonMachine` and drive `status` from `snapshot.value` (see playground **Button lifecycle**).
+
+---
+
+## 3. Form field (orthogonal regions)
+
+### What traditional UI skips
+
+Interaction, validation, and submission are merged into one visual “error state.”
+
+### Aeon model
+
+Machine: `fieldMachine` (parallel)
+
+| Region | States |
+|--------|--------|
+| `interaction` | `pristine` · `dirty` |
+| `validation` | `valid` · `invalid` |
+| `submission` | `idle` · `pending` |
+
+Root: `data-aeon-state="interaction:dirty validation:invalid submission:idle"`
+
+### Component API
+
+```tsx
+import { Field } from '@aeon-ui/ui'
+
+<Field.Root>
+  <Field.Label htmlFor="email">Email</Field.Label>
+  <Field.Control id="email" validate={(v) => isValidEmail(v)} />
+  <Field.Message>Enter a valid email.</Field.Message>
+  <Field.Hint>Shown when pristine.</Field.Hint>
+</Field.Root>
+```
+
+`Field.Control` sends `INPUT`, `BLUR`, and `VALIDATE` events.  
+`Field.Message` renders only when `validation:invalid`.  
+Pending submission dims the control via `[data-aeon-state*="submission:pending"]` in global CSS.
+
+---
+
+## 4. Primitives already chart-backed
+
+| Primitive | Stable states (high level) |
+|-----------|----------------------------|
+| **Dialog** | `closed` · `open` |
+| **Toggle / Switch** | `checked` / `unchecked` + interaction `idle` · `pressed` |
+| **Tabs** | single active value |
+| **Accordion** | per-item open/closed |
+
+Future optional substates (documented, not all implemented): dialog `entering` / `exiting`, accordion `expanding` / `collapsing`.
+
+---
+
+## 5. Scroll regions
+
+### What traditional UI skips
+
+Scroll position is implicit. Overflow axis (vertical, horizontal, or both) and whether the user is at the start, middle, or end of each axis are rarely reflected in the DOM — so edge fades, scrollbar styling, and assistive hints stay out of sync.
+
+### Aeon model
+
+No XState machine — `getScrollSnapshot()` in `@aeon-ui/core` derives state from the viewport element on scroll and resize.
+
+| `data-aeon-state` token | Meaning |
+|-------------------------|---------|
+| `idle` | No overflow on either axis |
+| `overflow-y` · `overflow-x` · `overflow-both` | Which axes scroll |
+| `at-start-y` · `between-y` · `at-end-y` | Vertical edge position |
+| `at-start-x` · `between-x` · `at-end-x` | Horizontal edge position |
+
+### Component API
+
+```tsx
+import { Scroll } from '@aeon-ui/ui'
+
+<Scroll.Root axis="both" maxH="md">
+  <Scroll.Viewport>
+    <Scroll.Content>{children}</Scroll.Content>
+  </Scroll.Viewport>
+  <Scroll.StateReadout />
+</Scroll.Root>
+```
+
+Import `@aeon-ui/panda/scrollbars.css` after `theme-runtime.css` for WebKit + Firefox scrollbar styling on `html`, `[data-aeon-scroll]`, and `.code-example`.
+
+---
+
+## 6. States to model in product code
+
+Aeon does not ship every domain machine, but the same rules apply:
+
+| Concern | Suggested states |
+|---------|------------------|
+| **Offline** | `online` · `offline` · `reconnecting` |
+| **Permissions** | `allowed` · `denied` (not `disabled`) |
+| **Optimistic UI** | `optimistic` · `confirmed` · `rolledBack` |
+| **Rate limit** | `ok` · `throttled` |
+| **Selection** | add `indeterminate` on checkboxes |
+
+Use **orthogonal regions** when concerns are independent (Nguyen / Harel statecharts).
+
+---
+
+## 7. Styling checklist
+
+Full ordered steps: **[docs/COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md)**.
+
+1. Model the chart in `@aeon-ui/primitives` (or app-level XState).
+2. Add anatomy in `@aeon-ui/core` if new scope.
+3. Project snapshot in `@aeon-ui/react` with `partAttrs` / `stateToAttr`.
+4. Add slot recipe or `globalCss` keyed on `data-aeon-state` in `@aeon-ui/panda`.
+5. Export styled compound from `@aeon-ui/ui`.
+6. Demo the **full rail** — track + readout + actions.
+
+---
+
+## 8. Play-surface layout (spatial, not XState)
+
+Games and spatial UIs need **desktop vs mobile composition** without breaking pointer math. Aeon models this separately from behavior:
+
+- **Layout mode** — `compact` | `wide` on `data-aeon-layout-mode`
+- **Composition** — `split` | `stack` | `overlay` on `data-aeon-layout-composition`
+- **Normalized coordinates** — `normFromClient` / `clientFromNorm` in `@aeon-ui/core` (0–100 plane per measured region)
+
+Full guide: **[docs/LAYOUT_COORDINATES.md](./docs/LAYOUT_COORDINATES.md)** · Anatomy: `playSurfaceAnatomy` · Hook: `useLayoutMode`.
+
+---
+
+## 9. Package map
+
+| Package | Role |
+|---------|------|
+| `@aeon-ui/primitives` | Machines: `async`, `buttonLifecycle`, `field`, … |
+| `@aeon-ui/core` | `asyncAnatomy`, `fieldAnatomy`, `scrollAnatomy`, `getScrollSnapshot` |
+| `@aeon-ui/react` | `Async.*`, `Field.*`, `Scroll.*`, `Button` + `status` |
+| `@aeon-ui/panda` | `aeonAsync`, `aeonField`, `aeonScroll`, `scrollbars.css` |
+| `@aeon-ui/ui` | Styled exports |
+
+---
+
+## References
+
+- [PHILOSOPHY.md](./PHILOSOPHY.md) — north star and tenets  
+- [Thanh Nguyen (2020) — Statecharts for modern web application state management](https://www.theseus.fi/bitstream/handle/10024/334118/Thanh_Nguyen.pdf?sequence=2&isAllowed=y)  
+- Live examples: `apps/demo` playground (**Async region**, **Button lifecycle**, **Field regions**, **Scroll regions**)

package/apps/demo/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Aeon UI — Future-proof UI infrastructure</title>
+    <!-- OG_META -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Instrument+Sans:wght@400;500;600;700&family=Syne:wght@600;700;800&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script>
+      (function () {
+        var t = localStorage.getItem('aeon-theme') || 'default';
+        var m = localStorage.getItem('aeon-mode');
+        if (m !== 'light' && m !== 'dark') {
+          m = window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+        }
+        document.documentElement.dataset.aeonTheme = t;
+        document.documentElement.dataset.aeonMode = m;
+        document.documentElement.style.colorScheme = m;
+      })();
+    </script>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/demo/og.config.mjs

@@ -0,0 +1,15 @@
+/** Shared OG / canonical URLs — override in CI with VITE_SITE_ORIGIN. */
+export const siteOrigin = (process.env.VITE_SITE_ORIGIN ?? 'https://aeon-ui.com').replace(
+  /\/$/,
+  '',
+)
+
+export const og = {
+  title: 'Aeon UI — Future-proof UI infrastructure',
+  description:
+    'Statechart-driven headless primitives and a Panda CSS styled layer — dependable behavior, anatomy you can theme, built to last.',
+  siteName: 'Aeon UI',
+  imagePath: '/og.png',
+  imageAlt: 'Aeon UI — Future-proof UI infrastructure for the web',
+  themeColor: '#0c0e12',
+}

package/apps/demo/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@aeon-ui/demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "generate:og": "node scripts/generate-og-png.mjs",
+    "build": "pnpm --filter @aeon-ui/panda codegen && pnpm --filter @aeon-ui/site build && node scripts/generate-og-png.mjs && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aeon-ui/geometry": "workspace:*",
+    "@aeon-ui/panda": "workspace:*",
+    "@aeon-ui/primitives": "workspace:*",
+    "@aeon-ui/react": "workspace:*",
+    "@aeon-ui/react-scene": "workspace:*",
+    "@aeon-ui/signal": "workspace:*",
+    "@aeon-ui/surface": "workspace:*",
+    "@aeon-ui/ui": "workspace:*",
+    "@xstate/react": "^5.0.3",
+    "mermaid": "^11.15.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "xstate": "^5.19.2"
+  },
+  "devDependencies": {
+    "@aeon-ui/site": "workspace:*",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@fontsource/instrument-sans": "^5.2.8",
+    "@fontsource/syne": "^5.2.7",
+    "@resvg/resvg-js": "^2.6.2",
+    "@types/node": "^22.15.3",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "wawoff2": "^2.0.1"
+  }
+}