@statorjs/stator 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.1.0",
+  "version": "2.3.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",
@@ -24,6 +24,9 @@
     "src",
     "README.md"
   ],
+  "bin": {
+    "stator": "./src/cli/stator.js"
+  },
   "exports": {
     "./server": {
       "types": "./src/server/index.ts",
@@ -41,6 +44,10 @@
       "types": "./src/build/index.ts",
       "default": "./src/build/index.ts"
     },
+    "./config": {
+      "types": "./src/config.ts",
+      "default": "./src/config.ts"
+    },
     "./template": {
       "types": "./src/template/index.ts",
       "default": "./src/template/index.ts"
@@ -88,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.1.0"
+    "@statorjs/stator": "2.3.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/build.ts

@@ -82,6 +82,11 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     if (await exists(src)) await cp(src, join(outDir, d), { recursive: true })
   }
 
+  // A root-level middleware.ts is a single file, not a source dir — copy it too
+  // (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'))
+
   // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
   const statorFiles = await walk(outDir, (f) => f.endsWith('.stator'))
   let css = ''

package/src/cli/commands/build.ts

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path'
+import { buildApp } from '../../build/index.ts'
+import type { CliContext } from '../run.ts'
+import { checkStack } from './check.ts'
+
+/** Compile the app to `dist/` — but validate the whole stack FIRST, so a broken
+ *  server file fails the build instead of shipping silently. */
+export async function run(ctx: CliContext): Promise<void> {
+  await checkStack(ctx.root)
+  const result = await buildApp({ root: ctx.root, outDir: resolve(ctx.root, 'dist') })
+  process.stdout.write(
+    `stator build: ${result.compiled} components → ${result.outDir}` +
+      `${result.islands ? ` (${result.islands} island${result.islands === 1 ? '' : 's'})` : ''}\n`,
+  )
+}

package/src/cli/commands/check.ts

@@ -0,0 +1,72 @@
+import ts from 'typescript'
+import { syncTypes } from '../../build/index.ts'
+import type { CliContext } from '../run.ts'
+
+/**
+ * Validate the WHOLE stack — server machines/routes/lib plus the generated
+ * `.stator` types — with no output. This is the piece production builds were
+ * missing: `buildApp` only ever touched client islands and copied server files
+ * to `dist/` unvalidated, so a broken server import shipped silently. `build`
+ * now runs this first.
+ *
+ * Two steps: (1) `syncTypes` regenerates each `.stator.d.ts` + the virtual TSX
+ * the language server typechecks, so the app's `tsconfig` sees current types;
+ * (2) a `tsc --noEmit`-equivalent pass via the TypeScript API over that config.
+ */
+export async function checkStack(root: string): Promise<void> {
+  const { written } = await syncTypes(root)
+
+  const configPath = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json')
+  if (!configPath) throw new Error(`no tsconfig.json found at or above ${root}`)
+
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    configPath,
+    { noEmit: true },
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (d) => {
+        throw new Error(ts.flattenDiagnosticMessageText(d.messageText, ts.sys.newLine))
+      },
+    },
+  )
+  if (!parsed) throw new Error(`could not parse ${configPath}`)
+
+  const program = ts.createProgram({ rootNames: parsed.fileNames, options: parsed.options })
+  const diagnostics = [
+    ...program.getConfigFileParsingDiagnostics(),
+    ...ts.getPreEmitDiagnostics(program),
+  ]
+
+  if (diagnostics.length > 0) {
+    process.stderr.write(
+      ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCanonicalFileName: (f) => f,
+        getCurrentDirectory: ts.sys.getCurrentDirectory,
+        getNewLine: () => ts.sys.newLine,
+      }),
+    )
+    const n = diagnostics.length
+    throw new Error(`typecheck failed with ${n} error${n === 1 ? '' : 's'}`)
+  }
+
+  // Split the program into the app's own files vs. framework/lib overhead so the
+  // count reads honestly: most of the program is @statorjs/stator's shipped source
+  // (raw TS — typechecked, not `skipLibCheck`-skipped) plus TS libs, not your code.
+  // App files = under the app root and outside node_modules; the rest is framework
+  // + libs. The same split holds for an installed app (framework source lives under
+  // `root/node_modules`, which the node_modules test excludes).
+  const rootPrefix = `${root.replace(/\\/g, '/').replace(/\/+$/, '')}/`
+  const sourceFiles = program.getSourceFiles()
+  const appFiles = sourceFiles.filter(
+    (sf) => sf.fileName.startsWith(rootPrefix) && !sf.fileName.includes('/node_modules/'),
+  ).length
+  const frameworkFiles = sourceFiles.length - appFiles
+
+  process.stdout.write(
+    `stator check: ok — ${written} .stator.d.ts, ${appFiles} app files (${frameworkFiles} framework files)\n`,
+  )
+}
+
+export async function run(ctx: CliContext): Promise<void> {
+  await checkStack(ctx.root)
+}

