aeon-ui-engine 1.4.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,143 @@
 # Changelog
 
+## [1.8.0] - 2026-09-27
+
+### Added
+
+- **`Popover.Positioner` / `FloatingPositioner` `anchorRef` + `matchAnchorWidth`.** Position a surface against the region it belongs to instead of the small trigger pinned to its edge, so a wide panel lands where the eye already is rather than being clamped back from the viewport edge.
+- **Optional philosophy note:** [docs/ANALOGY.md](./docs/ANALOGY.md) — Aeon as metaphor for formless truth and sensory projection (not product doctrine). Linked from [PHILOSOPHY.md](./PHILOSOPHY.md) and the docs index.
+- `@aeon-ui/tree` — widget trees. A widget is immutable data describing one face
+  of a chart, interpreted into DOM with `data-aeon-scope|part|state`. Flutter's
+  Widget and Element layers only: no RenderObject (layout stays CSS), no
+  `StatefulWidget` (the chart is the only state).
+- `exclusiveActionWidget` — the shared face for "confirm, then await" regions
+  (`idle → confirming → busy → idle | failure`): pending label, disabled set,
+  failure copy and confirm slot are functions of the snapshot.
+- `uncoveredStates(states, project)` — totality as a test: every state the chart
+  names must appear on the tree projected for it.
+- `interpret(tree, hosts)` — element layer; hosts slot existing compounds
+  (`Prompt`, fields) into names the tree declares.
+- Vite aliases, optimizeDeps exclude and tsconfig paths include `@aeon-ui/tree`.
+
+## [1.7.7] - 2026-08-18
+
+### Added
+
+- **Three more primitives in the live section, chosen for chart complexity.** `Slider` is hierarchical — the snapshot reports `interaction.dragging`, so the chart lights the region *and* the leaf inside it while you drag, and an arrow key shows `SET_VALUE` writing context without leaving the state. `FileUpload` runs a real drag-and-drop lifecycle (`idle` / `dragging` / `rejected`), driveable by dragging a file or by sending the same events from buttons. `Toast` is the one chart that moves without you: `visible` carries a delayed `TIMEOUT` that retires it on the machine's own clock.
+- **`useSliderContext`** exported from `@aeon-ui/react`, so a slider's live machine state (including the nested `interaction` value) is readable from inside `Slider.Root` — matching `useAsyncContext` / `useFieldContext` / `useStickyBarContext`.
+
+### Fixed
+
+- **The live chart never highlighted a component's *initial* state.** A late SVG swap replaced the diagram after the highlight was painted, so the first snapshot silently went dark until you interacted. The explorer now repaints when the rendered chart changes.
+- **`valid` also lit up `invalid`.** Node matching compared id substrings, so any state whose name contained another's was highlighted too. Matching is now segment-aware, and a region's `[*]` marker no longer inherits its parent's highlight.
+- **Nested snapshot values are highlighted properly.** A dotted path such as `interaction.dragging` now lights every node on the path, since the ancestors are genuinely active.
+- **Live charts are readable.** The explorer box was short enough that parallel and nested diagrams auto-fit to ~30%; it now has room, and the slider's nested region lays out left-to-right.
+
+## [1.7.6] - 2026-08-18
+
+### Changed
+
+- **Hero video: resolved an apparent contradiction in the narration.** "Nothing else exists" (about the async machine) could read as conflicting with the later child-machine states (broadcasting, seen, mined). The closed-world line is now scoped — "that's this machine's entire world" — and the hierarchy scene opens with the bridge: "Need more states? Charts nest." Transcript re-aligned (61s).
+
+## [1.7.5] - 2026-08-18
+
+### Changed
+
+- **Hero video narration re-recorded for clarity.** "Statechart" is now fed to TTS as "state chart" so it isn't mispronounced (the on-screen subtitle keeps the correct spelling — `speak` overrides audio only, the same mechanism the closing URL already used). The parallel-regions explanation is rebuilt around three plain questions — "Has it been edited? Does it pass? Is it sending?" — and each chart lane now prints its question next to the region name, so the words and the diagram agree. Also clearer: "no in-between states" replaces "no half states", "your CSS targets that attribute" replaces "your styles key off it", and the child machine's middle state is spoken as "seen on the network" rather than a bare "seen". Transcript re-aligned (59s).
+
+## [1.7.4] - 2026-08-18
+
+### Changed
+
+- **Hero video intro now shows the pain, and the ending is de-branded.** The opening scene names the actual symptoms of boolean soup — a mystery spinner with no context, two buttons wired to the same job (`Retry` / `Reload`), and "state is a mess" — instead of an abstract truth count. The narration no longer says the word "dirty" (the state node still shows it, since that's the real machine state). The hierarchy scene presents the nested send flow as "a real example / wallet · send" without naming the product. Transcript re-aligned (57s).
+
+## [1.7.3] - 2026-08-18
+
+### Changed
+
+- **Hero video: plainer intro, glossed jargon, and a real hierarchical chart from a shipping product.** The intro now shows three plain `loading` / `empty` / `error` toggles with what each means in English, instead of prop-name jargon. The parallel-regions scene explains `dirty` outright ("dirty just means the user typed") and prints a plain-English gloss under the composite value. The machine catalog scene is replaced with the send flow from HandCash Desktop: the `sendPayment` chart (`editing → confirming → handoff`) with the `txLifecycle` child machine (`broadcasting → seenInMempool → mined`) nested inside `handoff` — the wallet surface and the breadcrumb (`handoff › broadcasting`) stay in lockstep with the chart. Also fixed a renderer bug where PIL ignored text alpha, so every text fade-in had been popping at full opacity (visible as floating state labels before their nodes appeared). Transcript re-aligned (55s).
+
+## [1.7.2] - 2026-08-18
+
+### Changed
+
+- **New hero video, built from scratch to teach statecharts — not one animated state.** Seven scenes: three booleans producing a screen with a spinner and an error at once; the async machine with every state named and every edge labelled with its event; an event with no matching edge blocked at the door; the field machine's three parallel regions all true at once beside the surface that projects them; `state → data-aeon-state → pixels`; and four components each running their own machine on their own clock. Real system typography (SF / SF Mono), a poster frame from the chart scene, faststart streaming, and re-aligned transcript cues (52s).
+
+## [1.7.1] - 2026-08-18
+
+### Changed
+
+- **Hero video now shows the actual thesis.** Previously the statechart node swept on its own float while the phone face animated separately, so the chart and the screen never agreed. The centrepiece is now one coupled demo: the component face and the highlighted chart node are the same state, driven by a single step timeline, with the causing event (`FETCH`, `RESOLVE`, `REJECT`, `REFRESH`) labelled on the transition edge — the same idea as the live section. The closing card points at "See it live" instead of the removed builder; transcript cues re-aligned.
+
+## [1.7.0] - 2026-08-18
+
+### Added
+
+- **Live section: real components beside the chart that tracks them.** Async, Button, Field, and Dialog run their shipped machines; the Mermaid chart highlights the state the component is actually in and names the event that caused the move. Field reports all three regions at once, because a field has no single state.
+- Machine-accurate diagrams for `buttonLifecycleMachine`, `dialogMachine`, and `fieldMachine`; the async chart now shows its `REFRESH` and re-fetch edges. `aeonDiagrams.test.ts` fails if a chart misses a machine state or invents one.
+
+### Fixed
+
+- **A controlled `Dialog`, `Popover`, or `Menu` could never be opened by its own trigger.** `onOpenChange` reported the resolved prop, so an owner holding `open` never heard the machine's intent — the trigger, escape key, and outside click were all dead. Each root now reports the machine's own transition (and no longer fires on mount).
+
+### Removed
+
+- **The generative app builder is gone** — sandbox, chart→schema compiler, live composer, model client, cost meter, and the `/api/aeon-generate` and `/api/aeon-scrape` endpoints, plus the OpenRouter proxy plugin and its env keys (~6,000 lines). Landing nav, hero, and header CTAs point at the live section.
+- The static "Determinism" diagram section, now that the live charts replace it. `expandActiveStates` lost its builder-specific token aliases.
+
+## [1.6.1] - 2026-08-18
+
+### Changed
+
+- **Builder previews read like designs, not state dumps.** The first screen now leads with the site's own hero headline and description (scraped, never invented); other screens are titled by their state once. Actions promote one primary button and group the rest instead of stacking equal buttons. The app bar no longer repeats the state label the dock already shows.
+- **Device selector is back** — phone / tablet / desktop toggle above the preview, with the desktop frame showing the scraped host in its address bar.
+
+## [1.6.0] - 2026-08-18
+
+### Added
+
+- **Redesign any site from its URL** — paste a domain into the builder and `/api/aeon-scrape` reads the page for its name, description, nav, actions, logo, and `theme-color`. The brand becomes chrome (logo in the app bar, accent palette scoped to the preview) and the page content becomes the prompt. Private and non-HTTP hosts are refused.
+- `builder/projectFaces.ts` — generic chart projection: states become screens, transitions become actions, `collect` demos add a field, `async` demos add an async region.
+- Demo tests now run in CI (`pnpm test`), covering projection, scraping, palette derivation, and a server render of the builder output.
+
+### Changed
+
+- **App builder rebuilt around one input.** Prompt or URL, Build, preview. The starter chips, engine bar, cost meter, inspector tabs, device picker, and build loader are gone.
+- **The model returns a chart and nothing else; the UI is projected from it.** Previously ~1,900 lines of prompt keyword matching decided that "match" meant a dating app, "faq" meant an accordion, and "pong" meant paddles, then filled screens with seeded catalogs, listings, and test stimuli. All of it is deleted, along with the preset app schemas it produced.
+- Empty nav tabs are dropped instead of being filled with placeholder screens, and the offline fallback chart is deliberately shapeless rather than a product guess.
+
+## [1.5.2] - 2026-08-18
+
+### Changed
+
+- **Landing page trimmed to essentials** — removed the pillars grid, the numbered setup box, and the full rule-file dump; the Cursor section is now one command plus a copy button. Hero shows a single install line, the why section keeps only the same-prompt contrast, specs show one chart, and the FAQ is four questions.
+
+## [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 +151,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.8.0",
   "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,13 +26,15 @@
     "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",
     "dev": "pnpm --filter @aeon-ui/demo dev",
     "examples": "pnpm --filter @aeon-ui/examples dev",
     "typecheck": "pnpm -r run typecheck",
-    "test": "pnpm run test:headless",
+    "test": "pnpm run test:headless && pnpm --filter @aeon-ui/demo run test",
     "test:headless": "pnpm run build:headless && pnpm --filter @aeon-ui/core --filter @aeon-ui/primitives --filter @aeon-ui/react run test",
     "changeset": "changeset",
     "version-packages": "changeset version",

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/node_modules/.bin/vitest

@@ -10,9 +10,9 @@ case `uname` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3_/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@4.1.8_@types+node@22.19.19_jsdom@29.1.1_vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3_/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
   exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"