@statorjs/stator 2.8.0 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "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.1"
   },
   "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/banner.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { networkInterfaces } from 'node:os'
 import { logger } from './logger.ts'
+import { type ClosableServer, drainAndClose } from './shutdown.ts'
 
 /**
  * Human-facing startup/exit output for the DEV plane. Production keeps
@@ -89,26 +90,32 @@ export function printStartupNotice(info: { port: number; machines: number; route
 }
 
 /**
- * Exit a server process like a well-mannered CLI: first signal closes
- * cleanly and exits 0 (Ctrl+C is a normal action, not a failure — without
- * this, the process dies 130 and pnpm prints an ELIFECYCLE error banner);
- * a second signal force-quits for anything that hangs in close().
+ * Exit a server process like a well-mannered CLI: first signal drains and exits
+ * 0 (Ctrl+C is a normal action, not a failure — without this, the process dies
+ * 130 and pnpm prints an ELIFECYCLE error banner); a second signal force-quits.
+ *
+ * The drain itself is `drainAndClose` — the server stops accepting, `teardown`
+ * runs (boot teardown, watchers), live connections are hung up, and in-flight
+ * requests get a bounded deadline. Waiting on `server.close()` alone would hang
+ * forever with a single live page open.
  */
-export function installGracefulShutdown(close: () => Promise<void> | void, quiet = false): void {
+export function installGracefulShutdown(
+  server: ClosableServer,
+  opts: { teardown?: () => Promise<void> | void; quiet?: boolean } = {},
+): void {
   let closing = false
-  const handler = (signal: NodeJS.Signals) => {
+  const handler = () => {
     if (closing) process.exit(130)
     closing = true
-    if (!quiet) process.stdout.write(`\n${c.dim('  stopping…')}\n`)
+    if (!opts.quiet) process.stdout.write(`\n${c.dim('  stopping…')}\n`)
     void (async () => {
       try {
-        await close()
+        await drainAndClose(server, { teardown: opts.teardown })
       } catch (err) {
         logger.warn({ err: String(err) }, 'error during shutdown')
       }
       process.exit(0)
     })()
-    void signal
   }
   process.on('SIGINT', handler)
   process.on('SIGTERM', handler)

package/src/server/create-app.ts

@@ -183,11 +183,9 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
             },
           })
           // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in prod.
-          // Boot teardown runs first (unsubscribe/clear timers), then the server.
-          installGracefulShutdown(async () => {
-            if (teardown) await teardown()
-            await new Promise<void>((done) => server.close(() => done()))
-          }, true)
+          // The server stops accepting before boot teardown runs, so nothing
+          // new arrives while its sources are being unsubscribed.
+          installGracefulShutdown(server, { teardown, quiet: true })
           resolveFn()
         })
         // Production is strict about its port (a collision is a deploy

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(
@@ -537,10 +589,11 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
                   cors: resolved.cors,
                 },
               })
-              installGracefulShutdown(async () => {
-                if (teardown) await teardown()
-                await watcher.close()
-                await new Promise<void>((done) => server.close(() => done()))
+              installGracefulShutdown(server, {
+                teardown: async () => {
+                  if (teardown) await teardown()
+                  await watcher.close()
+                },
               })
               resolveFn()
             })

package/src/server/dev-vite.ts

@@ -306,10 +306,11 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
                   cors: resolved.cors,
                 },
               })
-              installGracefulShutdown(async () => {
-                if (teardown) await teardown()
-                await vite.close()
-                await new Promise<void>((done) => server.close(() => done()))
+              installGracefulShutdown(server, {
+                teardown: async () => {
+                  if (teardown) await teardown()
+                  await vite.close()
+                },
               })
               resolveFn()
             })

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

