@statorjs/stator 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.8.0",
+  "version": "2.9.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, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.8.0"
+    "@statorjs/stator": "2.9.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/runtime.ts

@@ -67,7 +67,17 @@ function init(): void {
   initLiveChannel()
 }
 
+/** The page's one live channel. `initLiveChannel` is NOT idempotent on its
+ *  own — each call mints an EventSource and a watchdog interval — so the
+ *  handle is parked here and a second call tears the first one down. Without
+ *  this a re-entered `init()` stacked channels that nothing could reach,
+ *  each holding a socket against the browser's per-origin cap. */
+let liveChannel: { close(): void } | undefined
+
 function initLiveChannel(): { close(): void } | undefined {
+  liveChannel?.close()
+  liveChannel = undefined
+
   const meta = document.querySelector('meta[name="stator-live"][content="true"]')
   if (!meta) return
 
@@ -83,8 +93,12 @@ function initLiveChannel(): { close(): void } | undefined {
   // (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.
+  //
+  // `idle` is a DELIBERATE release, not a fault, and is deliberately its own
+  // state: apps hang offline banners off `disconnected`/`stale`, and reusing
+  // either would flash "you're offline" every time a tab loses focus.
   let connectionState: string | undefined
-  const setConnectionState = (state: 'connected' | 'disconnected' | 'stale'): void => {
+  const setConnectionState = (state: 'connected' | 'disconnected' | 'stale' | 'idle'): void => {
     if (state === connectionState) return
     connectionState = state
     document.documentElement.setAttribute('data-stator-connection', state)
@@ -103,6 +117,10 @@ function initLiveChannel(): { close(): void } | undefined {
       console.error('stator: malformed SSE message', err)
       return
     }
+    // Raw envelope, before interpretation — the observability seam for
+    // inspectors and for the dev client, which reads its rebuild/error
+    // signals off this instead of opening a second event-stream.
+    emit('stator:live-message', { envelope: data, timestamp: Date.now() })
     if (data.patches) {
       // SSE is server-pushed — no client round-trip to time — so report the
       // apply duration (still the useful "how expensive was this update?").
@@ -142,33 +160,118 @@ function initLiveChannel(): { close(): void } | undefined {
     })
   }
 
+  /** Hand the socket back. `es.close()` also stops EventSource's own
+   *  auto-reconnect, so a released channel stays released until we say
+   *  otherwise. */
+  const release = (): void => {
+    if (!sse) return
+    sse.close()
+    sse = null
+    setConnectionState('idle')
+  }
+
   // 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.
+  // channel is dead, and a rebuilt connection re-syncs. Hidden tabs are
+  // either still in their grace period or already released — neither wants a
+  // staleness reconnect.
   const STALE_MS = 65_000
   const checkStale = (): void => {
-    if (document.hidden) return
+    if (document.hidden || !sse) return
     if (Date.now() - lastSeen > STALE_MS) {
       console.warn('stator: SSE channel stale — reconnecting to re-sync')
       setConnectionState('stale')
       connect()
     }
   }
+
+  // ── Proactive release ────────────────────────────────────────────────────
+  // A live page holds one HTTP/1.1 socket for as long as it is open, and the
+  // browser's per-origin pool (6 in Chrome) is shared across every tab in the
+  // profile — so background tabs spend the foreground tab's budget, and
+  // enough of them wedge every request to the origin. Browsers never reclaim
+  // these on their own: hiding a tab throttles timers but leaves sockets
+  // untouched.
+  //
+  // Releasing is cheap here because reconnect is a full resync: a fresh
+  // /__sse gets the server's initial sync, so a released page converges in
+  // place on return. Nothing durable rides the connection — session state
+  // lives in the Store, `after` timers in a process-wide registry, in-flight
+  // effects in a process-wide map — so dropping one costs a re-render, not a
+  // fact.
+  const HIDDEN_GRACE_MS = 30_000
+  let releaseTimer: ReturnType<typeof setTimeout> | undefined
+
+  const cancelRelease = (): void => {
+    if (releaseTimer === undefined) return
+    clearTimeout(releaseTimer)
+    releaseTimer = undefined
+  }
+
+  const onVisibility = (): void => {
+    if (document.hidden) {
+      // Grace period, not an immediate drop: alt-tabbing away for a moment is
+      // not abandonment, and every reconnect costs a full route render server
+      // side. Hidden-tab timer throttling is 1/s, so this fires ~on time; the
+      // 1/min intensive throttling only starts at 5 minutes, long after.
+      cancelRelease()
+      releaseTimer = setTimeout(release, HIDDEN_GRACE_MS)
+    } else {
+      cancelRelease()
+      if (!sse) connect()
+      else checkStale()
+    }
+  }
+
+  // A frozen tab runs no timers at all, so the grace period would never
+  // elapse — release synchronously on the way in. `resume` fires when the
+  // browser thaws the page without a navigation.
+  const onFreeze = (): void => {
+    cancelRelease()
+    release()
+  }
+  const onResume = (): void => {
+    if (!document.hidden && !sse) connect()
+  }
+
+  // pagehide covers both exits: `persisted` means bfcache (the document
+  // survives, and would otherwise sit in the cache still holding a socket and
+  // pinning a SessionRuntime), plain unload means it's going away. Either way
+  // the connection has no further use. pageshow with `persisted` is the
+  // bfcache restore — reconnect and resync.
+  const onPageHide = (): void => {
+    cancelRelease()
+    release()
+  }
+  const onPageShow = (e: PageTransitionEvent): void => {
+    if (e.persisted && !document.hidden && !sse) connect()
+  }
+
   const watchdog = setInterval(checkStale, 10_000)
-  document.addEventListener('visibilitychange', checkStale)
+  document.addEventListener('visibilitychange', onVisibility)
+  document.addEventListener('freeze', onFreeze)
+  document.addEventListener('resume', onResume)
+  window.addEventListener('pagehide', onPageHide)
+  window.addEventListener('pageshow', onPageShow)
 
   connect()
 
-  return {
+  liveChannel = {
     close(): void {
       clearInterval(watchdog)
-      document.removeEventListener('visibilitychange', checkStale)
+      cancelRelease()
+      document.removeEventListener('visibilitychange', onVisibility)
+      document.removeEventListener('freeze', onFreeze)
+      document.removeEventListener('resume', onResume)
+      window.removeEventListener('pagehide', onPageHide)
+      window.removeEventListener('pageshow', onPageShow)
       sse?.close()
+      sse = null
     },
   }
+  return liveChannel
 }
 
 function handleEvent(e: Event): void {
@@ -323,5 +426,6 @@ if (document.readyState === 'loading') {
 
 // 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.
+// addEventListener dedupes an identical listener reference, and the live
+// channel closes its predecessor before opening a replacement.
 export { init, initLiveChannel }

package/src/server/dev-native.ts

@@ -33,7 +33,10 @@ import { logger, setLogLevel } from './logger.ts'
 import { codeHashOf, codeInputsOf } from './machine-hash.ts'
 import { MachineStore } from './machine-store.ts'
 import { discoverMiddleware } from './middleware.ts'
+import type { DiscoveredRoute } from './route-discovery.ts'
 import { discoverRoutes } from './route-discovery.ts'
+import { isStatorQueryRoute } from './routing.ts'
+import { broadcastEnvelope } from './sse.ts'
 import { InMemoryStore } from './store.ts'
 
 /**
@@ -71,10 +74,29 @@ export interface NativeDevApp {
   close: () => Promise<void>
 }
 
-// The dev browser client (replaces Vite's `/@vite/client`): reconnecting-EventSource
-// that reloads on a successful rebuild and renders a full-screen overlay with the
-// message on a build failure, so a compile error is visible instead of a frozen page.
-const DEV_CLIENT_SCRIPT = `(()=>{let o;const show=(m)=>{if(o)o.remove();o=document.createElement('div');o.style.cssText='position:fixed;inset:0;z-index:2147483647;margin:0;padding:24px;overflow:auto;background:#1a1015;color:#f8d7da;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre-wrap';o.textContent='stator \\u2014 build failed\\n\\n'+m;document.body.appendChild(o)};const es=new EventSource('/__stator_dev');es.onmessage=(e)=>{let m;try{m=JSON.parse(e.data)}catch{return}if(m.type==='reload')location.reload();else if(m.type==='error')show(m.message)}})()`
+// The dev browser client (replaces Vite's `/@vite/client`): reloads on a successful
+// rebuild and renders a full-screen overlay with the message on a build failure, so
+// a compile error is visible instead of a frozen page.
+//
+// Transport depends on the page. A `live: true` page already holds a /__sse stream,
+// so the dev signals ride it and this script opens NOTHING — a second event-stream
+// would take a second slot from the browser's six-per-origin pool (shared across
+// every tab in the profile), and two-per-tab is what wedges a dev session at three
+// tabs. Reload arrives there as the wire protocol's own directive, applied by the
+// page runtime; only the dev-only error overlay needs listening for. Pages without
+// a live channel keep their own /__stator_dev stream — still one per tab.
+const DEV_OVERLAY = `let o;const show=(m)=>{if(o)o.remove();o=document.createElement('div');o.style.cssText='position:fixed;inset:0;z-index:2147483647;margin:0;padding:24px;overflow:auto;background:#1a1015;color:#f8d7da;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;white-space:pre-wrap';o.textContent='stator \\u2014 build failed\\n\\n'+m;document.body.appendChild(o)};const go=(m)=>{if(m.type==='reload')location.reload();else if(m.type==='error')show(m.message)};`
+
+/** A page route (not a data route) declared `live: true` — the pages that hold
+ *  a /__sse stream, and so need no second one for dev signals. */
+const isLiveRoute = (def: DiscoveredRoute['GET']): boolean =>
+  def !== undefined && !isStatorQueryRoute(def) && def.live === true
+
+/** `live` pages piggyback on /__sse; everything else opens /__stator_dev. */
+const devClientScript = (live: boolean): string =>
+  live
+    ? `(()=>{${DEV_OVERLAY}window.addEventListener('stator:live-message',(e)=>{const d=e.detail&&e.detail.envelope&&e.detail.envelope.dev;if(d)go(d)})})()`
+    : `(()=>{${DEV_OVERLAY}const es=new EventSource('/__stator_dev');es.onmessage=(e)=>{let m;try{m=JSON.parse(e.data)}catch{return}go(m)}})()`
 
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'tests', 'test', '__tests__'])
 const APP_EXT = /\.(stator|ts|tsx|mts|cts|js|mjs)$/
@@ -111,9 +133,13 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
   const machinesDir = real(resolve(config.machinesDir))
   const routesDir = real(resolve(config.routesDir))
   const staticDir = config.staticDir ? real(resolve(config.staticDir)) : resolve(root, 'static')
-  // One build-id per dev process, as the Vite dev server did — rebuilds reload
-  // through the dev channel, a restart is a new id for the SSE reconnect handshake.
-  const buildId = randomUUID()
+  // One build-id per successful BUILD, not per process. Connected pages reload
+  // through the dev signal, but a page whose channel was released while it sat
+  // in the background (or dropped over a blip) never sees that signal — it
+  // reconnects later carrying the id it was rendered against, and the /__sse
+  // handshake is the only thing that can tell it its slot-ID map is stale. A
+  // per-process id would answer "same build" to a page from three rebuilds ago.
+  let buildId = randomUUID()
 
   // Loaders, BEFORE the first app import. The CLI's TS loader first — a no-op
   // extra link when the CLI already registered it, required when the dev server
@@ -166,6 +192,11 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     import(`${pathToFileURL(file).href}?v=${versions.get(file) ?? 1}`)
 
   // ── Dev live-reload channel (replaces Vite's `/@vite/client` HMR socket) ────
+  // Only pages WITHOUT a live channel open this. A `live: true` page already
+  // holds a /__sse stream, and its dev signals ride that one instead — a
+  // second event-stream would spend another slot from the browser's six-per-
+  // origin pool (shared across every tab in the profile), which is what wedges
+  // a multi-tab dev session at three tabs.
   const reloadClients = new Set<ReadableStreamDefaultController<Uint8Array>>()
   const enc = new TextEncoder()
   type DevMessage = { type: 'reload' } | { type: 'error'; message: string }
@@ -178,15 +209,29 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
         reloadClients.delete(c)
       }
     }
+    // Live pages: a reload rides the wire protocol's own directive (the page
+    // runtime applies it with no dev-specific code), an error rides a `dev`
+    // key the production runtime ignores and the dev client picks up off
+    // `stator:live-message`.
+    void broadcastEnvelope(
+      msg.type === 'reload' ? { directives: [{ type: 'reload' }] } : { dev: msg },
+    )
   }
