@statorjs/stator 2.0.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.0.2",
+  "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.0.2"
+    "@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/compiler/client-emit.ts

@@ -1,6 +1,7 @@
 import ts from 'typescript'
 import { elementMarkerSelector } from '../wire/island-markers.ts'
 import type { ClientDirective, ClientElement } from './client-script.ts'
+import { CLIENT_AUTHOR_GLOBALS, CLIENT_LOWERING_TARGETS, importLine } from './emit-names.ts'
 
 /**
  * Phase 3b stage 5 — emit the client entry module for a client component: the
@@ -13,8 +14,10 @@ import type { ClientDirective, ClientElement } from './client-script.ts'
  * class as written; the subclass overrides `setup()`.
  */
 
-const PRIMITIVES =
-  "import { StatorElement, defineElement, use, machine, bind, bindSlot, effect, dispatch, attrValue, setAttr } from '@statorjs/stator/client'"
+const PRIMITIVES = importLine(
+  [...CLIENT_AUTHOR_GLOBALS, ...CLIENT_LOWERING_TARGETS],
+  '@statorjs/stator/client',
+)
 
 export interface EmitClientInput {
   /** The author's `<script>` source. */

package/src/compiler/compile.ts

@@ -8,6 +8,12 @@ import {
   pascalToKebab,
 } from './client-script.ts'
 import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
+import {
+  ISLAND_SHELL_EXTRAS,
+  importLine,
+  TEMPLATE_AUTHOR_GLOBALS,
+  TEMPLATE_LOWERING_TARGETS,
+} from './emit-names.ts'
 import { scopeHash } from './hash.ts'
 import { type LowerMeta, lowerTemplate } from './lower.ts'
 import { splitStator } from './split.ts'
@@ -47,8 +53,19 @@ export interface CompileResult {
   clientTag?: string
 }
 
-const PRIMITIVES_IMPORT =
-  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList, spreadAttrs } from '@statorjs/stator/template'"
+const PRIMITIVES_IMPORT = importLine(
+  [...TEMPLATE_AUTHOR_GLOBALS, ...TEMPLATE_LOWERING_TARGETS],
+  '@statorjs/stator/template',
+)
+
+const SHELL_PRIMITIVES_IMPORT = importLine(
+  [
+    ...TEMPLATE_AUTHOR_GLOBALS,
+    ...TEMPLATE_LOWERING_TARGETS.filter((n) => n !== 'itemBind'),
+    ...ISLAND_SHELL_EXTRAS,
+  ],
+  '@statorjs/stator/template',
+)
 
 export interface CompileOptions {
   /** Stable id for the component (file path). Used for the scope hash so the
@@ -81,24 +98,17 @@ export function compile(source: string, opts: CompileOptions = {}): CompileResul
   const script = scripts.join('\n')
   if (script.trim()) {
     if (analyzeScriptClasses(script).length > 0) {
-      // An island's shell renders from props — there is no frontmatter
-      // execution on this path, and silently discarding the fence produced
-      // either a dangling-identifier crash at render or dead code that
-      // looked alive. Surface it instead.
-      if (frontmatter.trim()) {
-        throw new CompileError(
-          `stator: an island file (a template with a StatorElement <script>) can't have ` +
-            `frontmatter — the fence would never run: the island's shell renders from props. ` +
-            `Move the server work into the route or component that renders this island and ` +
-            `pass the results as props.`,
-          locAt(source, 0, opts.id),
-        )
-      }
+      // The island's SERVER FENCE (2.1): runs per shell render, on the
+      // server only, with its bindings in template scope. The <script>
+      // never sees it, in either direction.
+      const fm = processFrontmatter(frontmatter, 'island', source, opts.id)
       return compileClient(template, script, {
         hash,
         scopeAttr,
         styles,
         file: opts.id,
+        fm,
+        source,
       })
     }
     throw new CompileError(
@@ -152,7 +162,16 @@ export function compile(source: string, opts: CompileOptions = {}): CompileResul
 function compileClient(
   template: string,
   script: string,
-  ctx: { hash: string; scopeAttr?: string; styles: string[]; file?: string },
+  ctx: {
+    hash: string
+    scopeAttr?: string
+    styles: string[]
+    file?: string
+    /** The island's processed server fence (2.1) — empty parts when absent. */
+    fm?: FrontmatterParts
+    /** Original source, for located collision diagnostics. */
+    source?: string
+  },
 ): CompileResult {
   const classes = analyzeScriptClasses(script)
   const root = extractClientRoot(template, ctx.file)
@@ -162,6 +181,22 @@ function compileClient(
   analyzeClient(script, tags, { file: ctx.file })
 
   const cls = classes.find((c) => pascalToKebab(c.name) === root.tag)
+
+  // A fence binding sharing a name with a `use()` field is ambiguous by
+  // construction (client wiring keys template identifiers on the use-field
+  // set) — a located error, not a precedence rule.
+  if (ctx.fm && cls) {
+    const fenceNames = fenceBindingNames(ctx.fm)
+    for (const field of cls.useFields.keys()) {
+      if (fenceNames.has(field)) {
+        throw new CompileError(
+          `stator: "${field}" is both a fence binding and a use() field — the template ` +
+            `couldn't tell the server value from the client machine. Rename one.`,
+          ctx.source ? locAt(ctx.source, 0, ctx.file) : undefined,
+        )
+      }
+    }
+  }
   if (!cls) {
     // analyzeClient validated the tag↔class match just above; reaching here is a bug.
     throw new CompileError(
@@ -199,9 +234,13 @@ function compileClient(
   const attrDecl = `{ ${[...cls.staticAttrs].map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`
   const rootScope = ctx.scopeAttr ? ` data-s-${ctx.hash}` : ''
   const serverCode = [
-    "import { html, read, each, when, match, defer, on, classList, styleList, spreadAttrs, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    SHELL_PRIMITIVES_IMPORT,
+    ...(ctx.fm?.hoisted ? [ctx.fm.hoisted] : []),
     '',
     `export default function (props = {}) {`,
+    // The fence body runs here — per shell render, server only, ahead of
+    // the template so its bindings are in scope for the interpolations.
+    ...(ctx.fm?.body ? [ctx.fm.body] : []),
     `  const __inner = ${innerExpr}`,
     `  const __attrs = clientShellAttrs(props, ${attrDecl}, ${JSON.stringify(root.rootAttrs)})`,
     `  return createHtmlFragment(\`<${root.tag}\${__attrs}${rootScope}>\` + __inner.html + \`</${root.tag}>\`)`,
@@ -324,7 +363,7 @@ const VALID_PRAGMAS = new Set(['live'])
  */
 function processFrontmatter(
   fm: string,
-  kind: 'route' | 'component',
+  kind: 'route' | 'component' | 'island',
   source: string,
   file?: string,
 ): FrontmatterParts {
@@ -355,6 +394,14 @@ function processFrontmatter(
     const repls: Array<[start: number, end: number, replacement: string]> = []
     const visit = (n: ts.Node): void => {
       if (ts.isCallExpression(n) && isStatorCall(n, 'props')) {
+        if (kind === 'island') {
+          throw new CompileError(
+            "stator: Stator.props() is not available in an island's fence — island props are " +
+              'declared by `static attrs` on the element class, and richer values arrive ' +
+              'through the hydrate pattern (the shell renders with the props of its use site).',
+            locInFm(n),
+          )
+        }
         if (kind === 'route') {
           throw new CompileError(
             'stator: Stator.props() is not available in a route page (a route has no parent props). ' +
@@ -387,6 +434,12 @@ function processFrontmatter(
         return
       }
       if (ts.isCallExpression(n) && isStatorCall(n, 'forwarded')) {
+        if (kind === 'island') {
+          throw new CompileError(
+            "stator: Stator.forwarded() is not available in an island's fence.",
+            locInFm(n),
+          )
+        }
         if (kind === 'route') {
           throw new CompileError(
             'stator: Stator.forwarded() is only available in a component — it reads a directive ' +
@@ -435,6 +488,41 @@ function processFrontmatter(
   }
 }
 
+/** Top-level names a fence declares — imports (default/named/namespace),
+ *  consts/lets, functions, classes — for the fence-vs-use()-field collision
+ *  check. Parsed from the processed parts (hoisted + body). */
+function fenceBindingNames(fm: FrontmatterParts): Set<string> {
+  const names = new Set<string>()
+  const sf = ts.createSourceFile(
+    'fence.ts',
+    `${fm.hoisted}\n${fm.body}`,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  )
+  const bind = (n: ts.BindingName): void => {
+    if (ts.isIdentifier(n)) names.add(n.text)
+    else for (const el of n.elements) if (ts.isBindingElement(el)) bind(el.name)
+  }
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+      const c = stmt.importClause
+      if (c.name) names.add(c.name.text)
+      if (c.namedBindings) {
+        if (ts.isNamespaceImport(c.namedBindings)) names.add(c.namedBindings.name.text)
+        else for (const s of c.namedBindings.elements) names.add(s.name.text)
+      }
+    } else if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) bind(d.name)
+    } else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      names.add(stmt.name.text)
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      names.add(stmt.name.text)
+    }
+  }
+  return names
+}
+
 function emitComponent(fm: FrontmatterParts, htmlExpr: string, meta: LowerMeta): string {
   let param = ''
   if (fm.propsType && meta.usesChildren) param = `props: ${fm.propsType} & { children?: any }`
@@ -469,7 +557,7 @@ function emitRoute(fm: FrontmatterParts, htmlExpr: string, _meta: LowerMeta): st
 /** Parse `// @stator <flag>` comment pragmas from the frontmatter text. */
 function parsePragmas(
   fm: string,
-  kind: 'route' | 'component',
+  kind: 'route' | 'component' | 'island',
   source: string,
   file?: string,
 ): Set<string> {
@@ -494,7 +582,11 @@ function parsePragmas(
   return out
 }
 
-function requireRoute(what: string, kind: 'route' | 'component', loc: DiagnosticLocation): void {
+function requireRoute(
+  what: string,
+  kind: 'route' | 'component' | 'island',
+  loc: DiagnosticLocation,
+): void {
   if (kind !== 'route') {
     throw new CompileError(
       `stator: ${what} is only available in a route page, not a component. ` +

package/src/compiler/emit-names.ts

@@ -0,0 +1,48 @@
+/** The names the compiler auto-injects into emitted modules — single source
+ *  of truth for the emitters (compile.ts, client-emit.ts) AND the language
+ *  server (virtual-code.ts), which must inject the same globals in-editor: a
+ *  name injected in one place but not the other hides a missing-import bug,
+ *  and a name injected that authors also legitimately import collides with
+ *  their import (`raw` is NOT a global — authors import it — which is why it
+ *  appears in no list here).
+ *
+ *  Author globals are names template/script authors may write directly;
+ *  lowering targets are names only the compiler's output references. */
+
+/** Template names authors write: control flow + display + directive values. */
+export const TEMPLATE_AUTHOR_GLOBALS = [
+  'read',
+  'each',
+  'when',
+  'match',
+  'defer',
+  'on',
+  'classList',
+  'styleList',
+] as const
+
+/** Template names only lowered code references. `itemBind` needs server
+ *  render state, so it is a SERVER-module target only — client-island shells
+ *  never emit it (see lower.ts, keyed-row lowering). */
+export const TEMPLATE_LOWERING_TARGETS = ['html', 'itemBind', 'spreadAttrs'] as const
+
+/** Extra lowering targets for a client island's server SHELL module. */
+export const ISLAND_SHELL_EXTRAS = ['createHtmlFragment', 'clientShellAttrs'] as const
+
+/** Client-module names island authors write in a `<script>`. */
+export const CLIENT_AUTHOR_GLOBALS = [
+  'StatorElement',
+  'use',
+  'machine',
+  'defineElement',
+  'bind',
+  'effect',
+  'dispatch',
+] as const
+
+/** Client-module names only lowered code references. */
+export const CLIENT_LOWERING_TARGETS = ['bindSlot', 'attrValue', 'setAttr'] as const
+
+export function importLine(names: readonly string[], from: string): string {
+  return `import { ${names.join(', ')} } from '${from}'`
+}

package/src/compiler/virtual-code.ts

@@ -21,6 +21,7 @@
 import ts from 'typescript'
 import { analyzeScriptClasses } from './client-script.ts'
 import { statorPropsType } from './dts.ts'
+import { CLIENT_AUTHOR_GLOBALS, TEMPLATE_AUTHOR_GLOBALS } from './emit-names.ts'
 import { type ScannedRegions, scanRegions } from './split.ts'
 
 /** A contiguous run mapping generated code back to source, 1:1 over its length. */
@@ -44,21 +45,11 @@ export interface VirtualCodeResult {
   styles: VirtualFile[]
 }
 
-// Must mirror the RUNTIME's auto-injected globals exactly (compile.ts
-// PRIMITIVES_IMPORT / client-emit.ts): a name injected here but not at
-// runtime hides a missing-import bug; a name in both collides with the
-// author's legitimate import (`raw` is NOT a runtime global — authors
-// import it — which is why it must not be in this list).
-const TEMPLATE_GLOBALS = ['read', 'each', 'when', 'match', 'defer', 'on', 'classList', 'styleList']
-const CLIENT_GLOBALS = [
-  'StatorElement',
-  'use',
-  'machine',
-  'defineElement',
-  'bind',
-  'effect',
-  'dispatch',
-]
+// The editor injects the AUTHOR-visible subsets only — lowering targets are
+// names authors never write, so injecting them here would shadow nothing and
+// pollute completions. Shared with the emitters via emit-names.ts.
+const TEMPLATE_GLOBALS = TEMPLATE_AUTHOR_GLOBALS
+const CLIENT_GLOBALS = CLIENT_AUTHOR_GLOBALS
 
 /** Local names the user's code already binds from `modulePath` imports —
  *  the runtime strips such habit-imports; the virtual emit (which must keep
@@ -79,7 +70,7 @@ function userImportedLocals(code: string, modulePath: string): Set<string> {
   return locals
 }
 
-function injectImports(globals: string[], modulePath: string, userCode: string): string {
+function injectImports(globals: readonly string[], modulePath: string, userCode: string): string {
   const bound = userImportedLocals(userCode, modulePath)
   const missing = globals.filter((g) => !bound.has(g))
   return missing.length > 0 ? `import { ${missing.join(', ')} } from '${modulePath}';\n` : ''
@@ -367,6 +358,28 @@ function buildClientTsx(regions: ScannedRegions): VirtualFile {
     AMBIENT_TYPE_IMPORTS +
     STATOR_AMBIENT
 
+  // The island's SERVER FENCE (2.1): typed here so the editor checks it, but
+  // wrapped so its bindings don't leak into the <script>'s scope (at runtime
+  // the two never meet). Hoisted imports that also appear verbatim in the
+  // script are skipped — same module, one binding.
+  const fm = regions.frontmatter?.content ?? ''
+  if (fm.trim()) {
+    const fmOffset = regions.frontmatter?.contentOffset ?? 0
+    const { hoisted, body } = splitFrontmatter(fm, fmOffset)
+    for (const seg of hoisted) {
+      if (userScript.includes(seg.text.trim())) continue
+      push(mappings, seg.sourceOffset, code.length, seg.text.length)
+      code += `${seg.text}\n`
+    }
+    code += 'function __statorFence(props: Record<string, unknown>) {\n'
+    for (const seg of body) {
+      code += '  '
+      push(mappings, seg.sourceOffset, code.length, seg.text.length)
+      code += `${seg.text}\n`
+    }
+    code += '}\nvoid __statorFence\n'
+  }
+
   for (const script of regions.scripts) {
     push(mappings, script.contentOffset, code.length, script.content.length)
     code += `${script.content}\n`

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,