@statorjs/stator 1.0.0

package/src/engine/types.ts

@@ -0,0 +1,236 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: type-level plumbing — existential machine slots and loose internal defaults require `any`; see the AnyMachineDef comment for the variance argument
+/**
+ * Stator's own state-machine engine — core types.
+ *
+ * Designed fresh for Stator's needs, NOT for XState compatibility. The shape is
+ * a declarative `states` map (so the transition graph stays statically
+ * analyzable — the framework's core value), with inline functions on
+ * transitions (Option A: per-transition event narrowing, co-located logic).
+ *
+ * Lean feature set per the engine spec: flat states, typed events, guards,
+ * mutation-style actions, declared emits, selectors, snapshot ser/de. State
+ * value is a PATH ARRAY (`['active']`) — depth-1 today, the extension point for
+ * hierarchy later without a rewrite.
+ *
+ * Reads are type-safe by inference: a machine that `reads` others gets a typed
+ * `helpers.reads` map keyed by each read machine's `name`, with that machine's
+ * selectors (and their return types) preserved. See `ReadsMap` / `InstanceOf`.
+ */
+
+/** Every event is a discriminated union member keyed on `type`. */
+export type EventObject = { type: string }
+
+/** Selectors derive views: of their own context, and — when the machine
+ *  declares `reads:` — of the read machines' selectors via the same helpers
+ *  object actions/guards receive. One-param selectors remain valid. */
+export type SelectorMap<C, R = Record<string, any>> = Record<
+  string,
+  // Method syntax → bivariant helpers param, so a machine with narrowly
+  // typed reads still satisfies contexts expecting the loose default.
+  { selector(ctx: C, helpers: ActionHelpers<R>): unknown }['selector']
+>
+
+/** Helpers handed to actions/guards. `reads` is the typed map of machines
+ *  declared in `reads:` (see `ReadsMap`). Defaults loose for internal/runtime
+ *  use where the concrete map isn't threaded. */
+export interface ActionHelpers<R = Record<string, any>> {
+  reads: R
+}
+
+/** An action mutates a draft of the context in place. The engine owns the
+ *  clone + commit, so user code writes plain mutation. */
+export type Action<C, E extends EventObject, R = Record<string, any>> = (
+  ctx: C,
+  ev: E,
+  helpers: ActionHelpers<R>,
+) => void
+
+/** A guard decides whether a transition may fire. Pure of (ctx, ev). */
+export type Guard<C, E extends EventObject, R = Record<string, any>> = (
+  ctx: C,
+  ev: E,
+  helpers: ActionHelpers<R>,
+) => boolean
+
+/** Passed to an effect alongside the snapshots. `effectId` is unique per
+ *  invocation — thread it to external calls as an idempotency key (1.x
+ *  durability implies at-least-once) and use it for log correlation. */
+export interface EffectMeta {
+  effectId: string
+}
+
+/**
+ * An effect: async I/O declared on a transition, run by the HOST after the
+ * transition commits (the engine itself never performs I/O). Receives
+ * commit-time `structuredClone` snapshots of context and event — never live
+ * state — plus meta. Returns the completion event to dispatch (typed against
+ * the machine's full event union), or null for fire-and-forget.
+ *
+ * Effects are infallible by construction: catch inside and return your
+ * declared failure event. A throw is the runtime backstop — logged and
+ * dropped, never a crash. See the engine-effects spec.
+ *
+ * Authoring note: annotate the effect's return type with your machine's event
+ * union — `effect: async (ctx, ev, meta): Promise<Events | null> => …`.
+ * TypeScript defers context-sensitive arrows during `defineMachine`'s generic
+ * inference, so an unannotated return widens its event literals and fails to
+ * typecheck (loudly — never silently unchecked). The annotation restores full
+ * checking: an undeclared completion event type is a compile error.
+ */
+export type Effect<C, E extends EventObject, EAll extends EventObject = EventObject> = (
+  ctx: C,
+  ev: E,
+  meta: EffectMeta,
+) => Promise<EAll | null>
+
+/** A scheduled effect surfaced to the host: everything needed to run it and
+ *  dispatch its completion. `run` closes over the commit-time snapshots. */
+export interface EffectInvocation {
+  machineName: string
+  effectId: string
+  run: () => Promise<EventObject | null>
+}
+
+/** Object form of a transition. A bare `Action` is sugar for `{ do: fn }`.
+ *  `E` is the event narrowed to this `on` key; `EAll` is the machine's full
+ *  event union (what an effect's completion event is typed against). */
+export interface TransitionConfig<
+  C,
+  E extends EventObject,
+  S extends string,
+  R = Record<string, any>,
+  EAll extends EventObject = EventObject,
+> {
+  /** Target state. Omit for a self-transition (action only, no state change). */
+  to?: S
+  /** Guard — transition is skipped if it returns false. */
+  when?: Guard<C, E, R>
+  /** Action — mutates the draft context. */
+  do?: Action<C, E, R>
+  /** Declared emit(s) to fire after the action commits. */
+  emit?: string | string[]
+  /** Async I/O, host-scheduled after commit. See `Effect`. */
+  effect?: Effect<C, E, EAll>
+}
+
+export type Transition<
+  C,
+  E extends EventObject,
+  S extends string,
+  R = Record<string, any>,
+  EAll extends EventObject = EventObject,
+> = Action<C, E, R> | TransitionConfig<C, E, S, R, EAll>
+
+/** The `on` map: each event type maps to a transition (or an ordered array of
+ *  guarded candidates — first whose `when` passes wins) whose action/guard see
+ *  the event NARROWED to exactly that type. This is the Option A payoff. */
+export type OnMap<C, E extends EventObject, S extends string, R = Record<string, any>> = {
+  [K in E['type']]?:
+    | Transition<C, Extract<E, { type: K }>, S, R, E>
+    | Array<Transition<C, Extract<E, { type: K }>, S, R, E>>
+}
+
+export interface StateNode<C, E extends EventObject, S extends string, R = Record<string, any>> {
+  on?: OnMap<C, E, S, R>
+}
+
+/** Payload selector runs synchronously AFTER the transition's action, so it
+ *  sees post-mutation context. Pure of (ctx, ev). The event is typed `any`
+ *  because an emit may fire from several transitions carrying different events;
+ *  the originating event isn't statically pinned to one union member. (Tighter
+ *  emit typing is tracked as an open question on the engine spec.) */
+export interface EmitDeclaration<C, _E extends EventObject = EventObject> {
+  payload?: (ctx: C, ev: any) => Record<string, unknown>
+}
+
+export type EmitsConfig<C, E extends EventObject> =
+  | readonly string[]
+  | Record<string, EmitDeclaration<C, E> | null>
+
+/** A machine's capability classification. `serverPinned` means it may not be
+ *  placed on the client; `reasons` explains why (surfaced in compile errors). */
+export interface Capabilities {
+  serverPinned: boolean
+  reasons: string[]
+}
+
+/** Compact, engine-owned snapshot. Serializes for the Store (server sessions)
+ *  and seeds a client actor on custom-element upgrade (hydration). */
+export interface Snapshot<C> {
+  /** State path. Depth-1 today (`['idle']`); extensible to hierarchy. */
+  value: string[]
+  context: C
+}
+
+export type Lifecycle = 'app' | 'session'
+
+/** Cross-machine subscription entry (carried through unchanged from the POC
+ *  model; the glue layer consumes it). */
+export interface SubscribeEntry {
+  from: AnyMachineDef
+  event: string
+  dispatch: string | { type: string; [k: string]: unknown }
+}
+
+export interface MachineDef<
+  C = any,
+  E extends EventObject = any,
+  S extends string = string,
+  Sel extends SelectorMap<C> = SelectorMap<C>,
+  Name extends string = string,
+> {
+  readonly __isStatorMachine: true
+  name: Name
+  lifecycle: Lifecycle
+  /** APP machines only: snapshot persists through the AppStore across
+   *  restarts (opt-in; see DefineMachineConfig.persist). */
+  persist: boolean
+  reads: AnyMachineDef[]
+  subscribes: SubscribeEntry[]
+  /** Normalized: every declared emit, possibly with a payload selector. */
+  emits: Record<string, EmitDeclaration<C, E>>
+  selectors: Sel
+  capabilities: Capabilities
+  initial: string
+  /** Engine internals — the transition graph (R erased post-construction; the
+   *  reads typing that matters is enforced at the authoring callsite) and the
+   *  initial context. */
+  states: Record<string, StateNode<C, E, S>>
+  context: C
+  /** Type-level carriers — never read at runtime. */
+  readonly __context: C
+  readonly __event: E
+}
+
+/** The "top type" for a machine def — used wherever a heterogeneous collection
+ *  of machines is held (e.g. `reads`). `any` in the slots is deliberate:
+ *  `MachineDef` is invariant in its context (context appears in contravariant
+ *  action-parameter positions), so a specific `MachineDef<{...}>` is NOT
+ *  assignable to `MachineDef<unknown>` — only `any` admits every concrete def.
+ *  Callsite type-safety is recovered via `ReadsMap` inference, not here. */
+export type AnyMachineDef = MachineDef<any, any, any, any, any>
+
+/** The instance-facing shape of a machine: each selector exposed as a property
+ *  carrying that selector's return type (callable if the selector returns a
+ *  function). This is what `helpers.reads.<Name>` resolves to. */
+export type InstanceOf<TDef extends AnyMachineDef> =
+  TDef extends MachineDef<any, any, any, infer Sel, any>
+    ? { readonly [K in keyof Sel]: ReturnType<Sel[K]> }
+    : never
+
+/** Build the typed `helpers.reads` map from a tuple of read machines: keyed by
+ *  each machine's literal `name`, valued by its instance type. */
+export type ReadsMap<TReads extends readonly AnyMachineDef[]> = {
+  [M in TReads[number] as M['name']]: InstanceOf<M>
+}
+
+/** The event union a machine accepts — used to type machine-mediated dispatch
+ *  (`dispatch(Machine, event)`) against the imported def. */
+export type EventOf<D extends AnyMachineDef> =
+  D extends MachineDef<any, infer E, any, any, any> ? E : never
+
+export function isStatorMachine(v: unknown): v is AnyMachineDef {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isStatorMachine === true
+  )
+}

