aeon-ui-engine 1.0.3 → 1.2.0

package/packages/cli/node_modules/.bin/tsup-node

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules/tsup/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules/tsup/dist/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules/tsup/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.3_typescript@5.9.3/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsup/dist/cli-node.js" "$@"
+else
+  exec node  "$basedir/../tsup/dist/cli-node.js" "$@"
+fi

package/packages/cli/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/dist/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsx@4.22.3/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/dist/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/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/../../../../node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/tsx@4.22.3/node_modules/tsx/dist/cli.mjs" "$@"
+fi

package/packages/cli/node_modules/.bin/vite

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/bin/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/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/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/bin/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/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/../../../../node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/bin/vite.js" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.27.7_jiti@2.7.0_tsx@4.22.3/node_modules/vite/bin/vite.js" "$@"
+fi

package/packages/cli/node_modules/.bin/vitest

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+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"
+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"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/packages/cli/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@aeon-ui/cli",
+  "version": "0.1.0",
+  "description": "AI-optimized CLI for injecting Aeon UI agent rules, schemas, and starter code",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GenericCPU/aeon-ui.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "keywords": [
+    "aeon-ui",
+    "cli",
+    "cursor",
+    "generative-ui",
+    "ai"
+  ],
+  "type": "module",
+  "bin": {
+    "aeon-ui": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/bin.ts src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aeon-ui/schemas": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.8"
+  }
+}

package/packages/cli/src/bin.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { initAeon } from './init.js'
+
+const args = process.argv.slice(2)
+const cmd = args[0] ?? 'help'
+const force = args.includes('--force') || args.includes('-f')
+
+function help() {
+  console.log(`aeon-ui — AI-optimized CLI for Aeon UI
+
+Usage:
+  npx aeon-ui init [--force]
+
+Commands:
+  init    Inject Cursor rules, JSON schemas, system prompt, and a starter component
+  help    Show this message
+
+Options:
+  --force, -f   Overwrite existing generated files
+`)
+}
+
+if (cmd === 'init') {
+  const result = initAeon({ force })
+  console.log(`Aeon UI init → ${result.cwd}`)
+  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 {
+  help()
+  if (cmd !== 'help' && cmd !== '--help' && cmd !== '-h') {
+    process.exitCode = 1
+  }
+}

package/packages/cli/src/index.ts

@@ -0,0 +1 @@
+export { initAeon, type InitOptions } from './init.js'

package/packages/cli/src/init.ts

@@ -0,0 +1,107 @@
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  CURSOR_RULES_SNIPPET,
+  AEON_SYSTEM_PROMPT,
+  catalog,
+  componentSchemas,
+} from '@aeon-ui/schemas'
+
+export type InitOptions = {
+  cwd?: string
+  force?: boolean
+}
+
+const STARTER = `/**
+ * Aeon UI starter — generated by \`npx aeon-ui init\`
+ * Headless: @aeon-ui/react · Styled: @aeon-ui/ui · 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>
+  )
+}
+`
+
+export function initAeon(options: InitOptions = {}) {
+  const cwd = options.cwd ?? process.cwd()
+  const force = options.force ?? false
+  const written: string[] = []
+
+  const write = (rel: string, body: string) => {
+    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}\n`)
+    written.push(`write ${rel}`)
+  }
+
+  write('.cursor/rules/aeon-ui.mdc', `---
+description: Aeon UI — 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()}\n`)
+  write('aeon.system-prompt.md', `${AEON_SYSTEM_PROMPT.trim()}\n`)
+  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,
+    )}\n`,
+  )
+
+  for (const [id, schema] of Object.entries(componentSchemas)) {
+    write(`aeon.schemas/components/${id}.json`, `${JSON.stringify(schema, null, 2)}\n`)
+  }
+
+  write('src/components/AeonStarter.tsx', STARTER)
+
+  write(
+    'AEON_AI.md',
+    `# Aeon UI — 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)** — never invent boolean combinations for states the schema does not list.
+`,
+  )
+
+  return { cwd, written }
+}

