@statorjs/stator 2.4.0 → 2.5.1

package/README.md

@@ -1,15 +1,8 @@
 # @statorjs/stator
 
-A server-canonical web framework: business logic lives in composable state
-machines that have no awareness of the UI, and the UI is a thin renderer
-binding machine outputs to DOM positions. Templates are `.stator` single-file
-components; interactions POST typed events; the server diffs affected bindings
-into small JSON patches. Client islands run the same machine engine in the
-browser as custom elements.
+A server-canonical web framework: business logic lives in composable state machines that have no awareness of the UI, and the UI is a thin renderer binding machine outputs to DOM positions. Templates are `.stator` single-file components; interactions POST typed events; the server diffs affected bindings into small JSON patches. Client islands run the same machine engine in the browser as custom elements.
 
-Full documentation — tutorial, concepts, guides — lives in the repo's
-[`apps/docs`](https://github.com/statorjs/stator/tree/main/apps/docs) site;
-the repo [README](https://github.com/statorjs/stator#readme) has the tour.
+Full documentation — tutorial, concepts, guides — lives in the repo's [`apps/docs`](https://github.com/statorjs/stator/tree/main/apps/docs) site; the repo [README](https://github.com/statorjs/stator#readme) has the tour.
 
 ## Install
 
@@ -36,8 +29,7 @@ pnpm add @statorjs/stator hono
 | `@statorjs/stator/build`    | `buildApp`, `loadProductionHead`, `syncTypes` |
 | `@statorjs/stator/components` | built-ins (`<JsonLd>`) |
 
-`compiler` and `vite` subpaths exist but are internal — their shape may change
-in minor releases.
+`compiler` and `vite` subpaths exist but are internal — their shape may change in minor releases.
 
 ## Minimal app
 
@@ -96,8 +88,7 @@ const [counter] = Stator.reads([Counter])
 </html>
 ```
 
-Run with `tsx server.ts`. See the repo's `examples/desksmith` for the full wiring
-(type sync, production build, deploy).
+Run with `tsx server.ts`. See the repo's `examples/desksmith` for the full wiring (type sync, production build, deploy).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.4.0",
+  "version": "2.5.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 (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.4.0"
+    "@statorjs/stator": "2.5.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/build.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { join, relative, resolve, sep } from 'node:path'
 import { compile } from '../compiler/index.ts'
@@ -47,8 +48,11 @@ export interface BuildResult {
   islands: number
 }
 
-/** Shape of `dist/stator-manifest.json` (only written when islands exist). */
+/** Shape of `dist/stator-manifest.json` (always written — carries `buildId`). */
 export interface StatorManifest {
+  /** Per-build identifier — `stator start` serves it into live pages for the
+   *  reload handshake (a client on an older build reloads on reconnect). */
+  buildId: string
   /** Island component (dist-relative `.stator` path) → its script URL. */
   islands: Record<string, string>
   /** Route file (dist-relative) → script URLs for every island it reaches. */
@@ -86,6 +90,9 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
   // (raw TS, run under tsx/native in prod like the rest of the server).
   const middlewareSrc = join(root, 'middleware.ts')
   if (await exists(middlewareSrc)) await cp(middlewareSrc, join(outDir, 'middleware.ts'))
+  // Same for a root-level boot.ts (the once-at-startup hook).
+  const bootSrc = join(root, 'boot.ts')
+  if (await exists(bootSrc)) await cp(bootSrc, join(outDir, 'boot.ts'))
 
   // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
   const statorFiles = await walk(outDir, (f) => f.endsWith('.stator'))
@@ -120,10 +127,13 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     await writeFile(join(outDir, 'static', 'components.css'), css)
   }
 
-  if (islands.length > 0) {
-    const manifest = await buildClientAssets(outDir, islands)
-    await writeFile(join(outDir, 'stator-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
-  }
+  // Always write the manifest — it carries the build-id even for an app with no
+  // islands (a live route without islands still needs the reload handshake).
+  const manifest: StatorManifest =
+    islands.length > 0
+      ? { buildId: randomUUID(), ...(await buildClientAssets(outDir, islands)) }
+      : { buildId: randomUUID(), islands: {}, routes: {} }
+  await writeFile(join(outDir, 'stator-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
 
   return { outDir, compiled: statorFiles.length, hasCss: Boolean(css), islands: islands.length }
 }
@@ -135,7 +145,7 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
 async function buildClientAssets(
   outDir: string,
   islands: Array<{ rel: string; entry: string }>,
-): Promise<StatorManifest> {
+): Promise<Omit<StatorManifest, 'buildId'>> {
   const [{ build: viteBuild }, { machineStub }] = await Promise.all([
     import('vite'),
     import('../vite/stub.ts'),

package/src/build/head.ts

@@ -7,12 +7,15 @@ import type { StatorManifest } from './build.ts'
  * build produced one, and injects each route's island `<script type="module">`
  * tags from `stator-manifest.json`. Pass the result to `createApp`:
  *
- *   const app = await createApp({ ..., headExtras: await loadProductionHead(dist) })
+ *   const { headExtras, buildId } = await loadProductionHead(dist)
+ *   const app = await createApp({ ..., headExtras, buildId })
  *
- * Both artifacts are optional — a server-only app without styles gets an
- * empty hook.
+ * Everything is optional — a server-only app without styles gets an empty hook,
+ * and a build with no `buildId` in its manifest just skips the reload handshake.
  */
-export async function loadProductionHead(distDir: string): Promise<(filePath: string) => string> {
+export async function loadProductionHead(
+  distDir: string,
+): Promise<{ headExtras: (filePath: string) => string; buildId?: string }> {
   const dist = resolve(distDir)
 
   let cssTag = ''
@@ -24,20 +27,23 @@ export async function loadProductionHead(distDir: string): Promise<(filePath: st
   }
 
   let routes: StatorManifest['routes'] = {}
+  let buildId: string | undefined
   try {
     const manifest = JSON.parse(
       await readFile(join(dist, 'stator-manifest.json'), 'utf8'),
     ) as StatorManifest
     routes = manifest.routes ?? {}
+    buildId = manifest.buildId
   } catch {
-    // no islands
+    // no manifest
   }
 
-  return (filePath: string): string => {
+  const headExtras = (filePath: string): string => {
     const rel = relative(dist, resolve(filePath)).replace(/\\/g, '/')
     const scripts = routes[rel] ?? []
     return [cssTag, ...scripts.map((url) => `<script type="module" src="${url}"></script>`)]
       .filter(Boolean)
       .join('\n')
   }
+  return { headExtras, buildId }
 }

package/src/cli/commands/start.ts

@@ -16,6 +16,7 @@ export async function run(ctx: CliContext): Promise<void> {
   }
 
   const config = await loadConfig(ctx.root)
+  const { headExtras, buildId } = await loadProductionHead(dist)
   const app = await createApp({
     machinesDir: resolve(dist, 'machines'),
     routesDir: resolve(dist, 'routes'),
@@ -26,9 +27,12 @@ export async function run(ctx: CliContext): Promise<void> {
     trustedOrigins: config.trustedOrigins,
     origin: config.origin,
     host: config.host,
+    secret: config.secret,
     cors: config.cors,
-    headExtras: await loadProductionHead(dist),
+    headExtras,
+    buildId,
     middlewareFile: resolve(dist, 'middleware.ts'),
+    bootFile: resolve(dist, 'boot.ts'),
   })
 
   await app.listen(resolvePort(ctx.portFlag, config.port))

package/src/client/runtime.ts

@@ -72,7 +72,12 @@ function initLiveChannel(): { close(): void } | undefined {
   if (!meta) return
 
   const routeKey = `GET ${location.pathname}${location.search}`
-  const url = `/__sse?route=${encodeURIComponent(routeKey)}&client=${encodeURIComponent(clientId)}`
+  // Echo the build this page was rendered against (if any) so the server can
+  // reload us when it's serving a newer build (dev restart / deploy). Baked
+  // into the URL at load time, so it rides EventSource's native reconnect too.
+  const build = document.querySelector('meta[name="stator-build"]')?.getAttribute('content')
+  const buildParam = build ? `&build=${encodeURIComponent(build)}` : ''
+  const url = `/__sse?route=${encodeURIComponent(routeKey)}&client=${encodeURIComponent(clientId)}${buildParam}`
 
   // Connection-state signal: `data-stator-connection` on the root element
   // (CSS hook for offline banners etc.) plus a `stator:connection-state`

package/src/server/boot.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import type { AnyMachineDef, EventOf } from '../engine/index.ts'
+import type { StatorConfigData } from './context.ts'
+import type { ModuleLoader } from './discovery.ts'
+
+// A global-registry symbol so the brand survives the dev dual-instance: the app's
+// `boot.ts` is loaded through Vite while the framework checks it from the native
+// module instance — `Symbol.for` resolves to the same symbol in both.
+const BOOT_BRAND = Symbol.for('stator.boot.definition')
+
+/**
+ * What a boot hook receives. Deliberately narrow: boot is a *source*, not a
+ * controller. It supplies events to the app-machine graph and reads config —
+ * policy (when/whether/how to act) belongs in the machine chart (a guard can
+ * debounce a `TICK`), not in this closure.
+ *
+ * Not exposed on purpose: `listen`/`fetch` (self-request foot-guns), the raw
+ * Hono app (that's `StatorApp.hono`'s break-glass), and the store (reaching
+ * around machines). Env is ambient — read `process.env` directly (`.env` is
+ * loaded before boot runs).
+ */
+export interface BootContext {
+  /** Feed an event into an APP-lifecycle machine — the bound `dispatchToApp`.
+   *  Boot has no session, so it operates on the app plane only. */
+  dispatchToApp<D extends AnyMachineDef>(
+    machine: D,
+    event: EventOf<D>,
+  ): Promise<{ committed: boolean }>
+  /** Curated framework config (the same view middleware sees via `stator(c)`):
+   *  `origin`, `trustedOrigins`, `sameSite`, `cors`. No adapters or secret. */
+  readonly config: StatorConfigData
+}
+
+/** Cleanup run on graceful shutdown — clear a poll interval, unsubscribe a
+ *  source. Return it from the boot function; the framework composes it into the
+ *  SIGTERM/SIGINT handler. */
+export type BootTeardown = () => void | Promise<void>
+
+/** A boot function: runs once when the server starts serving. May be async, and
+ *  may return a teardown. The `void` union is the React-`useEffect` shape — a
+ *  hook that MAY return a cleanup — and is required so `defineBoot(() => {…})`
+ *  with no return typechecks (`() => void` isn't assignable to `undefined`). */
+// biome-ignore lint/suspicious/noConfusingVoidType: intentional useEffect-style optional-teardown return
+export type BootFn = (ctx: BootContext) => void | BootTeardown | Promise<void | BootTeardown>
+
+/** The value an app's `boot.ts` exports (default). Opaque — build it with
+ *  `defineBoot`. */
+export interface BootDefinition {
+  readonly [BOOT_BRAND]: true
+  readonly run: BootFn
+}
+
+/** Type guard for a discovered `boot.ts` default export. */
+export function isBootDefinition(value: unknown): value is BootDefinition {
+  return typeof value === 'object' && value !== null && BOOT_BRAND in value
+}
+
+/**
+ * Define code that runs once when the server starts serving — the home for a
+ * long-lived inbound source: query config at boot, start a poll or subscription
+ * that dispatches events into the app-machine graph. Export the result as the
+ * default from `boot.ts` at the app root.
+ *
+ * Runs once per process (a dev restart re-runs it; an in-process rebuild does
+ * not). Return a teardown to clean up on shutdown.
+ *
+ * ```ts
+ * // boot.ts
+ * export default defineBoot(async ({ dispatchToApp }) => {
+ *   const timer = setInterval(
+ *     () => dispatchToApp(FleetMachine, { type: 'TICK', data: await poll() }),
+ *     30_000,
+ *   )
+ *   return () => clearInterval(timer)
+ * })
+ * ```
+ */
+export function defineBoot(run: BootFn): BootDefinition {
+  return { [BOOT_BRAND]: true, run }
+}
+
+const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
+
+/**
+ * Load an app's `boot.ts` (if present) and validate its default export. Returns
+ * `undefined` when there's no file. `loader` is injected so dev goes through
+ * Vite; prod/native uses `import` — the same single toolchain touch-point as
+ * `discoverMiddleware`.
+ */
+export async function discoverBoot(
+  file: string,
+  loader: ModuleLoader = nativeLoader,
+): Promise<BootDefinition | undefined> {
+  if (!existsSync(file)) return undefined
+  const mod = await loader(file)
+  const def = (mod as { default?: unknown }).default
+  if (!isBootDefinition(def)) {
+    throw new Error(`${file} must \`export default defineBoot((ctx) => { ... })\``)
+  }
+  return def
+}
+
+/**
+ * Run a discovered boot definition and return its teardown (if any). Called from
+ * `listen()` — once the server is up — so boot never fires during tests that use
+ * `app.fetch` without listening.
+ */
+export async function runBoot(
+  def: BootDefinition | undefined,
+  ctx: BootContext,
+): Promise<BootTeardown | undefined> {
+  if (!def) return undefined
+  const result = await def.run(ctx)
+  return typeof result === 'function' ? result : undefined
+}

