@statorjs/stator 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.5.1"
+    "@statorjs/stator": "1.6.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/client-id.ts

@@ -8,3 +8,12 @@ export const clientId: string =
   typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
     : `c${Math.random().toString(36).slice(2)}`
+
+/** Per-dispatch idempotency key: the server replays a duplicate POST's cached
+ *  response instead of re-applying it, which is what makes retrying a lost
+ *  response safe. Stable across retries of the SAME dispatch, never reused. */
+export function newEventId(): string {
+  return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+    ? crypto.randomUUID()
+    : `e${Math.random().toString(36).slice(2)}`
+}

package/src/client/dispatch.ts

@@ -1,7 +1,8 @@
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { applyDirectives, applyPatches } from '../wire/apply.ts'
 import type { WireEnvelope } from '../wire/index.ts'
-import { clientId } from './client-id.ts'
+import { newEventId } from './client-id.ts'
+import { type DispatchError, postEvent } from './transport.ts'
 
 export interface DispatchResult {
   /** The POST reached the server and returned 200. */
@@ -12,6 +13,8 @@ export interface DispatchResult {
   /** Patches applied to THIS page (a committed event may patch zero slots
    *  here if the touched machines aren't bound on the current route). */
   patchCount: number
+  /** Present only when `ok` is false — how the POST failed. */
+  error?: DispatchError
 }
 
 /**
@@ -30,28 +33,14 @@ export async function dispatch<D extends AnyMachineDef>(
   machine: D,
   event: EventOf<D>,
 ): Promise<DispatchResult> {
-  let res: Response
-  try {
-    res = await fetch('/__events', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        'X-Stator-Route': `GET ${location.pathname}${location.search}`,
-        'X-Stator-Client': clientId,
-      },
-      credentials: 'same-origin',
-      body: JSON.stringify({ machine: machine.name, event }),
-    })
-  } catch (err) {
-    console.error('stator: dispatch network error', err)
-    return { ok: false, committed: false, patchCount: 0 }
+  const result = await postEvent(
+    { machine: machine.name, event, eventId: newEventId() },
+    `GET ${location.pathname}${location.search}`,
+  )
+  if (!result.ok) {
+    return { ok: false, committed: false, patchCount: 0, error: result.error }
   }
-  if (!res.ok) {
-    console.error('stator: dispatch failed', res.status)
-    return { ok: false, committed: false, patchCount: 0 }
-  }
-  const data = (await res.json()) as WireEnvelope
+  const data = (await result.res.json()) as WireEnvelope
   applyPatches(data.patches ?? [])
   applyDirectives(data.directives ?? [])
   return {

package/src/client/inspector.ts

@@ -155,6 +155,21 @@ function mount(): void {
     )
   })
 
+  window.addEventListener('stator:dispatch-error', (e: Event) => {
+    const { machine, phase, status, timestamp } = (e as CustomEvent).detail
+    addEntry(
+      'up',
+      `<div class="stator-inspector-summary">
+        <span class="stator-inspector-time">${fmtTime(timestamp)}</span>
+        <span class="stator-inspector-arrow">✕</span>
+        <span class="stator-inspector-machine">${escapeHtml(machine ?? 'form')}</span>
+        <span class="stator-inspector-event-type">${escapeHtml(phase)}</span>
+        <span class="stator-inspector-params">${status != null ? escapeHtml(String(status)) : ''}</span>
+      </div>`,
+      (e as CustomEvent).detail,
+    )
+  })
+
   window.addEventListener('stator:patches-received', (e: Event) => {
     const { patches, source, durationMs, timestamp } = (e as CustomEvent).detail
     const timing = durationMs != null ? `${durationMs}ms` : ''

package/src/client/runtime.ts

@@ -19,10 +19,35 @@
 
 import { applyDirectives, applyPatches } from '../wire/apply.ts'
 import type { WireEnvelope } from '../wire/index.ts'
-import { clientId } from './client-id.ts'
+import { clientId, newEventId } from './client-id.ts'
+import { emitDispatchError, fetchWithTimeout, postEvent, TimeoutError } from './transport.ts'
 
 const EVENT_TYPES = ['click', 'submit', 'change', 'input'] as const
 
+/* ------------------------------------------------------------------ */
+/* In-flight affordance                                                */
+/* ------------------------------------------------------------------ */
+
+/** `data-stator-pending` marks the element whose event POST is in flight
+ *  (CSS hook: `[data-stator-pending]`). Counted per element so rapid repeat
+ *  dispatches keep the attribute until the LAST one settles. */
+const pendingCounts = new WeakMap<Element, number>()
+
+function beginPending(el: Element): void {
+  pendingCounts.set(el, (pendingCounts.get(el) ?? 0) + 1)
+  el.setAttribute('data-stator-pending', '')
+}
+
+function endPending(el: Element): void {
+  const count = (pendingCounts.get(el) ?? 1) - 1
+  if (count <= 0) {
+    pendingCounts.delete(el)
+    el.removeAttribute('data-stator-pending')
+  } else {
+    pendingCounts.set(el, count)
+  }
+}
+
 /* ------------------------------------------------------------------ */
 /* Observability hooks                                                 */
 /* ------------------------------------------------------------------ */
@@ -42,25 +67,30 @@ function init(): void {
   initLiveChannel()
 }
 
-function initLiveChannel(): void {
+function initLiveChannel(): { close(): void } | undefined {
   const meta = document.querySelector('meta[name="stator-live"][content="true"]')
   if (!meta) return
 
   const routeKey = `GET ${location.pathname}${location.search}`
   const url = `/__sse?route=${encodeURIComponent(routeKey)}&client=${encodeURIComponent(clientId)}`
-  const sse = new EventSource(url, { withCredentials: true })
 
-  let everOpened = false
-  sse.addEventListener('open', () => {
-    if (everOpened) {
-      // Reconnect — reload rather than risk stale state.
-      location.reload()
-      return
-    }
-    everOpened = true
-  })
+  // Connection-state signal: `data-stator-connection` on the root element
+  // (CSS hook for offline banners etc.) plus a `stator:connection-state`
+  // event. Change-guarded — EventSource fires `error` on every failed
+  // auto-reconnect attempt, and only transitions are worth announcing.
+  let connectionState: string | undefined
+  const setConnectionState = (state: 'connected' | 'disconnected' | 'stale'): void => {
+    if (state === connectionState) return
+    connectionState = state
+    document.documentElement.setAttribute('data-stator-connection', state)
+    emit('stator:connection-state', { state, timestamp: Date.now() })
+  }
+
+  let sse: EventSource | null = null
+  let lastSeen = Date.now()
 
-  sse.addEventListener('message', (e) => {
+  const onMessage = (e: MessageEvent): void => {
+    lastSeen = Date.now()
     let data: WireEnvelope
     try {
       data = JSON.parse(e.data)
@@ -83,13 +113,57 @@ function initLiveChannel(): void {
     if (data.directives && data.directives.length > 0) {
       applyDirectives(data.directives)
     }
-  })
+  }
 
-  sse.addEventListener('error', () => {
-    if (sse.readyState === EventSource.CLOSED) {
-      console.warn('stator: SSE permanently closed')
+  // Reconnect = resync, never reload. Every fresh /__sse connection gets the
+  // server's initial sync (every binding's current value, keyed lists reset
+  // wholesale), so a rebuilt channel converges the DOM in place — and the
+  // browser's own auto-reconnect on the same instance re-runs that server
+  // path too, its sync arriving as an ordinary message. Directives fired
+  // during an outage (e.g. a navigate) are not replayed; resync converges
+  // state only.
+  const connect = (): void => {
+    sse?.close()
+    const es = new EventSource(url, { withCredentials: true })
+    sse = es
+    lastSeen = Date.now() // fresh grace period — no instant re-stale loop
+    es.addEventListener('open', () => setConnectionState('connected'))
+    es.addEventListener('message', onMessage)
+    es.addEventListener('error', () => {
+      setConnectionState('disconnected')
+      if (es.readyState === EventSource.CLOSED) {
+        console.warn('stator: SSE permanently closed')
+      }
+    })
+  }
+
+  // Zombie watchdog. A half-open connection (device sleep, silent NAT drop)
+  // never fires `error` — EventSource just sits "open" and silent forever,
+  // and the page quietly stops being live. The server sends an observable
+  // ping every 25s; two missed pings while the page is VISIBLE means the
+  // channel is dead, and a rebuilt connection re-syncs. Hidden tabs wait for
+  // visibility — no churn for pages nobody is watching.
+  const STALE_MS = 65_000
+  const checkStale = (): void => {
+    if (document.hidden) return
+    if (Date.now() - lastSeen > STALE_MS) {
+      console.warn('stator: SSE channel stale — reconnecting to re-sync')
+      setConnectionState('stale')
+      connect()
     }
-  })
+  }
+  const watchdog = setInterval(checkStale, 10_000)
+  document.addEventListener('visibilitychange', checkStale)
+
+  connect()
+
+  return {
+    close(): void {
+      clearInterval(watchdog)
+      document.removeEventListener('visibilitychange', checkStale)
+      sse?.close()
+    },
+  }
 }
 
 function handleEvent(e: Event): void {
@@ -111,7 +185,7 @@ function handleEvent(e: Event): void {
           console.error('stator: malformed event descriptor on form', form, descriptorAttr)
           return
         }
-        void dispatchEvent(descriptor)
+        void dispatchEvent(descriptor, form)
         return
       }
       // Opt-in interception via `data-stator-enhance`. Plain forms without
@@ -148,13 +222,13 @@ function handleEvent(e: Event): void {
     return
   }
 
-  void dispatchEvent(descriptor)
+  void dispatchEvent(descriptor, el)
 }
 
-async function dispatchEvent(descriptor: {
-  machine: string
-  event: { type: string }
-}): Promise<void> {
+async function dispatchEvent(
+  descriptor: { machine: string; event: { type: string } },
+  el?: Element,
+): Promise<void> {
   const routeKey = `GET ${location.pathname}${location.search}`
 
   emit('stator:event-sent', {
@@ -165,28 +239,14 @@ async function dispatchEvent(descriptor: {
   })
 
   const startedAt = performance.now()
-  let res: Response
+  if (el) beginPending(el)
   try {
-    res = await fetch('/__events', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        'X-Stator-Route': routeKey,
-        'X-Stator-Client': clientId,
-      },
-      credentials: 'same-origin',
-      body: JSON.stringify(descriptor),
-    })
-  } catch (err) {
-    console.error('stator: network error during dispatch', err)
-    return
-  }
-  if (!res.ok) {
-    console.error('stator: event POST failed', res.status, await res.text())
-    return
+    const result = await postEvent({ ...descriptor, eventId: newEventId() }, routeKey)
+    if (!result.ok) return
+    await applyEnvelopeFromResponse(result.res, startedAt, 'post')
+  } finally {
+    if (el) endPending(el)
   }
-  await applyEnvelopeFromResponse(res, startedAt, 'post')
 }
 
 /**
@@ -197,23 +257,30 @@ async function dispatchEvent(descriptor: {
 async function submitForm(form: HTMLFormElement): Promise<void> {
   const formData = new FormData(form)
   const startedAt = performance.now()
-  let res: Response
+  beginPending(form)
   try {
-    res = await fetch(form.action, {
-      method: 'POST',
-      headers: { Accept: 'application/json' },
-      credentials: 'same-origin',
-      body: formData,
-    })
-  } catch (err) {
-    console.error('stator: network error during form submit', err)
-    return
-  }
-  if (!res.ok) {
-    console.error('stator: form submit failed', res.status, await res.text())
-    return
+    let res: Response
+    try {
+      res = await fetchWithTimeout(form.action, {
+        method: 'POST',
+        headers: { Accept: 'application/json' },
+        credentials: 'same-origin',
+        body: formData,
+      })
+    } catch (err) {
+      console.error('stator: network error during form submit', err)
+      emitDispatchError({ phase: err instanceof TimeoutError ? 'timeout' : 'network' }, {})
+      return
+    }
+    if (!res.ok) {
+      console.error('stator: form submit failed', res.status, await res.text())
+      emitDispatchError({ phase: 'http', status: res.status }, {})
+      return
+    }
+    await applyEnvelopeFromResponse(res, startedAt, 'post')
+  } finally {
+    endPending(form)
   }
-  await applyEnvelopeFromResponse(res, startedAt, 'post')
 }
 
 async function applyEnvelopeFromResponse(
@@ -248,3 +315,8 @@ if (document.readyState === 'loading') {
 } else {
   init()
 }
+
+// Exported for tests only — the runtime self-initializes above, and the
+// client bundle (esbuild IIFE) ignores exports. Re-calling init() is safe:
+// addEventListener dedupes an identical listener reference.
+export { init, initLiveChannel }

package/src/client/transport.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared POST transport for the two `/__events` callers — the delegated page
+ * runtime and island `dispatch()`. Lives apart from runtime.ts because that
+ * module self-initializes on import; islands importing `dispatch` must not
+ * drag the page runtime (and its document-wide listeners) into their bundle.
+ *
+ * Failure contract: network errors, timeouts, and non-2xx responses resolve
+ * (never throw) as `{ ok: false, error }`, and a `stator:dispatch-error`
+ * CustomEvent fires on window once per dispatch when the failure is final.
+ */
+
+import { clientId } from './client-id.ts'
+
+/** App-level deadline for event POSTs — browsers' own connection timeouts are
+ *  far too long to leave an interaction hanging on a flaky link. */
+export const FETCH_TIMEOUT_MS = 10_000
+
+/** Backoff before each retry of a network/timeout failure. Retries carry the
+ *  same eventId, so a duplicate that actually reached the server replays. */
+export const RETRY_DELAYS_MS = [300, 1000]
+
+export interface DispatchError {
+  phase: 'network' | 'timeout' | 'http'
+  /** HTTP status — present only for `phase: 'http'`. */
+  status?: number
+}
+
+/** Thrown by `fetchWithTimeout` when the deadline aborts the request, so
+ *  callers can tell a dead-slow connection from an unreachable one. */
+export class TimeoutError extends Error {
+  constructor() {
+    super(`request exceeded ${FETCH_TIMEOUT_MS}ms`)
+    this.name = 'TimeoutError'
+  }
+}
+
+function emit(name: string, detail: unknown): void {
+  window.dispatchEvent(new CustomEvent(name, { detail }))
+}
+
+export function emitDispatchError(
+  error: DispatchError,
+  context: { machine?: string; event?: { type: string } },
+): void {
+  emit('stator:dispatch-error', { ...context, ...error, timestamp: Date.now() })
+}
+
+/** `fetch` with the app-level deadline applied via AbortController. */
+export async function fetchWithTimeout(input: string, init: RequestInit): Promise<Response> {
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort()
+  }, FETCH_TIMEOUT_MS)
+  try {
+    return await fetch(input, { ...init, signal: controller.signal })
+  } catch (err) {
+    throw timedOut ? new TimeoutError() : err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export type PostEventResult = { ok: true; res: Response } | { ok: false; error: DispatchError }
+
+/**
+ * POST an event descriptor to `/__events`. Resolves — never throws — and
+ * emits `stator:dispatch-error` once when a failure is final. Network and
+ * timeout failures retry with backoff, but ONLY when the body carries an
+ * `eventId` (the server's replay cache is what makes a duplicate safe —
+ * keyed-list patches are not idempotent). Non-2xx responses are terminal
+ * immediately: the server saw the event and answered.
+ */
+export async function postEvent(
+  body: { machine: string; event: { type: string }; eventId?: string },
+  routeKey: string,
+): Promise<PostEventResult> {
+  let error: DispatchError
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const res = await fetchWithTimeout('/__events', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          'X-Stator-Route': routeKey,
+          'X-Stator-Client': clientId,
+        },
+        credentials: 'same-origin',
+        body: JSON.stringify(body),
+      })
+      if (res.ok) return { ok: true, res }
+      error = { phase: 'http', status: res.status }
+      console.error('stator: event POST failed', res.status, await res.text())
+      break
+    } catch (err) {
+      error = { phase: err instanceof TimeoutError ? 'timeout' : 'network' }
+      const delay = RETRY_DELAYS_MS[attempt]
+      if (delay === undefined || !body.eventId) {
+        console.error('stator: network error during dispatch', err)
+        break
+      }
+      console.warn(`stator: dispatch ${error.phase} — retrying in ${delay}ms`)
+      await new Promise((r) => setTimeout(r, delay))
+    }
+  }
+  emitDispatchError(error, body)
+  return { ok: false, error }
+}

package/src/server/create-app.ts

@@ -24,6 +24,8 @@ export interface CreateAppConfig {
   /** Per-session TTL in seconds. Every set to any of the session's
    *  machines refreshes this expiry. Defaults to 24h (86400). */
   sessionTtlSeconds?: number
+  /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
+  ssePingMs?: 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>
@@ -69,6 +71,7 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
         }
       : config.headExtras,
     inspector: config.inspector,
+    ssePingMs: config.ssePingMs,
   })
 
   return {

package/src/server/event-dedupe.ts

@@ -0,0 +1,54 @@
+/**
+ * In-process replay cache for `/__events` idempotency keys. A retried POST
+ * whose first attempt committed (but whose response was lost on the wire)
+ * must not re-apply — keyed-list patches are positional and not idempotent —
+ * so the exact response body is cached per (session, eventId) and replayed
+ * verbatim on a duplicate.
+ *
+ * Module-level and in-process, like the SSE connection registry and timers:
+ * single-replica is a stated 1.0 constraint, and the cache carries the same
+ * non-durable contract (a restart forgets it — the retry window is seconds,
+ * the cost of a lost entry is one duplicate apply, and durable delivery is
+ * 1.x inbox work).
+ */
+
+/** Ample for the retry window (client retries at ~0.3s/1s); bounds memory. */
+const MAX_PER_SESSION = 32
+const SESSION_IDLE_MS = 30 * 60_000
+
+interface SessionCache {
+  /** eventId → serialized response body, insertion-ordered for eviction. */
+  byId: Map<string, string>
+  lastTouched: number
+}
+
+const sessions = new Map<string, SessionCache>()
+
+export function replayFor(sessionId: string, eventId: string): string | undefined {
+  const cache = sessions.get(sessionId)
+  if (!cache) return undefined
+  cache.lastTouched = Date.now()
+  return cache.byId.get(eventId)
+}
+
+export function record(sessionId: string, eventId: string, body: string): void {
+  let cache = sessions.get(sessionId)
+  if (!cache) {
+    sweepIdle()
+    cache = { byId: new Map(), lastTouched: 0 }
+    sessions.set(sessionId, cache)
+  }
+  cache.lastTouched = Date.now()
+  cache.byId.set(eventId, body)
+  if (cache.byId.size > MAX_PER_SESSION) {
+    const oldest = cache.byId.keys().next().value
+    if (oldest !== undefined) cache.byId.delete(oldest)
+  }
+}
+
+function sweepIdle(): void {
+  const cutoff = Date.now() - SESSION_IDLE_MS
+  for (const [id, cache] of sessions) {
+    if (cache.lastTouched < cutoff) sessions.delete(id)
+  }
+}

package/src/server/http.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 import { applyRenderedEffects, runApiRoute } from './api-route.ts'
 import { isBlockedCrossSite } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
+import { record, replayFor } from './event-dedupe.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import { initialSyncPatches, recompute } from './recompute.ts'
@@ -33,6 +34,8 @@ export interface HttpConfig {
   /** Serve the dev inspector asset at `/@stator/inspector.js`. The dev server
    *  sets this and injects the script tag; production leaves it off. */
   inspector?: boolean
+  /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
+  ssePingMs?: number
 }
 
 const eventSchema = z.object({
@@ -42,6 +45,8 @@ const eventSchema = z.object({
       type: z.string(),
     })
     .passthrough(),
+  /** Client-generated idempotency key — see server/event-dedupe.ts. */
+  eventId: z.string().min(1).max(128).optional(),
 })
 
 /** Compiled matcher: turns `/p/:id` into a regex that captures params. */
@@ -249,13 +254,17 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         await conn.send(JSON.stringify({ patches: sync }))
       }
 
