aeon-ui-engine 1.3.5 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [1.5.1] - 2026-08-18
+
+### Added
+
+- **Scoped package linking (Next.js works without aliases)** — `postinstall` and `npx aeon-ui link` symlink `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`. Next.js consumers now need only `transpilePackages` plus `"use client"`; the Vite plugin is optional (optimizeDeps convenience).
+- **`aeon-ui link` CLI command** — `--cwd`, `--force`, `--quiet`; also runs at the end of `npx aeon-ui init`. Exported as `aeon-ui-engine/link`.
+
+### Changed
+
+- CONSUMER.md, README, INTEGRATION, VITE_CONSUMER, MIGRATION_FROM_ARK, PUBLISHING: install once, link automatically, Vite plugin optional; `file:` link workaround for Next.js removed.
+- Landing FAQ and Cursor rules snippet state that Aeon is React-first with Next.js supported, and that Vue / Solid / Svelte are thin adapters rather than the main catalog.
+
+## [1.4.1] - 2026-08-17
+
+### Fixed
+
+- **Floating surfaces are collision aware** — `Menu` / `Popover` / `Tooltip` / `Select` positioners now accept `bottom-end` / `top-end` / `*-center` placements, flip when the preferred side has no room, and clamp inside the viewport. Right-aligned triggers (avatar menus in a sticky header) no longer render offscreen.
+- **Positioner stacking is configurable** — `gutter` and `zIndex` props on `Menu.Positioner`, `Popover.Positioner`, `Tooltip.Positioner` replace the hardcoded 4px gap and `z-index: 50`, so menus can sit above app chrome.
+- **Menu keyboard behavior** — `Menu.Content` takes focus while open, restores focus to the trigger on dismiss, and closes on Escape from anywhere on the page (previously only when focus was already inside the surface).
+- **Controlled `Slider` reports interaction** — pointer and keyboard input now call `onValueChange` even when `value` is set, so a controlled thumb (audio seek bar) follows its prop instead of Aeon's internal value. `onValueChange` no longer fires on mount or echoes the controlled prop.
+- **`sliderMachine` bounds follow the host** — new `SET_BOUNDS` / `SET_DISABLED` events, sent by `Slider.Root` on prop change, so a range that grows later (track duration arriving) stops clamping to the initial `max`.
+
+### Added
+
+- Positioners publish `data-side`, `data-align`, `--aeon-available-height`, and `--aeon-anchor-width` for recipes that cap their own scroll area.
+
+## [1.4.0] - 2026-08-17
+
+### Added
+
+- **RangeSlider** — `rangeSliderMachine` + headless/styled compound (two thumbs, `minStepsBetween`).
+- **FileUpload** — `fileUploadMachine` + dropzone compound (`idle | dragging | rejected`; file bytes in React).
+- **Button `asChild`** + exported `Slot` — merge button attrs onto `Link` / `<a>`.
+- **`npx aeon-ui migrate`** — scan known workarounds + write `AEON_MIGRATION_CHECKLIST.md`.
+- **docs/MIGRATION.md** — greenfield + upgrade playbook for future app migrations.
+
+### Changed
+
+- COMPONENTS / MACHINES / PRIMITIVE_COVERAGE / API_PATTERNS updated for 1.4 primitives.
+- **aeon-ui.com** hero, FAQ, Cursor docs, CONSUMER, and README now lead with `npx aeon-ui migrate` for existing apps.
+
+## [1.3.6] - 2026-07-31
+
+### Changed
+
+- **Landing hero** — “A better way to build with AI” (title, OG, tagline).
+- **Builder statecharts** — live chart follows the active UX scope/machine and highlights more reliably as you interact.
+
+### Earlier in 1.3.6
+
+- **Landing why-first** — philosophy, pillars, FAQ, and charts/totality support that outcome instead of leading with mechanics.
+
 ## [1.3.5] - 2026-07-31
 
 ### Added

package/CONSUMER.md

@@ -1,6 +1,16 @@
 # Using `aeon-ui-engine` from npm
 
