aeon-ui-engine 1.0.3 → 1.2.0

package/packages/primitives/dist/machines/content-region.d.ts

@@ -0,0 +1,72 @@
+import * as xstate from 'xstate';
+
+/** Totality for page / list / hub bodies — every state has a slot. */
+declare const CONTENT_REGION_STATES: readonly ["idle", "pending", "empty", "error", "ready", "loadingMore", "success"];
+type ContentRegionState = (typeof CONTENT_REGION_STATES)[number];
+interface ContentRegionContext {
+    error: string | null;
+}
+type ContentRegionEvent = {
+    type: 'LOAD';
+} | {
+    type: 'RESOLVE';
+    empty?: boolean;
+} | {
+    type: 'REJECT';
+    error: string;
+} | {
+    type: 'RETRY';
+} | {
+    type: 'LOAD_MORE';
+} | {
+    type: 'MORE_DONE';
+    empty?: boolean;
+} | {
+    type: 'SUCCEED';
+} | {
+    type: 'RESET';
+};
+/**
+ * Content region — status-slotted body under app chrome.
+ * Makes async / list / hub totality trivial: pending | empty | error | ready | loadingMore | success.
+ * Reference: items-market EmptyPlaceholder + loading skeletons + InfiniteScrollSentinel.
+ */
+declare const contentRegionMachine: xstate.StateMachine<ContentRegionContext, {
+    type: "LOAD";
+} | {
+    type: "RESOLVE";
+    empty?: boolean;
+} | {
+    type: "REJECT";
+    error: string;
+} | {
+    type: "RETRY";
+} | {
+    type: "LOAD_MORE";
+} | {
+    type: "MORE_DONE";
+    empty?: boolean;
+} | {
+    type: "SUCCEED";
+} | {
+    type: "RESET";
+}, {}, never, {
+    type: "clearError";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "setError";
+    params: xstate.NonReducibleUnknown;
+}, never, never, "error" | "idle" | "success" | "empty" | "pending" | "ready" | "loadingMore", string, Partial<ContentRegionContext>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "contentRegion";
+    states: {
+        readonly idle: {};
+        readonly pending: {};
+        readonly empty: {};
+        readonly error: {};
+        readonly ready: {};
+        readonly loadingMore: {};
+        readonly success: {};
+    };
+}>;
+
+export { CONTENT_REGION_STATES, type ContentRegionContext, type ContentRegionEvent, type ContentRegionState, contentRegionMachine };

package/packages/primitives/dist/machines/content-region.js

@@ -0,0 +1,8 @@
+import {
+  CONTENT_REGION_STATES,
+  contentRegionMachine
+} from "../chunk-RO2DMFN5.js";
+export {
+  CONTENT_REGION_STATES,
+  contentRegionMachine
+};

package/packages/primitives/dist/machines/panel.d.ts

@@ -0,0 +1,50 @@
+import * as xstate from 'xstate';
+
+interface PanelContext {
+    expanded: boolean;
+}
+type PanelEvent = {
+    type: 'EXPAND';
+} | {
+    type: 'COLLAPSE';
+} | {
+    type: 'TOGGLE';
+} | {
+    type: 'SET_EXPANDED';
+    expanded: boolean;
+};
+/**
+ * Panel layout region — expanded | collapsed.
+ * Collapsed hides content and exposes a vertical rail label.
+ */
+declare const panelMachine: xstate.StateMachine<PanelContext, {
+    type: "EXPAND";
+} | {
+    type: "COLLAPSE";
+} | {
+    type: "TOGGLE";
+} | {
+    type: "SET_EXPANDED";
+    expanded: boolean;
+}, {}, never, {
+    type: "markExpanded";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "markCollapsed";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "toggleExpanded";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "setExpanded";
+    params: xstate.NonReducibleUnknown;
+}, never, never, "expanded" | "resolve" | "collapsed", string, Partial<PanelContext>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "panel";
+    states: {
+        readonly resolve: {};
+        readonly expanded: {};
+        readonly collapsed: {};
+    };
+}>;
+
+export { type PanelContext, type PanelEvent, panelMachine };

package/packages/primitives/dist/machines/panel.js

@@ -0,0 +1,6 @@
+import {
+  panelMachine
+} from "../chunk-V5D7LS4J.js";
+export {
+  panelMachine
+};

package/packages/primitives/dist/machines/sticky-bar.d.ts