package/src/server/api-route.ts

@@ -0,0 +1,149 @@
+import type { Context } from 'hono'
+import { setCookie } from 'hono/cookie'
+import { scheduleSessionEffects } from './effects.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+import type { RenderedResponseEffects } from './render.ts'
+import type { DiscoveredRoute } from './route-discovery.ts'
+import { buildRouteRequest } from './route-request.ts'
+import type {
+  ApiRouteDefinition,
+  ApiRouteEnvelope,
+  ApiRouteHelpers,
+  Directive,
+  RouteRequest,
+} from './routing.ts'
+import { getOrCreateSessionId } from './session.ts'
+import { withSessionLock } from './session-lock.ts'
+import { SessionRuntime } from './session-runtime.ts'
+import { fanOut } from './sse.ts'
+
+const apiLog = scopedLogger('api')
+
+/**
+ * Run an API route handler under a fresh SessionRuntime, marshal the
+ * result into an HTTP response, fan-out to live SSE connections.
+ *
+ * The handler can return:
+ *   - A raw Response (escape hatch; framework returns it verbatim).
+ *   - A directives envelope `{ patches?, directives? }`. The framework
+ *     synthesizes the HTTP response based on the client's Accept header:
+ *     `text/html` gets a 303 redirect (or a re-render of the source page);
+ *     anything else (default JSON for the client runtime) gets the
+ *     envelope as JSON.
+ */
+export async function runApiRoute(
+  c: Context,
+  discovered: DiscoveredRoute,
+  route: ApiRouteDefinition,
+  store: MachineStore,
+  /** Path params from the framework's own matcher (the dispatch catch-all
+   *  bypasses Hono's per-route param extraction). */
+  params?: Record<string, string>,
+): Promise<Response> {
+  const { sessionId } = getOrCreateSessionId(c)
+  const request = params
+    ? { ...buildRouteRequest(c, discovered.paramNames), params }
+    : buildRouteRequest(c, discovered.paramNames)
+
+  return withSessionLock(sessionId, async () => {
+    const runtime = new SessionRuntime(sessionId, store)
+    try {
+      await runtime.loadGraph(route.reads)
+      runtime.wireSubscriptions()
+
+      // Track which machines got touched so we can persist + fan-out.
+      const touched = new Set<string>()
+
+      const helpers: ApiRouteHelpers = {
+        dispatch: async (machine, event) => {
+          // API routes have no render target to diff against, so dispatches
+          // here don't produce patches. (Patches from API-route dispatches
+          // would need a target page; that's a future spec.)
+          // The target machine is addressed by its def; read the name off it.
+          const dispatchedTouched = runtime.processEvent(machine.name, event)
+          for (const name of dispatchedTouched) touched.add(name)
+        },
+      }
+
+      let result: Response | ApiRouteEnvelope
+      try {
+        result = await route.handler(request, helpers)
+      } catch (err) {
+        apiLog.error({ err: String(err), path: c.req.path }, 'api route handler threw')
+        return c.text('Internal Server Error', 500)
+      }
+
+      if (touched.size > 0) {
+        await runtime.persistTouched(touched)
+        await fanOut(touched, { sessionId })
+      }
+      // Effects queued by dispatched events run after this callback returns
+      // (never under the session lock); see server/effects.ts.
+      scheduleSessionEffects(runtime, store, sessionId)
+
+      // Escape hatch: handler returned a real Response. Pass through.
+      if (result instanceof Response) return result
+
+      const envelope = result as ApiRouteEnvelope
+      return synthesizeResponse(c, request, envelope)
+    } finally {
+      runtime.dispose()
+    }
+  })
+}
+
+/**
+ * Content-negotiated response synthesis from a directives envelope.
+ *
+ * - HTML clients (Accept includes text/html, typical for raw browser form
+ *   POSTs) get an HTTP-native equivalent. The first `navigate` directive
+ *   becomes a 303 + Location. `reload` becomes a 303 back to the referer.
+ *   Without a directive, return a minimal 204.
+ * - JSON clients (client runtime, default) get the envelope as JSON.
+ */
+function synthesizeResponse(
+  c: Context,
+  request: RouteRequest,
+  envelope: ApiRouteEnvelope,
+): Response {
+  const accept = request.headers.get('accept') ?? ''
+  const wantsHtml = accept.includes('text/html') && !accept.includes('application/json')
+
+  if (wantsHtml) {
+    const navigate = envelope.directives?.find(
+      (d): d is Extract<Directive, { type: 'navigate' }> => d.type === 'navigate',
+    )
+    if (navigate) {
+      return c.redirect(navigate.to, 303)
+    }
+    const reload = envelope.directives?.find((d) => d.type === 'reload')
+    if (reload) {
+      const ref = request.headers.get('referer') ?? '/'
+      return c.redirect(ref, 303)
+    }
+    // No actionable directive for a no-JS client. Send a minimal 204.
+    return new Response(null, { status: 204 })
+  }
+
+  // JSON / client-runtime path.
+  return c.json({
+    patches: envelope.patches ?? [],
+    directives: envelope.directives ?? [],
+  })
+}
+
+/** Apply rendered response effects (cookies, headers, status) to a Hono
+ *  context. Used for GET routes that wrote to the response side-effect
+ *  surface during render. */
+export function applyRenderedEffects(c: Context, effects: RenderedResponseEffects): void {
+  effects.headers.forEach((value, key) => {
+    c.header(key, value)
+  })
+  for (const cookie of effects.cookies) {
+    setCookie(c, cookie.name, cookie.value, cookie.options as never)
+  }
+  if (effects.status !== 200) {
+    c.status(effects.status as never)
+  }
+}