-  const devReloadResponse = (): Response =>
-    new Response(
+  const devReloadResponse = (): Response => {
+    let mine: ReadableStreamDefaultController<Uint8Array> | undefined
+    return new Response(
       new ReadableStream<Uint8Array>({
         start(controller) {
+          mine = controller
           controller.enqueue(enc.encode(': connected\n\n'))
           reloadClients.add(controller)
         },
-        // A closed stream's controller throws on the next enqueue and is pruned then.
+        // Disconnect arrives as a stream cancel; without this the controller
+        // lingers until the next broadcast's enqueue throws, and this channel
+        // has no heartbeat to provoke one.
+        cancel() {
+          if (mine) reloadClients.delete(mine)
+        },
       }),
       {
         headers: {
@@ -197,6 +242,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
         },
       },
     )
+  }
 
   // ── Source scan: scoped CSS + island-ness of every `.stator` ───────────────
   // The loader compiles each `.stator` into its server module on import; this
@@ -304,7 +350,12 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
       if (url) head.push(`<script type="module" src="${url}"></script>`)
     }
     if (inspectorOn) head.push('<script src="/@stator/inspector.js" defer></script>')
-    head.push(`<script>${DEV_CLIENT_SCRIPT}</script>`)
+    // Liveness is decided HERE, not sniffed from the DOM: headExtras is injected
+    // ahead of the `stator-live` meta, so a script querying for it would always
+    // find nothing and open a redundant stream.
+    const abs = resolve(routeFile)
+    const live = routes.some((r) => resolve(r.filePath) === abs && isLiveRoute(r.GET))
+    head.push(`<script>${devClientScript(live)}</script>`)
     return head.join('\n')
   }
 
