aeon-ui-engine 1.0.2 → 1.1.0

package/packages/core/node_modules/.bin/tsserver

@@ -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/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/typescript@5.9.3/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/brandoncryderman/AeonUI/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/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/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/packages/core/node_modules/.bin/tsup

@@ -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-default.js" "$@"
+else
+  exec node  "$basedir/../tsup/dist/cli-default.js" "$@"
+fi

package/packages/core/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/core/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/core/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.28.0_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.28.0_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.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/vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_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.28.0_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.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/../../../../node_modules/.pnpm/vite@8.0.16_@types+node@22.19.19_esbuild@0.28.0_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.28.0_jiti@2.7.0_tsx@4.22.3/node_modules/vite/bin/vite.js" "$@"
+fi

package/packages/core/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.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.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" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

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

@@ -0,0 +1 @@
+{"version":"3.2.4","results":[[":src/machine.test.ts",{"duration":2.8135839999999916,"failed":false}],[":src/theme.test.ts",{"duration":2.691708999999989,"failed":false}],[":../../apps/demo/src/aeonSchemaCompiler.test.ts",{"duration":7.737041999999974,"failed":false}]]}

package/packages/core/package.json

@@ -8,9 +8,21 @@
     "url": "https://github.com/GenericCPU/aeon-ui.git",
     "directory": "packages/core"
   },
-  "publishConfig": { "access": "public" },
-  "files": ["dist", "theme-transition.css", "README.md"],
-  "keywords": ["aeon-ui", "statechart", "xstate", "headless", "anatomy"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "theme-transition.css",
+    "README.md"
+  ],
+  "keywords": [
+    "aeon-ui",
+    "statechart",
+    "xstate",
+    "headless",
+    "anatomy"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,11 +39,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "xstate": "^5.19.2"
+    "xstate": "^5.32.0"
   },
   "devDependencies": {
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }

package/packages/core/src/anatomy.ts