-One package. One plugin. Done.
+One package. Install once. `@aeon-ui/*` resolves automatically.
+
+Aeon is **React-first** (Next.js included). Vue / Solid / Svelte adapters are thin — not the main product.
+
+## 0. Existing app? Migrate first
+
+```bash
+npx aeon-ui migrate
+```
+
+Scans for known local workarounds (custom dropzones, range sliders, toast bridges, hand-rolled link buttons) and writes `AEON_MIGRATION_CHECKLIST.md`. Use `--check` to print findings only. New projects can skip straight to install + `npx aeon-ui init`.
 
 ## 1. Install
 
@@ -8,51 +18,81 @@ One package. One plugin. Done.
 npm install aeon-ui-engine react react-dom xstate @xstate/react
 ```
 
-## 2. Vite plugin
+**Postinstall** runs `scripts/link-scoped-packages.mjs`, which symlinks:
 
-```ts
-// vite.config.ts
-import react from '@vitejs/plugin-react'
-import { defineConfig } from 'vite'
-import { aeonUiVitePlugin } from 'aeon-ui-engine/vite'
+`node_modules/@aeon-ui/*` → `node_modules/aeon-ui-engine/packages/*`
 
-export default defineConfig({
-  plugins: [react(), aeonUiVitePlugin()],
-})
+Re-run manually anytime:
+
+```bash
+npx aeon-ui link
+# or
+node node_modules/aeon-ui-engine/scripts/link-scoped-packages.mjs
 ```
 
-## 3. Import CSS (one line)
+No bundler aliases are required for `@aeon-ui/ui` / `@aeon-ui/react` imports.
+
+## 2. Import CSS (one line)
 
 ```tsx
-// main.tsx or app entry
+// app/layout.tsx (Next.js) or main.tsx (Vite)
 import 'aeon-ui-engine/aeon.css'
 ```
 
-## 4. Use components
+## 3. Use components
 
 ```tsx
 import { Button, Dialog, Menu, Toast } from '@aeon-ui/ui'
 ```
 
-That's it. The plugin handles all `@aeon-ui/*` aliases, TypeScript paths, and optimizeDeps.
+---
+
+## Next.js
+
+```js
+// next.config.mjs
+export default {
+  transpilePackages: [
+    '@aeon-ui/ui',
+    '@aeon-ui/react',
+    '@aeon-ui/core',
+    '@aeon-ui/primitives',
+    '@aeon-ui/panda',
+  ],
+}
+```
+
+Mark interactive surfaces as Client Components:
+
+```tsx
+'use client'
+import { Button } from '@aeon-ui/ui'
+```
+
+No `resolve.alias` / webpack alias block. If Turbopack mis-resolves after install, run `npx aeon-ui link` and prefer `next dev --webpack` while evaluating.
 
 ---
 
-## Optional: TypeScript
+## Vite (optional plugin)
 
-If your tsconfig doesn't extend the engine base:
+Scoped imports already work via the link step. The Vite plugin is optional — it still helps with `optimizeDeps` and monorepo `packagesRoot`:
 