package/src/server/app-dispatch.ts

@@ -0,0 +1,52 @@
+import type { AnyMachineDef, EventOf } from '../engine/index.ts'
+import { withDispatchContext } from './dispatch-context.ts'
+import type { MachineStore } from './machine-store.ts'
+import { SessionRuntime } from './session-runtime.ts'
+import { fanOut } from './sse.ts'
+
+/**
+ * Server-originated dispatch to an APP-lifecycle machine — the entry point
+ * for webhooks, cron jobs, and app-effect completions. No HTTP request, no
+ * session, no lock (app actors are long-lived and in-process; sends are
+ * atomic): send → persist opted-in touched app machines → fan out to every
+ * live SSE connection whose route reads a touched machine.
+ *
+ * Typed like client dispatch: the machine is addressed by its imported def
+ * and the event checks against its declared union.
+ */
+export async function dispatchToApp<D extends AnyMachineDef>(
+  store: MachineStore,
+  machine: D,
+  event: EventOf<D>,
+): Promise<void> {
+  const name = machine.name
+  const handle = store.appInstance(name)
+  if (!handle) {
+    const known = store.hasMachine(name)
+    throw new Error(
+      known
+        ? `stator: dispatchToApp("${name}") — machine is not app-lifecycle. ` +
+            `Session machines are dispatched per-session via /__events or an API route.`
+        : `stator: dispatchToApp("${name}") — unknown machine. Is it in the machines directory?`,
+    )
+  }
+
+  const touched = new Set<string>([name])
+  // A throwaway runtime backs `reads` resolution for the dispatch context:
+  // app machines resolve via its app-instance fallback, and a stray read of a
+  // session machine throws (correct — there is no session here).
+  const runtime = new SessionRuntime(`@app-dispatch:${name}`, store)
+  try {
+    const before = handle.actor.getCommitCount()
+    withDispatchContext({ runtime, touched }, () => {
+      handle.actor.send(event as never)
+    })
+    if (handle.actor.getCommitCount() === before) touched.delete(name)
+    for (const touchedName of touched) {
+      await store.persistAppMachine(touchedName)
+    }
+    await fanOut(touched)
+  } finally {
+    runtime.dispose()
+  }
+}

