aeon-ui-engine 1.4.0 → 1.8.0

package/packages/react/src/hooks/use-anchor-position.ts

@@ -1,13 +1,38 @@
 import { useEffect, type RefObject } from 'react'
 
-export type AnchorPlacement = 'bottom-start' | 'top-start'
+export type AnchorSide = 'top' | 'bottom'
+export type AnchorAlign = 'start' | 'end' | 'center'
+export type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`
 
 export interface AnchorPositionOptions {
   /** Match floating width to anchor (select listboxes). */
   matchWidth?: boolean
+  /** Gap between anchor and floating surface. */
+  gutter?: number
+  /** Stack level written to the floating surface. */
+  zIndex?: number
+  /** Viewport padding kept clear when flipping and clamping. */
+  padding?: number
 }
 
-/** Pin floating surface to trigger rect (for portalled overlays). */
+const DEFAULT_GUTTER = 4
+const DEFAULT_Z_INDEX = 50
+const DEFAULT_PADDING = 8
+
+function splitPlacement(placement: AnchorPlacement): [AnchorSide, AnchorAlign] {
+  const [side, align] = placement.split('-') as [AnchorSide, AnchorAlign]
+  return [side, align]
+}
+
+/**
+ * Pin floating surface to trigger rect (for portalled overlays).
+ *
+ * Collision aware: the preferred side flips when it has no room, and the
+ * surface is clamped inside the viewport so an end-aligned trigger near an edge
+ * never renders offscreen. The resolved geometry is published as
+ * `data-side` / `data-align` plus `--aeon-available-height` and
+ * `--aeon-anchor-width` so recipes can cap their own scroll area.
+ */
 export function useAnchorPosition(
   anchorRef: RefObject<HTMLElement | null>,
   floatingRef: RefObject<HTMLElement | null>,
@@ -15,22 +40,32 @@ export function useAnchorPosition(
   placement: AnchorPlacement = 'bottom-start',
   options: AnchorPositionOptions = {},
 ) {
-  const { matchWidth = false } = options
+  const {
+    matchWidth = false,
+    gutter = DEFAULT_GUTTER,
+    zIndex = DEFAULT_Z_INDEX,
+    padding = DEFAULT_PADDING,
+  } = options
 
   useEffect(() => {
     if (!active || !anchorRef.current || !floatingRef.current) return
 
+    let frame = 0
+
     const update = () => {
       const anchor = anchorRef.current
       const floating = floatingRef.current
       if (!anchor || !floating) return
 
+      const [preferredSide, align] = splitPlacement(placement)
       const rect = anchor.getBoundingClientRect()
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+
       floating.style.position = 'fixed'
-      floating.style.left = `${rect.left}px`
       floating.style.bottom = ''
       floating.style.right = ''
-      floating.style.zIndex = '50'
+      floating.style.zIndex = String(zIndex)
 
       if (matchWidth) {
         floating.style.width = `${rect.width}px`
@@ -40,22 +75,58 @@ export function useAnchorPosition(
         floating.style.minWidth = ''
       }
 
-      if (placement === 'top-start') {
-        const height = floating.offsetHeight || floating.getBoundingClientRect().height
-        floating.style.top = `${rect.top - height - 4}px`
-      } else {
-        floating.style.top = `${rect.bottom + 4}px`
-      }
+      const width = floating.offsetWidth || floating.getBoundingClientRect().width
+      const height = floating.offsetHeight || floating.getBoundingClientRect().height
+
+      const roomBelow = viewportHeight - rect.bottom - gutter - padding
+      const roomAbove = rect.top - gutter - padding
+      const room = preferredSide === 'top' ? roomAbove : roomBelow
+      const side =
+        room >= height
+          ? preferredSide
+          : roomAbove > roomBelow
+            ? 'top'
+            : 'bottom'
+      const available = side === 'top' ? roomAbove : roomBelow
+
+      let left = rect.left
+      if (align === 'end') left = rect.right - width
+      else if (align === 'center') left = rect.left + rect.width / 2 - width / 2
+
+      const maxLeft = Math.max(padding, viewportWidth - width - padding)
+      left = Math.min(Math.max(padding, left), maxLeft)
+
+      const top =
+        side === 'top'
+          ? Math.max(padding, rect.top - gutter - Math.min(height, Math.max(available, 0)))
+          : Math.min(
+              rect.bottom + gutter,
+              Math.max(padding, viewportHeight - height - padding),
+            )
+
+      floating.style.left = `${Math.round(left)}px`
+      floating.style.top = `${Math.round(top)}px`
+      floating.style.setProperty('--aeon-available-height', `${Math.round(Math.max(available, 0))}px`)
+      floating.style.setProperty('--aeon-anchor-width', `${Math.round(rect.width)}px`)
+      floating.dataset.side = side
+      floating.dataset.align = align
+    }
+
+    const schedule = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(update)
     }
 
     update()
-    requestAnimationFrame(update)
+    // Measure again once the surface has laid out (flip/clamp need real height).
+    schedule()
 
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
+    window.addEventListener('resize', schedule)
+    window.addEventListener('scroll', schedule, true)
     return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
+      cancelAnimationFrame(frame)
+      window.removeEventListener('resize', schedule)
+      window.removeEventListener('scroll', schedule, true)
     }
-  }, [active, anchorRef, floatingRef, placement, matchWidth])
+  }, [active, anchorRef, floatingRef, placement, matchWidth, gutter, zIndex, padding])
 }

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

@@ -51,16 +51,21 @@ const Root = forwardRef<HTMLDivElement, MenuRootProps>(function MenuRoot(
   ref,
 ) {
   const [snapshot, send] = useAeonMachine(popoverMachine, { input: { open: defaultOpen } })
-  const resolvedOpen = open ?? snapshot.context.open
+  const machineOpen = snapshot.context.open
+  const resolvedOpen = open ?? machineOpen
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement>(null)
   const positionerRef = useRef<HTMLDivElement>(null)
   const triggerId = useId()
   const menuId = useId()
 
+  /** Machine intent, so a controlled owner still hears its own trigger. */
+  const reportedOpen = useRef(machineOpen)
   useEffect(() => {
-    onOpenChange?.(resolvedOpen)
-  }, [resolvedOpen, onOpenChange])
+    if (reportedOpen.current === machineOpen) return
+    reportedOpen.current = machineOpen
+    onOpenChange?.(machineOpen)
+  }, [machineOpen, onOpenChange])
 
   useEffect(() => {
     if (open !== undefined) send({ type: 'SET_OPEN', open })
@@ -129,11 +134,15 @@ export interface MenuPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount menu in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and menu (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function MenuPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = useMenuCtx()
@@ -148,6 +157,8 @@ const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function Menu
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >
@@ -160,13 +171,41 @@ const Content = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(funct
   { onKeyDown, ...rest },
   ref,
 ) {
-  const { open, send, menuId } = useMenuCtx()
+  const { open, send, menuId, triggerRef } = useMenuCtx()
+  const contentRef = useRef<HTMLDivElement | null>(null)
+
+  // Focus enters the surface while it is open and returns to the trigger on
+  // dismiss, so keyboard users stay inside the menu they opened.
+  useEffect(() => {
+    if (!open) return
+    const trigger = triggerRef.current
+    contentRef.current?.focus({ preventScroll: true })
+    return () => {
+      if (trigger?.isConnected) trigger.focus({ preventScroll: true })
+    }
+  }, [open, triggerRef])
+
+  // Escape closes wherever focus sits — trigger, item or elsewhere on the page.
+  useEffect(() => {
+    if (!open) return
+    const onDocumentKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') send({ type: 'ESCAPE' })
+    }
+    document.addEventListener('keydown', onDocumentKeyDown)
+    return () => document.removeEventListener('keydown', onDocumentKeyDown)
+  }, [open, send])
+
   if (!open) return null
   return (
     <div
-      ref={ref}
+      ref={(node) => {
+        contentRef.current = node
+        if (typeof ref === 'function') ref(node)
+        else if (ref) ref.current = node
+      }}
       id={menuId}
       role="menu"
+      tabIndex={-1}
       {...mergeProps(
         partAttrs(menuAnatomy.scope, menuAnatomy.content, { state: 'open' }),
         {

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

@@ -53,16 +53,21 @@ const Root = forwardRef<HTMLDivElement, PopoverRootProps>(function PopoverRoot(
   const [snapshot, send] = useAeonMachine(popoverMachine, {
     input: { open: defaultOpen },
   })
-  const resolvedOpen = open ?? snapshot.context.open
+  const machineOpen = snapshot.context.open
+  const resolvedOpen = open ?? machineOpen
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement>(null)
   const positionerRef = useRef<HTMLDivElement>(null)
   const triggerId = useId()
   const contentId = useId()
 
+  /** Machine intent, so a controlled owner still hears its own trigger. */
+  const reportedOpen = useRef(machineOpen)
   useEffect(() => {
-    onOpenChange?.(resolvedOpen)
-  }, [resolvedOpen, onOpenChange])
+    if (reportedOpen.current === machineOpen) return
+    reportedOpen.current = machineOpen
+    onOpenChange?.(machineOpen)
+  }, [machineOpen, onOpenChange])
 
   useEffect(() => {
     if (open !== undefined) send({ type: 'SET_OPEN', open })
@@ -132,11 +137,29 @@ export interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount panel in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+  anchorRef?: React.RefObject<HTMLElement | null>
+  /** Size the panel to the anchor, so it spans the region it belongs to. */
+  matchAnchorWidth?: boolean
+  /** Gap between trigger and panel (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function PopoverPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  {
+    portalled = true,
+    placement = 'bottom-start',
+    anchorRef,
+    matchAnchorWidth = false,
+    gutter,
+    zIndex,
+    children,
+    className,
+    ...rest
+  },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = usePopoverCtx()
@@ -149,8 +172,12 @@ const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function P
       part={popoverAnatomy.positioner}
       triggerRef={triggerRef}
       positionerRef={positionerRef}
+      anchorRef={anchorRef}
+      matchAnchorWidth={matchAnchorWidth}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >

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

@@ -16,22 +16,30 @@ import {
 import { useAeonMachine } from '../hooks/use-aeon-machine.js'
 import { mergeProps } from '../utils/merge-props.js'
 
-interface SliderContextValue {
+export interface SliderContextValue {
   value: number
   min: number
   max: number
   step: number
   disabled: boolean
   dragging: boolean
+  /** Nested region value from the machine: `interaction.idle` | `interaction.dragging`. */
+  interaction: 'idle' | 'dragging'
   send: ReturnType<typeof useAeonMachine<typeof sliderMachine>>[1]
   onValueChange?: (value: number) => void
+  /** Snap, store and report a user-intended value. */
+  commit: (value: number) => void
   setValueFromClientX: (clientX: number) => void
   trackRef: React.RefObject<HTMLDivElement | null>
 }
 
 const SliderCtx = createContext<SliderContextValue | null>(null)
 
-function useSliderCtx() {
+/**
+ * Read the slider's live machine state from inside `Slider.Root`.
+ * `interaction` is the nested region value — the same thing the snapshot holds.
+ */
+export function useSliderContext() {
   const ctx = useContext(SliderCtx)
   if (!ctx) throw new Error('Slider parts must be used within Slider.Root')
   return ctx
@@ -83,14 +91,33 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
   const resolvedValue = value ?? snapshot.context.value
   const dragging = snapshot.matches({ interaction: 'dragging' })
 
-  useEffect(() => {
-    onValueChange?.(resolvedValue)
-  }, [resolvedValue, onValueChange])
-
   useEffect(() => {
     if (value !== undefined) send({ type: 'SET_VALUE', value })
   }, [value, send])
 
+  useEffect(() => {
+    send({ type: 'SET_BOUNDS', min, max, step })
+  }, [min, max, step, send])
+
+  useEffect(() => {
+    send({ type: 'SET_DISABLED', disabled })
+  }, [disabled, send])
+
+  /**
+   * Interaction is emitted here, never echoed from the resolved value. A
+   * controlled slider therefore reports what the user did (Aeon ≤1.4.0 stayed
+   * silent while `value` was set) and never fires on mount.
+   */
+  const commit = useCallback(
+    (next: number) => {
+      if (disabled) return
+      const snapped = snapSliderValue(next, min, max, step)
+      send({ type: 'SET_VALUE', value: snapped })
+      onValueChange?.(snapped)
+    },
+    [disabled, min, max, step, send, onValueChange],
+  )
+
   const setValueFromClientX = useCallback(
     (clientX: number) => {
       const track = trackRef.current
@@ -98,11 +125,9 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
       const rect = track.getBoundingClientRect()
       if (rect.width <= 0) return
       const ratio = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width))
-      const next = snapSliderValue(min + ratio * (max - min), min, max, step)
-      send({ type: 'SET_VALUE', value: next })
-      if (value === undefined) onValueChange?.(next)
+      commit(min + ratio * (max - min))
     },
-    [disabled, min, max, step, send, value, onValueChange],
+    [commit, disabled, min, max],
   )
 
   useEffect(() => {
@@ -125,12 +150,25 @@ const Root = forwardRef<HTMLDivElement, SliderRootProps>(function SliderRoot(
       step,
       disabled,
       dragging,
+      interaction: (dragging ? 'dragging' : 'idle') as 'idle' | 'dragging',
       send,
       onValueChange,
+      commit,
       setValueFromClientX,
       trackRef,
     }),
-    [resolvedValue, min, max, step, disabled, dragging, send, onValueChange, setValueFromClientX],
+    [
+      resolvedValue,
+      min,
+      max,
+      step,
+      disabled,
+      dragging,
+      send,
+      onValueChange,
+      commit,
+      setValueFromClientX,
+    ],
   )
 
   return (
@@ -156,7 +194,7 @@ const Track = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(functio
   { onPointerDown, ...rest },
   ref,
 ) {
-  const { disabled, send, setValueFromClientX, trackRef } = useSliderCtx()
+  const { disabled, send, setValueFromClientX, trackRef } = useSliderContext()
 
   return (
     <div
@@ -186,7 +224,7 @@ const Range = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(functio
   { style, ...rest },
   ref,
 ) {
-  const { value, min, max } = useSliderCtx()
+  const { value, min, max } = useSliderContext()
   return (
     <div
       ref={ref}
@@ -201,7 +239,8 @@ const Thumb = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(funct
   { onKeyDown, onPointerDown, style, ...rest },
   ref,
 ) {
-  const { value, min, max, step, disabled, dragging, send, setValueFromClientX } = useSliderCtx()
+  const { value, min, max, step, disabled, dragging, send, commit, setValueFromClientX } =
+    useSliderContext()
 
   return (
     <span
@@ -229,19 +268,27 @@ const Thumb = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(funct
             if (disabled || e.defaultPrevented) return
             if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
               e.preventDefault()
-              send({ type: 'STEP', delta: step })
+              commit(value + step)
             }
             if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
               e.preventDefault()
-              send({ type: 'STEP', delta: -step })
+              commit(value - step)
+            }
+            if (e.key === 'PageUp') {
+              e.preventDefault()
+              commit(value + (max - min) / 10)
+            }
+            if (e.key === 'PageDown') {
+              e.preventDefault()
+              commit(value - (max - min) / 10)
             }
             if (e.key === 'Home') {
               e.preventDefault()
-              send({ type: 'HOME' })
+              commit(min)
             }
             if (e.key === 'End') {
               e.preventDefault()
-              send({ type: 'END' })
+              commit(max)
             }
           },
         },
@@ -255,7 +302,7 @@ const ValueText = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(f
   props,
   ref,
 ) {
-  const { value } = useSliderCtx()
+  const { value } = useSliderContext()
   return (
     <span ref={ref} {...mergeProps(partOnlyAttrs(sliderAnatomy.valueText), props)}>
       {props.children ?? value}

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

@@ -272,11 +272,15 @@ export interface TooltipPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount tooltip in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and tip (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, TooltipPositionerProps>(function TooltipPositioner(
-  { portalled = true, placement = 'top-start', children, className, ...rest },
+  { portalled = true, placement = 'top-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = useTooltipCtx()
@@ -291,6 +295,8 @@ const Positioner = forwardRef<HTMLDivElement, TooltipPositionerProps>(function T
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >

package/packages/schemas/dist/index.js

@@ -926,7 +926,9 @@ When generating Aeon UI, constrain props/parts/states to @aeon-ui/schemas catalo
 Import headless from @aeon-ui/react or styled from @aeon-ui/ui.
 Install: npm install aeon-ui-engine react react-dom xstate @xstate/react
 CSS: import 'aeon-ui-engine/aeon.css'
-Vite: aeonUiVitePlugin() from aeon-ui-engine/vite
+Link: postinstall + npx aeon-ui link (node_modules/@aeon-ui/*)
+Next.js: transpilePackages for @aeon-ui/* + "use client"; Vite plugin optional
+Vue/Solid/Svelte: thin adapters only \u2014 React is the full catalog
 
 ${STATECHART_PROMPTS.async}
 

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

@@ -1 +1 @@
-{"version":"4.1.8","results":[[":src/index.test.ts",{"duration":5.161209000000014,"failed":false}],[":src/aeon-to-schema.test.ts",{"duration":5.569166999999993,"failed":false}]]}
+{"version":"4.1.8","results":[[":src/index.test.ts",{"duration":42.299125000000004,"failed":false}],[":src/aeon-to-schema.test.ts",{"duration":7.255999999999972,"failed":false}]]}

package/packages/schemas/prompts/cursorrules.md

@@ -35,7 +35,9 @@ When generating Aeon UI, constrain props/parts/states to @aeon-ui/schemas catalo
 Import headless from @aeon-ui/react or styled from @aeon-ui/ui.
 Install: npm install aeon-ui-engine react react-dom xstate @xstate/react
 CSS: import 'aeon-ui-engine/aeon.css'
-Vite: aeonUiVitePlugin() from aeon-ui-engine/vite
+Link: postinstall + npx aeon-ui link (node_modules/@aeon-ui/*)
+Next.js: transpilePackages for @aeon-ui/* + "use client"; Vite plugin optional
+Vue/Solid/Svelte: thin adapters only — React is the full catalog
 
 ## Async region statechart
 States: idle → loading → (success | empty | failure); REFRESH from success/empty/failure; STALE flag while success.

package/packages/schemas/registry/machines/slider.json

@@ -2,6 +2,8 @@
   "id": "slider",
   "initial": "interaction",
   "events": [
+    "SET_BOUNDS",
+    "SET_DISABLED",
     "SET_VALUE",
     "STEP",
     "HOME",
@@ -14,6 +16,8 @@
     "id": "slider",
     "type": "compound",
     "events": [
+      "SET_BOUNDS",
+      "SET_DISABLED",
       "SET_VALUE",
       "STEP",
       "HOME",
@@ -21,7 +25,18 @@
       "POINTER_DOWN",
       "POINTER_UP"
     ],
-    "transitions": [],
+    "transitions": [
+      {
+        "event": "SET_BOUNDS",
+        "target": [],
+        "guarded": false
+      },
+      {
+        "event": "SET_DISABLED",
+        "target": [],
+        "guarded": false
+      }
+    ],
     "children": [
       {
         "key": "interaction",
@@ -110,6 +125,8 @@
   "states": {
     "slider": {
       "events": [
+        "SET_BOUNDS",
+        "SET_DISABLED",
         "SET_VALUE",
         "STEP",
         "HOME",

package/packages/schemas/src/prompts.ts

@@ -128,7 +128,9 @@ When generating Aeon UI, constrain props/parts/states to @aeon-ui/schemas catalo
 Import headless from @aeon-ui/react or styled from @aeon-ui/ui.
 Install: npm install aeon-ui-engine react react-dom xstate @xstate/react
 CSS: import 'aeon-ui-engine/aeon.css'
-Vite: aeonUiVitePlugin() from aeon-ui-engine/vite
+Link: postinstall + npx aeon-ui link (node_modules/@aeon-ui/*)
+Next.js: transpilePackages for @aeon-ui/* + "use client"; Vite plugin optional
+Vue/Solid/Svelte: thin adapters only — React is the full catalog
 
 ${STATECHART_PROMPTS.async}
 

package/packages/tree/README.md

@@ -0,0 +1,29 @@
+# @aeon-ui/tree
+
+Widget trees for Aeon. A widget is configuration — immutable data describing one face of a chart — interpreted into DOM that carries `data-aeon-scope`, `data-aeon-part`, and `data-aeon-state`.
+
+This is Flutter's Widget and Element layers only. There is no RenderObject (layout stays CSS) and no `StatefulWidget` (the chart is the only state). A tree that stored `busy` itself would be the boolean twin the philosophy rules out.
+
+```ts
+import { exclusiveActionWidget, interpret, uncoveredStates, EXCLUSIVE_ACTION_STATES } from '@aeon-ui/tree'
+
+const tree = exclusiveActionWidget({
+  scope: 'settings-change-password',
+  part: 'change-password-form',
+  state,            // snapshot token
+  busy,
+  error,
+  body: { type: 'host', id: 'body' },
+  idleLabel: 'Update password',
+  pendingLabel: 'Updating…',
+  onSubmit,
+  confirm: confirm !== null,
+})
+
+uncoveredStates(EXCLUSIVE_ACTION_STATES, (s) => exclusiveActionWidget({ ...args, state: s }))
+// [] — every state of the chart has a face
+```
+
+`interpret(tree, hosts)` is the element layer. Hosts are where an existing compound (a field, a `Prompt`) fills a slot the tree names. Product CSS restyles the anatomy attributes; class names are passed in by the app, not invented here.
+
+`exclusiveActionWidget` is the one face shared by every "confirm, then await" region: `idle → confirming → busy → idle | failure`.