@@ -81,10 +81,10 @@ export const fieldAnatomy = anatomy('field', [
 export const scrollAnatomy = anatomy('scroll', ['root', 'viewport', 'content'] as const)
 
 /**
- * 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.
  */
-export const playSurfaceAnatomy = anatomy('play', ['mat', 'table', 'dice', 'bank'] as const)
+export const playSurfaceAnatomy = anatomy('play', ['root', 'mat', 'region', 'entity'] as const)
 
 export const selectAnatomy = anatomy('select', [
   'root',
@@ -140,8 +140,118 @@ export const toastAnatomy = anatomy('toast', [
   'closeTrigger',
 ] as const)
 
-/** Profile image — loaded / loading / error on root `data-aeon-state`. */
-export const avatarAnatomy = anatomy('avatar', ['root', 'image', 'fallback'] as const)
+/** Profile image — loaded / loading / error on root `data-aeon-state`. Badge = presence / status corner. */
+export const avatarAnatomy = anatomy('avatar', ['root', 'image', 'fallback', 'badge'] as const)
+
+/**
+ * Identity strip — avatar + primary/secondary text (items-market AvatarWithName).
+ * Presentational; compose into ProfileHeader / ListRow / AccountCluster.
+ */
+export const identityAnatomy = anatomy('identity', [
+  'root',
+  'avatar',
+  'title',
+  'subtitle',
+  'meta',
+  'trailing',
+] as const)
+
+/**
+ * Profile header — dense account hero (not dating). Media optional; metrics + actions zones.
+ * Spatial: identity leading, metrics inline, actions trailing / bottom leading pair.
+ */
+export const profileHeaderAnatomy = anatomy('profileHeader', [
+  'root',
+  'media',
+  'identity',
+  'metrics',
+  'actions',
+  'body',
+] as const)
+
+/**
+ * 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.
+ */
+export const entryAnatomy = anatomy('entry', [
+  'list',
+  'root',
+  'header',
+  'leading',
+  'heading',
+  'title',
+  'subtitle',
+  'meta',
+  'media',
+  'body',
+  'values',
+  'value',
+  'actions',
+  'footer',
+] as const)
+
+/**
+ * Metric strip — ultra-dense value/label chips (items-market im-stat cluster).
+ * Generic stats only — not wallet/currency product niches.
+ */
+export const metricStripAnatomy = anatomy('metricStrip', [
+  'root',
+  'chip',
+  'value',
+  'label',
+] as const)
+
+/**
+ * List row — settings / account menu row (h-12 hit target, leading icon, trailing control).
+ */
+export const listRowAnatomy = anatomy('listRow', [
+  'root',
+  'leading',
+  'label',
+  'description',
+  'trailing',
+] as const)
+
+/**
+ * Conversation — inbox / DM list row (universal messaging chrome, not dating).
+ * Leading avatar · title · preview · meta (time) · badge (unread).
+ * Item state: idle | unread | selected.
+ */
+export const conversationAnatomy = anatomy('conversation', [
+  'root',
+  'item',
+  'leading',
+  'body',
+  'title',
+  'preview',
+  'meta',
+  'badge',
+] as const)
+
+/**
+ * Thread — message stream. Items project mine | theirs | pending | failed.
+ */
+export const threadAnatomy = anatomy('thread', [
+  'root',
+  'list',
+  'item',
+  'bubble',
+  'meta',
+  'day',
+] as const)
+
+/**
+ * Composer — bottom compose chrome for threads (input + send).
+ * Root state: idle | sending | disabled | error.
+ */
+export const composerAnatomy = anatomy('composer', [
+  'root',
+  'input',
+  'actions',
+  'send',
+] as const)
 
 export const separatorAnatomy = anatomy('separator', ['root'] as const)
 
@@ -165,3 +275,84 @@ export const sliderAnatomy = anatomy('slider', [
 ] as const)
 
 export const pinInputAnatomy = anatomy('pinInput', ['root', 'input'] as const)
+
+/**
+ * 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.
+ */
+export const barAnatomy = anatomy('bar', [
+  'root',
+  'leading',
+  'center',
+  'trailing',
+  'seam',
+] as const)
+
+/**
+ * Panel — collapsible layout region for split views.
+ * Group lays out siblings; Root is expanded|collapsed; Label rails vertically when collapsed.
+ */
+export const panelAnatomy = anatomy('panel', [
+  'group',
+  'root',
+  'trigger',
+  'label',
+  'content',
+] as const)
+
+/**
+ * App shell — layered application chrome (items-market MainLayout pattern).
+ * header / subheader / content / aside / footer / dock / scrim under root.
+ */
+export const appShellAnatomy = anatomy('appShell', [
+  'root',
+  'header',
+  'subheader',
+  'content',
+  'aside',
+  'footer',
+  'dock',
+  'scrim',
+] as const)
+
+/**
+ * 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.
+ */
+export const contentAnatomy = anatomy('content', [
+  'root',
+  'toolbar',
+  'body',
+  'pending',
+  'empty',
+  'error',
+  'success',
+  'sentinel',
+] as const)
+
+/**
+ * Nav — navigational collection (top links, bottom tabs, side rail).
+ * Selection reuses tabsMachine; items project inactive|active|disabled.
+ */
+export const navAnatomy = anatomy('nav', [
+  'root',
+  'item',
+  'indicator',
+  'label',
+  'icon',
+  'badge',
+] as const)
+
+/**
+ * ThemeSwitcher — mode toggle (light/dark) + theme preset selector.
+ * Parts: root, modes (button group), modeBtn, themeSelect, themeTrigger.
+ */
+export const themeSwitcherAnatomy = anatomy('themeSwitcher', [
+  'root',
+  'modes',
+  'modeBtn',
+  'themeSelect',
+  'themeTrigger',
+] as const)

package/packages/core/src/machine.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest'
-import { stateToAttr } from './machine.js'
+import {
+  fieldFace,
+  fieldRegions,
+  getRegionValue,
+  regionLeaf,
+  regionMatches,
+  regionPath,
+  stateToAttr,
+} from './machine.js'
 
 describe('stateToAttr', () => {
   it('stringifies string states', () => {
@@ -16,3 +24,56 @@ describe('stateToAttr', () => {
     ).toBe('interaction:dirty validation:invalid submission:idle')
   })
 })
+
+describe('fieldFace', () => {
+  it('projects a single leaf face (pending > invalid > dirty > idle)', () => {
+    expect(fieldFace({ interaction: 'pristine', validation: 'valid', submission: 'idle' })).toBe(
+      'idle',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'valid', submission: 'idle' })).toBe(
+      'dirty',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'invalid', submission: 'idle' })).toBe(
+      'invalid',
+    )
+    expect(fieldFace({ interaction: 'dirty', validation: 'valid', submission: 'pending' })).toBe(
+      'pending',
+    )
+  })
+
+  it('exposes orthogonal regions separately', () => {
+    expect(
+      fieldRegions({ interaction: 'dirty', validation: 'invalid', submission: 'idle' }),
+    ).toEqual({
+      interaction: 'dirty',
+      validation: 'invalid',
+      submission: 'idle',
+    })
+  })
+})
+
+describe('region helpers', () => {
+  const value = {
+    session: { authenticating: 'verifyCode' },
+    route: 'discover',
+    deck: { ready: 'matched' },
+  }
+
+  it('reads a region value', () => {
+    expect(getRegionValue(value, 'route')).toBe('discover')
+    expect(getRegionValue(value, 'deck')).toEqual({ ready: 'matched' })
+  })
+
+  it('walks compound paths to a leaf', () => {
+    expect(regionPath(value, 'deck')).toEqual(['ready', 'matched'])
+    expect(regionLeaf(value, 'deck')).toBe('matched')
+    expect(regionLeaf(value, 'session')).toBe('verifyCode')
+    expect(regionLeaf(value, 'route')).toBe('discover')
+  })
+
+  it('matches leaves and path prefixes', () => {
+    expect(regionMatches(value, 'deck', 'matched')).toBe(true)
+    expect(regionMatches(value, 'deck', ['ready', 'matched'])).toBe(true)
+    expect(regionMatches(value, 'deck', 'loading')).toBe(false)
+  })
+})

package/packages/core/src/machine.ts

@@ -13,3 +13,96 @@ export function stateToAttr(value: unknown): string {
     .map(([k, v]) => `${k}:${stateToAttr(v)}`)
     .join(' ')
 }
+
+/**
+ * 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.
+ */
+export type FieldFace = 'idle' | 'dirty' | 'invalid' | 'pending'
+
+export function fieldFace(value: unknown): FieldFace {
+  if (value == null || typeof value !== 'object') return 'idle'
+  const v = value as Record<string, unknown>
+  if (v.submission === 'pending') return 'pending'
+  if (v.validation === 'invalid') return 'invalid'
+  if (v.interaction === 'dirty') return 'dirty'
+  return 'idle'
+}
+
+/** Orthogonal field regions for advanced CSS (`data-aeon-interaction`, etc.). */
+export function fieldRegions(value: unknown): {
+  interaction: string
+  validation: string
+  submission: string
+} {
+  if (value == null || typeof value !== 'object') {
+    return { interaction: 'pristine', validation: 'valid', submission: 'idle' }
+  }
+  const v = value as Record<string, unknown>
+  return {
+    interaction: typeof v.interaction === 'string' ? v.interaction : 'pristine',
+    validation: typeof v.validation === 'string' ? v.validation : 'valid',
+    submission: typeof v.submission === 'string' ? v.submission : 'idle',
+  }
+}
+
+/** Read one region from a (possibly parallel) snapshot value. */
+export function getRegionValue(value: unknown, region: string): unknown {
+  if (value == null) return undefined
+  if (typeof value === 'string') return value === region ? value : undefined
+  if (typeof value === 'object') {
+    return (value as Record<string, unknown>)[region]
+  }
+  return undefined
+}
+
+/**
+ * Active path under a region — e.g. `{ deck: { ready: 'matched' } }` →
+ * `regionPath(v, 'deck')` → `['ready', 'matched']`.
+ */
+export function regionPath(value: unknown, region: string): string[] {
+  const path: string[] = []
+  let cur: unknown = getRegionValue(value, region)
+  while (cur != null) {
+    if (typeof cur === 'string') {
+      path.push(cur)
+      break
+    }
+    if (typeof cur !== 'object') break
+    const entries = Object.entries(cur as Record<string, unknown>)
+    if (entries.length === 0) break
+    if (entries.length > 1) {
+      path.push(entries.map(([k]) => k).sort().join('+'))
+      break
+    }
+    const [key, next] = entries[0]!
+    path.push(key)
+    cur = next
+  }
+  return path
+}
+
+/** Deepest active key under a region (`['ready','matched']` → `'matched'`). */
+export function regionLeaf(value: unknown, region: string): string | undefined {
+  const path = regionPath(value, region)
+  return path[path.length - 1]
+}
+
+/** True when the region path equals or ends with the given leaf / path prefix. */
+export function regionMatches(
+  value: unknown,
+  region: string,
+  match: string | readonly string[],
+): boolean {
+  const path = regionPath(value, region)
+  if (path.length === 0) return false
+  if (typeof match === 'string') {
+    return path.includes(match) || path[path.length - 1] === match
+  }
+  if (match.length === 0) return false
+  if (match.length <= path.length) {
+    return match.every((part, i) => path[i] === part)
+  }
+  return false
+}

package/packages/core/src/theme.ts

@@ -51,3 +51,108 @@ export function runAeonThemeTransition(apply: () => void): void {
 
   apply()
 }
+
+/* ------------------------------------------------------------------ */
+/*  Theme catalog — pure DOM runtime, no Panda dependency               */
+/* ------------------------------------------------------------------ */
+
+export 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
+}
+
+export interface AeonThemeDefinition {
+  id: string
+  label: string
+  description: string
+  light: AeonPalette
+  dark: AeonPalette
+}
+
+const STORAGE_THEME = 'aeon-theme'
+const STORAGE_MODE = 'aeon-mode'
+
+const DEFAULT_THEME_ID = 'default'
+const DEFAULT_MODE: AeonColorMode = 'dark'
+
+/**
+ * Register theme definitions. Call once at app init.
+ * Returns the registered themes array and lookup map.
+ */
+export function registerAeonThemes(themes: AeonThemeDefinition[]) {
+  const map = Object.fromEntries(themes.map((t) => [t.id, t])) as Record<string, AeonThemeDefinition>
+  const ids = themes.map((t) => t.id)
+  return { themes, map, ids }
+}
+
+export function isAeonThemeId(value: string): boolean {
+  return value !== undefined
+}
+
+export function isAeonMode(value: string): value is AeonColorMode {
+  return value === 'light' || value === 'dark'
+}
+
+/**
+ * Apply a theme + mode to `<html>`. Persists to localStorage.
+ */
+export function applyAeonTheme(
+  themeId: string,
+  mode: AeonColorMode,
+  themeMap?: Record<string, AeonThemeDefinition>,
+) {
+  const root = document.documentElement
+  root.dataset.aeonTheme = themeId
+  root.dataset.aeonMode = mode
+  root.style.colorScheme = mode
+
+  if (themeMap && themeMap[themeId]) {
+    const meta = document.querySelector('meta[name="theme-color"]')
+    if (meta) {
+      meta.setAttribute('content', themeMap[themeId][mode].bg)
+    }
+  }
+
+  try {
+    localStorage.setItem(STORAGE_THEME, themeId)
+    localStorage.setItem(STORAGE_MODE, mode)
+  } catch {
+    /* private mode */
+  }
+}
+
+/**
+ * Read saved prefs or system preference, apply to `<html>`, return current values.
+ */
+export function initAeonTheme(
+  themeMap?: Record<string, AeonThemeDefinition>,
+): { themeId: string; mode: AeonColorMode } {
+  let themeId = DEFAULT_THEME_ID
+  let mode: AeonColorMode = DEFAULT_MODE
+
+  try {
+    const storedTheme = localStorage.getItem(STORAGE_THEME)
+    const storedMode = localStorage.getItem(STORAGE_MODE)
+    if (storedTheme) themeId = storedTheme
+    if (storedMode && isAeonMode(storedMode)) {
+      mode = storedMode
+    } else if (!storedMode && window.matchMedia('(prefers-color-scheme: light)').matches) {
+      mode = 'light'
+    }
+  } catch {
+    if (window.matchMedia('(prefers-color-scheme: light)').matches) mode = 'light'
+  }
+
+  applyAeonTheme(themeId, mode, themeMap)
+  return { themeId, mode }
+}