package/packages/cli/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/packages/core/README.md

@@ -51,10 +51,16 @@ partAttrs(asyncAnatomy.scope, asyncAnatomy.readout, {
 ## Parallel regions
 
 ```ts
-import { stateToAttr } from '@aeon-ui/core'
+import { fieldFace, fieldRegions, stateToAttr } from '@aeon-ui/core'
 
+// Debug / serialization — not product UI labels
 stateToAttr({ interaction: 'dirty', validation: 'invalid', submission: 'idle' })
 // → "interaction:dirty validation:invalid submission:idle"
+
+// Field DOM face (same hierarchy as Button status)
+fieldFace({ interaction: 'dirty', validation: 'invalid', submission: 'idle' }) // "invalid"
+fieldRegions({ interaction: 'dirty', validation: 'invalid', submission: 'idle' })
+// → { interaction: "dirty", validation: "invalid", submission: "idle" }
 ```
 
 ## Adding a scope

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

@@ -26,6 +26,25 @@ declare const checkboxAnatomy: Record<"root" | "label" | "control" | "hiddenInpu
 declare const dialogAnatomy: Record<"root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger", "root" | "trigger" | "portal" | "backdrop" | "positioner" | "content" | "title" | "description" | "closeTrigger"> & {
     scope: string;
 };
+/**
+ * Prompt — confirm / permission / update-style dialog on top of Dialog.
+ * Universal parts: eyebrow, meta, amount, actions (primary + secondary).
+ */
+declare const promptAnatomy: Record<"root" | "eyebrow" | "meta" | "amount" | "actions" | "primary" | "secondary", "root" | "eyebrow" | "meta" | "amount" | "actions" | "primary" | "secondary"> & {
+    scope: string;
+};
+/**
+ * AppNav — section + detail stack (list→detail, settings drill-in).
+ */
+declare const appNavAnatomy: Record<"root" | "rail" | "section" | "stage" | "breadcrumb" | "crumb" | "back", "root" | "rail" | "section" | "stage" | "breadcrumb" | "crumb" | "back"> & {
+    scope: string;
+};
+/**
+ * StatusBanner — non-blocking top-of-app notice (update ready, syncing, offline).
+ */
+declare const statusBannerAnatomy: Record<"root" | "title" | "actions" | "copy" | "body", "root" | "title" | "actions" | "copy" | "body"> & {
+    scope: string;
+};
 declare const tabsAnatomy: Record<"root" | "indicator" | "trigger" | "content" | "list", "root" | "indicator" | "trigger" | "content" | "list"> & {
     scope: string;
 };
@@ -33,7 +52,7 @@ declare const accordionAnatomy: Record<"root" | "item" | "itemTrigger" | "itemCo
     scope: string;
 };
 /** Async data region — track shows every lifecycle state; readout + actions mirror snapshot. */
-declare const asyncAnatomy: Record<"root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions", "root" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody" | "actions"> & {
+declare const asyncAnatomy: Record<"root" | "actions" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody", "root" | "actions" | "track" | "segment" | "readout" | "readoutRail" | "readoutBody"> & {
     scope: string;
 };
 /** Form field — orthogonal interaction × validation × submission (see STATES.md). */
@@ -45,10 +64,10 @@ declare const scrollAnatomy: Record<"root" | "content" | "viewport", "root" | "c
     scope: string;
 };
 /**
- * Play / game surface — mat shell with table, dice, and bank regions.
- * Use with normalized layout coords (@see docs/LAYOUT_COORDINATES.md).
+ * Spatial play surface — universal mat + regions + entities (not a specific game).
+ * App logic names regions; entity labels come from compose `items`. See LAYOUT_COORDINATES.md.
  */
