aeon-ui-engine 1.3.5 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [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.
+
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeon-ui-engine",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "private": false,
   "type": "module",
   "bin": {

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,24 +1,29 @@
 #!/usr/bin/env node
 import {
-  initAeon
-} from "./chunk-IW5NT2Z2.js";
+  initAeon,
+  migrateAeon
+} from "./chunk-5L47SLNV.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");
 function help() {
   console.log(`aeon-ui \u2014 AI-optimized CLI for Aeon UI
 
 Usage:
   npx aeon-ui init [--force]
+  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
+  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)
+  --check       Report findings only; do not write checklist (migrate)
 `);
 }
 if (cmd === "init") {
@@ -27,6 +32,19 @@ if (cmd === "init") {
   for (const line of result.written) console.log(`  ${line}`);
   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 === "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") {

package/packages/cli/dist/chunk-5L47SLNV.js

@@ -0,0 +1,247 @@
+// src/init.ts
+import { mkdirSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import {
+  CURSOR_RULES_SNIPPET,
+  AEON_SYSTEM_PROMPT,
+  catalog,
+  componentSchemas
+} from "@aeon-ui/schemas";
+var STARTER = `/**
+ * Aeon UI starter \u2014 generated by \`npx aeon-ui init\`
+ * Headless: @aeon-ui/react \xB7 Styled: @aeon-ui/ui \xB7 Schemas: @aeon-ui/schemas
+ */
+import { Button, Field } from '@aeon-ui/ui'
+
+export function AeonStarter() {
+  return (
+    <div>
+      <Field.Root>
+        <Field.Label>Email</Field.Label>
+        <Field.Control type="email" placeholder="you@example.com" />
+        <Field.Message />
+      </Field.Root>
+      <Button.Root status="idle">Continue</Button.Root>
+    </div>
+  )
+}
+`;
+function initAeon(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const force = options.force ?? false;
+  const written = [];
+  const write = (rel, body) => {
+    const path = join(cwd, rel);
+    if (existsSync(path) && !force) {
+      written.push(`skip ${rel} (exists)`);
+      return;
+    }
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, body.endsWith("\n") ? body : `${body}
+`);
+    written.push(`write ${rel}`);
+  };
+  write(".cursor/rules/aeon-ui.mdc", `---
+description: Aeon UI \u2014 statechart-driven components for AI agents
+globs: **/*.{tsx,ts,jsx,js}
+alwaysApply: true
+---
+
+${CURSOR_RULES_SNIPPET.trim()}
+`);
+  write("aeon.cursorrules.md", `${CURSOR_RULES_SNIPPET.trim()}
+`);
+  write("aeon.system-prompt.md", `${AEON_SYSTEM_PROMPT.trim()}
+`);
+  write(
+    "aeon.schemas/catalog.json",
+    `${JSON.stringify(
+      {
+        $id: catalog.$id,
+        title: catalog.title,
+        description: catalog.description,
+        version: catalog.version,
+        principle: catalog.principle,
+        attributes: catalog.attributes,
+        components: catalog.components,
+        note: "Full schemas live under aeon.schemas/components/*.json"
+      },
+      null,
+      2
+    )}
+`
+  );
+  for (const [id, schema] of Object.entries(componentSchemas)) {
+    write(`aeon.schemas/components/${id}.json`, `${JSON.stringify(schema, null, 2)}
+`);
+  }
+  write("src/components/AeonStarter.tsx", STARTER);
+  write(
+    "AEON_AI.md",
+    `# Aeon UI \u2014 AI agent setup
+
+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/\`
+
+## Principle
+
+**UI = f(state)** \u2014 never invent boolean combinations for states the schema does not list.
+`
+  );
+  return { cwd, written };
+}
+
+// src/migrate.ts
+import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+var FINDINGS = [
+  {
+    id: "preview-window-machine",
+    severity: "replace",
+    patterns: ["preview-window-machine", "previewWindowMachine"],
+    advice: "Replace with RangeSlider from @aeon-ui/react or @aeon-ui/ui (rangeSliderMachine)."
+  },
+  {
+    id: "file-dropzone",
+    severity: "replace",
+    patterns: ["file-dropzone-machine", "fileDropzoneMachine", "FileDropzone"],
+    advice: "Replace with FileUpload compound (fileUploadMachine) \u2014 idle | dragging | rejected."
+  },
+  {
+    id: "sonner-bridge",
+    severity: "replace",
+    patterns: ["from 'sonner'", 'from "sonner"', "components/ui/sonner"],
+    advice: "Use Toast.Provider + useToast().publish / dismiss (aeon-ui-engine \u2265 1.2)."
+  },
+  {
+    id: "manual-link-button",
+    severity: "optional",
+    patterns: ['data-aeon-scope="button"', "buttonVariants("],
+    advice: "Prefer <Button.Root asChild><Link \u2026 /></Button.Root> instead of hand-rolled data-aeon-* on anchors."
+  },
+  {
+    id: "chakra",
+    severity: "info",
+    patterns: ["@chakra-ui/react", "@ark-ui/react"],
+    advice: "Migrate leaf \u2192 forms \u2192 overlays per docs/MIGRATION_FROM_ARK.md; see docs/MIGRATION.md for greenfield checklist."
+  },
+  {
+    id: "alert-dialog-local",
+    severity: "optional",
+    patterns: ["alertDialogMachine", 'role="alertdialog"'],
+    advice: "Prefer Dialog/Prompt with dismissible=false for destructive confirms until AlertDialog ships."
+  }
+];
+var CANDIDATES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "lib/preview-window-machine.ts",
+  "lib/file-dropzone-machine.ts",
+  "components/file-dropzone.tsx",
+  "components/ui/sonner.tsx",
+  "components/ui/alert-dialog.tsx",
+  "components/ui/slider.tsx",
+  "components/ui/button.tsx",
+  "components/dual-login-buttons.tsx"
+];
+function walkHints(cwd) {
+  const hits = [];
+  let corpus = "";
+  for (const rel of CANDIDATES) {
+    const abs = join2(cwd, rel);
+    if (!existsSync2(abs)) continue;
+    try {
+      corpus += `
+${rel}
+${readFileSync(abs, "utf8")}`;
+    } catch {
+    }
+  }
+  for (const rule of FINDINGS) {
+    const matched = rule.patterns.find((p) => corpus.includes(p));
+    if (matched) {
+      hits.push({
+        id: rule.id,
+        severity: rule.severity,
+        pattern: matched,
+        advice: rule.advice
+      });
+    }
+  }
+  return hits;
+}
+var CHECKLIST = `# Aeon migration checklist
+
+Generated by \`npx aeon-ui migrate\`.
+
+## Install
+
+\`\`\`bash
+npm install aeon-ui-engine@^1.4.0 react react-dom xstate @xstate/react
+\`\`\`
+
+\`\`\`ts
+import 'aeon-ui-engine/aeon.css'
+\`\`\`
+
+## Agent setup
+
+\`\`\`bash
+npx aeon-ui init
+\`\`\`
+
+Paste \`aeon.cursorrules.md\` into Cursor rules. Keep domain machines in the app; use Aeon for chrome + interactive primitives.
+
+## Statechart-first rule
+
+1. Model interaction with an XState machine (or reuse Aeon machines).
+2. Project \`snapshot\` \u2192 \`data-aeon-state\` / compound parts.
+3. Do not invent parallel booleans for chart-owned concerns.
+
+## New primitives (1.4+)
+
+| Need | Use |
+|------|-----|
+| Two-thumb range | \`RangeSlider\` + \`rangeSliderMachine\` |
+| Link styled as button | \`<Button.Root asChild><Link/></Button.Root>\` |
+| Drag-drop file surface | \`FileUpload\` + \`fileUploadMachine\` |
+| Toast | \`Toast.Provider\` + \`useToast()\` |
+| Confirm sheet | \`Prompt\` / \`Dialog\` |
+
+## Docs
+
+- docs/MIGRATION.md (in aeon-ui-engine / AeonUI repo)
+- docs/MIGRATION_FROM_ARK.md
+- AGENTS.md
+`;
+function migrateAeon(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const write = options.write ?? true;
+  const findings = walkHints(cwd);
+  const written = [];
+  if (write) {
+    const path = join2(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
+
+${findings.map((f) => `- **${f.severity}** \`${f.id}\` (matched \`${f.pattern}\`): ${f.advice}`).join("\n")}
+`;
+    writeFileSync2(path, `${CHECKLIST.trim()}
+${findingsBlock}`);
+    written.push("write AEON_MIGRATION_CHECKLIST.md");
+  }
+  return { cwd, written, findings };
+}
+
+export {
+  initAeon,
+  migrateAeon
+};

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

@@ -7,4 +7,20 @@ declare function initAeon(options?: InitOptions): {
     written: string[];
 };
 
-export { type InitOptions, initAeon };
+type MigrateOptions = {
+    cwd?: string;
+    write?: boolean;
+};
+type Finding = {
+    id: string;
+    severity: 'replace' | 'optional' | 'info';
+    pattern: string;
+    advice: string;
+};
+declare function migrateAeon(options?: MigrateOptions): {
+    cwd: string;
+    written: string[];
+    findings: Finding[];
+};
+
+export { type InitOptions, type MigrateOptions, initAeon, migrateAeon };

package/packages/cli/dist/index.js

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

package/packages/cli/src/bin.ts

@@ -1,22 +1,27 @@
 #!/usr/bin/env node
 import { initAeon } from './init.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')
 
 function help() {
   console.log(`aeon-ui — AI-optimized CLI for Aeon UI
 
 Usage:
   npx aeon-ui init [--force]
+  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
+  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)
+  --check       Report findings only; do not write checklist (migrate)
 `)
 }
 
@@ -26,6 +31,19 @@ if (cmd === 'init') {
   for (const line of result.written) console.log(`  ${line}`)
   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 === 'migrate') {
+  const result = migrateAeon({ write: !checkOnly })
+  console.log(`Aeon UI migrate → ${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 · repo docs/MIGRATION.md')
 } else {
   help()
   if (cmd !== 'help' && cmd !== '--help' && cmd !== '-h') {

package/packages/cli/src/index.ts

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

package/packages/cli/src/migrate.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type MigrateOptions = {
+  cwd?: string
+  write?: boolean
+}
+
+type Finding = {
+  id: string
+  severity: 'replace' | 'optional' | 'info'
+  pattern: string
+  advice: string
+}
+
+const FINDINGS: Array<{
+  id: string
+  severity: Finding['severity']
+  patterns: string[]
+  advice: string
+}> = [
+  {
+    id: 'preview-window-machine',
+    severity: 'replace',
+    patterns: ['preview-window-machine', 'previewWindowMachine'],
+    advice: 'Replace with RangeSlider from @aeon-ui/react or @aeon-ui/ui (rangeSliderMachine).',
+  },
+  {
+    id: 'file-dropzone',
+    severity: 'replace',
+    patterns: ['file-dropzone-machine', 'fileDropzoneMachine', 'FileDropzone'],
+    advice: 'Replace with FileUpload compound (fileUploadMachine) — idle | dragging | rejected.',
+  },
+  {
+    id: 'sonner-bridge',
+    severity: 'replace',
+    patterns: ["from 'sonner'", 'from "sonner"', 'components/ui/sonner'],
+    advice: 'Use Toast.Provider + useToast().publish / dismiss (aeon-ui-engine ≥ 1.2).',
+  },
+  {
+    id: 'manual-link-button',
+    severity: 'optional',
+    patterns: ['data-aeon-scope="button"', 'buttonVariants('],
+    advice:
+      'Prefer <Button.Root asChild><Link … /></Button.Root> instead of hand-rolled data-aeon-* on anchors.',
+  },
+  {
+    id: 'chakra',
+    severity: 'info',
+    patterns: ['@chakra-ui/react', '@ark-ui/react'],
+    advice:
+      'Migrate leaf → forms → overlays per docs/MIGRATION_FROM_ARK.md; see docs/MIGRATION.md for greenfield checklist.',
+  },
+  {
+    id: 'alert-dialog-local',
+    severity: 'optional',
+    patterns: ['alertDialogMachine', 'role="alertdialog"'],
+    advice:
+      'Prefer Dialog/Prompt with dismissible=false for destructive confirms until AlertDialog ships.',
+  },
+]
+
+const CANDIDATES = [
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'lib/preview-window-machine.ts',
+  'lib/file-dropzone-machine.ts',
+  'components/file-dropzone.tsx',
+  'components/ui/sonner.tsx',
+  'components/ui/alert-dialog.tsx',
+  'components/ui/slider.tsx',
+  'components/ui/button.tsx',
+  'components/dual-login-buttons.tsx',
+]
+
+function walkHints(cwd: string): Finding[] {
+  const hits: Finding[] = []
+  let corpus = ''
+
+  for (const rel of CANDIDATES) {
+    const abs = join(cwd, rel)
+    if (!existsSync(abs)) continue
+    try {
+      corpus += `\n${rel}\n${readFileSync(abs, 'utf8')}`
+    } catch {
+      /* ignore unreadable */
+    }
+  }
+
+  for (const rule of FINDINGS) {
+    const matched = rule.patterns.find((p) => corpus.includes(p))
+    if (matched) {
+      hits.push({
+        id: rule.id,
+        severity: rule.severity,
+        pattern: matched,
+        advice: rule.advice,
+      })
+    }
+  }
+
+  return hits
+}
+
+const CHECKLIST = `# Aeon migration checklist
+
+Generated by \`npx aeon-ui migrate\`.
+
+## Install
+
+\`\`\`bash
+npm install aeon-ui-engine@^1.4.0 react react-dom xstate @xstate/react
+\`\`\`
+
+\`\`\`ts
+import 'aeon-ui-engine/aeon.css'
+\`\`\`
+
+## Agent setup
+
+\`\`\`bash
+npx aeon-ui init
+\`\`\`
+
+Paste \`aeon.cursorrules.md\` into Cursor rules. Keep domain machines in the app; use Aeon for chrome + interactive primitives.
+
+## Statechart-first rule
+
+1. Model interaction with an XState machine (or reuse Aeon machines).
+2. Project \`snapshot\` → \`data-aeon-state\` / compound parts.
+3. Do not invent parallel booleans for chart-owned concerns.
+
+## New primitives (1.4+)
+
+| Need | Use |
+|------|-----|
+| Two-thumb range | \`RangeSlider\` + \`rangeSliderMachine\` |
+| Link styled as button | \`<Button.Root asChild><Link/></Button.Root>\` |
+| Drag-drop file surface | \`FileUpload\` + \`fileUploadMachine\` |
+| Toast | \`Toast.Provider\` + \`useToast()\` |
+| Confirm sheet | \`Prompt\` / \`Dialog\` |
+
+## Docs
+
+- docs/MIGRATION.md (in aeon-ui-engine / AeonUI repo)
+- docs/MIGRATION_FROM_ARK.md
+- AGENTS.md
+`
+
+export function migrateAeon(options: MigrateOptions = {}) {
+  const cwd = options.cwd ?? process.cwd()
+  const write = options.write ?? true
+  const findings = walkHints(cwd)
+  const written: string[] = []
+
+  if (write) {
+    const path = join(cwd, 'AEON_MIGRATION_CHECKLIST.md')
+    const findingsBlock =
+      findings.length === 0
+        ? '\n## Scan results\n\nNo known local workarounds detected in the quick scan.\n'
+        : `\n## Scan results\n\n${findings
+            .map((f) => `- **${f.severity}** \`${f.id}\` (matched \`${f.pattern}\`): ${f.advice}`)
+            .join('\n')}\n`
+    writeFileSync(path, `${CHECKLIST.trim()}\n${findingsBlock}`)
+    written.push('write AEON_MIGRATION_CHECKLIST.md')
+  }
+
+  return { cwd, written, findings }
+}