@@ -435,6 +486,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
         machinesChanged = await rebuildStore()
         storeRebuilt = true
       }
+      buildId = randomUUID()
       await rebuildServer()
       broadcast({ type: 'reload' })
       logger.info(

package/src/server/http.ts

@@ -376,6 +376,26 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       const runtime = new SessionRuntime(sessionId, config.store)
       await runtime.loadGraph(route.reads)
       const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request)
+
+      // The handler parks on `finished` until the connection ends. Both ways
+      // out resolve it: the client aborting, and the server hanging up on a
+      // superseded connection. A server-side `stream.close()` does NOT raise
+      // onAbort, so without the second path an evicted connection would leave
+      // its heartbeat interval running for the life of the process.
+      //
+      // Subscribe BEFORE registering — and before the ': open' flush and the
+      // initial sync below. Hono fires its abort subscribers exactly once, at
+      // abort time (utils/stream.ts), so a listener added after the client has
+      // already gone is never called: the connection would sit in the registry
+      // for the life of the process, pinning its SessionRuntime and taking a
+      // slice of every fan-out. A page that opens the channel and immediately
+      // navigates away hits that window every time.
+      let finish!: () => void
+      const finished = new Promise<void>((resolveFn) => {
+        finish = resolveFn
+      })
+      stream.onAbort(() => finish())
+
       const conn = registerConnection({
         sessionId,
         clientId: c.req.query('client'),
@@ -387,6 +407,10 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         send: async (data: string) => {
           await stream.writeSSE({ data })
         },
+        close: () => {
+          void stream.close()
+          finish()
+        },
       })
 
       // Force an immediate flush so edge proxies commit response headers