@@ -0,0 +1,62 @@
+import * as xstate from 'xstate';
+
+declare const STICKY_BAR_STATES: readonly ["floating", "docked", "collapsed", "hidden"];
+type StickyBarState = (typeof STICKY_BAR_STATES)[number];
+interface StickyBarContext {
+    /** CSS inset for stacked sticky chrome (e.g. under a fixed site header). */
+    offsetPx: number;
+    /** Resolved once on start from input.initial. */
+    initial: StickyBarState;
+}
+type StickyBarEvent = {
+    type: 'DOCK';
+} | {
+    type: 'FLOAT';
+} | {
+    type: 'COLLAPSE';
+} | {
+    type: 'EXPAND';
+} | {
+    type: 'HIDE';
+} | {
+    type: 'SHOW';
+} | {
+    type: 'SET_OFFSET';
+    offsetPx: number;
+};
+/**
+ * Sticky / fixed chrome band — site header, subnav, reveal trays.
+ * Reference: items-market NavigationBar shrink, MarketNavbar sticky stack, BalanceStickyTray.
+ *
+ * States: floating | docked | collapsed | hidden
+ */
+declare const stickyBarMachine: xstate.StateMachine<StickyBarContext, {
+    type: "DOCK";
+} | {
+    type: "FLOAT";
+} | {
+    type: "COLLAPSE";
+} | {
+    type: "EXPAND";
+} | {
+    type: "HIDE";
+} | {
+    type: "SHOW";
+} | {
+    type: "SET_OFFSET";
+    offsetPx: number;
+}, {}, never, {
+    type: "setOffset";
+    params: xstate.NonReducibleUnknown;
+}, never, never, "resolve" | "collapsed" | "hidden" | "floating" | "docked", string, Partial<StickyBarContext>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "stickyBar";
+    states: {
+        readonly resolve: {};
+        readonly floating: {};
+        readonly docked: {};
+        readonly collapsed: {};
+        readonly hidden: {};
+    };
+}>;
+
+export { STICKY_BAR_STATES, type StickyBarContext, type StickyBarEvent, type StickyBarState, stickyBarMachine };

package/packages/primitives/dist/machines/sticky-bar.js

@@ -0,0 +1,8 @@
+import {
+  STICKY_BAR_STATES,
+  stickyBarMachine
+} from "../chunk-YBPNI2LI.js";
+export {
+  STICKY_BAR_STATES,
+  stickyBarMachine
+};

package/packages/primitives/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/primitives/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/primitives/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/primitives/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":src/machines/dialog.test.ts",{"duration":5.771292000000017,"failed":false}],[":src/machines/select.test.ts",{"duration":6.394416000000035,"failed":false}],[":src/__tests__/dialog.test.ts",{"duration":3.686000000000007,"failed":false}],[":src/__tests__/select.test.ts",{"duration":2.8540000000000134,"failed":false}],[":src/__tests__/floating-surface.test.ts",{"duration":4.358541000000002,"failed":false}]]}
+{"version":"3.2.4","results":[[":src/machines/dialog.test.ts",{"duration":5.771292000000017,"failed":false}],[":src/machines/select.test.ts",{"duration":6.394416000000035,"failed":false}],[":src/__tests__/dialog.test.ts",{"duration":3.686000000000007,"failed":false}],[":src/__tests__/select.test.ts",{"duration":2.8540000000000134,"failed":false}],[":src/__tests__/floating-surface.test.ts",{"duration":6.529208000000011,"failed":false}],[":src/__tests__/app-nav.test.ts",{"duration":7.017959000000019,"failed":false}]]}

package/packages/primitives/package.json

@@ -8,9 +8,19 @@
     "url": "https://github.com/GenericCPU/aeon-ui.git",
     "directory": "packages/primitives"
   },