package/src/server/app-store.ts

@@ -0,0 +1,35 @@
+/**
+ * Persistence boundary for APP-lifecycle machine state — a sibling of the
+ * session `Store`, deliberately not a merger (see the app-machine-state-
+ * persistence spec): app state is one blob per machine name, has NO TTL
+ * (process-equivalent persistence, not user-session storage), and no
+ * per-session sharding key.
+ *
+ * Opt-in per machine via `persist: true` in `defineMachine` — some app
+ * machines genuinely should reset on restart (caches, connection pools).
+ *
+ * Single-writer assumption: two replicas both persisting the same app
+ * machine will drift. Multi-replica coordination is out of scope for 1.x —
+ * see the spec's open questions.
+ */
+export interface AppStore {
+  loadAppMachine(name: string): Promise<unknown | null>
+  saveAppMachine(name: string, snapshot: unknown): Promise<void>
+}
+
+/** Process-memory implementation — same restart-wipe semantics as no
+ *  persistence at all; exists so the interface is uniform and tests are
+ *  trivial. */
+export class InMemoryAppStore implements AppStore {
+  private data = new Map<string, unknown>()
+
+  async loadAppMachine(name: string): Promise<unknown | null> {
+    return this.data.has(name) ? this.data.get(name)! : null
+  }
+
+  async saveAppMachine(name: string, snapshot: unknown): Promise<void> {
+    // Clone through JSON so callers can't mutate stored state by reference —
+    // and so anything non-serializable fails here, not in a Redis swap later.
+    this.data.set(name, JSON.parse(JSON.stringify(snapshot)))
+  }
+}