package/src/cli/commands/dev.ts

@@ -0,0 +1,24 @@
+import { resolve } from 'node:path'
+import { createDevApp } from '../../server/dev.ts'
+import { loadConfig, resolvePort } from '../config.ts'
+import type { CliContext } from '../run.ts'
+
+/** Run the dev server (Vite-backed today: live reload, compile-error overlay,
+ *  inspector). Conventions for machines/routes/static; `stator.config.ts` for
+ *  the store/session/port an app previously hand-wrote a `server.ts` for. */
+export async function run(ctx: CliContext): Promise<void> {
+  const config = await loadConfig(ctx.root)
+  const app = await createDevApp({
+    root: ctx.root,
+    machinesDir: resolve(ctx.root, 'machines'),
+    routesDir: resolve(ctx.root, 'routes'),
+    staticDir: resolve(ctx.root, 'static'),
+    persistence: config.persistence,
+    sessions: config.sessions,
+    dev: config.dev,
+    trustedOrigins: config.trustedOrigins,
+    origin: config.origin,
+    cors: config.cors,
+  })
+  await app.listen(resolvePort(ctx.portFlag, config.port))
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,35 @@
+import { stat } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { loadProductionHead } from '../../build/index.ts'
+import { createApp } from '../../server/index.ts'
+import { loadConfig, resolvePort } from '../config.ts'
+import type { CliContext } from '../run.ts'
+
+/** Serve a built `dist/` in production mode (no Vite). Same `stator.config.ts`
+ *  as `dev` supplies the store/session/port. */
+export async function run(ctx: CliContext): Promise<void> {
+  const dist = resolve(ctx.root, 'dist')
+  try {
+    await stat(resolve(dist, 'routes'))
+  } catch {
+    throw new Error('no dist/ found — run `stator build` first')
+  }
+
+  const config = await loadConfig(ctx.root)
+  const app = await createApp({
+    machinesDir: resolve(dist, 'machines'),
+    routesDir: resolve(dist, 'routes'),
+    staticDir: resolve(dist, 'static'),
+    persistence: config.persistence,
+    sessions: config.sessions,
+    realtime: config.realtime,
+    trustedOrigins: config.trustedOrigins,
+    origin: config.origin,
+    host: config.host,
+    cors: config.cors,
+    headExtras: await loadProductionHead(dist),
+    middlewareFile: resolve(dist, 'middleware.ts'),
+  })
+
+  await app.listen(resolvePort(ctx.portFlag, config.port))
+}

package/src/cli/commands/test.ts

@@ -0,0 +1,31 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { CliContext } from '../run.ts'
+
+/**
+ * Run the test suite. The runner is a deliberately swappable seam — today it
+ * wraps the app's local Vitest; as the platform matures this becomes
+ * `node --test` (with a `.stator` loader hook), invisibly to callers.
+ */
+export async function run(ctx: CliContext): Promise<void> {
+  const bin = join(
+    ctx.root,
+    'node_modules',
+    '.bin',
+    process.platform === 'win32' ? 'vitest.cmd' : 'vitest',
+  )
+  if (!existsSync(bin)) {
+    throw new Error(
+      'vitest not found in node_modules — install it, or run your test script directly',
+    )
+  }
+  const args = ctx.rest.length > 0 ? ctx.rest : ['run']
+  await new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(bin, args, { stdio: 'inherit', cwd: ctx.root })
+    child.on('error', reject)
+    child.on('exit', (code) =>
+      code === 0 ? resolvePromise() : reject(new Error(`tests failed (exit ${code})`)),
+    )
+  })
+}

