@statorjs/stator 1.5.0 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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.0"
+    "@statorjs/stator": "1.5.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/runtime.ts

@@ -51,6 +51,7 @@ function initLiveChannel(): void {
   const sse = new EventSource(url, { withCredentials: true })
 
   let everOpened = false
+  let lastSeen = Date.now()
   sse.addEventListener('open', () => {
     if (everOpened) {
       // Reconnect — reload rather than risk stale state.
@@ -60,7 +61,26 @@ function initLiveChannel(): void {
     everOpened = true
   })
 
+  // 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 reload re-syncs (same strategy as reconnect).
+  // Hidden tabs wait for visibility — no reloading pages nobody is watching.
+  const STALE_MS = 65_000
+  const staleReload = (): void => {
+    if (!everOpened || document.hidden) return
+    if (Date.now() - lastSeen > STALE_MS) {
+      console.warn('stator: SSE channel stale — reloading to re-sync')
+      sse.close()
+      location.reload()
+    }
+  }
+  setInterval(staleReload, 10_000)
+  document.addEventListener('visibilitychange', staleReload)
+
   sse.addEventListener('message', (e) => {
+    lastSeen = Date.now()
     let data: WireEnvelope
     try {
       data = JSON.parse(e.data)

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/http.ts

@@ -33,6 +33,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({
@@ -249,13 +251,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) => {

package/src/server/machine-store.ts

@@ -200,8 +200,11 @@ export class MachineStore {
               `This is almost always a circular import between machine modules — the module ` +
               `defining "${def.name}" and the module defining its subscription source import ` +
               `each other, and the loader resolved the mid-cycle binding to undefined. ` +
-              `Break the module cycle (e.g. move one machine or the subscription), ` +
-              `or define the mutually-subscribing machines in one module.`,
+              `Break the module cycle: move the DISPLAY selectors into a third machine ` +
+              `that \`reads:\` both sides (the read/write split — see the weather example's ` +
+              `PanelsMachine), or move one machine or the subscription. Note that defining ` +
+              `both machines in one module does NOT work with directory discovery, which ` +
+              `registers default exports only.`,
           )
         }
         if (!this.defs.has(sub.from.name)) {