@statorjs/stator 2.7.0 → 2.9.0

package/package.json

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

package/src/build/islands-esbuild.ts

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { BundleIslandsOptions, IslandAsset, IslandBundler } from './islands.ts'
+
+/**
+ * Implementation #2 of the island-bundling seam (spike for Option E of the
+ * Vite exit): one esbuild build over every island entry, `splitting: true` so
+ * shared modules — the client runtime above all — land in shared chunks
+ * instead of duplicating per island.
+ *
+ * Same contract as the Vite implementation in `islands.ts`: entries are
+ * `.stator` sources (compiled to their client module here) or prebuilt client
+ * entry modules; server-machine imports collapse to `{ name }` stubs; nothing
+ * is written — callers own the assets.
+ */
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+
+const STUB_NS = 'stator-machine-stub'
+
+/** Extensions an island may reference by URL; emitted as hashed files (the
+ *  seam contract — never inlined), mirroring Vite's `assetsInlineLimit: 0`. */
+const FILE_LOADERS: Record<string, 'file'> = Object.fromEntries(
+  ['.wasm', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.woff', '.woff2'].map((e) => [
+    e,
+    'file' as const,
+  ]),
+)
+
+export const bundleIslandsEsbuild: IslandBundler = async (opts: BundleIslandsOptions) => {
+  const [{ build }, { compile, regionResolverFor }] = await Promise.all([
+    import('esbuild'),
+    import('../compiler/index.ts'),
+  ])
+  const publicPath = opts.publicPath ?? '/static/assets/'
+  const root = resolve(opts.root)
+  const machinesDir = resolve(opts.machinesDir)
+  const outDir = resolve(root, '.stator-island-out') // virtual — write: false
+  const inMachinesDir = (abs: string): boolean =>
+    abs === machinesDir || abs.startsWith(machinesDir + sep)
+
+  const entryPoints = opts.entries.map((entry) => ({
+    in: resolve(entry.file),
+    out: entry.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_'),
+  }))
+  const byFile = new Map(opts.entries.map((e) => [norm(resolve(e.file)), e]))
+
+  // Rollup/Vite rewrite `new URL('./x', import.meta.url)` to an emitted asset;
+  // esbuild does not, so the seam does it here: each URL-referenced relative
+  // asset becomes an import (the file loader emits it hashed and exports its
+  // public URL, root-absolute under `publicPath`, so the `new URL` still
+  // resolves). Only string-literal relative specifiers — same limit as Vite.
+  const URL_ASSET_RE = /new\s+URL\(\s*(['"])(\.{1,2}\/[^'"\n]+)\1\s*,\s*import\.meta\.url\s*\)/g
+  const rewriteUrlAssets = (code: string): string => {
+    let n = 0
+    const imports: string[] = []
+    const out = code.replace(URL_ASSET_RE, (_m, _q: string, spec: string) => {
+      const id = `__stator_url_asset_${n++}`
+      imports.push(`import ${id} from ${JSON.stringify(spec)}`)
+      return `new URL(${id}, import.meta.url)`
+    })
+    return imports.length === 0 ? code : `${imports.join('\n')}\n${out}`
+  }
+
+  const statorPlugin = {
+    name: 'stator-client',
+    setup(b: import('esbuild').PluginBuild) {
+      b.onLoad({ filter: /\.stator$/ }, async (args) => {
+        const source = await readFile(args.path, 'utf8')
+        const kind = /[\\/]routes[\\/].*\.stator$/.test(args.path) ? 'route' : 'component'
+        const result = compile(source, {
+          id: args.path,
+          kind,
+          resolveRegions: regionResolverFor(args.path, source),
+        })
+        return {
+          contents: result.isClient ? rewriteUrlAssets(result.clientCode) : 'export {}',
+          loader: 'ts',
+          resolveDir: dirname(args.path),
+        }
+      })
+      b.onLoad({ filter: /\.(ts|mts|js|mjs)$/ }, async (args) => {
+        const source = await readFile(args.path, 'utf8')
+        const rewritten = rewriteUrlAssets(source)
+        if (rewritten === source) return undefined
+        return {
+          contents: rewritten,
+          loader: args.path.endsWith('js') ? 'js' : 'ts',
+          resolveDir: dirname(args.path),
+        }
+      })
+    },
+  }
+
+  const machineStubPlugin = {
+    name: 'stator-machine-stub',
+    setup(b: import('esbuild').PluginBuild) {
+      b.onResolve({ filter: /^[./]/ }, (args) => {
+        if (args.namespace === STUB_NS) return null
+        const base = isAbsolute(args.path) ? args.path : resolve(args.resolveDir, args.path)
+        const abs = [base, `${base}.ts`, `${base}.js`].find(inMachinesDir)
+        if (!abs) return null
+        return { path: abs, namespace: STUB_NS }
+      })
+      b.onLoad({ filter: /.*/, namespace: STUB_NS }, async (args) => {
+        let name: unknown
+        try {
+          const mod = (await import(pathToFileURL(args.path).href)) as {
+            default?: { name?: unknown }
+          }
+          name = mod.default?.name
+        } catch (err) {
+          throw new Error(
+            `stator: cannot stub server-machine import "${args.path}" for the client bundle — ` +
+              `importing it in Node failed: ${(err as Error).message}`,
+          )
+        }
+        if (typeof name !== 'string') {
+          throw new Error(
+            `stator: cannot stub "${args.path}" — it does not default-export a machine with a name. ` +
+              `Only machine defs may be imported from the machines directory in client code.`,
+          )
+        }
+        return { contents: `export default { name: ${JSON.stringify(name)} }\n`, loader: 'js' }
+      })
+    },
+  }
+
+  const result = await build({
+    absWorkingDir: root,
+    entryPoints,
+    outdir: outDir,
+    bundle: true,
+    splitting: true,
+    format: 'esm',
+    write: false,
+    metafile: true,
+    minify: true,
+    publicPath,
+    sourcemap: opts.sourcemap ? 'inline' : false,
+    entryNames: '[name]-[hash]',
+    chunkNames: 'chunks/[name]-[hash]',
+    assetNames: '[name]-[hash]',
+    loader: FILE_LOADERS,
+    logLevel: 'warning',
+    plugins: [machineStubPlugin, statorPlugin],
+  })
+
+  const assets: IslandAsset[] = result.outputFiles.map((f) => {
+    const fileName = norm(relative(outDir, f.path))
+    return fileName.endsWith('.js')
+      ? { fileName, source: f.text }
+      : { fileName, source: f.contents }
+  })
+
+  const modules = new Set<string>()
+  for (const key of Object.keys(result.metafile.inputs)) {
+    if (key.startsWith(`${STUB_NS}:`)) modules.add(norm(key.slice(STUB_NS.length + 1)))
+    else modules.add(norm(resolve(root, key)))
+  }
+
+  const islandUrls: Record<string, string> = {}
+  for (const [outPath, meta] of Object.entries(result.metafile.outputs)) {
+    if (!meta.entryPoint) continue
+    const entry = byFile.get(norm(resolve(root, meta.entryPoint)))
+    if (entry) islandUrls[entry.rel] = publicPath + norm(relative(outDir, resolve(root, outPath)))
+  }
+  for (const entry of opts.entries) {
+    if (!islandUrls[entry.rel])
+      throw new Error(`stator: island "${entry.rel}" missing from the bundle output`)
+  }
+
+  return { islandUrls, assets, modules: [...modules] }
+}

package/src/build/islands-vite.ts

@@ -0,0 +1,88 @@
+import { resolve } from 'node:path'
+import type { Rollup } from 'vite'
+import type { BundleIslandsOptions, IslandAsset, IslandBundler } from './islands.ts'
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+const stripQuery = (id: string): string => {
+  const q = id.indexOf('?')
+  return q === -1 ? id : id.slice(0, q)
+}
+
+/** Implementation #1: one Vite build over every island entry. Vite is imported
+ *  lazily — server-only apps never load it. */
+export const bundleIslandsVite: IslandBundler = async (opts: BundleIslandsOptions) => {
+  const [{ build: viteBuild }, { CLIENT_QUERY, MACHINE_STUB_PREFIX, machineStub, stator }] =
+    await Promise.all([import('vite'), import('../vite/index.ts')])
+  const publicPath = opts.publicPath ?? '/static/assets/'
+
+  const input: Record<string, string> = {}
+  const byFile = new Map<string, BundleIslandsOptions['entries'][number]>()
+  for (const entry of opts.entries) {
+    const file = resolve(entry.file)
+    input[entry.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_')] = file.endsWith('.stator')
+      ? `${file}?${CLIENT_QUERY}`
+      : file
+    byFile.set(norm(file), entry)
+  }
+
+  const result = await viteBuild({
+    root: opts.root,
+    // Assets referenced by URL from island code (`new URL(...)`, CSS `url()`)
+    // render against `base`, so it must be where the assets are served from.
+    base: publicPath,
+    logLevel: 'warn',
+    configFile: false,
+    plugins: [stator(), machineStub({ machinesDir: resolve(opts.machinesDir) })],
+    build: {
+      write: false,
+      // Seam contract: a URL-referenced asset (`new URL('./x.wasm',
+      // import.meta.url)`) is always emitted as a hashed FILE, never inlined
+      // as a data: URL — deterministic for callers and identical to what the
+      // esbuild implementation (file loader) produces.
+      assetsInlineLimit: 0,
+      sourcemap: opts.sourcemap ? 'inline' : false,
+      rollupOptions: {
+        input,
+        output: {
+          entryFileNames: '[name]-[hash].js',
+          chunkFileNames: 'chunks/[name]-[hash].js',
+          assetFileNames: '[name]-[hash][extname]',
+        },
+      },
+    },
+  })
+  const outputs = (Array.isArray(result) ? result : [result]).filter(
+    (r): r is Rollup.RollupOutput => 'output' in r,
+  )
+
+  const islandUrls: Record<string, string> = {}
+  const assets: IslandAsset[] = []
+  const modules = new Set<string>()
+  const sourcePathOf = (id: string): string | null => {
+    const raw = id.startsWith(MACHINE_STUB_PREFIX) ? id.slice(MACHINE_STUB_PREFIX.length) : id
+    if (raw.startsWith('\0')) return null
+    return norm(stripQuery(raw))
+  }
+  for (const out of outputs) {
+    for (const item of out.output) {
+      if (item.type === 'chunk') {
+        assets.push({ fileName: item.fileName, source: item.code })
+        for (const id of Object.keys(item.modules)) {
+          const p = sourcePathOf(id)
+          if (p) modules.add(p)
+        }
+        if (item.isEntry && item.facadeModuleId) {
+          const entry = byFile.get(norm(stripQuery(item.facadeModuleId)))
+          if (entry) islandUrls[entry.rel] = publicPath + item.fileName
+        }
+      } else {
+        assets.push({ fileName: item.fileName, source: item.source })
+      }
+    }
+  }
+  for (const entry of opts.entries) {
+    if (!islandUrls[entry.rel])
+      throw new Error(`stator: island "${entry.rel}" missing from the bundle output`)
+  }
+  return { islandUrls, assets, modules: [...modules] }
+}

package/src/build/islands.ts

@@ -1,6 +1,5 @@
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
-import type { Rollup } from 'vite'
 
 /**
  * The island-bundling seam — Lock 1 of the Vite exit (spec
@@ -59,89 +58,23 @@ export interface BundleIslandsOptions {
 
 export type IslandBundler = (opts: BundleIslandsOptions) => Promise<IslandBundle>
 
-const norm = (p: string): string => p.replace(/\\/g, '/')
-const stripQuery = (id: string): string => {
-  const q = id.indexOf('?')
-  return q === -1 ? id : id.slice(0, q)
-}
-
-/** Implementation #1: one Vite build over every island entry. Vite is imported
- *  lazily — server-only apps never load it. */
+/**
+ * The seam's one export: dispatches to an implementation. Vite (impl #1,
+ * `islands-vite.ts`) is the default; `STATOR_ISLAND_BUNDLER=esbuild` selects
+ * impl #2 (`islands-esbuild.ts`, the Option E candidate — Spike 1). Both run
+ * the same contract tests; the default flips (and #1 is deleted) when the
+ * Phase 2 gate in the toolchain-adapter spec passes.
+ */
 export const bundleIslands: IslandBundler = async (opts) => {
-  const [{ build: viteBuild }, { CLIENT_QUERY, MACHINE_STUB_PREFIX, machineStub, stator }] =
-    await Promise.all([import('vite'), import('../vite/index.ts')])
-  const publicPath = opts.publicPath ?? '/static/assets/'
-
-  const input: Record<string, string> = {}
-  const byFile = new Map<string, IslandEntry>()
-  for (const entry of opts.entries) {
-    const file = resolve(entry.file)
-    input[entry.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_')] = file.endsWith('.stator')
-      ? `${file}?${CLIENT_QUERY}`
-      : file
-    byFile.set(norm(file), entry)
-  }
-
-  const result = await viteBuild({
-    root: opts.root,
-    // Assets referenced by URL from island code (`new URL(...)`, CSS `url()`)
-    // render against `base`, so it must be where the assets are served from.
-    base: publicPath,
-    logLevel: 'warn',
-    configFile: false,
-    plugins: [stator(), machineStub({ machinesDir: resolve(opts.machinesDir) })],
-    build: {
-      write: false,
-      // Seam contract: a URL-referenced asset (`new URL('./x.wasm',
-      // import.meta.url)`) is always emitted as a hashed FILE, never inlined
-      // as a data: URL — deterministic for callers and identical to what an
-      // esbuild implementation (file loader) produces.
-      assetsInlineLimit: 0,
-      sourcemap: opts.sourcemap ? 'inline' : false,
-      rollupOptions: {
-        input,
-        output: {
-          entryFileNames: '[name]-[hash].js',
-          chunkFileNames: 'chunks/[name]-[hash].js',
-          assetFileNames: '[name]-[hash][extname]',
-        },
-      },
-    },
-  })
-  const outputs = (Array.isArray(result) ? result : [result]).filter(
-    (r): r is Rollup.RollupOutput => 'output' in r,
-  )
-
-  const islandUrls: Record<string, string> = {}
-  const assets: IslandAsset[] = []
-  const modules = new Set<string>()
-  const sourcePathOf = (id: string): string | null => {
-    const raw = id.startsWith(MACHINE_STUB_PREFIX) ? id.slice(MACHINE_STUB_PREFIX.length) : id
-    if (raw.startsWith('\0')) return null
-    return norm(stripQuery(raw))
-  }
-  for (const out of outputs) {
-    for (const item of out.output) {
-      if (item.type === 'chunk') {
-        assets.push({ fileName: item.fileName, source: item.code })
-        for (const id of Object.keys(item.modules)) {
-          const p = sourcePathOf(id)
-          if (p) modules.add(p)
-        }
-        if (item.isEntry && item.facadeModuleId) {
-          const entry = byFile.get(norm(stripQuery(item.facadeModuleId)))
-          if (entry) islandUrls[entry.rel] = publicPath + item.fileName
-        }
-      } else {
-        assets.push({ fileName: item.fileName, source: item.source })
-      }
-    }
-  }
-  for (const entry of opts.entries) {
-    if (!islandUrls[entry.rel])
-      throw new Error(`stator: island "${entry.rel}" missing from the bundle output`)
+  const choice = process.env.STATOR_ISLAND_BUNDLER ?? 'vite'
+  if (choice === 'esbuild') {
+    const { bundleIslandsEsbuild } = await import('./islands-esbuild.ts')
+    return bundleIslandsEsbuild(opts)
   }
-  return { islandUrls, assets, modules: [...modules] }
+  if (choice !== 'vite')
+    throw new Error(`stator: unknown STATOR_ISLAND_BUNDLER "${choice}" (vite | esbuild)`)
+  const { bundleIslandsVite } = await import('./islands-vite.ts')
+  return bundleIslandsVite(opts)
 }
 
 /**

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

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, stat } from 'node:fs/promises'
 import { dirname, extname, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { build } from 'esbuild'
@@ -282,6 +282,38 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         return c.text('forbidden', 403)
       }
       try {
+        const st = await stat(full)
+        if (!st.isFile()) return c.text('not found', 404)
+
+        // Caching contract: `/static/assets/*` is the framework's hashed-output
+        // namespace (island bundles, emitted URL assets) — content-addressed by
+        // construction, so a year of `immutable` is correct. Everything else
+        // under `/static/` is user files with stable names: always revalidate,
+        // but revalidation is a bodyless 304 (ETag from size+mtime, plus
+        // Last-Modified for validators that only speak dates).
+        const etag = `"${st.size.toString(16)}-${Math.trunc(st.mtimeMs).toString(16)}"`
+        c.header(
+          'Cache-Control',
+          rel.startsWith('assets/')
+            ? 'public, max-age=31536000, immutable'
+            : 'public, max-age=0, must-revalidate',
+        )
+        c.header('ETag', etag)
+        c.header('Last-Modified', st.mtime.toUTCString())
+
+        const inm = c.req.header('if-none-match')
+        if (inm) {
+          if (inm.split(',').some((t) => t.trim().replace(/^W\//, '') === etag)) {
+            return c.body(null, 304)
+          }
+        } else {
+          const ims = Date.parse(c.req.header('if-modified-since') ?? '')
+          // HTTP dates have second precision; compare mtime truncated to match.
+          if (!Number.isNaN(ims) && Math.trunc(st.mtimeMs / 1000) * 1000 <= ims) {
+            return c.body(null, 304)
+          }
+        }
+
         const buf = await readFile(full)
         c.header('Content-Type', contentTypeFor(rel))
         return c.body(buf)
@@ -344,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'),
@@ -355,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
@@ -383,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)
@@ -684,10 +738,13 @@ export function contentTypeFor(path: string): string {
   if (ext === '.png') return 'image/png'
   if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
   if (ext === '.webp') return 'image/webp'
+  if (ext === '.avif') return 'image/avif'
   if (ext === '.gif') return 'image/gif'
   if (ext === '.ico') return 'image/x-icon'
   if (ext === '.wasm') return 'application/wasm'
   if (ext === '.woff2') return 'font/woff2'
   if (ext === '.woff') return 'font/woff'
+  if (ext === '.ttf') return 'font/ttf'
+  if (ext === '.otf') return 'font/otf'
   return 'application/octet-stream'
 }

package/src/server/route-discovery.ts

@@ -41,10 +41,12 @@ export interface DiscoveredRoute {
  * Walk the routes directory recursively and build URL patterns from file
  * paths. Conventions:
  *
- *   - `routes/foo.ts`         → `/foo`
- *   - `routes/foo/index.ts`   → `/foo`
- *   - `routes/foo/[id].ts`    → `/foo/:id`  (path param `id`)
- *   - `routes/[a]/[b].ts`     → `/:a/:b`
+ *   - `routes/foo.ts`           → `/foo`
+ *   - `routes/foo/index.ts`     → `/foo`
+ *   - `routes/foo/[id].ts`      → `/foo/:id`   (path param `id`)
+ *   - `routes/[a]/[b].ts`       → `/:a/:b`
+ *   - `routes/foo/[...rest].ts` → `/foo/*rest` (catch-all: terminal, matches
+ *     zero+ segments, param is the raw remainder incl. slashes)
  *
  * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
  * GET is a `defineRoute` (page renderer) or a `defineApiRoute` declaring

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