package/src/cli/config.ts

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { StatorConfig } from '../config.ts'
+
+const CONFIG_NAMES = [
+  'stator.config.ts',
+  'stator.config.mts',
+  'stator.config.js',
+  'stator.config.mjs',
+]
+
+/**
+ * Load `stator.config.{ts,mts,js,mjs}` from the app root if present. Returns `{}`
+ * when there is none — every field is optional. The default export may be the
+ * config object or a (possibly async) function returning one.
+ *
+ * No key normalization: `StatorConfig` is a brand-new, never-released surface, so
+ * the nested shape is the only shape — there is nothing to be backward-compatible
+ * with.
+ */
+export async function loadConfig(root: string): Promise<StatorConfig> {
+  for (const name of CONFIG_NAMES) {
+    const path = join(root, name)
+    if (!existsSync(path)) continue
+    const mod = (await import(pathToFileURL(path).href)) as { default?: unknown }
+    const raw = mod.default ?? mod
+    const resolved = typeof raw === 'function' ? await (raw as () => unknown)() : raw
+    if (resolved && typeof resolved === 'object') return resolved as StatorConfig
+    throw new Error(`${name} must export a config object (or a function returning one)`)
+  }
+  return {}
+}
+
+/** Resolve the listen port: `--port` flag > `$PORT` > config > 3000. */
+export function resolvePort(flag: number | undefined, configPort: number | undefined): number {
+  if (flag != null) return flag
+  if (process.env.PORT) return Number(process.env.PORT)
+  return configPort ?? 3000
+}

package/src/cli/loader.js

@@ -0,0 +1,40 @@
+// Minimal TS-on-import loader for the `stator` CLI, so the plain-`node` bin can
+// import the framework's TypeScript source without a `tsx` dependency. Uses
+// esbuild (already a framework dep) to strip/transform types at load time.
+//
+// This is the seed of Stator's own thin toolchain glue: the same shape a
+// `.stator` `node:test` loader hook will take later. It intentionally handles
+// only `.ts`/`.tsx` — `.stator` is compiled by the framework's own compiler on
+// the dev/build path, not here.
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { transform } from 'esbuild'
+
+const TS = /\.(?:ts|tsx|mts|cts)$/
+
+/** Tell Node a `.ts` URL is an ES module so it reaches the `load` hook instead
+ *  of throwing ERR_UNKNOWN_FILE_EXTENSION. Imports carry explicit extensions
+ *  (framework convention), so no specifier rewriting is needed. */
+export async function resolve(specifier, context, nextResolve) {
+  const result = await nextResolve(specifier, context)
+  if (TS.test(new URL(result.url).pathname))
+    return { ...result, format: 'module', shortCircuit: true }
+  return result
+}
+
+/** Transform TS source to ESM JS at load time. */
+export async function load(url, context, nextLoad) {
+  if (url.startsWith('file:') && TS.test(new URL(url).pathname)) {
+    const path = fileURLToPath(url)
+    const source = await readFile(path, 'utf8')
+    const { code } = await transform(source, {
+      loader: path.endsWith('x') ? 'tsx' : 'ts',
+      format: 'esm',
+      target: 'node20',
+      sourcemap: 'inline',
+      sourcefile: path,
+    })
+    return { format: 'module', source: code, shortCircuit: true }
+  }
+  return nextLoad(url, context)
+}

package/src/cli/run.ts

