@statorjs/stator 2.3.0 → 2.5.0

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.3.0",
+  "version": "2.5.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 (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.3.0"
+    "@statorjs/stator": "2.5.0"
   },
   "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/cli/run.ts

@@ -59,6 +59,12 @@ const ctx: CliContext = {
   rest: positionals.slice(1),
 }
 
+// Load .env before importing the command — so `stator.config.ts` (imported by
+// loadConfig inside the command) can read `process.env.*`. createApp/createDevApp
+// load it again for the direct-`server.ts` path; idempotent.
+const { loadDotenv } = await import('../server/env.ts')
+loadDotenv(ctx.root)
+
 // Dynamic import per command so `check` never loads the dev server's Vite, etc.
 const { run } = (await import(`./commands/${command}.ts`)) as {
   run: (ctx: CliContext) => Promise<void>

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

@@ -30,6 +30,12 @@ export interface StatorConfig {
    *  (redirects, SSE reconnect, OG tags) and as a spoof-proof same-origin
    *  anchor. Exposed to middleware via `stator(c).origin`. */
   origin?: string
+  /** Signing secret for signed cookies (`cookies.setSigned`/`getSigned`) — the
+   *  sealed short-lived-state primitive (OAuth `state`/PKCE, a magic-link token,
+   *  a WebAuthn challenge). Falls back to `process.env.STATOR_SECRET`. Use a long
+   *  random string (≥32 chars); keep it out of source — set it in `.env.local` or
+   *  a platform secret. Absent → the signed-cookie methods throw. */
+  secret?: string
   /** The swappable persistence adapters, grouped by concern. Both optional —
    *  default to in-memory (restart-wipe). Neither is a machine-graph entry
    *  point (machines are file-discovered). */

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/config-compat.ts

@@ -32,6 +32,7 @@ interface NestedReads {
   trustedOrigins?: readonly string[]
   origin?: string
   host?: string
+  secret?: string
   cors?: { origins?: readonly string[]; credentials?: boolean }
 }
 
@@ -47,6 +48,8 @@ export interface ResolvedAppConfig {
   sameSite?: 'Lax' | 'Strict'
   origin?: string
   host?: string
+  /** Signed-cookie signing key. `config.secret` ?? `STATOR_SECRET`. */
+  secret?: string
   cors?: { origins: readonly string[]; credentials: boolean }
 }
 
@@ -82,6 +85,8 @@ export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): Re
     sameSite: config.sessions?.cookie?.sameSite,
     origin: config.origin,
     host: config.host,
+    // The signing key: explicit config wins, else the env (loadable via .env).
+    secret: config.secret ?? process.env.STATOR_SECRET,
     cors: config.cors
       ? {
           origins: config.cors.origins ?? config.trustedOrigins ?? [],

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'
@@ -20,6 +20,8 @@ declare module 'hono' {
   interface ContextVariableMap {
     stator: StatorConfigData
     statorStore: { persistence: Store }
+    /** Signed-cookie signing key, stashed by the bridge when configured. */
+    statorSecret: string
   }
 }
 

package/src/server/cookies.ts

@@ -1,5 +1,5 @@
 import type { Context } from 'hono'
-import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
+import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'hono/cookie'
 import type { RouteCookieOptions } from './routing.ts'
 
 /**
@@ -17,8 +17,31 @@ export interface CookieJar {
   /** Write a cookie on the response. Defaults are hono's (not HttpOnly/Secure);
    *  pass options for auth-shaped cookies. */
   set(name: string, value: string, options?: RouteCookieOptions): void
-  /** Expire a cookie. `path`/`domain` must match how it was set. */
+  /** Expire a cookie. `path`/`domain` must match how it was set. Works for
+   *  signed cookies too — deletion needs no signature. */
   delete(name: string, options?: Pick<RouteCookieOptions, 'path' | 'domain'>): void
+  /** Read a signed cookie, verifying its signature against the app secret.
+   *  `undefined` if absent OR the signature is invalid (tampered, or signed
+   *  with a since-rotated secret) — an untrustworthy value is treated as absent.
+   *  Throws if no secret is configured. The sealed short-lived-state read
+   *  (OAuth `state`/PKCE, a magic-link token, a WebAuthn challenge). */
+  getSigned(name: string): Promise<string | undefined>
+  /** Write a signed cookie — the value is tamper-evident, not encrypted (still
+   *  readable by the client, so don't put secrets *in* it; put a nonce it can't
+   *  forge). Throws if no secret is configured. */
+  setSigned(name: string, value: string, options?: RouteCookieOptions): Promise<void>
+}
+
+/** Read the configured signing secret, or throw a fix-it error. */
+function requireSecret(c: Context): string {
+  const secret = c.get('statorSecret')
+  if (!secret) {
+    throw new Error(
+      'stator: signed cookies require a secret — set `secret` in stator.config.ts ' +
+        'or `STATOR_SECRET` in the environment (e.g. .env.local).',
+    )
+  }
+  return secret
 }
 
 /** Build the cookie jar bound to a request context. Shared by `stator(c)`
@@ -33,5 +56,14 @@ export function cookieJar(c: Context): CookieJar {
     delete: (name, options) => {
       deleteCookie(c, name, options as never)
     },
+    getSigned: async (name) => {
+      // hono returns `false` for a present-but-invalid signature; collapse it to
+      // undefined so callers never trust (or even see) a tampered value.
+      const value = await getSignedCookie(c, requireSecret(c), name)
+      return value === false ? undefined : value
+    },
+    setSigned: async (name, value, options) => {
+      await setSignedCookie(c, name, value, requireSecret(c), options as never)
+    },
   }
 }

package/src/server/create-app.ts

@@ -6,9 +6,11 @@ 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'
+import { loadDotenv } from './env.ts'
 import { buildHonoApp } from './http.ts'
 import { logger, setLogLevel } from './logger.ts'
 import { MachineStore } from './machine-store.ts'
@@ -63,6 +65,9 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   trustedOrigins?: readonly string[]
   /** Canonical app URL, exposed via `stator(c).origin`. */
   origin?: string
+  /** Signed-cookie signing key. Falls back to `STATOR_SECRET`. Mirrors
+   *  `StatorConfig.secret`. */
+  secret?: string
   /** Listen host / bind address (used by `listen`). Default: all interfaces. */
   host?: string
   /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
@@ -73,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 {
@@ -96,6 +107,9 @@ export interface StatorApp {
 }
 
 export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
+  // Load .env before anything reads process.env (LOG_LEVEL below, app secrets).
+  // No-op if the CLI already loaded it; covers the direct `server.ts` entry.
+  loadDotenv()
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
   const staticDir = config.staticDir ? resolve(config.staticDir) : undefined
@@ -121,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,
@@ -137,6 +152,8 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     trustedOrigins: resolved.trustedOrigins,
     sameSite: resolved.sameSite,
     origin: resolved.origin,
+    secret: resolved.secret,
+    buildId: config.buildId,
     cors: resolved.cors,
     middleware,
   })