package/src/server/context.ts

@@ -7,7 +7,7 @@ import type { Store } from './store.ts'
  * The resolved config data `buildHonoApp` stashes on the context (early), for
  * the security defaults, `cors()`, and app middleware to read.
  */
-interface StatorConfigData {
+export interface StatorConfigData {
   readonly origin?: string
   readonly trustedOrigins: readonly string[]
   readonly sameSite: 'Lax' | 'Strict'

package/src/server/create-app.ts

@@ -6,6 +6,7 @@ import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { dispatchToApp } from './app-dispatch.ts'
 import type { AppStore } from './app-store.ts'
 import { installGracefulShutdown, printStartupNotice } from './banner.ts'
+import { type BootTeardown, discoverBoot, runBoot } from './boot.ts'
 import { type DeprecatedFlatConfig, resolveAppConfig } from './config-compat.ts'
 import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
@@ -77,6 +78,12 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   /** Path to the app's `middleware.ts` (if any). Loaded and validated; its
    *  default export must be `defineMiddleware`/`dangerouslyDefineMiddleware`. */
   middlewareFile?: string
+  /** Path to the app's `boot.ts` (if any). Its default export must be
+   *  `defineBoot(...)`; it runs once when the app starts listening. */
+  bootFile?: string
+  /** Build identifier for the deploy-aware reload handshake. `stator start`
+   *  passes the id baked into the build manifest; absent → no handshake. */
+  buildId?: string
 }
 
 export interface StatorApp {
@@ -128,6 +135,7 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   const middleware = config.middlewareFile
     ? await discoverMiddleware(config.middlewareFile)
     : undefined
+  const bootDef = config.bootFile ? await discoverBoot(config.bootFile) : undefined
   const inspector = resolved.inspector
   const app = await buildHonoApp({
     routes,
@@ -145,6 +153,7 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     sameSite: resolved.sameSite,
     origin: resolved.origin,
     secret: resolved.secret,
+    buildId: config.buildId,
     cors: resolved.cors,
     middleware,
   })
@@ -152,9 +161,27 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   return {
     listen(port: number): Promise<void> {
       return new Promise((resolveFn) => {
-        const server = serve({ fetch: app.fetch, port, hostname: resolved.host }, () => {
+        const server = serve({ fetch: app.fetch, port, hostname: resolved.host }, async () => {
           // Always-on (level-independent) so `warn` prod still confirms boot.
           printStartupNotice({ port, machines: defs.length, routes: routes.length })
+          // Run boot.ts once the server is up — its long-lived work (a poll, a
+          // subscription) starts here, not during createApp, so tests that only
+          // `app.fetch` never trigger it.
+          const teardown: BootTeardown | undefined = await runBoot(bootDef, {
+            dispatchToApp: (machine, event) => dispatchToApp(store, machine, event),
+            config: {
+              origin: resolved.origin,
+              trustedOrigins: resolved.trustedOrigins ?? [],
+              sameSite: resolved.sameSite ?? 'Lax',
+              cors: resolved.cors,
+            },
+          })
+          // 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)
           resolveFn()
         })
         // Production is strict about its port (a collision is a deploy
@@ -169,9 +196,6 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
           }
           throw err
         })
-        // Ctrl+C / SIGTERM (deploy rollover) exits 0, not 130 — quiet in
-        // prod: the structured logs are the record.
-        installGracefulShutdown(() => new Promise<void>((done) => server.close(() => done())), true)
       })
     },
     fetch: (request: Request) => app.fetch(request),

package/src/server/dev.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { createServer as createHttpServer } from 'node:http'
@@ -115,6 +116,10 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   // Load .env before anything reads process.env. No-op if the CLI already
   // loaded it; covers a direct `createDevApp` call (a hand-written dev entry).
   loadDotenv(resolve(config.root))
+  // One build-id per dev boot — a `tsx` restart is a new process → new id → the
+  // client reloads on reconnect (the restart-without-reload gap). An inner Vite
+  // rebuild keeps the same id (no full reload; islands hot-reload via Vite).
+  const devBuildId = randomUUID()
   // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
   // stator apps side by side would fight over it (the loser's live reload
   // silently dies). Probe a free one instead.
@@ -122,6 +127,11 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   const vite = await createViteServer({
     root: resolve(config.root),
     appType: 'custom',
+    // Ignore a user `vite.config.*` — the production build already sets this,
+    // and reading it only in dev is a dev/prod divergence footgun (a plugin
+    // configured there would run in `stator dev` and silently vanish in
+    // `stator build`). Stator's own plugins are passed inline below.
+    configFile: false,
     server: { middlewareMode: true, hmr: { port: hmrPort } },
     // machineStub keeps server machines out of browser module graphs: island
     // imports of a machine resolve to a `{ name }` stub (SSR loads are
@@ -254,6 +264,7 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       sameSite: resolved.sameSite,
       origin: resolved.origin,
       secret: resolved.secret,
+      buildId: devBuildId,
       cors: resolved.cors,
       middleware,
     })
@@ -263,6 +274,10 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   await rebuildRoutes()
   await rebuildServer()
 
+  // Discover boot.ts ONCE per process (not per rebuild) — a long-lived source
+  // shouldn't restart on every edit. Runs in listen() below.
+  const bootDef = await runtime.discoverBoot(resolve(root, 'boot.ts'), loader)
+
   // Live reload: on a relevant source change, re-discover and rebuild the app,
   // then tell the browser to reload. A template/route edit keeps the store (and
   // your session — cart contents and all) intact; only a machine edit resets it,
@@ -313,16 +328,12 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       const server = createHttpServer((req, res) => {
         vite.middlewares(req, res, () => honoListener(req, res))
       })
-      installGracefulShutdown(async () => {
-        await vite.close()
-        await new Promise<void>((done) => server.close(() => done()))
-      })
       // Busy port? Shift up like every modern dev server (the requested
       // port is someone's other project, not an error).
       return findFreePort(port).then(
         (freePort) =>
           new Promise((resolveFn) => {
-            server.listen(freePort, () => {
+            server.listen(freePort, async () => {
               printDevBanner({
                 port: freePort,
                 requestedPort: port,
@@ -330,6 +341,23 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
                 routes: routes.length,
                 inspector: true,
               })
+              // Boot runs once the dev server is up (store is read at call time,
+              // so a later rebuild's store is used). Teardown composes into the
+              // shutdown below.
+              const teardown = await runtime.runBoot(bootDef, {
+                dispatchToApp: (machine, event) => runtime.dispatchToApp(store, machine, event),
+                config: {
+                  origin: resolved.origin,
+                  trustedOrigins: resolved.trustedOrigins ?? [],
+                  sameSite: resolved.sameSite ?? 'Lax',
+                  cors: resolved.cors,
+                },
+              })
+              installGracefulShutdown(async () => {
+                if (teardown) await teardown()
+                await vite.close()
+                await new Promise<void>((done) => server.close(() => done()))
+              })
               resolveFn()
             })
           }),

package/src/server/http.ts

@@ -49,6 +49,10 @@ export interface HttpConfig {
   /** Signed-cookie signing key (`config.secret` ?? `STATOR_SECRET`). Stashed on
    *  the request context so `cookies.setSigned`/`getSigned` can reach it. */
   secret?: string
+  /** Build identifier — per-boot in dev, per-build in prod. Emitted into live
+   *  pages as `<meta name="stator-build">`; the client echoes it on /__sse
+   *  connect, and a mismatch reloads the page (its slot map may be stale). */
+  buildId?: string
   /** Resolved CORS read policy, exposed via `stator(c).cors`. */
   cors?: { origins: readonly string[]; credentials: boolean }
   /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
@@ -304,6 +308,17 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     c.header('X-Accel-Buffering', 'no')
 
     return streamSSE(c, async (stream) => {
+      // Build-id handshake: this page was rendered against a server build
+      // (`build` param, from its `stator-build` meta). If ours differs — a dev
+      // restart or a deploy since page load — its DOM↔slot-ID map may be stale,
+      // so reload to fetch a fresh page instead of resyncing onto it. Checked
+      // before any render/registration: a doomed connection does no work.
+      const pageBuild = c.req.query('build')
+      if (config.buildId && pageBuild && pageBuild !== config.buildId) {
+        await stream.writeSSE({ data: JSON.stringify({ directives: [{ type: 'reload' }] }) })
+        return
+      }
+
       const runtime = new SessionRuntime(sessionId, config.store)
       await runtime.loadGraph(route.reads)
       const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request)
@@ -497,7 +512,15 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     if (isStatorQueryRoute(getRoute)) {
       return runQueryRoute(c, matched.route, getRoute, config.store, matched.params)
     }
-    return handleGet(c, matched.route, getRoute, matched.params, config.store, config.headExtras)
+    return handleGet(
+      c,
+      matched.route,
+      getRoute,
+      matched.params,
+      config.store,
+      config.headExtras,
+      config.buildId,
+    )
   })
 
   return app
@@ -568,6 +591,7 @@ async function handleGet(
   params: Record<string, string>,
   store: MachineStore,
   headExtras?: (filePath: string) => string | Promise<string>,
+  buildId?: string,
 ): Promise<Response> {
   {
     const { sessionId } = getOrCreateSessionId(c)
@@ -586,7 +610,15 @@ async function handleGet(
         const extra = await headExtras(discovered.filePath)
         if (extra) headHtml.push(extra)
       }
-      if (route.live) headHtml.push('<meta name="stator-live" content="true">')
+      if (route.live) {
+        headHtml.push('<meta name="stator-live" content="true">')
+        // The build this page was rendered against — the client echoes it on
+        // /__sse connect so the server can reload a page from a stale build.
+        // `buildId` is a framework-generated UUID (no HTML-special chars).
+        if (buildId) {
+          headHtml.push(`<meta name="stator-build" content="${buildId}">`)
+        }
+      }
 
       // Auto-inject the client runtime (delegated events + patch application).
       // Apps never hand-include it — a forgotten <script> is a silently dead

package/src/server/index.ts

@@ -18,6 +18,8 @@ export type {
 export { dispatchToApp } from './app-dispatch.ts'
 export type { AppStore } from './app-store.ts'
 export { InMemoryAppStore } from './app-store.ts'
+export type { BootContext, BootDefinition, BootFn, BootTeardown } from './boot.ts'
+export { defineBoot, discoverBoot, isBootDefinition, runBoot } from './boot.ts'
 export type { CachedStoreOptions } from './cached-store.ts'
 export { CachedStore } from './cached-store.ts'
 export type { StatorContext } from './context.ts'