@@ -0,0 +1,72 @@
+import { resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+
+/** Shared context every command receives. */
+export interface CliContext {
+  /** App root — where machines/, routes/, static/, dist/ live. Defaults to cwd. */
+  root: string
+  /** `--port` flag, if given. Final port resolves flag > $PORT > config > 3000. */
+  portFlag?: number
+  /** Extra positionals after the command (e.g. test file globs). */
+  rest: string[]
+}
+
+const COMMANDS = ['dev', 'build', 'start', 'check', 'test'] as const
+type Command = (typeof COMMANDS)[number]
+
+const HELP = `stator — the Stator toolchain CLI
+
+Usage: stator <command> [options]
+
+Commands:
+  dev       Run the dev server (live reload, inspector)
+  build     Compile the app to dist/ (runs \`check\` first)
+  start     Serve a built dist/ in production mode
+  check     Typecheck the whole stack (server + generated .stator types), no output
+  test      Run the test suite
+
+Options:
+  --root <dir>    App root (default: current directory)
+  --port <n>      Listen port for dev/start (default: $PORT or 3000)
+  -h, --help      Show this help
+`
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  strict: false,
+  options: {
+    root: { type: 'string' },
+    port: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+  },
+})
+
+const command = positionals[0] as Command | undefined
+
+if (values.help || !command) {
+  process.stdout.write(HELP)
+  process.exit(command ? 0 : values.help ? 0 : 1)
+}
+
+if (!COMMANDS.includes(command)) {
+  process.stderr.write(`stator: unknown command "${command}"\n\n${HELP}`)
+  process.exit(1)
+}
+
+const ctx: CliContext = {
+  root: resolve(String(values.root ?? process.cwd())),
+  portFlag: values.port != null ? Number(values.port) : undefined,
+  rest: positionals.slice(1),
+}
+
+// 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>
+}
+
+try {
+  await run(ctx)
+} catch (err) {
+  process.stderr.write(`stator ${command}: ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exit(1)
+}

package/src/cli/stator.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// The `stator` CLI entry (bin). Plain JS so it runs on any Node the framework
+// supports; it registers a small esbuild TS loader (see loader.js) so the rest
+// of the CLI — and the framework API it drives — can be authored in TypeScript
+// without a `tsx` dependency. As Node's native TS support stabilizes this loader
+// becomes removable; the bin stays.
+//
+// The CLI's one hard runtime requirement is `module.register` — present on
+// Node 18.19+ or 20.6+. The framework RUNTIME has no such floor, so we do NOT
+// declare a package-wide `engines` — this opt-in tool self-detects instead,
+// keeping the CLI a purely additive feature with no change to the package's
+// node-compat contract.
+import nodeModule from 'node:module'
+
+const register = nodeModule?.register
+if (typeof register !== 'function') {
+  process.stderr.write(
+    `stator: the CLI requires module.register — Node 18.19+ or 20.6+ (found ${process.version}).\n` +
+      `The framework runtime itself has no such requirement.\n`,
+  )
+  process.exit(1)
+}
+
+register('./loader.js', import.meta.url)
+
+// The real CLI is TypeScript, transformed on import by the loader just registered.
+await import('./run.ts')

package/src/config.ts

@@ -0,0 +1,92 @@
+import type { AppStore, Store } from './server/index.ts'
+
+/** Log verbosity, from most to least severe. Setting a level emits it and
+ *  everything above it — `warn` shows `warn`+`error`+`fatal`, hiding
+ *  `info`/`debug`. Pino's levels. */
+export type LogLevel = 'silent' | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+
+/**
+ * Stator app configuration — the home for what previously forced a hand-written
+ * `server.ts`/`start.ts`: the persistence adapters, session/realtime policy, and
+ * dev port.
+ *
+ * Loaded from `stator.config.{ts,mts,js,mjs}` at the app root by the `stator`
+ * CLI (`dev`/`start`). Grouped by concern so the config principle is visible in
+ * the shape: `persistence` holds the swappable adapters (infra); `sessions` /
+ * `realtime` / `dev` hold policy. Config owns *how it runs*, never *what it does*
+ * (behavior — e.g. a route's `live` flag — stays in code).
+ *
+ * Every field is optional; omit the file entirely to accept defaults (in-memory
+ * persistence, 24h session TTL, port 3000). There is no required machine-graph
+ * entry point — machines are file-discovered from `machines/`.
+ */
+export interface StatorConfig {
+  /** Listen port for `dev`/`start`. Precedence: `--port` flag > `$PORT` > this > 3000. */
+  port?: number
+  /** Listen host / bind address. Default: all interfaces. Containers behind a
+   *  proxy typically need `0.0.0.0`. */
+  host?: string
+  /** Canonical app URL (`https://example.com`) — for absolute-URL generation
+   *  (redirects, SSE reconnect, OG tags) and as a spoof-proof same-origin
+   *  anchor. Exposed to middleware via `stator(c).origin`. */
+  origin?: 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). */
+  persistence?: {
+    /** Session-lifecycle machine state. Default: `InMemoryStore`. Pass a
+     *  `RedisStore`/`CachedStore` for durability — the adapter seam. */
+    session?: Store
+    /** App-lifecycle machine state for `persist: true` machines (no TTL, one
+     *  blob per machine). Advanced — most apps never set it. Default:
+     *  in-memory (restart-wipe). Pass a `RedisAppStore` for durable app state. */
+    app?: AppStore
+  }
+  /** Session policy (no adapter here — that lives in `persistence.session`). */
+  sessions?: {
+    /** Per-session idle TTL in seconds. Default: 86400 (24h). */
+    ttlSeconds?: number
+    /** Session cookie policy. */
+    cookie?: {
+      /** `SameSite` attribute. Default `Lax` (allows same-site subdomains).
+       *  `Strict` withholds the cookie from every cross-site request and flips
+       *  the CSRF guard to allowlist-only — the controlled posture. */
+      sameSite?: 'Lax' | 'Strict'
+    }
+    // cookieName?, rotation? — reserved policy siblings (not wired yet).
+  }
+  /** Realtime / push policy. Protocol-neutral so a future WS transport doesn't
+   *  make the key a lie. */
+  realtime?: {
+    /** SSE heartbeat interval in ms (`start` only). Default: 25000. */
+    pingMs?: number
+    // transport? — reserved INTERNAL seam (not user-facing).
+  }
+  /** Dev-only tooling. */
+  dev?: {
+    /** Dev inspector toolbar (`dev` only). Default: on. */
+    inspector?: boolean
+  }
+  /** Origins allowed to make cross-site writes despite the CSRF guard — exact
+   *  (`https://app.example.com`) or wildcard-subdomain (`https://*.example.com`).
+   *  Same-origin and same-site writes are already allowed; this is for decoupled
+   *  frontends or partner domains. */
+  trustedOrigins?: string[]
+  /** Cross-origin READ policy (CORS) — governs which cross-origin sites may read
+   *  responses (distinct from `trustedOrigins`, which governs cross-site writes).
+   *  Opt in per route/app with the `cors()` middleware; `origins` defaults to
+   *  `trustedOrigins`. */
+  cors?: { origins?: string[]; credentials?: boolean }
+  /** Logging policy. */
+  logging?: {
+    /** Minimum level to emit. Default: `warn` in production, `info` in dev.
+     *  Precedence: `LOG_LEVEL` env > this > default. */
+    level?: LogLevel
+  }
+  // observers?: Observer[] — top-level when the observability spec lands.
+}
+
+/** Identity helper for a typed config: `export default defineConfig({ … })`. */
+export function defineConfig(config: StatorConfig): StatorConfig {
+  return config
+}

