aeon-ui-engine 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
@@ -13,6 +39,7 @@
 ### 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
 

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.4.0",
+  "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/dist/bin.js

@@ -1,37 +1,63 @@
 #!/usr/bin/env node
 import {
   initAeon,
+  linkAeon,
   migrateAeon
-} from "./chunk-5L47SLNV.js";
+} 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
+  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 (init)
+  --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}`);

package/packages/cli/dist/{chunk-5L47SLNV.js → chunk-JMNRJCWF.js}

@@ -85,10 +85,16 @@ Generated by \`npx aeon-ui init\`.
 ## Next steps
 
 1. Install: \`npm install aeon-ui-engine react react-dom xstate @xstate/react\`
-2. CSS: \`import 'aeon-ui-engine/aeon.css'\`
-3. Vite: add \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\`
-4. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
-5. Constrain generation with JSON under \`aeon.schemas/\`
+   - Postinstall links \`@aeon-ui/*\` into \`node_modules\` (re-run with \`npx aeon-ui link\` if needed).
+2. CSS: \`import 'aeon-ui-engine/aeon.css'\` (e.g. root layout).
+3. **Next.js:** add \`transpilePackages\` for \`@aeon-ui/ui\`, \`@aeon-ui/react\`, \`@aeon-ui/core\`, \`@aeon-ui/primitives\`, \`@aeon-ui/panda\`. Use \`"use client"\` for interactive components. No webpack aliases required.
+4. **Vite (optional):** \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\` still helps with optimizeDeps; scoped imports resolve via the link step alone.
+5. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
+6. Constrain generation with JSON under \`aeon.schemas/\`
+
+## Frameworks
+
+Aeon is **React-first** (full catalog + styled layer). Next.js is supported. Vue / Solid / Svelte adapters exist but are thin \u2014 not the main product.
 
 ## Principle
 
@@ -98,9 +104,56 @@ Generated by \`npx aeon-ui init\`.
   return { cwd, written };
 }
 
+// src/link.ts
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function resolveLinkScript() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const fromMonorepo = join2(here, "../../../scripts/link-scoped-packages.mjs");
+  if (existsSync2(fromMonorepo)) return fromMonorepo;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const engineRoot = dirname(require2.resolve("aeon-ui-engine/package.json"));
+    return join2(engineRoot, "scripts/link-scoped-packages.mjs");
+  } catch {
+    throw new Error(
+      "Could not find scripts/link-scoped-packages.mjs (aeon-ui-engine not installed?)"
+    );
+  }
+}
+function linkAeon(options = {}) {
+  const script = resolveLinkScript();
+  const args = [script];
+  if (options.cwd) {
+    args.push("--cwd", options.cwd);
+  }
+  if (options.quiet) {
+    args.push("--quiet");
+  }
+  if (options.force) {
+    args.push("--force");
+  }
+  const result = spawnSync(process.execPath, args, {
+    stdio: options.quiet ? "pipe" : "inherit",
+    env: process.env,
+    cwd: options.cwd ?? process.cwd()
+  });
+  if (result.status !== 0 && result.status !== null) {
+    const err = result.stderr?.toString() || `link exited with code ${result.status}`;
+    throw new Error(err);
+  }
+  return {
+    cwd: options.cwd ?? process.cwd(),
+    status: result.status ?? 0
+  };
+}
+
 // src/migrate.ts
-import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
 var FINDINGS = [
   {
     id: "preview-window-machine",
@@ -156,8 +209,8 @@ function walkHints(cwd) {
   const hits = [];
   let corpus = "";
   for (const rel of CANDIDATES) {
-    const abs = join2(cwd, rel);
-    if (!existsSync2(abs)) continue;
+    const abs = join3(cwd, rel);
+    if (!existsSync3(abs)) continue;
     try {
       corpus += `
 ${rel}