-  "publishConfig": { "access": "public" },
-  "files": ["dist", "README.md"],
-  "keywords": ["aeon-ui", "xstate", "statechart", "machines"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "aeon-ui",
+    "xstate",
+    "statechart",
+    "machines"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,11 +41,11 @@
   },
   "dependencies": {
     "@aeon-ui/core": "workspace:*",
-    "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/primitives/scripts/xstate-introspect.mjs

@@ -0,0 +1,35 @@
+import { asyncMachine } from '../dist/index.js';
+import { createActor, getStateNodes, getNextTransitions, __unsafe_getAllOwnEventDescriptors } from 'xstate';
+import { getStateNodes as graphGetStateNodes } from 'xstate/graph';
+
+const machine = asyncMachine;
+console.log('=== Object.keys(machine) ===');
+console.log(Object.keys(machine));
+console.log('\n=== Object.keys(machine.states) ===');
+console.log(Object.keys(machine.states));
+const idle = machine.states.idle;
+console.log('\n=== idle: Object.keys(idle) ===');
+console.log(Object.keys(idle));
+console.log('\n=== idle.events ===');
+console.log(idle.events);
+console.log('\n=== idle.config.on ===');
+console.log(JSON.stringify(idle.config.on, null, 2));
+const actor = createActor(machine);
+actor.start();
+const snap = actor.getSnapshot();
+console.log('\n=== snapshot.value ===');
+console.log(snap.value);
+console.log("\n=== snapshot.can({ type: 'FETCH' }) ===");
+console.log(snap.can({ type: 'FETCH' }));
+console.log('\n=== typeof snap.getNextEvents ===');
+console.log(typeof snap.getNextEvents);
+console.log('\n=== getNextTransitions(snap) ===');
+console.log(getNextTransitions(snap).map((t) => ({ eventType: t.eventType, target: t.target })));
+console.log('\n=== __unsafe_getAllOwnEventDescriptors(snap) ===');
+console.log(__unsafe_getAllOwnEventDescriptors(snap));
+console.log('\n=== snap._nodes events ===');
+for (const n of snap._nodes) console.log(n.id, n.events);
+console.log('\n=== graphGetStateNodes ===');
+for (const n of graphGetStateNodes(machine)) {
+  console.log({ id: n.id, events: n.events, onKeys: n.config?.on ? Object.keys(n.config.on) : [] });
+}

package/packages/primitives/src/__tests__/app-nav.test.ts

@@ -0,0 +1,30 @@
+import { createActor } from 'xstate'
+import { describe, expect, it } from 'vitest'
+import {
+  appNavChild,
+  appNavMachine,
+  appNavStateAttr,
+} from '../machines/app-nav.js'
+
+describe('appNavMachine', () => {
+  it('switches section and clears stack', () => {
+    const actor = createActor(appNavMachine, { input: { section: 'home' } }).start()
+    actor.send({ type: 'PUSH', child: { id: '1', type: 'detail' } })
+    expect(appNavChild(actor.getSnapshot().context)?.id).toBe('1')
+    actor.send({ type: 'SET_SECTION', section: 'settings' })
+    const ctx = actor.getSnapshot().context
+    expect(ctx.section).toBe('settings')
+    expect(ctx.stack).toEqual([])
+  })
+
+  it('push / pop / popTo maintain stack', () => {
+    const actor = createActor(appNavMachine, { input: { section: 'apps' } }).start()
+    actor.send({ type: 'PUSH', child: { id: 'a', type: 'app' } })
+    actor.send({ type: 'PUSH', child: { id: 'p', type: 'permission' } })
+    expect(appNavStateAttr(actor.getSnapshot().context)).toBe('apps/permission')
+    actor.send({ type: 'POP_TO', id: 'a' })
+    expect(appNavChild(actor.getSnapshot().context)?.id).toBe('a')
+    actor.send({ type: 'POP' })
+    expect(appNavChild(actor.getSnapshot().context)).toBeNull()
+  })
+})

package/packages/primitives/src/index.ts

@@ -1,5 +1,6 @@
 export * from './machines/toggle.js'
 export * from './machines/dialog.js'
+export * from './machines/panel.js'
 export * from './machines/tabs.js'
 export * from './machines/accordion.js'
 export * from './machines/async.js'
@@ -8,3 +9,7 @@ export * from './machines/field.js'
 export * from './machines/popover.js'
 export * from './machines/toast.js'
 export * from './machines/slider.js'
+export * from './machines/app-shell.js'
+export * from './machines/app-nav.js'
+export * from './machines/sticky-bar.js'
+export * from './machines/content-region.js'

package/packages/primitives/src/machines/app-nav.ts

@@ -0,0 +1,107 @@
+import { assign, setup } from 'xstate'
+
+/**
+ * Section + detail stack navigation — the pattern every multi-panel product
+ * reinvented (wallet sections, settings drill-in, list→detail).
+ *
+ * Not product-specific: `section` is a string id; `stack` is opaque child records.
+ */
+export type AppNavChild = {
+  id: string
+  /** Free-form type tag (e.g. "detail", "compose", "settings"). */
+  type: string
+  /** Optional payload for the view layer. */
+  data?: unknown
+}
+
+export interface AppNavContext {
+  section: string
+  stack: AppNavChild[]
+}
+
+export type AppNavEvent =
+  | { type: 'SET_SECTION'; section: string }
+  | { type: 'PUSH'; child: AppNavChild }
+  | { type: 'REPLACE'; child: AppNavChild }
+  | { type: 'POP' }
+  | { type: 'POP_TO'; id: string }
+  | { type: 'CLEAR' }
+  | { type: 'RESET'; section: string }
+
+export function appNavDepth(ctx: AppNavContext): number {
+  return ctx.stack.length
+}
+
+export function appNavChild(ctx: AppNavContext): AppNavChild | null {
+  return ctx.stack.length ? ctx.stack[ctx.stack.length - 1]! : null
+}
+
+/** Projected state for data-aeon-state: `section` or `section/childType`. */
+export function appNavStateAttr(ctx: AppNavContext): string {
+  const child = appNavChild(ctx)
+  return child ? `${ctx.section}/${child.type}` : ctx.section
+}
+
+export const appNavMachine = setup({
+  types: {
+    context: {} as AppNavContext,
+    events: {} as AppNavEvent,
+    input: {} as Partial<AppNavContext> & { section?: string },
+  },
+  actions: {
+    setSection: assign({
+      section: ({ event }) => (event.type === 'SET_SECTION' ? event.section : ''),
+      stack: [],
+    }),
+    push: assign({
+      stack: ({ context, event }) =>
+        event.type === 'PUSH' ? [...context.stack, event.child] : context.stack,
+    }),
+    replace: assign({
+      stack: ({ context, event }) => {
+        if (event.type !== 'REPLACE') return context.stack
+        if (!context.stack.length) return [event.child]
+        return [...context.stack.slice(0, -1), event.child]
+      },
+    }),
+    pop: assign({
+      stack: ({ context }) => context.stack.slice(0, -1),
+    }),
+    popTo: assign({
+      stack: ({ context, event }) => {
+        if (event.type !== 'POP_TO') return context.stack
+        const idx = context.stack.findIndex((c) => c.id === event.id)
+        if (idx < 0) return context.stack
+        return context.stack.slice(0, idx + 1)
+      },
+    }),
+    clear: assign({ stack: [] }),
+    reset: assign({
+      section: ({ event }) => (event.type === 'RESET' ? event.section : ''),
+      stack: [],
+    }),
+  },
+  guards: {
+    canPop: ({ context }) => context.stack.length > 0,
+  },
+}).createMachine({
+  id: 'appNav',
+  context: ({ input }) => ({
+    section: input?.section ?? 'home',
+    stack: input?.stack ?? [],
+  }),
+  initial: 'ready',
+  states: {
+    ready: {
+      on: {
+        SET_SECTION: { actions: 'setSection' },
+        PUSH: { actions: 'push' },
+        REPLACE: { actions: 'replace' },
+        POP: { guard: 'canPop', actions: 'pop' },
+        POP_TO: { actions: 'popTo' },
+        CLEAR: { actions: 'clear' },
+        RESET: { actions: 'reset' },
+      },
+    },
+  },
+})

package/packages/primitives/src/machines/app-shell.ts

@@ -0,0 +1,63 @@
+import { assign, setup } from 'xstate'
+
+export const APP_SHELL_STATES = ['idle', 'overlayOpen'] as const
+export type AppShellState = (typeof APP_SHELL_STATES)[number]
+
+export interface AppShellContext {
+  /** Bottom (or edge) dock chrome — tab bar, action dock. */
+  dockVisible: boolean
+}
+
+export type AppShellEvent =
+  | { type: 'OPEN_OVERLAY' }
+  | { type: 'CLOSE_OVERLAY' }
+  | { type: 'SHOW_DOCK' }
+  | { type: 'HIDE_DOCK' }
+  | { type: 'SET_DOCK'; visible: boolean }
+
+/**
+ * Application chrome frame — layered top / content / dock / overlays.
+ * Reference: HandCash items-market MainLayout (content dims when overlay open).
+ *
+ * Parallel concerns:
+ * - region `chrome`: idle | overlayOpen (content inert + scrim)
+ * - context `dockVisible`: whether the edge dock is shown
+ */
+export const appShellMachine = setup({
+  types: {
+    context: {} as AppShellContext,
+    events: {} as AppShellEvent,
+    input: {} as Partial<AppShellContext>,
+  },
+  actions: {
+    showDock: assign({ dockVisible: true }),
+    hideDock: assign({ dockVisible: false }),
+    setDock: assign({
+      dockVisible: ({ event }) => (event.type === 'SET_DOCK' ? event.visible : true),
+    }),
+  },
+}).createMachine({
+  id: 'appShell',
+  context: ({ input }) => ({
+    dockVisible: input?.dockVisible ?? true,
+  }),
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        OPEN_OVERLAY: 'overlayOpen',
+        SHOW_DOCK: { actions: 'showDock' },
+        HIDE_DOCK: { actions: 'hideDock' },
+        SET_DOCK: { actions: 'setDock' },
+      },
+    },
+    overlayOpen: {
+      on: {
+        CLOSE_OVERLAY: 'idle',
+        SHOW_DOCK: { actions: 'showDock' },
+        HIDE_DOCK: { actions: 'hideDock' },
+        SET_DOCK: { actions: 'setDock' },
+      },
+    },
+  },
+})