@statorjs/stator 2.1.0 → 2.2.0

package/package.json

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

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,21 @@
+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,
+  })
+  await app.listen(resolvePort(ctx.portFlag, config.port))
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,30 @@
+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,
+    headExtras: await loadProductionHead(dist),
+  })
+
+  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,68 @@
+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
+  /** 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
+    // 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
+  }
+  /** 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/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

package/src/server/config-compat.ts

@@ -0,0 +1,73 @@
+import type { LogLevel } from '../config.ts'
+import type { AppStore } from './app-store.ts'
+import type { Store } from './store.ts'
+
+/**
+ * The pre-nesting flat config keys. `createApp` shipped all of these at 2.1.0 (and
+ * `createDevApp` all but `ssePingMs`), so they stay ACCEPTED — typed and
+ * `@deprecated`, not removed — to keep those callers compiling and running:
+ * nesting the args would otherwise be a breaking change (a major). The removal is
+ * parked as a major-cutover (see ROADMAP surface hygiene). Nested values win when
+ * both a flat key and its nested home are present.
+ */
+export interface DeprecatedFlatConfig {
+  /** @deprecated use `persistence.session` */
+  store?: Store
+  /** @deprecated use `persistence.app` */
+  appStore?: AppStore
+  /** @deprecated use `sessions.ttlSeconds` */
+  sessionTtlSeconds?: number
+  /** @deprecated use `realtime.pingMs` */
+  ssePingMs?: number
+  /** @deprecated use `dev.inspector` */
+  inspector?: boolean
+}
+
+interface NestedReads {
+  persistence?: { session?: Store; app?: AppStore }
+  sessions?: { ttlSeconds?: number }
+  realtime?: { pingMs?: number }
+  dev?: { inspector?: boolean }
+  logging?: { level?: LogLevel }
+}
+
+/** The flat internal values `createApp`/`createDevApp` actually consume. */
+export interface ResolvedAppConfig {
+  session?: Store
+  app?: AppStore
+  sessionTtlSeconds?: number
+  ssePingMs?: number
+  inspector?: boolean
+  logLevel?: LogLevel
+}
+
+/**
+ * Resolve the nested config, falling back to the deprecated flat keys, and warn
+ * once (per app construction) if any flat key is in use. Nested wins. Exported for
+ * testing.
+ */
+export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): ResolvedAppConfig {
+  const deprecated: string[] = []
+  if (config.store !== undefined) deprecated.push('store → persistence.session')
+  if (config.appStore !== undefined) deprecated.push('appStore → persistence.app')
+  if (config.sessionTtlSeconds !== undefined)
+    deprecated.push('sessionTtlSeconds → sessions.ttlSeconds')
+  if (config.ssePingMs !== undefined) deprecated.push('ssePingMs → realtime.pingMs')
+  if (config.inspector !== undefined) deprecated.push('inspector → dev.inspector')
+
+  if (deprecated.length > 0) {
+    console.warn(
+      'stator: these createApp/createDevApp options are deprecated and will be removed in a future major — move to the nested shape:\n' +
+        deprecated.map((d) => `  ${d}`).join('\n'),
+    )
+  }
+
+  return {
+    session: config.persistence?.session ?? config.store,
+    app: config.persistence?.app ?? config.appStore,
+    sessionTtlSeconds: config.sessions?.ttlSeconds ?? config.sessionTtlSeconds,
+    ssePingMs: config.realtime?.pingMs ?? config.ssePingMs,
+    inspector: config.dev?.inspector ?? config.inspector,
+    logLevel: config.logging?.level,
+  }
+}

package/src/server/create-app.ts

@@ -1,39 +1,60 @@
 import { resolve } from 'node:path'
 import { serve } from '@hono/node-server'
+import type { LogLevel } from '../config.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { dispatchToApp } from './app-dispatch.ts'
 import type { AppStore } from './app-store.ts'
-import { installGracefulShutdown } from './banner.ts'
+import { installGracefulShutdown, printStartupNotice } from './banner.ts'
+import { type DeprecatedFlatConfig, resolveAppConfig } from './config-compat.ts'
 import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
 import { buildHonoApp } from './http.ts'
-import { logger } from './logger.ts'
+import { logger, setLogLevel } from './logger.ts'
 import { MachineStore } from './machine-store.ts'
 import { discoverRoutes } from './route-discovery.ts'
 import { InMemoryStore, type Store } from './store.ts'
 