-declare const playSurfaceAnatomy: Record<"mat" | "table" | "dice" | "bank", "mat" | "table" | "dice" | "bank"> & {
+declare const playSurfaceAnatomy: Record<"root" | "mat" | "region" | "entity", "root" | "mat" | "region" | "entity"> & {
     scope: string;
 };
 declare const selectAnatomy: Record<"root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value", "root" | "icon" | "trigger" | "positioner" | "content" | "item" | "value"> & {
@@ -70,8 +89,65 @@ declare const tooltipAnatomy: Record<"root" | "trigger" | "positioner" | "conten
 declare const toastAnatomy: Record<"root" | "title" | "description" | "closeTrigger" | "viewport", "root" | "title" | "description" | "closeTrigger" | "viewport"> & {
     scope: string;
 };
-/** Profile image — loaded / loading / error on root `data-aeon-state`. */
-declare const avatarAnatomy: Record<"root" | "image" | "fallback", "root" | "image" | "fallback"> & {
+/** Profile image — loaded / loading / error on root `data-aeon-state`. Badge = presence / status corner. */
+declare const avatarAnatomy: Record<"root" | "image" | "fallback" | "badge", "root" | "image" | "fallback" | "badge"> & {
+    scope: string;
+};
+/**
+ * Identity strip — avatar + primary/secondary text (items-market AvatarWithName).
+ * Presentational; compose into ProfileHeader / ListRow / AccountCluster.
+ */
+declare const identityAnatomy: Record<"root" | "title" | "meta" | "avatar" | "subtitle" | "trailing", "root" | "title" | "meta" | "avatar" | "subtitle" | "trailing"> & {
+    scope: string;
+};
+/**
+ * Profile header — dense account hero (not dating). Media optional; metrics + actions zones.
+ * Spatial: identity leading, metrics inline, actions trailing / bottom leading pair.
+ */
+declare const profileHeaderAnatomy: Record<"root" | "actions" | "body" | "identity" | "media" | "metrics", "root" | "actions" | "body" | "identity" | "media" | "metrics"> & {
+    scope: string;
+};
+/**
+ * Entry — compact multi-value content card (feed post, catalog listing, activity item).
+ * Universal layout only — not a social/marketplace niche.
+ * List stacks cards; Root is one card (idle | selected | muted).
+ * Zones: header (leading · heading · meta) · media · body · values · actions · footer.
+ */
+declare const entryAnatomy: Record<"values" | "root" | "title" | "meta" | "actions" | "body" | "list" | "value" | "subtitle" | "media" | "header" | "leading" | "heading" | "footer", "values" | "root" | "title" | "meta" | "actions" | "body" | "list" | "value" | "subtitle" | "media" | "header" | "leading" | "heading" | "footer"> & {
+    scope: string;
+};
+/**
+ * Metric strip — ultra-dense value/label chips (items-market im-stat cluster).
+ * Generic stats only — not wallet/currency product niches.
+ */
+declare const metricStripAnatomy: Record<"root" | "label" | "value" | "chip", "root" | "label" | "value" | "chip"> & {
+    scope: string;
+};
+/**
+ * List row — settings / account menu row (h-12 hit target, leading icon, trailing control).
+ */
+declare const listRowAnatomy: Record<"root" | "label" | "description" | "trailing" | "leading", "root" | "label" | "description" | "trailing" | "leading"> & {
+    scope: string;
+};
+/**
+ * Conversation — inbox / DM list row (universal messaging chrome, not dating).
+ * Leading avatar · title · preview · meta (time) · badge (unread).
+ * Item state: idle | unread | selected.
+ */
+declare const conversationAnatomy: Record<"root" | "title" | "meta" | "body" | "item" | "badge" | "leading" | "preview", "root" | "title" | "meta" | "body" | "item" | "badge" | "leading" | "preview"> & {
+    scope: string;
+};
+/**
+ * Thread — message stream. Items project mine | theirs | pending | failed.
+ */
+declare const threadAnatomy: Record<"root" | "meta" | "list" | "item" | "bubble" | "day", "root" | "meta" | "list" | "item" | "bubble" | "day"> & {
+    scope: string;
+};
+/**
+ * Composer — bottom compose chrome for threads (input + send).
+ * Root state: idle | sending | disabled | error.
+ */
+declare const composerAnatomy: Record<"root" | "actions" | "input" | "send", "root" | "actions" | "input" | "send"> & {
     scope: string;
 };
 declare const separatorAnatomy: Record<"root", "root"> & {
@@ -90,6 +166,50 @@ declare const sliderAnatomy: Record<"root" | "thumb" | "track" | "range" | "valu
 declare const pinInputAnatomy: Record<"root" | "input", "root" | "input"> & {
     scope: string;
 };
+/**
+ * Bar — horizontal layout primitive for toolbars, headers, footers.
+ * Enforces safe flex behavior: no overlap, responsive collapse via overflow.
+ * Parts: root (flex row), leading, center, trailing, optional seam (sticky stack join).
+ * Drive sticky lifecycle with stickyBarMachine → data-aeon-state on root.
+ */
+declare const barAnatomy: Record<"root" | "trailing" | "leading" | "center" | "seam", "root" | "trailing" | "leading" | "center" | "seam"> & {
+    scope: string;
+};
+/**
+ * Panel — collapsible layout region for split views.
+ * Group lays out siblings; Root is expanded|collapsed; Label rails vertically when collapsed.
+ */
+declare const panelAnatomy: Record<"root" | "group" | "label" | "trigger" | "content", "root" | "group" | "label" | "trigger" | "content"> & {
+    scope: string;
+};
+/**
+ * App shell — layered application chrome (items-market MainLayout pattern).
+ * header / subheader / content / aside / footer / dock / scrim under root.
+ */
+declare const appShellAnatomy: Record<"root" | "content" | "header" | "footer" | "subheader" | "aside" | "dock" | "scrim", "root" | "content" | "header" | "footer" | "subheader" | "aside" | "dock" | "scrim"> & {
+    scope: string;
+};
+/**
+ * Content region — status-slotted body. Every contentRegionMachine state has a part.
+ * Pair with Async for fetch; use slots for idle/pending/empty/error/ready/loadingMore/success.
+ */
+declare const contentAnatomy: Record<"root" | "body" | "empty" | "toolbar" | "pending" | "error" | "success" | "sentinel", "root" | "body" | "empty" | "toolbar" | "pending" | "error" | "success" | "sentinel"> & {
+    scope: string;
+};
+/**
+ * Nav — navigational collection (top links, bottom tabs, side rail).
+ * Selection reuses tabsMachine; items project inactive|active|disabled.
+ */
+declare const navAnatomy: Record<"root" | "label" | "icon" | "indicator" | "item" | "badge", "root" | "label" | "icon" | "indicator" | "item" | "badge"> & {
+    scope: string;
+};
+/**
+ * ThemeSwitcher — mode toggle (light/dark) + theme preset selector.
+ * Parts: root, modes (button group), modeBtn, themeSelect, themeTrigger.
+ */
+declare const themeSwitcherAnatomy: Record<"root" | "modes" | "modeBtn" | "themeSelect" | "themeTrigger", "root" | "modes" | "modeBtn" | "themeSelect" | "themeTrigger"> & {
+    scope: string;
+};
 
 type AttrOptions = {
     state?: string | string[];
@@ -108,6 +228,30 @@ type AeonSnapshot<M extends AnyStateMachine> = SnapshotFrom<M>;
 type AeonActor<M extends AnyStateMachine> = ActorRefFrom<M>;
 /** Flatten nested state value for data-aeon-state attribute. */
 declare function stateToAttr(value: unknown): string;
+/**
+ * Primary visual face for parallel field charts — same hierarchy as Button/Dialog:
+ * one leaf on `data-aeon-state`, not a region dump.
+ * Priority: pending > invalid > dirty > idle.
+ */
+type FieldFace = 'idle' | 'dirty' | 'invalid' | 'pending';
+declare function fieldFace(value: unknown): FieldFace;
+/** Orthogonal field regions for advanced CSS (`data-aeon-interaction`, etc.). */
+declare function fieldRegions(value: unknown): {
+    interaction: string;
+    validation: string;
+    submission: string;
+};
+/** Read one region from a (possibly parallel) snapshot value. */
+declare function getRegionValue(value: unknown, region: string): unknown;
+/**
+ * Active path under a region — e.g. `{ deck: { ready: 'matched' } }` →
+ * `regionPath(v, 'deck')` → `['ready', 'matched']`.
+ */
+declare function regionPath(value: unknown, region: string): string[];
+/** Deepest active key under a region (`['ready','matched']` → `'matched'`). */
+declare function regionLeaf(value: unknown, region: string): string | undefined;
+/** True when the region path equals or ends with the given leaf / path prefix. */
+declare function regionMatches(value: unknown, region: string, match: string | readonly string[]): boolean;
 
 /** Stable conditions the machine may occupy — mutually exclusive at a given depth. */
 type AeonStateValue = string | {
@@ -253,5 +397,109 @@ declare function syncAeonColorMode(root: HTMLElement, mode: AeonColorMode, optio
 }): void;
 /** Cross-fade theme changes when View Transitions API is available. */
 declare function runAeonThemeTransition(apply: () => void): void;
+type AeonPalette = {
+    bg: string;
+    surface: string;
+    surfaceRaised: string;
+    border: string;
+    text: string;
+    muted: string;
+    accent: string;
+    accentDim: string;
+    danger: string;
+    dangerDim: string;
+    focusRing: string;
+    gridLine: string;
+};
+interface AeonThemeDefinition {
+    id: string;
+    label: string;
+    description: string;
+    light: AeonPalette;
+    dark: AeonPalette;
+}
+/**
+ * Register theme definitions. Call once at app init.
+ * Returns the registered themes array and lookup map.
+ */
+declare function registerAeonThemes(themes: AeonThemeDefinition[]): {
+    themes: AeonThemeDefinition[];
+    map: Record<string, AeonThemeDefinition>;
+    ids: string[];
+};
+declare function isAeonThemeId(value: string): boolean;
+declare function isAeonMode(value: string): value is AeonColorMode;
+/**
+ * Apply a theme + mode to `<html>`. Persists to localStorage.
+ */
+declare function applyAeonTheme(themeId: string, mode: AeonColorMode, themeMap?: Record<string, AeonThemeDefinition>): void;
+/**
+ * Read saved prefs or system preference, apply to `<html>`, return current values.
+ */
+declare function initAeonTheme(themeMap?: Record<string, AeonThemeDefinition>): {
+    themeId: string;
+    mode: AeonColorMode;
+};
+
+/**
+ * Brand → Aeon CSS variable bridge.
+ *
+ * Product apps often already have design tokens. Instead of maintaining a parallel
+ * `--product-*` layer forever, map them onto Aeon’s runtime vars so `@aeon-ui/ui`
+ * recipes and `aeon.css` pick up the brand without forking Panda.
+ */
+
+/** Minimal brand fields — anything omitted gets a safe default. */
+type BrandPaletteInput = {
+    bg: string;
+    surface: string;
+    surfaceRaised?: string;
+    border: string;
+    text: string;
+    muted: string;
+    accent: string;
+    accentDim?: string;
+    danger?: string;
+    dangerDim?: string;
+    gridLine?: string;
+    /** Optional product fonts (applied as --aeon-font / --aeon-font-display). */
+    font?: string;
+    fontDisplay?: string;
+    radius?: string;
+};
+type BrandPalette = Required<Pick<BrandPaletteInput, 'bg' | 'surface' | 'surfaceRaised' | 'border' | 'text' | 'muted' | 'accent' | 'accentDim' | 'danger' | 'dangerDim' | 'gridLine'>> & {
+    font?: string;
+    fontDisplay?: string;
+    radius?: string;
+    focusRing: string;
+};
+/** Normalize a partial brand palette into a full Aeon-compatible palette. */
+declare function normalizeBrandPalette(input: BrandPaletteInput, mode?: AeonColorMode): BrandPalette;
+/** CSS custom properties Aeon recipes already read. */
+declare function brandPaletteToCssVars(palette: BrandPalette): Record<string, string>;
+type ApplyBrandPaletteOptions = {
+    mode?: AeonColorMode;
+    /** Theme id stamped on <html> (default: `brand`). */
+    themeId?: string;
+    /** Persist mode/theme to localStorage (default: false — brand apps usually own prefs). */
+    persist?: boolean;
+    root?: HTMLElement;
+};
+/**
+ * Apply a product brand palette to the document so Aeon CSS vars match the app.
+ * Does not require registering a catalog theme — one call at boot is enough.
+ *
+ * @example
+ * applyBrandPalette({
+ *   bg: '#000', surface: '#0a0a0a', border: '#262626',
+ *   text: '#fafafa', muted: '#a1a1aa', accent: '#57ff97',
+ * }, { mode: 'dark' })
+ */
+declare function applyBrandPalette(input: BrandPaletteInput, options?: ApplyBrandPaletteOptions): BrandPalette;
+/** Serialize palette vars for injecting a `<style>` tag (SSR / non-DOM). */
+declare function brandPaletteToCssText(input: BrandPaletteInput, options?: {
+    mode?: AeonColorMode;
+    selector?: string;
+}): string;
 
-export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonSnapshot, type AeonStateValue, DEFAULT_COMPACT_MQ, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, asyncAnatomy, avatarAnatomy, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, dialogAnatomy, fieldAnatomy, getCompactMq, getScrollSnapshot, insetNormCluster, isAeonColorMode, layoutCompositionForMode, layoutModeAttrs, matchLayoutMode, measureElement, menuAnatomy, normFromClient, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, progressAnatomy, radioGroupAnatomy, regionBoundsForMode, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, switchAnatomy, syncAeonColorMode, tabsAnatomy, toastAnatomy, tooltipAnatomy };
+export { AEON_PRINCIPLE, AEON_THEME_TRANSITION_CLASS, type AeonActor, type AeonColorMode, type AeonContext, type AeonDataAttrs, type AeonEvent, type AeonPalette, type AeonSnapshot, type AeonStateValue, type AeonThemeDefinition, type ApplyBrandPaletteOptions, type BrandPalette, type BrandPaletteInput, DEFAULT_COMPACT_MQ, type FieldFace, type LayoutComposition, type LayoutCompositionSpec, type LayoutMode, NORM_PLANE, type NormOrigin, type NormPoint, type NormRect, type RegionLayoutSlot, type ResponsiveLayoutSpec, type ScrollOverflow, type ScrollSnapshot, UI_IS_FUNCTION_OF_STATE, accordionAnatomy, anatomy, appNavAnatomy, appShellAnatomy, applyAeonTheme, applyBrandPalette, asyncAnatomy, avatarAnatomy, barAnatomy, brandPaletteToCssText, brandPaletteToCssVars, buttonAnatomy, checkboxAnatomy, clampNorm, clientFromNorm, comboboxAnatomy, composerAnatomy, contentAnatomy, conversationAnatomy, dialogAnatomy, entryAnatomy, fieldAnatomy, fieldFace, fieldRegions, getCompactMq, getRegionValue, getScrollSnapshot, identityAnatomy, initAeonTheme, insetNormCluster, isAeonColorMode, isAeonMode, isAeonThemeId, layoutCompositionForMode, layoutModeAttrs, listRowAnatomy, matchLayoutMode, measureElement, menuAnatomy, metricStripAnatomy, navAnatomy, normFromClient, normalizeBrandPalette, panelAnatomy, partAttrs, partOnlyAttrs, pinInputAnatomy, playSurfaceAnatomy, popoverAnatomy, profileHeaderAnatomy, progressAnatomy, promptAnatomy, radioGroupAnatomy, regionBoundsForMode, regionLeaf, regionMatches, regionPath, registerAeonThemes, resolveAeonColorMode, resolveRegionRect, runAeonThemeTransition, scopeAttrs, scrollAnatomy, selectAnatomy, separatorAnatomy, sliderAnatomy, stateToAttr, statusBannerAnatomy, switchAnatomy, syncAeonColorMode, tabsAnatomy, themeSwitcherAnatomy, threadAnatomy, toastAnatomy, tooltipAnatomy };