package/src/engine/define-machine.ts

@@ -30,6 +30,13 @@ export interface DefineMachineConfig<
   /** Typed event surface. Pass `{} as MyEvents` — a phantom carrier the engine
    *  reads only for its type. Actions/guards then narrow per transition. */
   events?: E
+  /** Event types NO client may dispatch to `/__events` — effect completions
+   *  (`CHARGE_APPROVED`), timer/`after:` events, cross-machine internals: events
+   *  only the server/engine generates. A production `stator start` rejects a
+   *  client POST of one with 403 (dev does not enforce). Typed against the event
+   *  union, so a name that isn't a real event is a compile error. The chart still
+   *  handles them normally when the engine/effects raise them. */
+  serverOnly?: readonly E['type'][]
   emits?: EmitsConfig<C, E>
   context: C
   initial: NoInfer<S>
@@ -116,6 +123,7 @@ export function defineMachine<
     persist: config.persist ?? false,
     reads,
     subscribes: config.subscribes ?? [],
+    serverOnly: config.serverOnly ?? [],
     emits: normalizeEmits<C, E>(config.emits),
     selectors: (config.selectors ?? {}) as Sel,
     capabilities: computeCapabilities(reads),

package/src/engine/types.ts

@@ -243,6 +243,10 @@ export interface MachineDef<
   persist: boolean
   reads: AnyMachineDef[]
   subscribes: SubscribeEntry[]
+  /** Event types no client may dispatch to `/__events` (server-generated only:
+   *  effect completions, timers, cross-machine internals). Normalized to `[]`.
+   *  Enforced with a 403 in production; the chart handles them normally. */
+  serverOnly: readonly string[]
   /** Normalized: every declared emit, possibly with a payload selector. */
   emits: Record<string, EmitDeclaration<C, E>>
   selectors: Sel