@@ -0,0 +1,127 @@
+import { scopedLogger } from './logger.ts'
+import { closeLiveConnections } from './sse.ts'
+
+const log = scopedLogger('shutdown')
+
+/**
+ * Draining a Stator process, which is not the same as closing its server.
+ *
+ * `server.close()` stops accepting new connections and then resolves only when
+ * every existing connection has ended — so it can never be the gate for an app
+ * with live routes: an SSE response is a single request that lasts as long as
+ * the page is open. Waiting on it means the process hangs until the platform
+ * loses patience (systemd `TimeoutStopSec`, Kubernetes
+ * `terminationGracePeriodSeconds`, `docker stop`) and SIGKILLs it, turning an
+ * ordinary deploy rollover into a 90-second failed stop.
+ *
+ * So long-lived streams are HUNG UP, never waited on — the same conclusion Go's
+ * `http.Server.Shutdown` documents ("does not attempt to close nor wait for
+ * hijacked connections... the caller should separately notify such long-lived
+ * connections") and every Node graceful-shutdown library reaches. The deadline
+ * that remains covers real request work, which is why it is short by default.
+ *
+ * Dropping a live channel costs a re-render, not a fact: session state is in the
+ * Store, `after` timers re-arm on hydration, and a reconnecting page re-syncs
+ * from the server's baseline (or reloads, if it comes back to a newer build via
+ * the build-id handshake).
+ */
+
+/** Deadline for in-flight request work once the streams are hung up. Short on
+ *  purpose: closing live connections is immediate, so this only ever covers
+ *  real requests, and it must stay well under the platform's own kill grace
+ *  (`docker stop` allows 10s). */
+const DEFAULT_TIMEOUT_MS = 5_000
+
+/** `STATOR_SHUTDOWN_TIMEOUT_MS`, or the default. An unparseable value warns and
+ *  falls back rather than shortening the drain to zero. */
+export function shutdownTimeoutMs(): number {
+  const raw = process.env.STATOR_SHUTDOWN_TIMEOUT_MS
+  if (raw === undefined || raw === '') return DEFAULT_TIMEOUT_MS
+  const ms = Number(raw)
+  if (!Number.isFinite(ms) || ms < 0) {
+    log.warn({ value: raw }, 'ignoring invalid STATOR_SHUTDOWN_TIMEOUT_MS')
+    return DEFAULT_TIMEOUT_MS
+  }
+  return ms
+}
+
+/** What the drain needs of a listening server — structurally satisfied by
+ *  `node:http`'s `Server` and by `@hono/node-server`'s `serve()` return.
+ *  `closeIdleConnections`/`closeAllConnections` are Node ≥18.2; optional so a
+ *  non-http server (or a test double) still drains. */
+export interface ClosableServer {
+  close(callback?: (err?: Error) => void): unknown
+  closeIdleConnections?: () => void
+  closeAllConnections?: () => void
+}
+
+export interface DrainResult {
+  /** Live (SSE) connections hung up by the drain. */
+  connections: number
+  /** True when the deadline expired and the remaining sockets were destroyed. */
+  forced: boolean
+}
+
+/**
+ * Stop accepting, tear down inbound sources, hang up live connections, and wait
+ * for in-flight requests up to a deadline — then destroy whatever is left.
+ * Never exits the process: the signal handler owns that, and tests own this.
+ */
+export async function drainAndClose(
+  server: ClosableServer,
+  opts: { teardown?: () => Promise<void> | void; timeoutMs?: number } = {},
+): Promise<DrainResult> {
+  const timeoutMs = opts.timeoutMs ?? shutdownTimeoutMs()
+
+  // Stop accepting FIRST, so nothing new arrives while sources are torn down.
+  const closed = new Promise<void>((done) => server.close(() => done()))
+
+  let connections = 0
+  const drain = (async () => {
+    // Inbound sources off before the streams they feed: a boot.ts poll or
+    // subscription can raise events, and a dev watcher can rebuild, so both
+    // stop before anything is hung up. A teardown that throws must not keep the
+    // sockets open — log it and carry on closing.
+    if (opts.teardown) {
+      try {
+        await opts.teardown()
+      } catch (err) {
+        log.warn({ err: String(err) }, 'teardown failed during shutdown')
+      }
+    }
+    // The reason close() can complete at all.
+    connections = closeLiveConnections()
+    // Then reap keep-alive sockets parked between requests — on a tick, not
+    // once. A hung-up stream's socket only becomes idle a moment later, and
+    // until something closes it, `close()` stays pending for as long as the
+    // CLIENT's keep-alive timeout (undici's is 4s) — measured, and the whole
+    // reason a one-shot call here isn't enough. A socket with a request in
+    // flight is never idle, so this never cuts real work short.
+    server.closeIdleConnections?.()
+    const reaper = setInterval(() => server.closeIdleConnections?.(), 50)
+    reaper.unref?.()
+    try {
+      await closed
+    } finally {
+      clearInterval(reaper)
+    }
+  })()
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<'timeout'>((done) => {
+    timer = setTimeout(() => done('timeout'), timeoutMs)
+    timer.unref?.()
+  })
+  const outcome = await Promise.race([drain.then(() => 'drained' as const), expired])
+  clearTimeout(timer)
+
+  if (outcome === 'timeout') {
+    // Real request work (or a wedged teardown) outlasted the deadline. Destroy
+    // what's left rather than hand the process to the platform's SIGKILL.
+    server.closeAllConnections?.()
+    log.warn({ timeoutMs }, 'shutdown deadline expired — remaining connections destroyed')
+    return { connections, forced: true }
+  }
+  log.debug({ connections }, 'drained')
+  return { connections, forced: false }
+}

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
@@ -68,6 +107,21 @@ export function activeConnectionCount(): number {
   return connections.size
 }
 
+/**
+ * Hang up every open connection — the shutdown path. A live response never ends
+ * on its own, so `server.close()` cannot complete until these do; see
+ * `shutdown.ts` for why they are closed rather than waited on. Returns how many
+ * were open. Each handler's own `finally` unregisters again, harmlessly.
+ */
+export function closeLiveConnections(): number {
+  const open = [...connections.values()]
+  for (const conn of open) {
+    unregisterConnection(conn.id)
+    conn.close?.()
+  }
+  return open.length
+}
+
 /**
  * After a state-changing dispatch settles, iterate every open connection
  * whose route's `reads:` intersects `touched`, recompute against that

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'
   }
 }