@statorjs/stator 2.11.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.11.0",
+  "version": "2.12.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, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,10 @@
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"
     },
+    "./server/runtime": {
+      "types": "./src/server/runtime.ts",
+      "default": "./src/server/runtime.ts"
+    },
     "./machine": {
       "types": "./src/engine/index.ts",
       "default": "./src/engine/index.ts"
@@ -101,7 +105,7 @@
     "pino-pretty": "^13.2.0",
     "vite": "^6.4.5",
     "vitest": "^3.2.7",
-    "@statorjs/stator": "2.11.0"
+    "@statorjs/stator": "2.12.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -109,6 +113,6 @@
     "test:watch": "vitest",
     "test:browser": "node browser-tests/tables.mjs",
     "build:client": "esbuild src/client/runtime.ts --bundle --format=iife --target=es2020 --outfile=dist/client.js",
-    "build:components": "node scripts/compile-components.mjs && biome check --write src/components/"
+    "build:components": "node src/cli/stator.js build:lib src/components && biome check --write src/components/"
   }
 }

package/src/build/compile-component.ts

@@ -12,8 +12,7 @@ export interface CompileComponentResult {
 }
 
 /** Compile one `.stator` file to its sibling `.ts` (+ a sibling `.css` when
- *  it has scoped styles). Used by both `build.ts` and
- *  `scripts/compile-components.ts`. */
+ *  it has scoped styles). Used by both `build.ts` and `compileLibrary`. */
 export async function compileComponentFile(
   file: string,
   baseDir: string,

package/src/build/compile-library.ts

@@ -0,0 +1,91 @@
+import { readFile, stat, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { compileComponentFile } from './compile-component.ts'
+import { walkFiles } from './islands.ts'
+import { entryCss } from './route-css.ts'
+
+export interface CompileLibraryOptions {
+  /** Package root. Compiled ids (scope hashes, diagnostics) are relative to it. */
+  root: string
+  /** Directory holding the `.stator` sources; walked recursively. */
+  dir: string
+  /** The barrel the published stylesheet is aggregated for. Defaults to
+   *  `<dir>/index.ts` when it exists; with no barrel every component's CSS is
+   *  included. */
+  entry?: string
+  /** Where the aggregated stylesheet is written. Default `<dir>/components.css`. */
+  cssOut?: string
+}
+
+export interface CompileLibraryResult {
+  compiled: number
+  islands: number
+  cssOut: string
+  cssBytes: number
+  /** The barrel the stylesheet was aggregated from; undefined when every
+   *  component's CSS was included. */
+  entry?: string
+}
+
+/**
+ * Compile a component library for publishing. Every `.stator` under `dir`
+ * becomes its sibling `.stator.ts` (+ `.css` when styled), `.stator` imports
+ * between them are rewritten to the compiled siblings, and one stylesheet is
+ * aggregated for the package's `./components.css` export — the same walk a
+ * route's CSS uses, rooted at the barrel, so the published file holds exactly
+ * what the barrel reaches.
+ */
+export async function compileLibrary(opts: CompileLibraryOptions): Promise<CompileLibraryResult> {
+  const root = resolve(opts.root)
+  const dir = resolve(opts.dir)
+  const files = (
+    await walkFiles(
+      dir,
+      (f) => f.endsWith('.stator'),
+      (name) => name === 'node_modules' || name === 'dist' || name.startsWith('.'),
+    )
+  ).sort()
+
+  let islands = 0
+  const compiled: string[] = []
+  for (const file of files) {
+    const r = await compileComponentFile(file, root)
+    if (r.isClient) islands++
+    compiled.push(`${file}.ts`)
+    if (r.clientFile) compiled.push(r.clientFile)
+  }
+
+  // A component importing a sibling `.stator` must import the compiled module
+  // in the published package. Bare specifiers stay as written: a package's
+  // exports map resolves them.
+  for (const file of compiled) {
+    const code = await readFile(file, 'utf8')
+    const rewritten = code.replace(/(['"])(\.\.?\/[^'"]+\.stator)\1/g, '$1$2.ts$1')
+    if (rewritten !== code) await writeFile(file, rewritten)
+  }
+
+  const entry = opts.entry ? resolve(opts.entry) : await existing(join(dir, 'index.ts'))
+  const cssOut = opts.cssOut ? resolve(opts.cssOut) : join(dir, 'components.css')
+  let css = ''
+  if (entry) {
+    css = await entryCss(entry, root)
+  } else {
+    for (const file of files) {
+      const text = await readFile(`${file}.css`, 'utf8').catch(() => undefined)
+      if (text) css += `/* ${file.slice(root.length + 1).replace(/\\/g, '/')}.ts */\n${text}\n`
+    }
+  }
+  // Always written, even empty, so the `./components.css` export resolves.
+  await writeFile(cssOut, css)
+
+  return { compiled: files.length, islands, cssOut, cssBytes: css.length, entry }
+}
+
+async function existing(path: string): Promise<string | undefined> {
+  try {
+    await stat(path)
+    return path
+  } catch {
+    return undefined
+  }
+}

package/src/build/index.ts

@@ -7,6 +7,8 @@ export type { ArtifactDeps } from './artifact.ts'
 export { writeArtifactDeps } from './artifact.ts'
 export type { BuildConfig, BuildResult, StatorManifest } from './build.ts'
 export { buildApp } from './build.ts'
+export type { CompileLibraryOptions, CompileLibraryResult } from './compile-library.ts'
+export { compileLibrary } from './compile-library.ts'
 export type { CopySet, CopySetOptions, UntracedImport } from './copy-set.ts'
 export { resolveCopySet } from './copy-set.ts'
 export { loadProductionHead } from './head.ts'

package/src/build/sync.ts

@@ -32,6 +32,8 @@ export interface SyncResult {
   checks: number
   /** The generated-types directory. */
   outDir: string
+  /** Every `.stator` file the walk found, absolute. */
+  files: string[]
 }
 
 const TYPES_DIR = join('.stator', 'types')
@@ -71,7 +73,7 @@ export async function syncTypes(root: string): Promise<SyncResult> {
     await writeFile(checkTarget, virtual.tsx.code)
     checks++
   }
-  return { written, checks, outDir }
+  return { written, checks, outDir, files }
 }
 
 async function walk(dir: string): Promise<string[]> {

package/src/cli/commands/build-lib.ts

@@ -0,0 +1,24 @@
+import { relative, resolve } from 'node:path'
+import { compileLibrary } from '../../build/index.ts'
+import type { CliContext } from '../run.ts'
+
+/** Compile a component library for publishing — see `compileLibrary`. The
+ *  directory is the first positional (default `src`); its `index.ts` is the
+ *  barrel when present, and the stylesheet lands beside it. */
+export async function run(ctx: CliContext): Promise<void> {
+  const dir = resolve(ctx.root, ctx.rest[0] ?? 'src')
+  const r = await compileLibrary({ root: ctx.root, dir })
+  const rel = (p: string) => relative(ctx.root, p).replace(/\\/g, '/')
+  const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
+  process.stdout.write(
+    `stator build:lib: ${plural(r.compiled, 'component')} under ${rel(dir)}/ → ${rel(r.cssOut)}: ` +
+      (r.entry
+        ? `${r.cssBytes} bytes reached from ${rel(r.entry)}\n`
+        : `${r.cssBytes} bytes, every component (no index.ts barrel)\n`),
+  )
+  if (r.islands > 0) {
+    process.stdout.write(
+      `  note: ${plural(r.islands, 'island')} compiled, but a consuming app can't discover islands from a package yet — they stay in the app\n`,
+    )
+  }
+}

package/src/cli/commands/check.ts

@@ -1,5 +1,9 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
 import ts from 'typescript'
 import { syncTypes } from '../../build/index.ts'
+import { sourceId } from '../../build/source-id.ts'
+import { CompileError, compile, regionResolverFor } from '../../compiler/index.ts'
 import type { CliContext } from '../run.ts'
 
 /**
@@ -9,12 +13,19 @@ import type { CliContext } from '../run.ts'
  * 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
+ * Three 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.
+ * (2) every `.stator` file goes through the real compiler — the same call `dev`
+ * makes on import and the editor makes per edit, so all three reject the same
+ * inputs; (3) a `tsc --noEmit`-equivalent pass via the TypeScript API.
  */
 export async function checkStack(root: string): Promise<void> {
-  const { written } = await syncTypes(root)
+  const { written, files } = await syncTypes(root)
+
+  const compileErrors = await compileAll(root, files)
+  if (compileErrors.length > 0) {
+    process.stderr.write(`${compileErrors.join('\n\n')}\n\n`)
+  }
 
   const configPath = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json')
   if (!configPath) throw new Error(`no tsconfig.json found at or above ${root}`)
@@ -45,7 +56,9 @@ export async function checkStack(root: string): Promise<void> {
         getNewLine: () => ts.sys.newLine,
       }),
     )
-    const n = diagnostics.length
+  }
+  const n = compileErrors.length + diagnostics.length
+  if (n > 0) {
     throw new Error(`typecheck failed with ${n} error${n === 1 ? '' : 's'}`)
   }
 
@@ -67,6 +80,29 @@ export async function checkStack(root: string): Promise<void> {
   )
 }
 
+/** Compile every `.stator` file, keeping only the errors — output is
+ *  discarded. Formatted like tsc's diagnostics (`file:line:col - error`) with
+ *  the compiler's own code frame. */
+async function compileAll(root: string, files: string[]): Promise<string[]> {
+  const errors: string[] = []
+  for (const file of files) {
+    const source = await readFile(file, 'utf8')
+    const { id, kind } = sourceId(root, file)
+    try {
+      compile(source, { id, kind, resolveRegions: regionResolverFor(file, source) })
+    } catch (e) {
+      if (!(e instanceof CompileError)) throw e
+      const rel = relative(root, file).replace(/\\/g, '/')
+      errors.push(
+        e.loc
+          ? `${rel}:${e.loc.line}:${e.loc.column} - error: ${e.message}\n\n${e.loc.frame}`
+          : `${rel} - error: ${e.message}`,
+      )
+    }
+  }
+  return errors
+}
+
 export async function run(ctx: CliContext): Promise<void> {
   await checkStack(ctx.root)
 }

package/src/cli/run.ts

@@ -11,7 +11,7 @@ export interface CliContext {
   rest: string[]
 }
 
-const COMMANDS = ['dev', 'build', 'start', 'check', 'test'] as const
+const COMMANDS = ['dev', 'build', 'start', 'check', 'test', 'build:lib'] as const
 type Command = (typeof COMMANDS)[number]
 
 const HELP = `stator — the Stator toolchain CLI
@@ -24,6 +24,7 @@ Commands:
   start     Serve a built dist/ in production mode
   check     Typecheck the whole stack (server + generated .stator types), no output
   test      Run the test suite
+  build:lib [dir]  Compile a component library for publishing (default dir: src)
 
 Options:
   --root <dir>    App root (default: current directory)
@@ -66,7 +67,7 @@ const { loadDotenv } = await import('../server/env.ts')
 loadDotenv(ctx.root)
 
 // Dynamic import per command so `check` never loads the dev server's watcher, etc.
-const { run } = (await import(`./commands/${command}.ts`)) as {
+const { run } = (await import(`./commands/${command.replace(':', '-')}.ts`)) as {
   run: (ctx: CliContext) => Promise<void>
 }
 

package/src/compiler/compile.ts

@@ -7,7 +7,7 @@ import {
   isCustomElementTag,
   pascalToKebab,
 } from './client-script.ts'
-import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
+import { CompileError, type DiagnosticLocation, locAt, parseDiagnosticsOf } from './diagnostics.ts'
 import {
   ISLAND_SHELL_EXTRAS,
   importLine,
@@ -109,6 +109,7 @@ export function compile(source: string, opts: CompileOptions = {}): CompileResul
         file: opts.id,
         fm,
         source,
+        templateOffset,
       })
     }
     throw new CompileError(
@@ -171,10 +172,12 @@ function compileClient(
     fm?: FrontmatterParts
     /** Original source, for located collision diagnostics. */
     source?: string
+    /** Offset of the template body in `source`. */
+    templateOffset?: number
   },
 ): CompileResult {
   const classes = analyzeScriptClasses(script)
-  const root = extractClientRoot(template, ctx.file)
+  const root = extractClientRoot(template, ctx)
 
   // Name-match validation (both directions, hyphen rule).
   const tags = new Set([root.tag])
@@ -271,20 +274,32 @@ function compileClient(
  *  split-and-reassemble so a component can style/flag its own root; the use site
  *  merges them under its props (FINDINGS #4). Namespaced directives (class:list,
  *  on:) and expression-valued attrs are not static and are skipped here. */
+/** The island root's own attributes: static only. The shell renders the root
+ *  from the use site's props, so a dynamic value here has nothing to bind to —
+ *  rather than silently dropping it, say so. */
 function staticRootAttrs(
+  tag: string,
   attrs: ts.JsxAttributes,
   sf: ts.SourceFile,
+  at: (node: ts.Node) => DiagnosticLocation | undefined,
 ): Record<string, string | boolean> {
   const out: Record<string, string | boolean> = {}
   for (const attr of attrs.properties) {
-    if (!ts.isJsxAttribute(attr) || ts.isJsxNamespacedName(attr.name)) continue
-    const name = attr.name.getText(sf)
-    const init = attr.initializer
-    if (init === undefined) {
-      out[name] = true // valueless boolean attribute
-    } else if (ts.isStringLiteral(init)) {
-      out[name] = init.text
+    const isStatic =
+      ts.isJsxAttribute(attr) &&
+      !ts.isJsxNamespacedName(attr.name) &&
+      (attr.initializer === undefined || ts.isStringLiteral(attr.initializer))
+    if (!isStatic) {
+      throw new CompileError(
+        `stator: <${tag} ${attr.getText(sf)}> — attributes on an island's root must be static ` +
+          `(a string literal or a bare boolean). The root is rendered by the shell from the use ` +
+          `site's props; a dynamic value belongs on an inner element, or declare it with ` +
+          `\`static attrs\` and pass it from the use site.`,
+        at(attr),
+      )
     }
