aeon-ui-engine 1.0.0

package/.changeset/README.md

@@ -0,0 +1,23 @@
+# 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

@@ -0,0 +1,9 @@
+---
+"@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

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [
+    [
+      "@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", "aeon-ui-monorepo"]
+}

package/.changeset/framework-adapters.md

@@ -0,0 +1,12 @@
+---
+"@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

@@ -0,0 +1,6 @@
+---
+"@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

@@ -0,0 +1,8 @@
+---
+"@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

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

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

@@ -0,0 +1,22 @@
+---
+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

@@ -0,0 +1,32 @@
+# 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

@@ -0,0 +1,226 @@
+# 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

@@ -0,0 +1,36 @@
+# 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 |
+| Toast | ✓ | ✓ | `toastMachine` | hidden / visible |
+| Avatar | ✓ | — | **React state** | idle / loading / loaded / error |
+
+## Planned (not shipped)
+
+Slider, Number Input, Date Picker, Tree View, Pin Input, File Upload, Carousel — 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.

package/FRAMEWORKS.md

@@ -0,0 +1,57 @@
+# Framework support
+
+**Agents:** [AGENTS.md](./AGENTS.md) · porting steps mirror React — [docs/COMPONENT_CHECKLIST.md](./docs/COMPONENT_CHECKLIST.md)
+
+## Today
+
+| Runtime | Package | Status |
+|---------|---------|--------|
+| React 18+ | `@aeon-ui/react`, `@aeon-ui/ui` | **Full catalog** (Button, Dialog, Select, Combobox, overlays, …) |
+| Vue 3 | `@aeon-ui/vue` | **Adapter v0.1** — `useAeonMachine`, `Switch` |
+| Solid 1.8+ | `@aeon-ui/solid` | **Adapter v0.1** — `useAeonMachine`, `Switch` |
+| Svelte 4/5 | `@aeon-ui/svelte` | **Adapter v0.1** — `useAeonMachine`, `Switch` (`.svelte` parts) |
+
+Styled Panda recipes (`@aeon-ui/ui`) remain **React-only** until a second framework needs them.
+
+## Install
+
+```bash
+# Vue
+pnpm add @aeon-ui/vue @aeon-ui/core @aeon-ui/primitives xstate vue
+
+# Solid
+pnpm add @aeon-ui/solid @aeon-ui/core @aeon-ui/primitives xstate solid-js
+
+# Svelte
+pnpm add @aeon-ui/svelte @aeon-ui/core @aeon-ui/primitives xstate svelte
+```
+
+## Headless contract (all adapters)
+
+Any port must preserve:
+
+1. **Machines** from `@aeon-ui/primitives` (XState) — single source of behavior.
+2. **Anatomy** from `@aeon-ui/core` — `data-aeon-scope`, `data-aeon-part`, `data-aeon-state`.
+3. **Compound parts** — same names as React (`Root`, `Trigger`, `Content`, …).
+4. **Controlled APIs** — `open`, `onOpenChange`, `checked`, `onCheckedChange` where applicable.
+
+Framework packages bind machine snapshots to their reactivity model (via `@xstate/vue`, `@xstate/solid`, or actor `subscribe` in Svelte). They do **not** reimplement transition tables.
+
+## Porting checklist (new component)
+
+1. Copy behavior from `packages/react/src/<component>/`.
+2. Reuse `partAttrs` / anatomy from `@aeon-ui/core`.
+3. Wire `useAeonMachine` (or framework binding) to the primitive machine.
+4. Add a minimal demo or test in that framework when the API stabilizes.
+
+## Why React stayed first
+
+- Largest catalog and Panda styled layer.
+- Demo and docs target JSX.
+- Adapters prove the contract before duplicating every component three times.
+
+## Comparison to Ark / Zag
+
+[Ark UI](https://ark-ui.com) ships many frameworks via [Zag.js](https://zag-js.com) with broad component coverage. Aeon optimizes for **explicit XState charts** and **full lifecycle states** on fewer, deeper primitives. Adapters close the framework gap incrementally; they do not yet match Ark’s breadth.
+
+Contributors: open a PR adding the next React component port to `@aeon-ui/vue` / `solid` / `svelte` using **Switch** as the template.

package/INTEGRATION.md

@@ -0,0 +1,89 @@
+# Integration guide
+
+**Agents:** [AGENTS.md](./AGENTS.md) · [docs/API_PATTERNS.md](./docs/API_PATTERNS.md)
+
+Aeon UI is **three layers**. You can use one or all.
+
+## 1. Headless only (`@aeon-ui/react`)
+
+No Panda required. Machines drive behavior; you style with any system.
+
+```tsx
+import { Menu } from '@aeon-ui/react'
+
+<Menu.Root>
+  <Menu.Trigger>Actions</Menu.Trigger>
+  <Menu.Positioner>
+    <Menu.Content>
+      <Menu.Item onClick={save}>Save</Menu.Item>
+    </Menu.Content>
+  </Menu.Positioner>
+</Menu.Root>
+```
+
+Target stable hooks:
+
+```css
+[data-aeon-scope="menu"][data-aeon-part="content"][data-aeon-state="open"] {
+  /* your panel */
+}
+[data-aeon-scope="menu"][data-aeon-part="item"]:hover {
+  background: var(--panel-hover);
+}
+```
+
+Use `partAttrs` / anatomy from `@aeon-ui/core` if you build wrappers.
+
+## 2. Panda recipes (`@aeon-ui/panda`)
+
+Slot recipes align with anatomy parts. Run `pnpm codegen` after recipe changes.
+
+```tsx
+import { aeonMenu } from '@aeon-ui/panda/styled-system/recipes'
+const styles = aeonMenu()
+```
+
+Import CSS once:
+
+```tsx
+import '@aeon-ui/panda/styles.css'
+import '@aeon-ui/panda/theme-runtime.css'
+```
+
+## 3. Styled components (`@aeon-ui/ui`)
+
+Batteries included — recipes applied for you.
+
+```tsx
+import { Menu, Button } from '@aeon-ui/ui'
+```
+
+## Tailwind example
+
+```html
+<button
+  data-aeon-scope="button"
+  data-aeon-part="root"
+  data-aeon-state="pending"
+  class="opacity-80 cursor-wait"
+>
+  Saving…
+</button>
+```
+
+## XState in your app
+
+Primitives use XState; your features can too. `useAeonMachine` is exported from `@aeon-ui/react` for shared machines.
+
+```tsx
+import { useAeonMachine } from '@aeon-ui/react'
+import { sicBoMachine } from './machines/sic-bo'
+```
+
+## Vite + custom CSS (no Panda)
+
+For apps that keep their own theme (Tailwind, plain CSS, etc.): [docs/VITE_CONSUMER.md](./docs/VITE_CONSUMER.md) — local clone aliases, `build:headless`, `ensure-headless-built.mjs`, and Ark → Aeon mapping.
+
+## Frameworks
+
+React is supported today. **Vue, Solid, and Svelte** ship v0.1 adapter packages (`@aeon-ui/vue`, `@aeon-ui/solid`, `@aeon-ui/svelte`) with `useAeonMachine` and a reference **Switch** port. See [FRAMEWORKS.md](./FRAMEWORKS.md) for the headless contract and install commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpiderCorp / Aeon UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PHILOSOPHY.md

@@ -0,0 +1,71 @@
+# Aeon UI — Founding Philosophy
+
+Aeon UI is infrastructure for the web, built for interfaces that remain clear as products grow.
+
+## North star
+
+**State is defined first. UI represents the totality of that definition.**
+
+A region’s behavior is modeled as an explicit set of conditions — named, mutually exclusive at a given depth, with known transitions. The interface’s job is to **fully express** that model: every stable state the chart allows should be visible in the UI (via structure, copy, and `data-aeon-state`), and the UI should never imply a condition the chart does not define (no mystery spinners, no ambiguous half-states, no styling that drifts from the snapshot).
+
+In short: **UI = f(state)** — not f(props), not f(local React flags), but f(the executable statechart).
+
+## Primary source
+
+**Thanh Nguyen**, *Statecharts for modern web application state management* (Metropolia, 2020).  
+[Theseus thesis PDF](https://www.theseus.fi/bitstream/handle/10024/334118/Thanh_Nguyen.pdf?sequence=2&isAllowed=y)
+
+## Core tenets
+
+### 1. Define state, then project UI
+
+Separate **behavior** (state evolution in a machine) from **presentation** (markup, style, anatomy). Components read a snapshot and render the corresponding face of the model. When the snapshot changes, the whole affordance updates — trigger, labels, indicators, and `data-aeon-state` together.
+
+### 2. Totality, not fragments
+
+If the machine has `idle`, `loading`, `success`, and `failure`, the product surface should account for all four — in layout, messaging, and styling — even when only one is active. Users and developers see the same complete map; nothing is left implicit.
+
+### 3. Explicit, coherent states
+
+Application regions benefit from **mutually exclusive states** at a given depth — one stable condition the team can name, test, and extend. That clarity keeps complex flows maintainable as features accumulate.
+
+### 4. Statecharts for lasting complexity
+
+When requirements grow, flat state diagrams become hard to follow. Statecharts add:
+
+- **Hierarchy** — cluster related states; share transitions at the right level of abstraction
+- **Orthogonality** — independent regions (e.g. playback and shuffle) without combinatorial sprawl
+- **Guards** — conditional transitions that document business rules in the model
+- **Transient states** — routing steps that keep flows readable
+- **Actions and activities** — entry, exit, and transition effects with defined ordering
+
+### 5. Deterministic, diagrammable behavior
+
+Every interactive primitive can own an **executable statechart** (via [XState](https://xstate.js.org)). Models can be visualized, reviewed, and extended alongside designers and stakeholders — a shared map for how the product behaves.
+
+### 6. Design systems in control
+
+Aeon provides **unstyled headless primitives** with explicit anatomy (`data-aeon-scope`, `data-aeon-part`, `data-aeon-state`) so your team owns every surface. The styled layer (`@aeon-ui/ui`) ships intentional defaults you can adopt or replace — **your brand, fully yours**.
+
+## Production-ready patterns
+
+| Concern | Approach |
+|---------|----------|
+| Structure & API | Compound components, part-based anatomy (`data-aeon-scope`, `data-aeon-part`, `data-aeon-state`), accessibility |
+| Styling | Panda CSS slot recipes on headless primitives — tokens and variants keyed to machine state |
+| Execution | XState statecharts (thesis case study) — explicit states and transitions in the browser |
+
+## Library shape
+
+```
+@aeon-ui/core        — philosophy, anatomy, machine helpers
+@aeon-ui/primitives  — headless, statechart-backed parts
+@aeon-ui/react       — React bindings (snapshot → DOM)
+@aeon-ui/ui          — styled components with intentional tokens
+```
+
+**Guideline:** Model the statechart first — list every stable state and transition. Then build UI that expresses the **whole** definition at once (track, readout, parts), with exactly one active condition per region.
+
+See **[STATES.md](./STATES.md)** for states traditional UI often omits (async empty/stale, button pending/success/failure, orthogonal field regions) and the corresponding Aeon primitives.
+
+**Coding agents:** [AGENTS.md](./AGENTS.md) · [docs/INDEX.md](./docs/INDEX.md)