package/src/server/cached-store.ts

@@ -0,0 +1,117 @@
+import type { Store } from './store.ts'
+
+interface CacheEntry {
+  snapshot: unknown
+  /** Epoch ms after which this entry is considered expired. */
+  expiresAt: number
+}
+
+export interface CachedStoreOptions {
+  /** Max number of (sessionId, machineName) entries kept in memory. LRU
+   *  eviction when exceeded. Defaults to 10_000. */
+  maxEntries?: number
+  /** Memory cache TTL per entry, in seconds. Capped at the backing TTL
+   *  on a per-set basis — memory never out-lives backing. Defaults to 300
+   *  (5 minutes). */
+  memoryTtlSeconds?: number
+}
+
+/**
+ * Write-through, read-cached `Store` decorator.
+ *
+ * Wraps any backing `Store` and keeps a small in-process LRU of recent
+ * reads to reduce backing-store traffic (Upstash command counts, Redis
+ * hops, etc.) on hot sessions.
+ *
+ * Properties:
+ *   - **Writes go to backing first**, then update memory. No data loss on
+ *     crash; durability matches backing.
+ *   - **Memory TTL ≤ backing TTL** per entry. When `set` is called with
+ *     `ttlSeconds`, the memory entry's expiry is `min(memoryTtlMs, ttlMs)`.
+ *     Memory cannot hold a value that backing would have expired.
+ *   - **Bounded by `maxEntries`**, LRU evicted via Map insertion-order
+ *     plus delete-then-set on access (`populate` and successful `get`).
+ *   - **Safe in single-replica deployments** where this process is the
+ *     only writer to the backing store. Not safe across replicas — would
+ *     need an invalidation channel (Redis pub/sub) for that.
+ */
+export class CachedStore implements Store {
+  private cache = new Map<string, CacheEntry>()
+  private readonly maxEntries: number
+  private readonly memoryTtlMs: number
+
+  constructor(
+    private readonly backing: Store,
+    opts: CachedStoreOptions = {},
+  ) {
+    this.maxEntries = opts.maxEntries ?? 10_000
+    this.memoryTtlMs = (opts.memoryTtlSeconds ?? 300) * 1000
+  }
+
+  private key(sid: string, name: string): string {
+    return `${sid}:${name}`
+  }
+
+  async get(sid: string, name: string): Promise<unknown | null> {
+    const k = this.key(sid, name)
+    const entry = this.cache.get(k)
+    if (entry) {
+      if (entry.expiresAt > Date.now()) {
+        // LRU bump: move to end of insertion order.
+        this.cache.delete(k)
+        this.cache.set(k, entry)
+        return entry.snapshot
+      }
+      // Expired — drop it and fall through to backing.
+      this.cache.delete(k)
+    }
+    const fresh = await this.backing.get(sid, name)
+    if (fresh !== null) {
+      this.populate(k, fresh, this.memoryTtlMs)
+    }
+    return fresh
+  }
+
+  async set(
+    sid: string,
+    name: string,
+    snapshot: unknown,
+    opts?: { ttlSeconds?: number },
+  ): Promise<void> {
+    // Write-through: backing first so durability matches its semantics
+    // even if the process crashes mid-set.
+    await this.backing.set(sid, name, snapshot, opts)
+    const backingTtlMs = opts?.ttlSeconds != null ? opts.ttlSeconds * 1000 : Infinity
+    this.populate(this.key(sid, name), snapshot, Math.min(this.memoryTtlMs, backingTtlMs))
+  }
+
+  async has(sid: string, name: string): Promise<boolean> {
+    const entry = this.cache.get(this.key(sid, name))
+    if (entry && entry.expiresAt > Date.now()) return true
+    return this.backing.has(sid, name)
+  }
+
+  async deleteSession(sid: string): Promise<void> {
+    const prefix = `${sid}:`
+    for (const k of [...this.cache.keys()]) {
+      if (k.startsWith(prefix)) this.cache.delete(k)
+    }
+    await this.backing.deleteSession(sid)
+  }
+
+  /** Insert / refresh an entry at LRU-end and evict oldest if over capacity. */
+  private populate(key: string, snapshot: unknown, ttlMs: number): void {
+    this.cache.delete(key)
+    this.cache.set(key, { snapshot, expiresAt: Date.now() + ttlMs })
+    while (this.cache.size > this.maxEntries) {
+      const oldest = this.cache.keys().next().value
+      if (!oldest) break
+      this.cache.delete(oldest)
+    }
+  }
+
+  /** Diagnostic: current cached entry count. */
+  get size(): number {
+    return this.cache.size
+  }
+}