-      // Keep-alive every 25s so proxy idle timeouts don't close the
-      // connection between real events.
+      // Heartbeat every 25s. This is a real DATA message, not a comment, on
+      // purpose: SSE comments keep proxies from reaping the connection but
+      // are invisible to the browser's EventSource API — a client can't
+      // detect a half-open zombie (device sleep, silent NAT drop: no FIN
+      // ever arrives, no error fires) unless liveness is OBSERVABLE. The
+      // runtime tracks last-message time and reconnects when pings stop.
       const keepAlive = setInterval(() => {
-        stream.write(': keep-alive\n\n').catch(() => {
-          // Stream closed; will be cleaned up by abort handler.
+        void conn.send('{"ping":true}').catch(() => {
+          // Stream closed; the abort handler cleans up.
         })
-      }, 25_000)
+      }, config.ssePingMs ?? 25_000)
 
       try {
         await new Promise<void>((resolveFn) => {
@@ -315,6 +324,17 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     }
 
     return withSessionLock(sessionId, async () => {
+      // Idempotent replay: a duplicate POST (client retry after a lost
+      // response) returns the original response body verbatim instead of
+      // re-applying — keyed-list patches are positional, not idempotent.
+      // Checked under the session lock so a retry racing its first attempt
+      // queues behind it and always sees the recorded body.
+      if (body.eventId) {
+        const cached = replayFor(sessionId, body.eventId)
+        if (cached !== undefined) {
+          return c.body(cached, 200, { 'Content-Type': 'application/json' })
+        }
+      }
       const runtime = new SessionRuntime(sessionId, config.store)
       try {
         await runtime.loadGraph([...route.reads, originDef])
@@ -352,7 +372,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // normal event path in server/effects.ts.
         scheduleSessionEffects(runtime, config.store, sessionId)
 
-        return c.json({ patches, directives: [], committed: touched.size > 0 })
+        const envelope = { patches, directives: [], committed: touched.size > 0 }
+        if (body.eventId) record(sessionId, body.eventId, JSON.stringify(envelope))
+        return c.json(envelope)
       } finally {
         runtime.dispose()
       }