-export interface CreateAppConfig {
+export interface CreateAppConfig extends DeprecatedFlatConfig {
   machinesDir: string
   routesDir: string
   staticDir?: string
-  /** Persistence adapter for session-lifecycle machine state. Defaults to
-   *  InMemoryStore — fine for dev, V1 adapters swap in here. */
-  store?: Store
-  /** Persistence for `persist: true` app-lifecycle machines (no TTL, one
-   *  blob per machine). Defaults to in-memory (restart-wipe); pass
-   *  RedisAppStore for durable app state. */
-  appStore?: AppStore
-  /** Per-session TTL in seconds. Every set to any of the session's
-   *  machines refreshes this expiry. Defaults to 24h (86400). */
-  sessionTtlSeconds?: number
-  /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
-  ssePingMs?: number
+  /** Swappable persistence adapters, grouped by concern. Both optional —
+   *  default to in-memory (restart-wipe). Mirrors `StatorConfig.persistence`. */
+  persistence?: {
+    /** Session-lifecycle machine state. Defaults to InMemoryStore — fine for
+     *  dev, V1 adapters swap in here. */
+    session?: Store
+    /** App-lifecycle machine state for `persist: true` machines (no TTL, one
+     *  blob per machine). Defaults to in-memory (restart-wipe); pass
+     *  RedisAppStore for durable app state. */
+    app?: AppStore
+  }
+  /** Session policy. */
+  sessions?: {
+    /** Per-session TTL in seconds. Every set to any of the session's machines
+     *  refreshes this expiry. Defaults to 24h (86400). */
+    ttlSeconds?: number
+  }
+  /** Realtime / push policy. */
+  realtime?: {
+    /** SSE heartbeat interval in ms (default 25s). Tests shorten it. */
+    pingMs?: number
+  }
+  /** Dev-only tooling. */
+  dev?: {
+    /** Serve + inject the wire inspector toolbar (the dev server's on by
+     *  default; production opts in — demo sites want the wire visible). */
+    inspector?: boolean
+  }
+  /** Logging policy. */
+  logging?: {
+    /** Minimum level to emit. Default: `warn` in production, `info` in dev.
+     *  `LOG_LEVEL` env takes precedence over this. */
+    level?: LogLevel
+  }
   /** Extra `<head>` HTML per GET route. A production build uses this to link the
    *  prebuilt `components.css`; ignored if omitted. */
   headExtras?: (filePath: string) => string | Promise<string>
-  /** Serve + inject the wire inspector toolbar (the dev server's on by
-   *  default; production opts in — demo sites want the wire visible). */
-  inspector?: boolean
 }
 
 export interface StatorApp {
@@ -57,11 +78,16 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   const routesDir = resolve(config.routesDir)
   const staticDir = config.staticDir ? resolve(config.staticDir) : undefined
 
+  const resolved = resolveAppConfig(config)
+  // Level precedence: LOG_LEVEL env > config > the production default (createApp
+  // is the production entry point, so it defaults quiet). setLogLevel also covers
+  // the scoped children (http/sse/…), which a bare `logger.level =` would miss.
+  setLogLevel(process.env.LOG_LEVEL ?? resolved.logLevel ?? 'warn')
   const { defs } = await discoverMachines(machinesDir)
-  const persistence = config.store ?? new InMemoryStore()
-  const store = new MachineStore(defs, persistence, {
-    sessionTtlSeconds: config.sessionTtlSeconds,
-    appStore: config.appStore,
+  const sessionStore = resolved.session ?? new InMemoryStore()
+  const store = new MachineStore(defs, sessionStore, {
+    sessionTtlSeconds: resolved.sessionTtlSeconds,
+    appStore: resolved.app,
   })
   // Wire the effect scheduler BEFORE booting: a fresh app machine fires its
   // initial-state entry effect during boot, and that must have somewhere to go.
@@ -69,25 +95,27 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   await store.bootAppMachines()
 
   const routes = await discoverRoutes(routesDir)
+  const inspector = resolved.inspector
   const app = await buildHonoApp({
     routes,
     store,
     staticDir,
-    headExtras: config.inspector
+    headExtras: inspector
       ? async (filePath) => {
           const base = (await config.headExtras?.(filePath)) ?? ''
           return `${base}\n<script src="/@stator/inspector.js" defer></script>`
         }
       : config.headExtras,
-    inspector: config.inspector,
-    ssePingMs: config.ssePingMs,
+    inspector,
+    ssePingMs: resolved.ssePingMs,
   })
 
   return {
     listen(port: number): Promise<void> {
       return new Promise((resolveFn) => {
         const server = serve({ fetch: app.fetch, port }, () => {
-          logger.info({ port, machines: defs.length, routes: routes.length }, 'listening')
+          // Always-on (level-independent) so `warn` prod still confirms boot.
+          printStartupNotice({ port, machines: defs.length, routes: routes.length })
           resolveFn()
         })
         // Production is strict about its port (a collision is a deploy

package/src/server/dev.ts

@@ -6,11 +6,13 @@ import { getRequestListener } from '@hono/node-server'
 import type { Hono } from 'hono'
 import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
+import type { LogLevel } from '../config.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
-import { logger } from './logger.ts'
+import { resolveAppConfig } from './config-compat.ts'
+import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { isStatorQueryRoute } from './routing.ts'
@@ -39,11 +41,39 @@ export interface DevAppConfig {
   machinesDir: string
   routesDir: string
   staticDir?: string
+  /** Swappable persistence adapters, grouped by concern. Both optional —
+   *  default to in-memory. Mirrors `StatorConfig.persistence`. */
+  persistence?: {
+    /** Session-lifecycle machine state. Defaults to InMemoryStore. */
+    session?: Store
+    /** App-lifecycle machine state for `persist: true` machines. Defaults to
+     *  in-memory. */
+    app?: AppStore
+  }
+  /** Session policy. */
+  sessions?: {
+    /** Per-session TTL in seconds. Defaults to 24h (86400). */
+    ttlSeconds?: number
+  }
+  /** Dev-only tooling. */
+  dev?: {
+    /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
+    inspector?: boolean
+  }
+  /** Logging policy. */
+  logging?: {
+    /** Minimum level to emit. Default: `info` in dev. `LOG_LEVEL` env wins. */
+    level?: LogLevel
+  }
+  // Deprecated flat keys — accepted (typed) so 2.1.0 callers don't break; nested
+  // wins. `createDevApp` never shipped `ssePingMs`, so it's not accepted here.
+  /** @deprecated use `persistence.session` */
   store?: Store
-  /** Persistence for `persist: true` app machines. Defaults to in-memory. */
+  /** @deprecated use `persistence.app` */
   appStore?: AppStore
+  /** @deprecated use `sessions.ttlSeconds` */
   sessionTtlSeconds?: number
-  /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
+  /** @deprecated use `dev.inspector` */
   inspector?: boolean
 }
 
@@ -92,7 +122,14 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   const root = resolve(config.root)
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
-  const inspectorOn = config.inspector ?? true
+  const resolved = resolveAppConfig(config)
+  // Level precedence: LOG_LEVEL env > config > dev default (info). Apply to this
+  // module's logger AND the Vite-loaded runtime instance — SSE/http/effects log
+  // through the latter — via setLogLevel, which also covers the scoped children.
+  const logLevel = process.env.LOG_LEVEL ?? resolved.logLevel ?? 'info'
+  setLogLevel(logLevel)
+  runtime.setLogLevel(logLevel)
+  const inspectorOn = resolved.inspector ?? true
 
   const resultCache = new Map<string, ReturnType<typeof compile>>()
   const compiledFor = async (file: string) => {
@@ -144,9 +181,9 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   const rebuildStore = async (): Promise<void> => {
     const { defs } = await runtime.discoverMachines(machinesDir, loader)
     machineCount = defs.length
-    store = new runtime.MachineStore(defs, config.store ?? new runtime.InMemoryStore(), {
-      sessionTtlSeconds: config.sessionTtlSeconds,
-      appStore: config.appStore,
+    store = new runtime.MachineStore(defs, resolved.session ?? new runtime.InMemoryStore(), {
+      sessionTtlSeconds: resolved.sessionTtlSeconds,
+      appStore: resolved.app,
     })
     // Wire the effect scheduler before booting — a fresh app machine's
     // initial-state entry effect fires during boot and needs a live scheduler.

package/src/server/http.ts

@@ -137,7 +137,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     const ms = Math.round(performance.now() - start)
     const status = c.res.status
     const isLive = c.req.path === '/__sse'
-    httpLog[status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info'](
+    // Successful requests log at debug (one line per asset is prod noise); 4xx
+    // warns and 5xx errors stay visible at the default level.
+    httpLog[status >= 500 ? 'error' : status >= 400 ? 'warn' : 'debug'](
       {
         method: c.req.method,
         path: c.req.path,

package/src/server/index.ts

@@ -47,7 +47,7 @@ export type { HttpConfig } from './http.ts'
 export { buildHonoApp } from './http.ts'
 export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
-export { logger, scopedLogger } from './logger.ts'
+export { logger, scopedLogger, setLogLevel } from './logger.ts'
 export { MachineStore } from './machine-store.ts'
 export { runQueryRoute } from './query-route.ts'
 export { recompute } from './recompute.ts'

package/src/server/logger.ts

@@ -3,8 +3,10 @@ import pino, { type Logger } from 'pino'
 
 /**
  * Framework logger. Pretty colored output in dev (auto-detected via
- * NODE_ENV), JSON in production for log aggregators. Level controlled by
- * LOG_LEVEL env (default 'info').
+ * NODE_ENV), JSON in production for log aggregators. Level defaults to `warn`
+ * in production (quiet — errors and warnings only) and `info` in dev; the
+ * `LOG_LEVEL` env overrides both, and `stator.config.ts`'s `logging.level`
+ * overrides the default when `LOG_LEVEL` is unset (applied at app construction).
  *
  * Application code can use this module-level logger or call `child()` for
  * scoped context. The framework uses scoped children for SSE events,
@@ -23,8 +25,8 @@ function hasPinoPretty(): boolean {
 }
 
 function buildLogger(): Logger {
-  const level = process.env.LOG_LEVEL ?? 'info'
   const isProd = process.env.NODE_ENV === 'production'
+  const level = process.env.LOG_LEVEL ?? (isProd ? 'warn' : 'info')
 
   if (isProd || !hasPinoPretty()) {
     return pino({ level })
@@ -46,7 +48,25 @@ function buildLogger(): Logger {
 
 export const logger: Logger = buildLogger()
 
+// Pino children capture the parent level at CREATION and do not follow later
+// changes to it. The framework's scoped loggers (http, sse, effect, …) are all
+// created at module load, so `logger.level = …` alone would never quiet them.
+// Track them and set the level on each explicitly in `setLogLevel`.
+const scopedChildren: Logger[] = []
+
 /** Child logger with a `scope` tag for filtering. */
 export function scopedLogger(scope: string): Logger {
-  return logger.child({ scope })
+  const child = logger.child({ scope })
+  scopedChildren.push(child)
+  return child
+}
+
+/**
+ * Set the level on the root logger AND every scoped child. Children created
+ * after this call inherit the new root level, so this is complete regardless of
+ * import order. Called once at app construction from the resolved config.
+ */
+export function setLogLevel(level: string): void {
+  logger.level = level
+  for (const child of scopedChildren) child.level = level
 }

package/src/server/sse.ts

@@ -45,7 +45,7 @@ export function registerConnection(init: Omit<Connection, 'id' | 'closed'>): Con
   const id = `sse${nextId++}`
   const conn: Connection = { ...init, id, closed: false }
   connections.set(id, conn)
-  sseLog.info(
+  sseLog.debug(
     { id, sid: conn.sessionId, route: conn.routeKey, total: connections.size },
     'connection opened',
   )
@@ -58,7 +58,7 @@ export function unregisterConnection(id: string): void {
   conn.closed = true
   conn.runtime.dispose()
   connections.delete(id)
-  sseLog.info(
+  sseLog.debug(
     { id, sid: conn.sessionId, route: conn.routeKey, total: connections.size },
     'connection closed',
   )
@@ -158,9 +158,9 @@ export async function fanOut(
     }
   }
 
-  // Log every fan-out at info so the user can see touched-machines flow and
-  // correlate against client-side inspector entries.
-  sseLog.info(
+  // Log every fan-out at debug so the user can see touched-machines flow and
+  // correlate against client-side inspector entries — noisy for prod, so debug.
+  sseLog.debug(
     {
       touched: [...touched],
       total: connections.size,