@@ -415,9 +439,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       }, config.ssePingMs ?? 25_000)
 
       try {
-        await new Promise<void>((resolveFn) => {
-          stream.onAbort(() => resolveFn())
-        })
+        await finished
       } finally {
         clearInterval(keepAlive)
         unregisterConnection(conn.id)

package/src/server/sse.ts

@@ -35,6 +35,9 @@ export interface Connection {
   runtime: SessionRuntime
   renderState: RenderState
   send: (data: string) => Promise<void>
+  /** Tear the underlying stream down from the server side. Supplied by the
+   *  transport; absent in tests that register a bare connection. */
+  close?: () => void
   closed: boolean
 }
 
@@ -44,6 +47,23 @@ let nextId = 0
 export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Connection {
   const id = `sse${nextId++}`
   const conn: Connection = { ...init, id, closed: false }
+  // A page-load holds at most one channel per route, so an existing
+  // connection with the same (clientId, routeKey) is a corpse whose abort we
+  // never observed — a half-open socket, or a reconnect that raced its own
+  // teardown. Left registered it would pin a SessionRuntime forever and take
+  // a slice of every fan-out. Evict it before the new one lands.
+  if (init.clientId !== undefined) {
+    for (const prior of connections.values()) {
+      if (prior.clientId === init.clientId && prior.routeKey === init.routeKey) {
+        sseLog.debug(
+          { id: prior.id, sid: prior.sessionId, route: prior.routeKey, replacedBy: id },
+          'evicting superseded connection',
+        )
+        unregisterConnection(prior.id)
+        prior.close?.()
+      }
+    }
+  }
   connections.set(id, conn)
   sseLog.debug(
     { id, sid: conn.sessionId, route: conn.routeKey, total: connections.size },
@@ -52,6 +72,25 @@ export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Con
   return conn
 }
 
+/**
+ * Push a pre-serialized envelope to every open connection, bypassing the
+ * recompute path. The dev server's rebuild/error signals ride this so a dev
+ * page holds ONE event-stream instead of two — see `dev-native.ts`. Not a
+ * fan-out: no diffing, no baseline advance, no per-connection filtering.
+ */
+export async function broadcastEnvelope(payload: unknown): Promise<void> {
+  if (connections.size === 0) return
+  const data = JSON.stringify(payload)
+  for (const conn of connections.values()) {
+    if (conn.closed) continue
+    try {
+      await conn.send(data)
+    } catch (err) {
+      sseLog.warn({ id: conn.id, err: String(err) }, 'broadcast failed')
+    }
+  }
+}
+
 export function unregisterConnection(id: string): void {
   const conn = connections.get(id)
   if (!conn) return

package/src/template/html-attributes.ts

@@ -92,11 +92,14 @@ export interface ElementSpecificAttributes {
     autocomplete?: string
     inputmode?: string
     autofocus?: boolean
+    accept?: string
+    multiple?: boolean
   }
   label: { for?: string }
   form: {
     action?: string
     method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
+    enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
     novalidate?: boolean
   }
   select: {
@@ -123,7 +126,11 @@ export interface ElementSpecificAttributes {
     alt?: string
     width?: number | string
     height?: number | string
+    srcset?: string
+    sizes?: string
     loading?: 'eager' | 'lazy'
+    decoding?: 'sync' | 'async' | 'auto'
+    fetchpriority?: 'high' | 'low' | 'auto'
   }
 }