@@ -144,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
@@ -161,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'
@@ -12,6 +13,7 @@ import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { resolveAppConfig } from './config-compat.ts'
+import { loadDotenv } from './env.ts'
 import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -73,6 +75,9 @@ export interface DevAppConfig {
   trustedOrigins?: readonly string[]
   /** Canonical app URL, exposed via `stator(c).origin`. */
   origin?: string
+  /** Signed-cookie signing key. Falls back to `STATOR_SECRET`. Mirrors
+   *  `StatorConfig.secret`. */
+  secret?: string
   /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
   // Deprecated flat keys — accepted (typed) so 2.1.0 callers don't break; nested
@@ -108,6 +113,13 @@ export interface DevApp {
 }
 
 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.
@@ -246,6 +258,8 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       trustedOrigins: resolved.trustedOrigins,
       sameSite: resolved.sameSite,
       origin: resolved.origin,
+      secret: resolved.secret,
+      buildId: devBuildId,
       cors: resolved.cors,
       middleware,
     })
@@ -255,6 +269,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,
@@ -305,16 +323,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,
@@ -322,6 +336,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/env.ts

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+/**
+ * Load `.env` files into `process.env` — the home for server config/secrets
+ * that's uniform across dev and prod (unlike Vite's transform-time
+ * `import.meta.env`, absent in prod). Precedence, highest first:
+ *
+ *   real shell env  >  .env.local  >  .env
+ *
+ * `process.loadEnvFile` (native, Node ≥20.12 — no dependency) never overrides
+ * an already-set key, so real env always wins, and `.env.local` is loaded
+ * *before* `.env`: the earlier load claims a key the later one can't reclaim.
+ * Absent files are skipped. Idempotent-safe — a second call adds nothing new,
+ * so the CLI (which loads before importing `stator.config.ts`) and
+ * `createApp`/`createDevApp` (which load for the direct `server.ts` path) can
+ * both call it without conflict.
+ *
+ * `.env.local` is for machine-local secrets and belongs in `.gitignore`; `.env`
+ * holds committed defaults.
+ */
+export function loadDotenv(root: string = process.cwd()): void {
+  for (const name of ['.env.local', '.env']) {
+    const path = resolve(root, name)
+    if (existsSync(path)) process.loadEnvFile(path)
+  }
+}

package/src/server/http.ts

@@ -46,6 +46,13 @@ export interface HttpConfig {
   sameSite?: 'Lax' | 'Strict'
   /** Canonical app origin, exposed to middleware via `stator(c).origin`. */
   origin?: string
+  /** 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`
@@ -179,6 +186,8 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
     // Stash the store so middleware session ops (rotate/clear) can act now.
     c.set('statorStore', config.store)
+    // Stash the signing key so the cookie jar's signed methods can reach it.
+    if (config.secret !== undefined) c.set('statorSecret', config.secret)
     const { sessionId, isNew } = getOrCreateSessionId(c)
     const session = getSessionState(c)
     if (!isNew && session) {
@@ -299,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)
@@ -492,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
@@ -563,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)
@@ -581,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'