aeon-ui-engine 1.0.1 → 1.0.3

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.

package/FRAMEWORKS.md

@@ -1,57 +0,0 @@
-# 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/PHILOSOPHY.md

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

package/PUBLISHING.md

@@ -1,85 +0,0 @@
-# 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/SCENE.md

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