aeon-ui-engine 1.0.3 → 1.2.0

package/packages/react/node_modules/.bin/esbuild

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

package/packages/react/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/react/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@3.2.4_@types+node@22.19.19_jiti@2.7.0_jsdom@26.1.0_lightningcss@1.32.0_tsx@4.22.3/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@3.2.4_@types+node@22.19.19_jiti@2.7.0_jsdom@26.1.0_lightningcss@1.32.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.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@3.2.4_@types+node@22.19.19_jiti@2.7.0_jsdom@26.1.0_lightningcss@1.32.0_tsx@4.22.3/node_modules/vitest/node_modules:/Users/brandoncryderman/AeonUI/node_modules/.pnpm/vitest@3.2.4_@types+node@22.19.19_jiti@2.7.0_jsdom@26.1.0_lightningcss@1.32.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.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" "$@"

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

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":src/select/select.test.tsx",{"duration":129.68645800000002,"failed":false}],[":src/dialog/dialog.test.tsx",{"duration":85.993334,"failed":false}],[":src/avatar/avatar.test.tsx",{"duration":55.48012499999993,"failed":false}],[":src/tooltip/tooltip.test.tsx",{"duration":139.61970800000006,"failed":false}],[":src/toast/toast.test.tsx",{"duration":78.39379199999996,"failed":false}]]}
+{"version":"3.2.4","results":[[":src/select/select.test.tsx",{"duration":226.72845800000005,"failed":false}],[":src/dialog/dialog.test.tsx",{"duration":181.9869580000002,"failed":false}],[":src/avatar/avatar.test.tsx",{"duration":144.93595800000003,"failed":false}],[":src/tooltip/tooltip.test.tsx",{"duration":226.42358300000024,"failed":false}],[":src/toast/toast.test.tsx",{"duration":126.48416699999984,"failed":false}]]}

package/packages/react/package.json

@@ -8,9 +8,20 @@
     "url": "https://github.com/GenericCPU/aeon-ui.git",
     "directory": "packages/react"
   },