@@ -228,7 +281,7 @@ function migrateAeon(options = {}) {
   const findings = walkHints(cwd);
   const written = [];
   if (write) {
-    const path = join2(cwd, "AEON_MIGRATION_CHECKLIST.md");
+    const path = join3(cwd, "AEON_MIGRATION_CHECKLIST.md");
     const findingsBlock = findings.length === 0 ? "\n## Scan results\n\nNo known local workarounds detected in the quick scan.\n" : `
 ## Scan results
 
@@ -243,5 +296,6 @@ ${findingsBlock}`);
 
 export {
   initAeon,
+  linkAeon,
   migrateAeon
 };

package/packages/cli/dist/index.d.ts

@@ -7,6 +7,20 @@ declare function initAeon(options?: InitOptions): {
     written: string[];
 };
 
+type LinkOptions = {
+    cwd?: string;
+    quiet?: boolean;
+    force?: boolean;
+};
+/**
+ * Symlink `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`.
+ * Prefer the postinstall hook; this command re-runs linking manually.
+ */
+declare function linkAeon(options?: LinkOptions): {
+    cwd: string;
+    status: number;
+};
+
 type MigrateOptions = {
     cwd?: string;
     write?: boolean;
@@ -23,4 +37,4 @@ declare function migrateAeon(options?: MigrateOptions): {
     findings: Finding[];
 };
 
-export { type InitOptions, type MigrateOptions, initAeon, migrateAeon };
+export { type InitOptions, type LinkOptions, type MigrateOptions, initAeon, linkAeon, migrateAeon };

package/packages/cli/dist/index.js

@@ -1,8 +1,10 @@
 import {
   initAeon,
+  linkAeon,
   migrateAeon
-} from "./chunk-5L47SLNV.js";
+} from "./chunk-JMNRJCWF.js";
 export {
   initAeon,
+  linkAeon,
   migrateAeon
 };

package/packages/cli/src/bin.ts

@@ -1,36 +1,64 @@
 #!/usr/bin/env node
 import { initAeon } from './init.js'
+import { linkAeon } from './link.js'
 import { migrateAeon } from './migrate.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0] ?? 'help'
 const force = args.includes('--force') || args.includes('-f')
 const checkOnly = args.includes('--check')
+const quiet = args.includes('--quiet') || args.includes('-q')
+
+function argValue(flag: string): string | undefined {
+  const i = args.indexOf(flag)
+  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith('-')) return args[i + 1]
+  return undefined
+}
+
+const cwdArg = argValue('--cwd')
 
 function help() {
   console.log(`aeon-ui — 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
+  link       Symlink node_modules/@aeon-ui/* → 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 (init)
+  --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 → ${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 · 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 → ${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 → ${result.cwd}`)

package/packages/cli/src/index.ts

@@ -1,2 +1,3 @@
 export { initAeon, type InitOptions } from './init.js'
+export { linkAeon, type LinkOptions } from './link.js'
 export { migrateAeon, type MigrateOptions } from './migrate.js'

package/packages/cli/src/init.ts

@@ -92,10 +92,16 @@ Generated by \`npx aeon-ui init\`.
 ## Next steps
 
 1. Install: \`npm install aeon-ui-engine react react-dom xstate @xstate/react\`
-2. CSS: \`import 'aeon-ui-engine/aeon.css'\`
-3. Vite: add \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\`
-4. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
-5. Constrain generation with JSON under \`aeon.schemas/\`
+   - Postinstall links \`@aeon-ui/*\` into \`node_modules\` (re-run with \`npx aeon-ui link\` if needed).
+2. CSS: \`import 'aeon-ui-engine/aeon.css'\` (e.g. root layout).
+3. **Next.js:** add \`transpilePackages\` for \`@aeon-ui/ui\`, \`@aeon-ui/react\`, \`@aeon-ui/core\`, \`@aeon-ui/primitives\`, \`@aeon-ui/panda\`. Use \`"use client"\` for interactive components. No webpack aliases required.
+4. **Vite (optional):** \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\` still helps with optimizeDeps; scoped imports resolve via the link step alone.
+5. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
+6. Constrain generation with JSON under \`aeon.schemas/\`
+
+## Frameworks
+
+Aeon is **React-first** (full catalog + styled layer). Next.js is supported. Vue / Solid / Svelte adapters exist but are thin — not the main product.
 
 ## Principle
 

package/packages/cli/src/link.ts

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export type LinkOptions = {
+  cwd?: string
+  quiet?: boolean
+  force?: boolean
+}
+
+function resolveLinkScript(): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const fromMonorepo = join(here, '../../../scripts/link-scoped-packages.mjs')
+  if (existsSync(fromMonorepo)) return fromMonorepo
+
+  try {
+    const require = createRequire(import.meta.url)
+    const engineRoot = dirname(require.resolve('aeon-ui-engine/package.json'))
+    return join(engineRoot, 'scripts/link-scoped-packages.mjs')
+  } catch {
+    throw new Error(
+      'Could not find scripts/link-scoped-packages.mjs (aeon-ui-engine not installed?)',
+    )
+  }
+}
+
+/**
+ * Symlink `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`.
+ * Prefer the postinstall hook; this command re-runs linking manually.
+ */
+export function linkAeon(options: LinkOptions = {}) {
+  const script = resolveLinkScript()
+  const args = [script]
+  if (options.cwd) {
+    args.push('--cwd', options.cwd)
+  }
+  if (options.quiet) {
+    args.push('--quiet')
+  }
+  if (options.force) {
+    args.push('--force')
+  }
+
+  const result = spawnSync(process.execPath, args, {
+    stdio: options.quiet ? 'pipe' : 'inherit',
+    env: process.env,
+    cwd: options.cwd ?? process.cwd(),
+  })
+
+  if (result.status !== 0 && result.status !== null) {
+    const err = result.stderr?.toString() || `link exited with code ${result.status}`
+    throw new Error(err)
+  }
+
+  return {
+    cwd: options.cwd ?? process.cwd(),
+    status: result.status ?? 0,
+  }
+}

package/packages/core/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":src/machine.test.ts",{"duration":2.9991249999999923,"failed":false}],[":src/theme.test.ts",{"duration":2.946333999999993,"failed":false}],[":../../apps/demo/src/aeonSchemaCompiler.test.ts",{"duration":7.737041999999974,"failed":false}],[":src/identicon.test.ts",{"duration":4.611709000000005,"failed":false}]]}
+{"version":"3.2.4","results":[[":src/machine.test.ts",{"duration":7.0908339999999725,"failed":false}],[":src/theme.test.ts",{"duration":3.866333999999995,"failed":false}],[":../../apps/demo/src/aeonSchemaCompiler.test.ts",{"duration":7.737041999999974,"failed":false}],[":src/identicon.test.ts",{"duration":9.875333000000012,"failed":false}]]}

package/packages/primitives/dist/{chunk-PB3LFHXU.js → chunk-VUPWYBGU.js}

@@ -29,6 +29,14 @@ var sliderMachine = setup({
     }),
     end: assign({
       value: ({ context }) => context.max
+    }),
+    setBounds: assign(({ context, event }) => {
+      if (event.type !== "SET_BOUNDS") return context;
+      const { min, max, step } = event;
+      return { ...context, min, max, step, value: snap(context.value, min, max, step) };
+    }),
+    setDisabled: assign({
+      disabled: ({ context, event }) => event.type === "SET_DISABLED" ? event.disabled : context.disabled
     })
   }
 }).createMachine({
@@ -41,6 +49,12 @@ var sliderMachine = setup({
     disabled: input.disabled ?? false
   }),
   initial: "interaction",
+  // Bounds and disabled follow the host regardless of interaction state, so a
+  // range that widens (audio duration arriving) stops clamping to stale limits.
+  on: {
+    SET_BOUNDS: { actions: "setBounds" },
+    SET_DISABLED: { actions: "setDisabled" }
+  },
   states: {
     interaction: {
       initial: "idle",