package/src/server/api-route.ts

@@ -1,7 +1,7 @@
-import { randomUUID } from 'node:crypto'
 import type { Context } from 'hono'
 import { setCookie } from 'hono/cookie'
 import { safeNavigationUrl } from '../wire/safe-url.ts'
+import { cookieJar } from './cookies.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -15,7 +15,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId, setSessionCookie } from './session.ts'
+import { getOrCreateSessionId, getSessionState, rotateSessionNow } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -73,6 +73,25 @@ export async function runApiRoute(
         rotateSession: (opts) => {
           rotation = { clear: opts?.clear === true }
         },
+        clearSession: () => {
+          rotation = { clear: true }
+        },
+        claims: <T = unknown>() => getSessionState(c)?.claims as T | undefined,
+        setClaims: (claims) => {
+          const s = getSessionState(c)
+          if (s) {
+            s.claims = claims
+            s.claimsDirty = true
+          }
+        },
+        clearClaims: () => {
+          const s = getSessionState(c)
+          if (s) {
+            s.claims = undefined
+            s.claimsDirty = true
+          }
+        },
+        cookies: cookieJar(c),
       }
 
       let result: Response | ApiRouteEnvelope
@@ -101,20 +120,11 @@ export async function runApiRoute(
       // new cookie. Effect completions must chase the NEW id.
       let effectsSessionId = sessionId
       if (rotation !== null) {
-        const newSessionId = randomUUID()
-        if ((rotation as { clear: boolean }).clear) {
-          await store.persistence.deleteSession(sessionId)
-        } else {
-          if (!store.persistence.renameSession) {
-            throw new Error(
-              'stator: rotateSession requires a store with renameSession — ' +
-                'the configured custom store does not implement it.',
-            )
-          }
-          await store.persistence.renameSession(sessionId, newSessionId)
-        }
-        setSessionCookie(c, newSessionId)
-        effectsSessionId = newSessionId
+        // Apply the deferred rotation now the handler has returned. The helper
+        // moves (or, on clear, deletes) the session, sets the new cookie, and
+        // updates the shared session state so the bridge persists claims to the
+        // new id. Effect completions must chase the NEW id.
+        effectsSessionId = await rotateSessionNow(c, store, rotation)
       }
       // Effects queued by dispatched events run after this callback returns
       // (never under the session lock); see server/effects.ts.
@@ -201,8 +211,10 @@ function synthesizeResponse(
       // same-origin, else fall back to '/' (no open redirect).
       return c.redirect(sameOriginReferer(request), 303)
     }
-    // No actionable directive for a no-JS client. Send a minimal 204.
-    return new Response(null, { status: 204 })
+    // No actionable directive for a no-JS client. Send a minimal 204 — via
+    // c.body so any cookies set this request (session rotation, the cookie jar)
+    // survive; a bare `new Response` would drop c's accumulated Set-Cookie.
+    return c.body(null, 204)
   }
 
   // JSON / client-runtime path.

package/src/server/banner.ts

@@ -70,6 +70,24 @@ export function printDevBanner(info: {
   process.stdout.write(`${lines.join('\n')}\n`)
 }
 
+/**
+ * One-line production startup notice. Printed to stdout directly — NOT through
+ * the leveled logger — so it always shows, even at the quiet `warn` default:
+ * "did it start, and where" is the one thing an operator always wants, distinct
+ * from the per-request logs that `warn` intentionally suppresses.
+ */
+export function printStartupNotice(info: { port: number; machines: number; routes: number }): void {
+  const v = statorVersion()
+  const inv = `${info.machines} machine${info.machines === 1 ? '' : 's'} · ${info.routes} route${
+    info.routes === 1 ? '' : 's'
+  }`
+  process.stdout.write(
+    `  ${c.copper(c.bold('stator'))}${v ? c.dim(` v${v}`) : ''} ${c.dim('·')} ${c.cyan(
+      `http://localhost:${info.port}/`,
+    )} ${c.dim(`· ${inv}`)}\n`,
+  )
+}
+
 /**
  * Exit a server process like a well-mannered CLI: first signal closes
  * cleanly and exits 0 (Ctrl+C is a normal action, not a failure — without