-  "publishConfig": { "access": "public" },
-  "files": ["dist", "README.md"],
-  "keywords": ["aeon-ui", "react", "headless", "xstate", "statechart"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "aeon-ui",
+    "react",
+    "headless",
+    "xstate",
+    "statechart"
+  ],
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -29,8 +40,8 @@
   "dependencies": {
     "@aeon-ui/core": "workspace:*",
     "@aeon-ui/primitives": "workspace:*",
-    "@xstate/react": "^5.0.3",
-    "xstate": "^5.19.2"
+    "@xstate/react": "^6.1.0",
+    "xstate": "^5.32.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -42,11 +53,11 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",
-    "jsdom": "^26.1.0",
+    "jsdom": "^29.1.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }

package/packages/react/src/app-nav/index.tsx

@@ -0,0 +1,249 @@
+import {
+  appNavAnatomy,
+  partAttrs,
+  scopeAttrs,
+} from '@aeon-ui/core'
+import {
+  appNavChild,
+  appNavMachine,
+  appNavStateAttr,
+  type AppNavChild,
+  type AppNavContext,
+} from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+export type { AppNavChild, AppNavContext }
+
+interface AppNavContextValue {
+  section: string
+  stack: AppNavChild[]
+  child: AppNavChild | null
+  stateAttr: string
+  send: ReturnType<typeof useAeonMachine<typeof appNavMachine>>[1]
+  setSection: (section: string) => void
+  push: (child: AppNavChild) => void
+  replace: (child: AppNavChild) => void
+  pop: () => void
+  popTo: (id: string) => void
+  clear: () => void
+}
+
+const AppNavCtx = createContext<AppNavContextValue | null>(null)
+
+export function useAppNav() {
+  const ctx = useContext(AppNavCtx)
+  if (!ctx) throw new Error('AppNav parts must be used within AppNav.Root')
+  return ctx
+}
+
+/** Use the machine without the compound tree. */
+export function useAppNavMachine(input?: { section?: string; stack?: AppNavChild[] }) {
+  const [snapshot, send] = useAeonMachine(appNavMachine, {
+    input: { section: input?.section ?? 'home', stack: input?.stack ?? [] },
+  })
+  const section = snapshot.context.section
+  const stack = snapshot.context.stack
+  const child = appNavChild(snapshot.context)
+  const stateAttr = appNavStateAttr(snapshot.context)
+
+  return useMemo(
+    () => ({
+      section,
+      stack,
+      child,
+      stateAttr,
+      send,
+      setSection: (next: string) => send({ type: 'SET_SECTION', section: next }),
+      push: (next: AppNavChild) => send({ type: 'PUSH', child: next }),
+      replace: (next: AppNavChild) => send({ type: 'REPLACE', child: next }),
+      pop: () => send({ type: 'POP' }),
+      popTo: (id: string) => send({ type: 'POP_TO', id }),
+      clear: () => send({ type: 'CLEAR' }),
+      reset: (next: string) => send({ type: 'RESET', section: next }),
+    }),
+    [section, stack, child, stateAttr, send],
+  )
+}
+
+export interface AppNavRootProps extends HTMLAttributes<HTMLDivElement> {
+  defaultSection?: string
+  children?: ReactNode
+}
+
+const Root = forwardRef<HTMLDivElement, AppNavRootProps>(function AppNavRoot(
+  { defaultSection = 'home', children, ...rest },
+  ref,
+) {
+  const nav = useAppNavMachine({ section: defaultSection })
+
+  return (
+    <AppNavCtx.Provider value={nav}>
+      <div
+        ref={ref}
+        {...mergeProps(
+          scopeAttrs(appNavAnatomy.scope, appNavAnatomy.root, { state: nav.stateAttr }),
+          rest,
+        )}
+      >
+        {children}
+      </div>
+    </AppNavCtx.Provider>
+  )
+})
+
+const Rail = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function AppNavRail(props, ref) {
+  const { stateAttr } = useAppNav()
+  return (
+    <nav
+      ref={ref as never}
+      {...mergeProps(partAttrs(appNavAnatomy.scope, appNavAnatomy.rail, { state: stateAttr }), props)}
+    />
+  )
+})
+
+export interface AppNavSectionProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  value: string
+}
+
+const Section = forwardRef<HTMLButtonElement, AppNavSectionProps>(function AppNavSection(
+  { value, onClick, ...rest },
+  ref,
+) {
+  const { section, child, setSection } = useAppNav()
+  const isActive = section === value && !child
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-current={isActive ? 'page' : undefined}
+      data-aeon-value={value}
+      onClick={(e) => {
+        onClick?.(e)
+        if (e.defaultPrevented) return
+        setSection(value)
+      }}
+      {...mergeProps(
+        partAttrs(appNavAnatomy.scope, appNavAnatomy.section, {
+          state: section === value ? (child ? 'section-active' : 'active') : 'inactive',
+        }),
+        rest,
+      )}
+    />
+  )
+})
+
+const Stage = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function AppNavStage(
+  props,
+  ref,
+) {
+  const { stateAttr } = useAppNav()
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(partAttrs(appNavAnatomy.scope, appNavAnatomy.stage, { state: stateAttr }), props)}
+    />
+  )
+})
+
+export interface AppNavBreadcrumbProps extends HTMLAttributes<HTMLElement> {
+  /** Labels for section + each stack entry (length = 1 + stack.length). */
+  labels?: string[]
+}
+
+const Breadcrumb = forwardRef<HTMLElement, AppNavBreadcrumbProps>(function AppNavBreadcrumb(
+  { labels, ...rest },
+  ref,
+) {
+  const { section, stack, setSection, popTo, clear, stateAttr } = useAppNav()
+  const crumbs = [
+    { id: section, label: labels?.[0] ?? section, kind: 'section' as const },
+    ...stack.map((entry, i) => ({
+      id: entry.id,
+      label: labels?.[i + 1] ?? entry.type,
+      kind: 'child' as const,
+    })),
+  ]
+
+  return (
+    <nav
+      ref={ref as never}
+      aria-label="Breadcrumb"
+      {...mergeProps(
+        partAttrs(appNavAnatomy.scope, appNavAnatomy.breadcrumb, { state: stateAttr }),
+        rest,
+      )}
+    >
+      {crumbs.map((crumb, index) => {
+        const last = index === crumbs.length - 1
+        return (
+          <button
+            key={`${crumb.kind}:${crumb.id}`}
+            type="button"
+            disabled={last}
+            {...partAttrs(appNavAnatomy.scope, appNavAnatomy.crumb, {
+              state: last ? 'current' : 'ancestor',
+            })}
+            onClick={() => {
+              if (crumb.kind === 'section') {
+                clear()
+                setSection(crumb.id)
+              } else {
+                popTo(crumb.id)
+              }
+            }}
+          >
+            {crumb.label}
+          </button>
+        )
+      })}
+    </nav>
+  )
+})
+
+const Back = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
+  function AppNavBack({ onClick, children = 'Back', ...rest }, ref) {
+    const { child, pop, stateAttr } = useAppNav()
+    if (!child) return null
+    return (
+      <button
+        ref={ref}
+        type="button"
+        onClick={(e) => {
+          onClick?.(e)
+          if (e.defaultPrevented) return
+          pop()
+        }}
+        {...mergeProps(
+          partAttrs(appNavAnatomy.scope, appNavAnatomy.back, { state: stateAttr }),
+          rest,
+        )}
+      >
+        {children}
+      </button>
+    )
+  },
+)
+
+/**
+ * AppNav — section rail + detail stack.
+ * Machine: SET_SECTION / PUSH / POP / CLEAR. UI = f(section, stack).
+ */
+export const AppNav = {
+  Root,
+  Rail,
+  Section,
+  Stage,
+  Breadcrumb,
+  Back,
+}