-```json
-{
-  "compilerOptions": {
-    "paths": {
-      "@aeon-ui/*": ["./node_modules/aeon-ui-engine/packages/*/src"]
-    }
-  }
-}
+```ts
+// vite.config.ts
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+import { aeonUiVitePlugin } from 'aeon-ui-engine/vite'
+
+export default defineConfig({
+  plugins: [react(), aeonUiVitePlugin()],
+})
 ```
 
-Or extend directly:
+---
+
+## Optional: TypeScript
+
+Linked packages usually typecheck via each package’s `types` field. If needed:
 
 ```json
 {
@@ -117,7 +157,7 @@ Style with any CSS system using `data-aeon-scope`, `data-aeon-part`, `data-aeon-
 
 ## Optional: Local monorepo
 
-Point the plugin at a local checkout:
+Point the Vite plugin at a local checkout (or set `AEON_UI_ROOT` before `aeon-ui link`):
 
 ```ts
 aeonUiVitePlugin({ packagesRoot: '/path/to/aeon-ui/packages' })
@@ -125,4 +165,4 @@ aeonUiVitePlugin({ packagesRoot: '/path/to/aeon-ui/packages' })
 
 ## Reference consumer
 
-[Casino-games](https://github.com/GenericCPU/Casino-games) uses this exact pattern.
+[Casino-games](https://github.com/GenericCPU/Casino-games) uses the engine install pattern. Next.js consumers: install + link + `transpilePackages` (see above).

package/INTEGRATION.md

@@ -2,7 +2,7 @@
 
 **Agents:** [AGENTS.md](./AGENTS.md) · [docs/API_PATTERNS.md](./docs/API_PATTERNS.md)
 
-**npm consumers:** start with **[CONSUMER.md](./CONSUMER.md)** — install `aeon-ui-engine`, peer deps, and `aeonUiViteAliases()` before any `@aeon-ui/*` import works.
+**npm consumers:** start with **[CONSUMER.md](./CONSUMER.md)** — install `aeon-ui-engine` (postinstall links `@aeon-ui/*`), peer deps, then import. Vite plugin is optional; Next.js needs `transpilePackages` only.
 
 Aeon UI is **three layers**. You can use one or all.
 

package/README.md

@@ -16,7 +16,7 @@ Aeon UI models interactive behavior as executable [statecharts](https://www.thes
 | `@aeon-ui/primitives` | XState machines (toggle, dialog, tabs, accordion, async, button lifecycle, field) |
 | `@aeon-ui/react` | React headless bindings |
 | `@aeon-ui/schemas` | JSON Schema catalog + agent system prompts |
-| `@aeon-ui/cli` | `npx aeon-ui init` — Cursor rules, schemas, starter |
+| `@aeon-ui/cli` | `npx aeon-ui init` · `link` · `migrate` — Cursor rules, scoped package link, migration checklist |
 | `@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`) |
@@ -33,13 +33,27 @@ Teach an AI agent first (optional but recommended):
 npx aeon-ui init
 ```
 
-The monorepo is published on npm as **`aeon-ui-engine`** (bundles all `@aeon-ui/*` workspace packages):
+Migrating an existing app? Scan for known workarounds and write a checklist:
+
+```bash
+npx aeon-ui migrate
+```
+
+The monorepo is published on npm as **`aeon-ui-engine`** (bundles all `@aeon-ui/*` workspace packages). Postinstall links `node_modules/@aeon-ui/*` so **Next.js and Vite** resolve imports without aliases:
 
 ```bash
 npm install aeon-ui-engine react react-dom xstate @xstate/react
+# re-link if needed: npx aeon-ui link
 ```
 
-Add the Vite plugin and import CSS:
+```tsx
+// app/layout.tsx or main.tsx
+import 'aeon-ui-engine/aeon.css'
+```
+
+**Next.js** — add `transpilePackages` for `@aeon-ui/ui`, `@aeon-ui/react`, `@aeon-ui/core`, `@aeon-ui/primitives`, `@aeon-ui/panda`, and use `"use client"` for interactive components.
+
+**Vite (optional)** — `aeonUiVitePlugin()` still helps with optimizeDeps; linking alone is enough for `@aeon-ui/*` resolution:
 
 ```ts
 // vite.config.ts
@@ -49,11 +63,6 @@ export default defineConfig({
 })
 ```
 
-```tsx
-// main.tsx
-import 'aeon-ui-engine/aeon.css'
-```
-
 Full setup guide: **[CONSUMER.md](./CONSUMER.md)**.
 
 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 the social image in `apps/demo/public/` correctly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeon-ui-engine",
-  "version": "1.3.5",
+  "version": "1.5.1",
   "private": false,
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "exports": {
     "./vite": "./scripts/vite-aliases.mjs",
+    "./link": "./scripts/link-scoped-packages.mjs",
     "./aeon.css": "./packages/panda/aeon.css",
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./CONSUMER.md": "./CONSUMER.md",
@@ -25,6 +26,8 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "postinstall": "node ./scripts/link-scoped-packages.mjs",
+    "link:scoped": "node ./scripts/link-scoped-packages.mjs",
     "build": "pnpm --filter @aeon-ui/panda run codegen && pnpm -r run build",
     "build:headless": "pnpm --filter @aeon-ui/core --filter @aeon-ui/primitives --filter @aeon-ui/react run build",
     "codegen": "pnpm --filter @aeon-ui/panda codegen",

package/packages/cli/README.md

@@ -4,14 +4,26 @@ AI-optimized CLI for Aeon UI.
 
 ```bash
 npx aeon-ui init
+npx aeon-ui migrate
 ```
 
+## `init`
+
 Injects:
 
 - `.cursor/rules/aeon-ui.mdc` — always-on Cursor rule
 - `aeon.cursorrules.md` / `aeon.system-prompt.md` — paste into any agent
 - `aeon.schemas/` — deterministic JSON schemas per component
-- `src/components/AeonStarter.tsx` — minimal Field + Button + Async scaffold
+- `src/components/AeonStarter.tsx` — minimal Field + Button scaffold
 - `AEON_AI.md` — next steps
 
 Use `--force` to overwrite.
+
+## `migrate`
+
+Scans for known local workarounds (preview-window machine, file dropzone, sonner bridge, etc.) and writes `AEON_MIGRATION_CHECKLIST.md`.
+
+```bash
+npx aeon-ui migrate          # write checklist
+npx aeon-ui migrate --check  # print findings only
+```

package/packages/cli/dist/bin.js

@@ -1,32 +1,76 @@
 #!/usr/bin/env node
 import {
-  initAeon
-} from "./chunk-IW5NT2Z2.js";
+  initAeon,
+  linkAeon,
+  migrateAeon
+} from "./chunk-JMNRJCWF.js";
 
 // src/bin.ts
 var args = process.argv.slice(2);
 var cmd = args[0] ?? "help";
 var force = args.includes("--force") || args.includes("-f");
+var checkOnly = args.includes("--check");
+var quiet = args.includes("--quiet") || args.includes("-q");
+function argValue(flag) {
+  const i = args.indexOf(flag);
+  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith("-")) return args[i + 1];
+  return void 0;
+}
+var cwdArg = argValue("--cwd");
 function help() {
   console.log(`aeon-ui \u2014 AI-optimized CLI for Aeon UI
 
 Usage:
   npx aeon-ui init [--force]
+  npx aeon-ui link [--quiet] [--force] [--cwd <dir>]
+  npx aeon-ui migrate [--check]
 
 Commands:
-  init    Inject Cursor rules, JSON schemas, system prompt, and a starter component
-  help    Show this message
+  init       Inject Cursor rules, JSON schemas, system prompt, and a starter component
+  link       Symlink node_modules/@aeon-ui/* \u2192 aeon-ui-engine/packages/* (also runs on postinstall)
+  migrate    Scan for known workarounds and write AEON_MIGRATION_CHECKLIST.md
+  help       Show this message
 
 Options:
-  --force, -f   Overwrite existing generated files
+  --force, -f   Overwrite existing generated files (init); replace existing @aeon-ui links (link)
+  --check       Report findings only; do not write checklist (migrate)
+  --quiet, -q   Suppress link output (link)
+  --cwd <dir>   Project root for link (defaults to process.cwd())
 `);
 }
 if (cmd === "init") {
-  const result = initAeon({ force });
+  const result = initAeon({ force, cwd: cwdArg });
   console.log(`Aeon UI init \u2192 ${result.cwd}`);
   for (const line of result.written) console.log(`  ${line}`);
+  try {
+    linkAeon({ cwd: result.cwd, quiet: true });
+    console.log("  link @aeon-ui/* (scoped packages)");
+  } catch {
+    console.log("  link skipped (install aeon-ui-engine first, then: npx aeon-ui link)");
+  }
   console.log("\nNext: npm install aeon-ui-engine react react-dom xstate @xstate/react");
   console.log("Docs: AEON_AI.md \xB7 paste aeon.cursorrules.md into your agent system prompt");
+} else if (cmd === "link") {
+  try {
+    const result = linkAeon({ quiet, force, cwd: cwdArg });
+    if (quiet) console.log(`Aeon UI link \u2192 ${result.cwd}`);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+  }
+} else if (cmd === "migrate") {
+  const result = migrateAeon({ write: !checkOnly });
+  console.log(`Aeon UI migrate \u2192 ${result.cwd}`);
+  for (const line of result.written) console.log(`  ${line}`);
+  if (result.findings.length === 0) {
+    console.log("  (no known workarounds matched in quick scan)");
+  } else {
+    for (const f of result.findings) {
+      console.log(`  [${f.severity}] ${f.id}: ${f.advice}`);
+    }
+  }
+  console.log("\nInstall: npm install aeon-ui-engine@^1.4.0 xstate @xstate/react");
+  console.log("Docs: https://aeon-ui.com \xB7 repo docs/MIGRATION.md");
 } else {
   help();
   if (cmd !== "help" && cmd !== "--help" && cmd !== "-h") {