package/src/server/create-app.ts

@@ -0,0 +1,83 @@
+import { resolve } from 'node:path'
+import { serve } from '@hono/node-server'
+import type { AppStore } from './app-store.ts'
+import { discoverMachines } from './discovery.ts'
+import { wireAppEffects } from './effects.ts'
+import { buildHonoApp } from './http.ts'
+import { logger } from './logger.ts'
+import { MachineStore } from './machine-store.ts'
+import { discoverRoutes } from './route-discovery.ts'
+import { InMemoryStore, type Store } from './store.ts'
+
+export interface CreateAppConfig {
+  machinesDir: string
+  routesDir: string
+  staticDir?: string
+  /** Persistence adapter for session-lifecycle machine state. Defaults to
+   *  InMemoryStore — fine for dev, V1 adapters swap in here. */
+  store?: Store
+  /** Persistence for `persist: true` app-lifecycle machines (no TTL, one
+   *  blob per machine). Defaults to in-memory (restart-wipe); pass
+   *  RedisAppStore for durable app state. */
+  appStore?: AppStore
+  /** Per-session TTL in seconds. Every set to any of the session's
+   *  machines refreshes this expiry. Defaults to 24h (86400). */
+  sessionTtlSeconds?: number
+  /** Extra `<head>` HTML per GET route. A production build uses this to link the
+   *  prebuilt `components.css`; ignored if omitted. */
+  headExtras?: (filePath: string) => string | Promise<string>
+  /** Serve + inject the wire inspector toolbar (the dev server's on by
+   *  default; production opts in — demo sites want the wire visible). */
+  inspector?: boolean
+}
+
+export interface StatorApp {
+  listen(port: number): Promise<void>
+  /** For tests — get the underlying Hono fetch handler. */
+  fetch: (request: Request) => Response | Promise<Response>
+  /** The machine registry + app actors — pass to `dispatchToApp` for
+   *  server-originated events (webhooks, cron). */
+  store: MachineStore
+}
+
+export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
+  const machinesDir = resolve(config.machinesDir)
+  const routesDir = resolve(config.routesDir)
+  const staticDir = config.staticDir ? resolve(config.staticDir) : undefined
+
+  const { defs } = await discoverMachines(machinesDir)
+  const persistence = config.store ?? new InMemoryStore()
+  const store = new MachineStore(defs, persistence, {
+    sessionTtlSeconds: config.sessionTtlSeconds,
+    appStore: config.appStore,
+  })
+  await store.bootAppMachines()
+  wireAppEffects(store)
+
+  const routes = await discoverRoutes(routesDir)
+  const app = await buildHonoApp({
+    routes,
+    store,
+    staticDir,
+    headExtras: config.inspector
+      ? async (filePath) => {
+          const base = (await config.headExtras?.(filePath)) ?? ''
+          return `${base}\n<script src="/@stator/inspector.js" defer></script>`
+        }
+      : config.headExtras,
+    inspector: config.inspector,
+  })
+
+  return {
+    listen(port: number): Promise<void> {
+      return new Promise((resolveFn) => {
+        serve({ fetch: app.fetch, port }, () => {
+          logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
+          resolveFn()
+        })
+      })
+    },
+    fetch: (request: Request) => app.fetch(request),
+    store,
+  }
+}

package/src/server/define-machine.ts

@@ -0,0 +1,10 @@
+/**
+ * The framework's machine API now lives in `../engine` — Stator's own
+ * isomorphic state-machine engine (replacing the XState-backed POC). This
+ * module re-exports it so existing server-side imports keep resolving, and
+ * adds the small back-compat alias the glue layer still references.
+ */
+export * from '../engine/index.ts'
+
+/** The dispatch shape a subscription delivers to its target. */
+export type SubscribeEvent = string | { type: string; [k: string]: unknown }