package/packages/react/src/app-shell/index.tsx

@@ -0,0 +1,154 @@
+import { appShellAnatomy, partAttrs, scopeAttrs } from '@aeon-ui/core'
+import { appShellMachine } from '@aeon-ui/primitives'
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useEffect,
+  useMemo,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { useAeonMachine } from '../hooks/use-aeon-machine.js'
+import { mergeProps } from '../utils/merge-props.js'
+
+type AppShellChrome = 'idle' | 'overlayOpen'
+
+interface AppShellContextValue {
+  chrome: AppShellChrome
+  dockVisible: boolean
+  overlayOpen: boolean
+  send: ReturnType<typeof useAeonMachine<typeof appShellMachine>>[1]
+}
+
+const AppShellCtx = createContext<AppShellContextValue | null>(null)
+
+export function useAppShellContext() {
+  const ctx = useContext(AppShellCtx)
+  if (!ctx) throw new Error('AppShell parts must be used within AppShell.Root')
+  return ctx
+}
+
+export interface AppShellRootProps extends HTMLAttributes<HTMLDivElement> {
+  /** Initial dock visibility when uncontrolled. */
+  defaultDockVisible?: boolean
+  /** Controlled dock visibility — syncs into the shell machine. */
+  dockVisible?: boolean
+  children?: ReactNode
+}
+
+const Root = forwardRef<HTMLDivElement, AppShellRootProps>(function AppShellRoot(
+  { defaultDockVisible = true, dockVisible: dockVisibleProp, children, ...rest },
+  ref,
+) {
+  const [snapshot, send] = useAeonMachine(appShellMachine, {
+    input: { dockVisible: dockVisibleProp ?? defaultDockVisible },
+  })
+  const chrome = snapshot.value as AppShellChrome
+  const dockVisible = dockVisibleProp ?? snapshot.context.dockVisible
+
+  useEffect(() => {
+    if (dockVisibleProp === undefined) return
+    if (snapshot.context.dockVisible !== dockVisibleProp) {
+      send({ type: 'SET_DOCK', visible: dockVisibleProp })
+    }
+  }, [dockVisibleProp, snapshot.context.dockVisible, send])
+
+  const value = useMemo(
+    () => ({
+      chrome,
+      dockVisible,
+      overlayOpen: chrome === 'overlayOpen',
+      send,
+    }),
+    [chrome, dockVisible, send],
+  )
+
+  return (
+    <AppShellCtx.Provider value={value}>
+      <div
+        ref={ref}
+        data-aeon-dock={dockVisible ? 'visible' : 'hidden'}
+        {...mergeProps(
+          scopeAttrs(appShellAnatomy.scope, appShellAnatomy.root, { state: chrome }),
+          rest,
+        )}
+      >
+        {children}
+      </div>
+    </AppShellCtx.Provider>
+  )
+})
+
+function ShellPart(
+  part: string,
+  displayName: string,
+  defaultTag: 'div' | 'header' | 'footer' | 'aside' | 'main' = 'div',
+) {
+  const Comp = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { as?: typeof defaultTag }>(
+    function AeonShellPart({ as: Tag = defaultTag, ...rest }, ref) {
+      const { chrome } = useAppShellContext()
+      return (
+        <Tag
+          ref={ref as never}
+          {...mergeProps(partAttrs(appShellAnatomy.scope, part, { state: chrome }), rest)}
+        />
+      )
+    },
+  )
+  Comp.displayName = displayName
+  return Comp
+}
+
+const Header = ShellPart(appShellAnatomy.header, 'AppShell.Header', 'header')
+const Subheader = ShellPart(appShellAnatomy.subheader, 'AppShell.Subheader')
+const Content = ShellPart(appShellAnatomy.content, 'AppShell.Content', 'main')
+const Aside = ShellPart(appShellAnatomy.aside, 'AppShell.Aside', 'aside')
+const Footer = ShellPart(appShellAnatomy.footer, 'AppShell.Footer', 'footer')
+
+const Dock = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function AppShellDock(
+  { hidden, ...rest },
+  ref,
+) {
+  const { chrome, dockVisible } = useAppShellContext()
+  if (!dockVisible) return null
+  return (
+    <div
+      ref={ref}
+      hidden={hidden}
+      {...mergeProps(partAttrs(appShellAnatomy.scope, appShellAnatomy.dock, { state: chrome }), rest)}
+    />
+  )
+})
+
+const Scrim = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function AppShellScrim(
+  props,
+  ref,
+) {
+  const { chrome, overlayOpen, send } = useAppShellContext()
+  if (!overlayOpen) return null
+  return (
+    <div
+      ref={ref}
+      role="presentation"
+      onClick={() => send({ type: 'CLOSE_OVERLAY' })}
+      {...mergeProps(partAttrs(appShellAnatomy.scope, appShellAnatomy.scrim, { state: chrome }), props)}
+    />
+  )
+})
+
+/**
+ * AppShell — application chrome frame.
+ * Machine: idle | overlayOpen (+ dockVisible context).
+ * UI = f(snapshot): content dims / scrim when overlayOpen; dock hides when dockVisible=false.
+ */
+export const AppShell = {
+  Root,
+  Header,
+  Subheader,
+  Content,
+  Aside,
+  Footer,
+  Dock,
+  Scrim,
+}