+    const name = attr.name.getText(sf)
+    out[name] = attr.initializer === undefined ? true : (attr.initializer as ts.StringLiteral).text
   }
   return out
 }
@@ -294,10 +309,16 @@ function staticRootAttrs(
  *  must be the custom element". */
 function extractClientRoot(
   template: string,
-  file?: string,
+  ctx: { file?: string; source?: string; templateOffset?: number },
 ): { tag: string; inner: string; rootAttrs: Record<string, string | boolean> } {
-  const wrapped = `const __t = (<>${template}</>);`
+  const { file } = ctx
+  const prefix = 'const __t = (<>'
+  const wrapped = `${prefix}${template}</>);`
   const sf = ts.createSourceFile('t.tsx', wrapped, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  const at = (node: ts.Node): DiagnosticLocation | undefined =>
+    ctx.source != null && ctx.templateOffset != null
+      ? locAt(ctx.source, ctx.templateOffset + (node.getStart(sf) - prefix.length), file)
+      : undefined
   let fragment: ts.JsxFragment | undefined
   const find = (n: ts.Node): void => {
     if (ts.isJsxFragment(n)) {
@@ -320,13 +341,13 @@ function extractClientRoot(
   if (ts.isJsxSelfClosingElement(rootEl)) {
     const tag = rootEl.tagName.getText(sf)
     requireCustomRoot(tag, file)
-    return { tag, inner: '', rootAttrs: staticRootAttrs(rootEl.attributes, sf) }
+    return { tag, inner: '', rootAttrs: staticRootAttrs(tag, rootEl.attributes, sf, at) }
   }
   const el = rootEl as ts.JsxElement
   const tag = el.openingElement.tagName.getText(sf)
   requireCustomRoot(tag, file)
   const inner = wrapped.slice(el.openingElement.getEnd(), el.closingElement.getStart())
-  return { tag, inner, rootAttrs: staticRootAttrs(el.openingElement.attributes, sf) }
+  return { tag, inner, rootAttrs: staticRootAttrs(tag, el.openingElement.attributes, sf, at) }
 }
 
 function requireCustomRoot(tag: string, file?: string): void {
@@ -379,6 +400,29 @@ function processFrontmatter(
   const locInFm = (node: ts.Node): DiagnosticLocation =>
     locAt(source, fmOffset(source) + node.getStart(sf), file)
 
+  // The fence is plain TypeScript (ScriptKind.TS): a bare `<p>` lexes as an
+  // old-style type assertion, so JSX here used to surface only as esbuild's
+  // `Expected ")" but found "return"` on the emitted module — while the
+  // editor's TSX model accepted it. Report syntax errors here, with the one
+  // targeted hint for that shape.
+  const syntax = parseDiagnosticsOf(sf)
+  if (syntax.length > 0) {
+    const jsx = findJsxLikeAssertion(sf)
+    if (jsx) {
+      throw new CompileError(
+        "stator: JSX isn't allowed in frontmatter — it's plain TypeScript. Markup belongs in " +
+          'the template (use when()/match() for conditional content); a different page for a ' +
+          'not-found case cascades to routes/404.stator.',
+        locInFm(jsx),
+      )
+    }
+    const d = syntax[0]!
+    throw new CompileError(
+      `stator: frontmatter syntax error — ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}`,
+      locAt(source, fmOffset(source) + d.start, file),
+    )
+  }
+
   for (const stmt of sf.statements) {
     if (
       ts.isImportDeclaration(stmt) ||
@@ -598,6 +642,28 @@ function requireRoute(
 
 /** Character offset of the frontmatter body in the original source (after the
  *  opening `---\n`). 4 = `---\n`; good enough for diagnostics line/col. */
+/** The node a `<p>` or `<NotFound>` becomes when parsed as TS: a type assertion
+ *  whose type is a bare identifier reference. A generic arrow (`<T>(a: T) => a`)
+ *  is not one, so it stays legal. */
+function findJsxLikeAssertion(sf: ts.SourceFile): ts.TypeAssertion | undefined {
+  let found: ts.TypeAssertion | undefined
+  const visit = (n: ts.Node): void => {
+    if (found) return
+    if (
+      ts.isTypeAssertionExpression(n) &&
+      ts.isTypeReferenceNode(n.type) &&
+      ts.isIdentifier(n.type.typeName) &&
+      !n.type.typeArguments
+    ) {
+      found = n
+      return
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(sf)
+  return found
+}
+
 function fmOffset(source: string): number {
   return source.startsWith('---') ? source.indexOf('\n') + 1 : 0
 }

package/src/compiler/diagnostics.ts

@@ -1,3 +1,5 @@
+import type ts from 'typescript'
+
 /**
  * Compiler diagnostics: a located `CompileError` plus helpers to turn a
  * character offset in the original `.stator` source into a line/column + code
@@ -58,6 +60,17 @@ export function codeFrame(source: string, line: number, column: number): string
   return out.join('\n')
 }
 
+/** TypeScript's syntactic diagnostics for a parsed file. `parseDiagnostics` is
+ *  not in the public typings, but it is what every tool reads and the only
+ *  way to get them without re-parsing; this is the one place to change if it
+ *  ever moves. */
+export function parseDiagnosticsOf(sf: ts.SourceFile): readonly ts.DiagnosticWithLocation[] {
+  const { parseDiagnostics } = sf as unknown as {
+    parseDiagnostics?: readonly ts.DiagnosticWithLocation[]
+  }
+  return parseDiagnostics ?? []
+}
+
 /** Build a `DiagnosticLocation` from a character offset in the original source. */
 export function locAt(source: string, offset: number, file?: string): DiagnosticLocation {
   const { line, column } = offsetToLineCol(source, offset)

package/src/compiler/lower.ts

@@ -319,6 +319,55 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
   }
   checkNoBindingInRcdata(fragment, null)
 
+  // Build-time gate for `child="x"` placement: the marker is read only off a
+  // DIRECT element child of a component tag. Anywhere else — inside a `{…}`
+  // expression, nested deeper, at the template root — it silently lands in the
+  // default slot, and on a component tag it is an ignored prop. Found in the
+  // wild: `{cond ? <div child="top"/> : null}` rendered inside <main> with no
+  // warning.
+  const childMarkerOf = (attrs: ts.JsxAttributes): ts.JsxAttribute | undefined =>
+    attrs.properties.find(
+      (a): a is ts.JsxAttribute =>
+        ts.isJsxAttribute(a) && !ts.isJsxNamespacedName(a.name) && a.name.getText(sf) === 'child',
+    )
+  const checkChildMarkers = (node: ts.Node, underComponent: boolean): void => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node
+      const tag = opening.tagName.getText(sf)
+      const marker = childMarkerOf(opening.attributes)
+      if (marker) {
+        const region =
+          marker.initializer && ts.isStringLiteral(marker.initializer)
+            ? marker.initializer.text
+            : 'x'
+        if (isComponentTag(tag)) {
+          throw new CompileError(
+            `stator: child="${region}" on <${tag}/> has no effect — a child="x" marker is only ` +
+              `read on a direct element child of a component tag; on a component it is an ` +
+              `ignored prop. Wrap it: <div child="${region}"><${tag}/></div>`,
+            loc(marker),
+          )
+        }
+        if (!underComponent) {
+          throw new CompileError(
+            `stator: child="${region}" has no effect here — a child="x" marker is only read on ` +
+              `a direct element child of a component tag. Move the condition inside the slotted ` +
+              `element: <div child="${region}">{cond ? … : null}</div>`,
+            loc(marker),
+          )
+        }
+      }
+      checkChildMarkers(opening.attributes, false)
+      if (ts.isJsxElement(node)) {
+        const inner = isComponentTag(tag)
+        for (const child of node.children) checkChildMarkers(child, inner)
+      }
+      return
+    }
+    ts.forEachChild(node, (child) => checkChildMarkers(child, false))
+  }
+  checkChildMarkers(fragment, false)
+
   // Build-time gate for item-read placement: a `read(<item>, …)` binding is
   // OWNED by its each() row — the row render supplies the item and collects the
   // binding, and the list's recompute is what re-diffs it. Three positions break

package/src/compiler/virtual-code.ts

@@ -21,6 +21,7 @@
 import ts from 'typescript'
 import { VOID_ELEMENTS } from '../template/void-elements.ts'
 import { analyzeScriptClasses } from './client-script.ts'
+import { parseDiagnosticsOf } from './diagnostics.ts'
 import { statorPropsType } from './dts.ts'
 import { CLIENT_AUTHOR_GLOBALS, TEMPLATE_AUTHOR_GLOBALS } from './emit-names.ts'
 import { type ScannedRegions, scanRegions } from './split.ts'
@@ -146,10 +147,7 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
     STATOR_AMBIENT
 
   const { hoisted, body } = splitFrontmatter(fm, fmOffset)
-  for (const seg of hoisted) {
-    push(mappings, seg.sourceOffset, code.length, seg.text.length)
-    code += `${seg.text}\n`
-  }
+  for (const seg of hoisted) code = emitSegment(mappings, code, seg)
 
   // A leading <!doctype> is static HTML, not JSX — drop it from the shell (no
   // intelligence lost) and advance the template mapping past it.
@@ -175,11 +173,7 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
     code += "type __SReadResult<T> = import('@statorjs/stator/template').ReadResult<T>\n"
   }
   code += `export default function (_props: ${propsT}) {\n`
-  for (const seg of body) {
-    code += '  '
-    push(mappings, seg.sourceOffset, code.length, seg.text.length)
-    code += `${seg.text}\n`
-  }
+  for (const seg of body) code = emitSegment(mappings, `${code}  `, seg)
   code += '  return (<>'
   code = appendTemplateTsx(code, mappings, tpl, tplOffset)
   code += '</>);\n}\n'
@@ -298,6 +292,16 @@ function expressionEnd(tpl: string, start: number): number {
 interface FmSegment {
   sourceOffset: number
   text: string
+  /** The statement has a syntax error in TS mode (JSX in the fence, usually).
+   *  Emitted as a string literal so the TSX model can't make it look fine —
+   *  the compiler's located error is the one the editor shows. */
+  opaque?: boolean
+}
+
+function emitSegment(mappings: VirtualMapping[], code: string, seg: FmSegment): string {
+  if (seg.opaque) return `${code}${JSON.stringify(seg.text)};\n`
+  push(mappings, seg.sourceOffset, code.length, seg.text.length)
+  return `${code}${seg.text}\n`
 }
 
 /**
@@ -315,8 +319,21 @@ function splitFrontmatter(
   const body: FmSegment[] = []
   if (!fm.trim()) return { hoisted, body }
   const sf = ts.createSourceFile('fm.ts', fm, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  // A syntax error splits what the author wrote as one statement into pieces
+  // (`return <p>not` / `found</p>`), and the piece without the diagnostic would
+  // read as valid JSX in the TSX model. Every statement sharing a line with a
+  // diagnostic is opaque.
+  const brokenLines = new Set(
+    parseDiagnosticsOf(sf).map((d) => sf.getLineAndCharacterOfPosition(d.start).line),
+  )
   for (const stmt of sf.statements) {
-    const seg: FmSegment = { sourceOffset: fmOffset + stmt.getStart(sf), text: stmt.getText(sf) }
+    const start = stmt.getStart(sf)
+    const seg: FmSegment = { sourceOffset: fmOffset + start, text: stmt.getText(sf) }
+    const first = sf.getLineAndCharacterOfPosition(start).line
+    const last = sf.getLineAndCharacterOfPosition(stmt.getEnd()).line
+    for (let line = first; line <= last; line++) {
+      if (brokenLines.has(line)) seg.opaque = true
+    }
     if (
       ts.isImportDeclaration(stmt) ||
       ts.isTypeAliasDeclaration(stmt) ||
@@ -352,15 +369,10 @@ function buildClientTsx(regions: ScannedRegions): VirtualFile {
     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 = emitSegment(mappings, code, seg)
     }
     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`
-    }
+    for (const seg of body) code = emitSegment(mappings, `${code}  `, seg)
     code += '}\nvoid __statorFence\n'
   }
 

package/src/components/components.css

@@ -1,7 +1,7 @@
-/* components/image.stator.ts */
+/* src/components/image.stator.ts */
 /* height:auto preserves the aspect ratio the width/height attributes
      declare; radius, margin, object-fit are the app's call. */
-:where(img[data-s-6e2813d6]) {
+:where(img[data-s-ff0b03fd]) {
   display: block;
   max-width: 100%;
   height: auto;

package/src/components/image.stator.css

@@ -1,6 +1,6 @@
 /* height:auto preserves the aspect ratio the width/height attributes
      declare; radius, margin, object-fit are the app's call. */
-:where(img[data-s-6e2813d6]) {
+:where(img[data-s-ff0b03fd]) {
   display: block;
   max-width: 100%;
   height: auto;

package/src/components/image.stator.ts

@@ -25,5 +25,5 @@ export default function (props: ImageProps) {
     decoding = 'async',
   } = p
   const img = getImage(p)
-  return html`<img src="${img.src}" srcset="${img.srcset ?? undefined}" sizes="${img.srcset ? sizes : undefined}" alt="${alt}" width="${img.width}" height="${img.height}" loading="${loading}" fetchpriority="${fetchpriority}" decoding="${decoding}" class="${className}" data-s-6e2813d6>`
+  return html`<img src="${img.src}" srcset="${img.srcset ?? undefined}" sizes="${img.srcset ? sizes : undefined}" alt="${alt}" width="${img.width}" height="${img.height}" loading="${loading}" fetchpriority="${fetchpriority}" decoding="${decoding}" class="${className}" data-s-ff0b03fd>`
 }

package/src/server/api-route.ts

@@ -15,7 +15,7 @@ import type {
   Directive,
   RouteRequest,
 } from './routing.ts'
-import { getOrCreateSessionId, getSessionState, rotateSessionNow, sessionUse } from './session.ts'
+import { getOrCreateSessionId, getSessionState, readClaims, rotateSessionNow } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -76,10 +76,7 @@ export async function runApiRoute(
         clearSession: () => {
           rotation = { clear: true }
         },
-        claims: <T = unknown>() => {
-          sessionUse(c).claimsRead = true
-          return getSessionState(c)?.claims as T | undefined
-        },
+        claims: <T = unknown>() => readClaims<T>(c),
         setClaims: (claims) => {
           const s = getSessionState(c)
           if (s) {

package/src/server/context.ts

@@ -1,6 +1,6 @@
 import type { Context } from 'hono'
 import { type CookieJar, cookieJar } from './cookies.ts'
-import { getOrCreateSessionId, getSessionState, rotateSessionNow, sessionUse } from './session.ts'
+import { getOrCreateSessionId, getSessionState, readClaims, rotateSessionNow } from './session.ts'
 import type { Store } from './store.ts'
 
 /**
@@ -75,11 +75,7 @@ export function stator(c: Context): StatorContext {
       return getSessionState(c)?.sid ?? ''
     },
     claims<T = unknown>(): T | undefined {
-      // A claims READ is a peek — it never establishes (an anonymous /admin
-      // probe redirects without minting state) — but it does make the
-      // response claims-dependent, so layer 3 marks it unprovable.
-      sessionUse(c).claimsRead = true
-      return getSessionState(c)?.claims as T | undefined
+      return readClaims<T>(c)
     },
     setClaims(claims: unknown): void {
       // Writing claims is an explicit session op — an establishment trigger.

package/src/server/cookies.ts

@@ -1,6 +1,7 @@
 import type { Context } from 'hono'
 import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'hono/cookie'
 import type { RouteCookieOptions } from './routing.ts'
+import { sessionUse } from './session.ts'
 
 /**
  * A focused read/write cookie surface for app-owned cookies (a login
@@ -49,7 +50,10 @@ function requireSecret(c: Context): string {
  *  the same way. */
 export function cookieJar(c: Context): CookieJar {
   return {
-    get: (name) => getCookie(c, name),
+    get: (name) => {
+      sessionUse(c).varied = true
+      return getCookie(c, name)
+    },
     set: (name, value, options) => {
       setCookie(c, name, value, options as never)
     },
@@ -57,6 +61,7 @@ export function cookieJar(c: Context): CookieJar {
       deleteCookie(c, name, options as never)
     },
     getSigned: async (name) => {
+      sessionUse(c).varied = true
       // hono returns `false` for a present-but-invalid signature; collapse it to
       // undefined so callers never trust (or even see) a tampered value.
       const value = await getSignedCookie(c, requireSecret(c), name)

package/src/server/dev-vite.ts

@@ -68,9 +68,12 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
 
   // Load the runtime through Vite so it shares an instance with the templates.
   // (Type-only: the static import type is erased, so no second instance.)
-  const runtime = (await vite.ssrLoadModule(
-    '@statorjs/stator/server',
-  )) as typeof import('./index.ts')
+  // Both subpaths through Vite's graph, so the plumbing shares module
+  // instances with the app code Vite loads.
+  const runtime = {
+    ...(await vite.ssrLoadModule('@statorjs/stator/server')),
+    ...(await vite.ssrLoadModule('@statorjs/stator/server/runtime')),
+  } as typeof import('./index.ts') & typeof import('./runtime.ts')
   const loader = (file: string) => vite.ssrLoadModule(file) as Promise<Record<string, unknown>>
 
   const root = resolve(config.root)

package/src/server/http.ts

@@ -914,8 +914,9 @@ async function renderGetCandidate(
     }
 
     // Layer 3 — derived Cache-Control: the page is PROVABLY anonymous-
-    // identical (no session reads declared, no session use or claims read
-    // during handling) and the route didn't hand-set the header. The
+    // identical (no session reads declared, no session use, claims or
+    // request inputs read during handling) and the route didn't hand-set
+    // the header. The
     // framework says what it can prove; hand-set always wins. Computed here
     // but only ever WRITTEN from `commit`, below — this render may be a
     // losing, discarded candidate under cascading, and only the winner's
@@ -927,6 +928,7 @@ async function renderGetCandidate(
       !needsSession &&
       !use.used &&
       !use.claimsRead &&
+      !use.varied &&
       result.response.status < 300 &&
       result.response.cookies.length === 0 &&
       !result.response.headers.has('cache-control')

package/src/server/index.ts

@@ -1,12 +1,11 @@
 /**
- * `/server` carries two tiers (see the docs' stability policy): the STABLE
- * app surface (createApp, defineMachine, defineApiRoute, the stores, logger,
- * dispatchToApp, rotateSession) and the TOOLCHAIN plumbing the compiler/Vite
- * module graph needs importable (recompute, renderRoute, buildHonoApp,
- * SessionRuntime, render-context internals, …). The Toolchain tier is not
- * covered by semver and is RESERVED to move to a dedicated subpath
- * (`@statorjs/stator/server/runtime`) in a 2.x minor — import it expecting
- * that move.
+ * `/server` is the STABLE app surface (see the docs' stability policy):
+ * createApp, defineMachine, the route definers, the stores, logger,
+ * dispatchToApp, middleware and security, images. The TOOLCHAIN plumbing the
+ * compiled output, dev server and build run on lives on `/server/runtime`,
+ * where the import path itself carries the tier. It is still re-exported
+ * here (the last block) so a 2.x import keeps resolving; that re-export is
+ * deprecated and goes away in the next major.
  */
 export type {
   ElementTarget,
@@ -19,7 +18,7 @@ export { dispatchToApp } from './app-dispatch.ts'
 export type { AppStore } from './app-store.ts'
 export { InMemoryAppStore } from './app-store.ts'
 export type { BootContext, BootDefinition, BootFn, BootTeardown } from './boot.ts'
-export { defineBoot, discoverBoot, isBootDefinition, runBoot } from './boot.ts'
+export { defineBoot } from './boot.ts'
 export type { CachedStoreOptions } from './cached-store.ts'
 export { CachedStore } from './cached-store.ts'
 export type { StatorContext } from './context.ts'
@@ -38,72 +37,13 @@ export type {
   SubscribeEntry,
   SubscribeEvent,
 } from './define-machine.ts'
-export { defineMachine, isStatorMachine } from './define-machine.ts'
-export type { PollLoopFinding } from './dev-lint.ts'
-export { findPollLoops } from './dev-lint.ts'
-export type { DiscoveryResult } from './discovery.ts'
-export { discoverMachines } from './discovery.ts'
-export type { DispatchContext } from './dispatch-context.ts'
-export {
-  getDispatchContext,
-  recordTouch,
-  withDispatchContext,
-} from './dispatch-context.ts'
-export { scheduleSessionEffects, wireAppEffects } from './effects.ts'
-export type { HttpConfig } from './http.ts'
-export { buildHonoApp } from './http.ts'
-export type { ImageTransformer, ResolvedImagesConfig } from './images.ts'
-export {
-  DEFAULT_IMAGE_WIDTHS,
-  probeImage,
-  resolveImagesConfig,
-  sharpTransformer,
-} from './images.ts'
-export type { InspectPayload, InspectRoute, InspectRouteMethod } from './inspect.ts'
-export { buildInspectPayload } from './inspect.ts'
-export type { InstanceHandle } from './instance-proxy.ts'
-export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
+export { defineMachine } from './define-machine.ts'
+export type { ImageTransformer } from './images.ts'
+export { probeImage, sharpTransformer } from './images.ts'
 export { logger, scopedLogger, setLogLevel } from './logger.ts'
-export { codeHashOf, codeInputsOf } from './machine-hash.ts'
-export { MachineStore } from './machine-store.ts'
 export type { MiddlewareDefinition } from './middleware.ts'
-export {
-  dangerouslyDefineMiddleware,
-  defineMiddleware,
-  discoverMiddleware,
-  isMiddlewareDefinition,
-} from './middleware.ts'
-export { runQueryRoute } from './query-route.ts'
-export { recompute } from './recompute.ts'
+export { dangerouslyDefineMiddleware, defineMiddleware } from './middleware.ts'
 export { RedisAppStore, RedisStore } from './redis-store.ts'
-export type { RenderResult } from './render.ts'
-export { renderRoute } from './render.ts'
-export type {
-  Binding,
-  BindingKind,
-  ElementId,
-  EventDescriptor,
-  MachineName,
-  RenderState,
-  SessionId,
-  SlotId,
-} from './render-context.ts'
-export {
-  allocElementId,
-  allocSlotId,
-  createEventDescriptor,
-  createRenderState,
-  getCurrentRenderState,
-  isEventDescriptor,
-  popListScope,
-  pushListScope,
-  registerBinding,
-  requireCurrentRenderState,
-  runInRender,
-  unregisterBindingsForScope,
-} from './render-context.ts'
-export type { DiscoveredRoute } from './route-discovery.ts'
-export { discoverRoutes } from './route-discovery.ts'
 export type {
   ApiRouteDefinition,
   ApiRouteEnvelope,
@@ -123,24 +63,13 @@ export type {
   RouteRequest,
   RouteResponseContext,
 } from './routing.ts'
-export {
-  defineApiRoute,
-  defineRoute,
-  isStatorApiRoute,
-  isStatorQueryRoute,
-  isStatorRoute,
-} from './routing.ts'
+export { defineApiRoute, defineRoute } from './routing.ts'
+/** @deprecated Import from `@statorjs/stator/server/runtime`. This re-export
+ *  of the Toolchain tier is removed in the next major. */
+export * from './runtime.ts'
 export type { SecurityHeadersOptions } from './security-headers.ts'
 export { securityHeaders } from './security-headers.ts'
-export { getOrCreateSessionId, SESSION_COOKIE, setSessionSameSite } from './session.ts'
-export { SessionRuntime } from './session-runtime.ts'
-export type { Connection } from './sse.ts'
-export {
-  activeConnectionCount,
-  fanOut,
-  registerConnection,
-  unregisterConnection,
-} from './sse.ts'
+export { activeConnectionCount } from './sse.ts'
 export type { Store } from './store.ts'
 export { InMemoryStore } from './store.ts'
 export type { StoreFromEnvOptions } from './store-intent.ts'

package/src/server/query-route.ts

@@ -28,6 +28,7 @@ const DATA_CONTENT_TYPES: Record<string, string> = {
   '.txt': 'text/plain; charset=utf-8',
   '.ics': 'text/calendar; charset=utf-8',
   '.csv': 'text/csv; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
 }
 
 /** Second-level file extensions (`feed.xml.ts`) that mark a route file as
@@ -141,8 +142,8 @@ export async function runQueryRoute(
 }
 
 /** Layer 3 — derived Cache-Control, same proof as pages: no session reads
- *  declared, no session use/claims read while handling, handler set nothing
- *  itself. Applied to 200 and 304 alike (a 304's headers update the cached
+ *  declared, no session use, claims or request inputs read while handling,
+ *  handler set nothing itself. Applied to 200 and 304 alike (a 304's headers update the cached
  *  entry's lifetime). */
 function applyDerivedCaching(
   c: Context,
@@ -155,6 +156,7 @@ function applyDerivedCaching(
     opts.needsSession ||
     use.used ||
     use.claimsRead ||
+    use.varied ||
     res.status >= 400 ||
     res.headers.has('cache-control')
   ) {

package/src/server/route-request.ts

@@ -1,5 +1,20 @@
 import type { Context } from 'hono'
 import type { RouteRequest } from './routing.ts'
+import { readClaims, sessionUse } from './session.ts'
+
+/** A read-tracking view over the request's headers. Any read marks the
+ *  response as request-varying (layer 3: a page that consulted a header may
+ *  differ per visitor, so it is never cache-marked). Methods are bound to the
+ *  real Headers, so the view behaves as one. */
+function trackedHeaders(c: Context, headers: Headers): Headers {
+  return new Proxy(headers, {
+    get(target, prop) {
+      sessionUse(c).varied = true
+      const value = Reflect.get(target, prop, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
 
 /**
  * Wrap Hono's request into the framework's RouteRequest shape. The raw
@@ -14,6 +29,7 @@ export function buildRouteRequest(c: Context, paramNames: string[]): RouteReques
     if (v !== undefined) params[name] = v
   }
   const query: Record<string, string | undefined> = c.req.query()
+  const headers = trackedHeaders(c, raw.headers)
 
   return {
     raw,
@@ -26,8 +42,9 @@ export function buildRouteRequest(c: Context, paramNames: string[]): RouteReques
       return raw.url
     },
     get headers() {
-      return raw.headers
+      return headers
     },
+    claims: <T = unknown>() => readClaims<T>(c),
     formData: () => raw.formData(),
     json: <T = unknown>() => raw.json() as Promise<T>,
     text: () => raw.text(),

package/src/server/routing.ts

@@ -27,8 +27,13 @@ export interface RouteRequest {
   readonly method: string
   /** Full request URL. Same as `raw.url`. */
   readonly url: string
-  /** Request headers. Same Headers instance as `raw.headers`. */
+  /** Request headers. Reading one marks the response as varying per visitor,
+   *  which withdraws derived Cache-Control; `raw.headers` is the untracked
+   *  escape hatch and is outside that proof. */
   readonly headers: Headers
+  /** This session's app-defined claims, or `undefined` if none. A peek: never
+   *  establishes a session. A defined result withdraws derived Cache-Control. */
+  claims<T = unknown>(): T | undefined
   /** Parsed form body. Throws if the content type doesn't match. */
   formData(): Promise<FormData>
   /** Parsed JSON body. Throws on invalid JSON. */

package/src/server/runtime.ts

@@ -0,0 +1,66 @@
+/**
+ * `/server/runtime` — the TOOLCHAIN tier of the server: what compiled `.stator`
+ * output, the dev server, the build and the framework's own tests run on.
+ * Public because they must be importable from a package boundary, not
+ * because an app should need them; per the docs' stability policy these may
+ * change in a minor. The STABLE app surface lives on `/server`.
+ */
+export { discoverBoot, isBootDefinition, runBoot } from './boot.ts'
+export { isStatorMachine } from './define-machine.ts'
+export type { PollLoopFinding } from './dev-lint.ts'
+export { findPollLoops } from './dev-lint.ts'
+export type { DiscoveryResult } from './discovery.ts'
+export { discoverMachines } from './discovery.ts'
+export type { DispatchContext } from './dispatch-context.ts'
+export {
+  getDispatchContext,
+  recordTouch,
+  withDispatchContext,
+} from './dispatch-context.ts'
+export { scheduleSessionEffects, wireAppEffects } from './effects.ts'
+export type { HttpConfig } from './http.ts'
+export { buildHonoApp } from './http.ts'
+export type { ResolvedImagesConfig } from './images.ts'
+export { DEFAULT_IMAGE_WIDTHS, resolveImagesConfig } from './images.ts'
+export type { InspectPayload, InspectRoute, InspectRouteMethod } from './inspect.ts'
+export { buildInspectPayload } from './inspect.ts'
+export type { InstanceHandle } from './instance-proxy.ts'
+export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
+export { codeHashOf, codeInputsOf } from './machine-hash.ts'
+export { MachineStore } from './machine-store.ts'
+export { discoverMiddleware, isMiddlewareDefinition } from './middleware.ts'
+export { runQueryRoute } from './query-route.ts'
+export { recompute } from './recompute.ts'
+export type { RenderResult } from './render.ts'
+export { renderRoute } from './render.ts'
+export type {
+  Binding,
+  BindingKind,
+  ElementId,
+  EventDescriptor,
+  MachineName,
+  RenderState,
+  SessionId,
+  SlotId,
+} from './render-context.ts'
+export {
+  allocElementId,
+  allocSlotId,
+  createEventDescriptor,
+  createRenderState,
+  getCurrentRenderState,
+  isEventDescriptor,
+  popListScope,
+  pushListScope,
+  registerBinding,
+  requireCurrentRenderState,
+  runInRender,
+  unregisterBindingsForScope,
+} from './render-context.ts'
+export type { DiscoveredRoute } from './route-discovery.ts'
+export { discoverRoutes } from './route-discovery.ts'
+export { isStatorApiRoute, isStatorQueryRoute, isStatorRoute } from './routing.ts'
+export { getOrCreateSessionId, SESSION_COOKIE, setSessionSameSite } from './session.ts'
+export { SessionRuntime } from './session-runtime.ts'
+export type { Connection } from './sse.ts'
+export { fanOut, registerConnection, unregisterConnection } from './sse.ts'

package/src/server/session.ts

@@ -28,7 +28,11 @@ export interface SessionState {
  *  response unprovable as anonymous-identical, so no derived Cache-Control. */
 export interface SessionUse {
   used: boolean
+  /** A claims read resolved to a value. */
   claimsRead: boolean
+  /** A request input beyond the URL was read (a header, a cookie), so the
+   *  response may differ per visitor. */
+  varied: boolean
 }
 
 declare module 'hono' {
@@ -47,12 +51,21 @@ export function getSessionState(c: Context): SessionState | undefined {
 export function sessionUse(c: Context): SessionUse {
   let use = c.get('statorSessionUse')
   if (!use) {
-    use = { used: false, claimsRead: false }
+    use = { used: false, claimsRead: false, varied: false }
     c.set('statorSessionUse', use)
   }
   return use
 }
 
+/** Read the resumed session's claims — a peek that never establishes. Only a
+ *  DEFINED result makes the response claims-dependent (layer 3): a visitor
+ *  whose claims read came back empty saw exactly the anonymous page. */
+export function readClaims<T = unknown>(c: Context): T | undefined {
+  const claims = getSessionState(c)?.claims as T | undefined
+  if (claims !== undefined) sessionUse(c).claimsRead = true
+  return claims
+}
+
 /** The session id this request WOULD have — established state or the arriving
  *  cookie — without creating anything. Null for a first-contact visitor. */
 export function peekSessionId(c: Context): string | null {