package/packages/react/src/async/index.tsx

@@ -5,13 +5,18 @@ import { AsyncRoot } from './root.js'
 import { AsyncTrack } from './track.js'
 
 export { AsyncProvider, useAsyncContext } from './context.js'
+export { asyncStatusToContentState } from './map-content-state.js'
 export { AsyncTrack } from './track.js'
 export { AsyncReadout } from './readout.js'
 export { AsyncActions } from './actions.js'
 export { AsyncRoot } from './root.js'
-export { AsyncRegion } from './legacy-region.js'
 export { createAsyncMachine } from '@aeon-ui/primitives'
 
+/**
+ * Async — fetch lifecycle driver (`createAsyncMachine`).
+ * Product UI: project status with Content slots via `asyncStatusToContentState`.
+ * `Track` is a totality/debug rail — not Instant default (see docs/PRIMITIVE_COVERAGE.md).
+ */
 export const Async = {
   Root: AsyncRoot,
   Provider: AsyncProvider,

package/packages/react/src/async/map-content-state.ts

@@ -0,0 +1,18 @@
+import type { ContentRegionState } from '@aeon-ui/primitives'
+
+/** Map async machine leaf → Content face (product UI — not Track). */
+export function asyncStatusToContentState(status: string): ContentRegionState {
+  switch (status) {
+    case 'loading':
+      return 'pending'
+    case 'empty':
+      return 'empty'
+    case 'failure':
+      return 'error'
+    case 'success':
+      return 'success'
+    case 'idle':
+    default:
+      return 'idle'
+  }
+}

package/packages/react/src/avatar/index.tsx

@@ -47,7 +47,10 @@ const Root = forwardRef<HTMLSpanElement, AvatarRootProps>(function AvatarRoot(
         ref={ref}
         className={className}
         {...mergeProps(
-          partAttrs(avatarAnatomy.scope, avatarAnatomy.root, { state: status }),
+          partAttrs(avatarAnatomy.scope, avatarAnatomy.root, {
+            // `ready` alias keeps product CSS friendly; `loaded` stays for existing recipes.
+            state: status === 'loaded' ? 'loaded ready' : status,
+          }),
           rest,
         )}
       >
@@ -115,8 +118,27 @@ const Fallback = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(fu
   )
 })
 
+export type PresenceState = 'idle' | 'active' | 'away' | 'busy' | 'offline'
+
+const Badge = forwardRef<
+  HTMLSpanElement,
+  HTMLAttributes<HTMLSpanElement> & { presence?: PresenceState }
+>(function AvatarBadge({ presence = 'idle', className, ...rest }, ref) {
+  useAvatarCtx()
+  return (
+    <span
+      ref={ref}
+      data-aeon-presence={presence}
+      {...partAttrs(avatarAnatomy.scope, avatarAnatomy.badge, { state: presence })}
+      className={className}
+      {...rest}
+    />
+  )
+})
+
 export const Avatar = {
   Root,
   Image,
   Fallback,
+  Badge,
 }