@statorjs/stator 2.10.0-next.1 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.10.0-next.1",
+  "version": "2.10.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",
@@ -27,6 +27,10 @@
     "stator": "./src/cli/stator.js"
   },
   "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"
@@ -95,7 +99,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.10.0-next.1"
+    "@statorjs/stator": "2.10.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/cli/commands/dev.ts

@@ -23,6 +23,8 @@ export async function run(ctx: CliContext): Promise<void> {
     trustedOrigins: config.trustedOrigins,
     origin: config.origin,
     cors: config.cors,
+    secret: config.secret,
+    logging: config.logging,
   })
   await app.listen(resolvePort(ctx.portFlag, config.port))
 }

package/src/cli/commands/start.ts

@@ -95,6 +95,8 @@ export async function run(ctx: CliContext): Promise<void> {
     host: config.host,
     secret: config.secret,
     cors: config.cors,
+    logging: config.logging,
+    caching: config.caching,
     headExtras,
     buildId,
     machineHashes: machines,

package/src/compiler/lower.ts

@@ -277,6 +277,47 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
   }
   checkNoReadInDefer(fragment, false)
 
+  // Build-time gate for RCDATA elements: inside <textarea> and <title> the
+  // parser treats children as RAW TEXT — a live-slot <span> (text-position
+  // read()) or a region comment marker (each/when/match/defer) is rendered as
+  // literal markup instead of becoming an element. Found in the wild: a
+  // textarea pre-filled via read() displayed `<span data-slot="…"></span>` to
+  // the user. Attributes on the element itself stay legal (attribute patches
+  // need no wrapper) — the gate covers children only.
+  const RCDATA_BINDINGS = new Set(['read', 'each', 'when', 'match', 'defer'])
+  const checkNoBindingInRcdata = (node: ts.Node, rcdataTag: string | null): void => {
+    if (
+      rcdataTag &&
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      RCDATA_BINDINGS.has(node.expression.text)
+    ) {
+      const callee = node.expression.text
+      throw new CompileError(
+        `stator: ${callee}() cannot appear inside <${rcdataTag}> — its content is raw text ` +
+          `(RCDATA), so the ${callee === 'read' ? 'live-slot wrapper' : 'region markers'} would ` +
+          `render as literal markup. Interpolate a static value instead (a selector property ` +
+          `like {machine.someSelector}, or a frontmatter constant); if the value must be live, ` +
+          `bind an attribute or use an island.`,
+        loc(node),
+      )
+    }
+    if (ts.isJsxElement(node)) {
+      const opening = node.openingElement
+      const tagName = ts.isIdentifier(opening.tagName) ? opening.tagName.text : null
+      const isRcdata = tagName === 'textarea' || tagName === 'title'
+      // Attributes keep the OUTER context; children enter the RCDATA scope.
+      checkNoBindingInRcdata(opening, rcdataTag)
+      for (const child of node.children) {
+        checkNoBindingInRcdata(child, isRcdata ? tagName : rcdataTag)
+      }
+      checkNoBindingInRcdata(node.closingElement, rcdataTag)
+      return
+    }
+    ts.forEachChild(node, (child) => checkNoBindingInRcdata(child, rcdataTag))
+  }
+  checkNoBindingInRcdata(fragment, null)
+
   // 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

@@ -102,7 +102,7 @@ const STATOR_AMBIENT = `declare const Stator: {
   reads<const T extends readonly __SMachineDef[]>(defs: T): { -readonly [K in keyof T]: __SInstanceOf<T[K]> };
   forwarded(name: \`on:\${string}\`): (() => unknown) | undefined;
   request: any;
-  response: { status: number; headers: Record<string, string>; cookies: any };
+  response: { status: number; headers: Headers; cookies: any };
 };
 declare global {
   namespace JSX {

package/src/config.ts

@@ -97,6 +97,22 @@ export interface StatorConfig {
    *  Opt in per route/app with the `cors()` middleware; `origins` defaults to
    *  `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
+  /** Derived Cache-Control (the cacheable read path, layer 3): on GET
+   *  responses the framework can PROVE anonymous-identical — every declared
+   *  read app-lifecycle, no session use or claims read while handling — it
+   *  emits `Cache-Control: public, s-maxage, stale-while-revalidate` so a
+   *  CDN can absorb anonymous traffic. Hand-set headers always win; pages
+   *  that read session machines are never marked. On by default under
+   *  `stator start` (60s / 300s); set to `false` to disable; dev never
+   *  emits (editing must always re-render). */
+  caching?:
+    | {
+        /** Shared-cache lifetime in seconds. Default: 60. */
+        sMaxAge?: number
+        /** Serve-stale-while-refreshing window in seconds. Default: 300. */
+        staleWhileRevalidate?: number
+      }
+    | false
   /** Logging policy. */
   logging?: {
     /** Minimum level to emit. Default: `warn` in production, `info` in dev.

package/src/index.ts

@@ -0,0 +1,7 @@
+// Root export = the config-authoring surface only. `stator.config.ts` is the
+// first file anyone writes against the bare package name, and it must never
+// drag server-only dependencies (sharp, ioredis) into a config load — anything
+// beyond config keeps its own subpath.
+
+export type { LogLevel, StatorConfig } from './config.ts'
+export { defineConfig } from './config.ts'

package/src/server/api-route.ts

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

package/src/server/config-compat.ts

@@ -34,6 +34,7 @@ interface NestedReads {
   host?: string
   secret?: string
   cors?: { origins?: readonly string[]; credentials?: boolean }
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 /** The flat internal values `createApp`/`createDevApp` actually consume. */
@@ -51,6 +52,8 @@ export interface ResolvedAppConfig {
   /** Signed-cookie signing key. `config.secret` ?? `STATOR_SECRET`. */
   secret?: string
   cors?: { origins: readonly string[]; credentials: boolean }
+  /** Derived Cache-Control knobs; `false` disables emission entirely. */
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 /**
@@ -93,5 +96,6 @@ export function resolveAppConfig(config: NestedReads & DeprecatedFlatConfig): Re
           credentials: config.cors.credentials ?? false,
         }
       : undefined,
+    caching: config.caching,
   }
 }

package/src/server/context.ts

@@ -1,6 +1,6 @@
 import type { Context } from 'hono'
 import { type CookieJar, cookieJar } from './cookies.ts'
-import { getSessionState, rotateSessionNow } from './session.ts'
+import { getOrCreateSessionId, getSessionState, rotateSessionNow, sessionUse } from './session.ts'
 import type { Store } from './store.ts'
 
 /**
@@ -64,25 +64,34 @@ const DEFAULT: StatorConfigData = { trustedOrigins: [], sameSite: 'Lax' }
  */
 export function stator(c: Context): StatorContext {
   const cfg = c.get('stator') ?? DEFAULT
-  const session = getSessionState(c)
   return {
     origin: cfg.origin,
     trustedOrigins: cfg.trustedOrigins,
     sameSite: cfg.sameSite,
     cors: cfg.cors,
+    // Live reads (not a captured snapshot): the session may be established
+    // mid-request, after this context object was built.
     get sid() {
-      return session?.sid ?? ''
+      return getSessionState(c)?.sid ?? ''
     },
     claims<T = unknown>(): T | undefined {
-      return session?.claims as 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
     },
     setClaims(claims: unknown): void {
+      // Writing claims is an explicit session op — an establishment trigger.
+      getOrCreateSessionId(c)
+      const session = getSessionState(c)
       if (session) {
         session.claims = claims
         session.claimsDirty = true
       }
     },
     clearClaims(): void {
+      const session = getSessionState(c)
       if (session) {
         session.claims = undefined
         session.claimsDirty = true

package/src/server/create-app.ts

@@ -89,6 +89,9 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
    *  keyed by file relative to `machinesDir`. Omitted ⇒ hashed live at boot;
    *  a discovered machine missing from a supplied map is a boot error. */
   machineHashes?: Readonly<Record<string, string>>
+  /** Derived Cache-Control (cacheable read path, layer 3). Defaults on with
+   *  modest values (60s / 300s); `false` disables emission. */
+  caching?: { sMaxAge?: number; staleWhileRevalidate?: number } | false
 }
 
 export interface StatorApp {
@@ -163,6 +166,16 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     buildId: config.buildId,
     cors: resolved.cors,
     middleware,
+    // Layer-3 derived Cache-Control: on by default with modest values; the
+    // whole block set to `false` disables. (createDevApp never passes it —
+    // dev pages must always re-render while editing.)
+    caching:
+      resolved.caching === false
+        ? undefined
+        : {
+            sMaxAge: resolved.caching?.sMaxAge ?? 60,
+            staleWhileRevalidate: resolved.caching?.staleWhileRevalidate ?? 300,
+          },
   })
 
   return {

package/src/server/http.ts

@@ -19,7 +19,14 @@ import { renderRoute } from './render.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
 import { isStatorQueryRoute, type RouteDefinition } from './routing.ts'
-import { CLAIMS_KEY, getOrCreateSessionId, getSessionState } from './session.ts'
+import {
+  CLAIMS_KEY,
+  getOrCreateSessionId,
+  getSessionState,
+  peekSessionId,
+  resumeSession,
+  sessionUse,
+} from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { enqueue, fanOut, registerConnection, unregisterConnection } from './sse.ts'
@@ -64,8 +71,18 @@ export interface HttpConfig {
   /** The app's discovered `middleware.ts` definition (if any). `withDefaults`
    *  controls whether the framework security stack is prepended. */
   middleware?: MiddlewareDefinition
+  /** Layer-3 derived Cache-Control: emitted on GET responses the framework can
+   *  PROVE anonymous-identical (no session reads declared, no session use or
+   *  claims read while handling, nothing hand-set). Absent → never emitted
+   *  (the dev servers leave it off so editing always re-renders). */
+  caching?: { sMaxAge: number; staleWhileRevalidate: number }
 }
 
+/** Placeholder sid for session-free page renders — `loadGraph` loads only
+ *  session-lifecycle machines, so on app-only routes this never reaches the
+ *  store; it exists to keep SessionRuntime's signature honest. */
+const ANONYMOUS_SID = '@anonymous'
+
 const eventSchema = z.object({
   machine: z.string(),
   event: z
@@ -113,14 +130,20 @@ function compileMatcher(route: DiscoveredRoute): RouteMatcher {
   return { route, regex: new RegExp(`^${pattern}$`) }
 }
 
+/** One matcher's result against a literal path: the route plus its
+ *  extracted path params. */
+interface PathMatch {
+  route: DiscoveredRoute
+  params: Record<string, string>
+}
+
 /**
- * Match a literal URL path against compiled matchers. Returns the matched
- * route + extracted params, or null if nothing matches.
+ * Match a literal URL path against every compiled matcher that matches it,
+ * in `matchers`' own (priority-sorted) order — every candidate a 404-
+ * cascading GET dispatch might need to try, not just the first.
  */
-function matchPath(
-  matchers: RouteMatcher[],
-  literalPath: string,
-): { route: DiscoveredRoute; params: Record<string, string> } | null {
+function matchAllPaths(matchers: RouteMatcher[], literalPath: string): PathMatch[] {
+  const matches: PathMatch[] = []
   for (const m of matchers) {
     const result = m.regex.exec(literalPath)
     if (!result) continue
@@ -128,9 +151,65 @@ function matchPath(
     m.route.paramNames.forEach((name, i) => {
       params[name] = decodeURIComponent(result[i + 1] ?? '')
     })
-    return { route: m.route, params }
+    matches.push({ route: m.route, params })
   }
-  return null
+  return matches
+}
+
+/**
+ * Match a literal URL path against compiled matchers. Returns the FIRST
+ * matched route + extracted params, or null if nothing matches — for call
+ * sites resolving an already-known route key (the SSE/event endpoints),
+ * where there is exactly one right answer and no cascading question.
+ */
+function matchPath(matchers: RouteMatcher[], literalPath: string): PathMatch | null {
+  return matchAllPaths(matchers, literalPath)[0] ?? null
+}
+
+/** True when any segment of a urlPath is a rest/catch-all (`*name`). */
+function isRestPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith('*'))
+}
+
+/** True when any segment of a urlPath is a suffixed param (`:name.ext`) —
+ *  the file-extension-routing pattern (`[id].json.ts` → `/p/:id.json`). */
+function isSuffixedParamPattern(urlPath: string): boolean {
+  return urlPath.split('/').some((seg) => seg.startsWith(':') && seg.includes('.'))
+}
+
+/**
+ * Candidates a 404-cascading GET dispatch may actually try, in priority
+ * order.
+ *
+ * Two matches can structurally overlap for one literal URL in ways that
+ * were never meant to form a "try something more general" chain:
+ *
+ *   - A suffixed param (`/p/:id.json`, from `[id].json.ts`) and its bare
+ *     sibling (`/p/:id`) — `compileMatcher`'s bare `:id` regex doesn't
+ *     exclude dots, so both structurally match `/p/abc.json`. The suffix
+ *     is the author's own explicit, dedicated handler for exactly that
+ *     extension (`sortRoutes`'s own doc comment: "so `/p/:id.json` wins
+ *     `/p/abc.json` before `/p/:id` can swallow it") — nothing ranked
+ *     below it, bare OR rest, is a MORE correct answer than what was
+ *     written on purpose for this exact case. (A rest/catch-all can't
+ *     even carry a suffix of its own — `filePathToRoute` rejects
+ *     `[...name].ext` outright — so it's exactly as wrong a fallback here
+ *     as bare is: confirmed against a real app, examples/live-poll's
+ *     `/p/:id.json` data route + `/p/:id` HTML page pair, where a 404
+ *     from the JSON route cascading into the page handed back HTML for a
+ *     request that explicitly asked for JSON.) So a winning suffixed
+ *     match is unconditionally terminal — no cascading at all, into
+ *     anything, once it's the one that matched.
+ *   - Anything bare/static vs. a rest/catch-all IS a legitimate fallback
+ *     chain (`routes/media/[...path].ts`, this feature's original
+ *     motivating case) — a catch-all stays cascade-eligible unless the
+ *     winning match was itself suffixed.
+ */
+function cascadeCandidates<T extends PathMatch>(all: T[]): T[] {
+  if (all.length === 0) return all
+  const winner = all[0]!
+  if (isSuffixedParamPattern(winner.route.urlPath)) return [winner]
+  return [winner, ...all.slice(1).filter((m) => isRestPattern(m.route.urlPath))]
 }
 
 /** Parse a route key like "GET /p/abc-123" into method + literal path. */
@@ -179,10 +258,13 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   })
 
   // Context bridge — expose resolved config to every middleware (cors, app
-  // middleware) that follows, off `stator(c)`. Runs first. Also establishes the
-  // session once and eager-loads its claims (for a returning session), so the
-  // whole request shares one sid + claims snapshot; dirty claims persist at the
-  // end, to the current (possibly rotated) sid.
+  // middleware) that follows, off `stator(c)`. Runs first. Sessions are LAZY
+  // (the cacheable-read-path layer 1): an arriving cookie RESUMES its session
+  // (claims eager-loaded, no cookie write), but first contact establishes
+  // nothing — creation happens only at a dispatch, a session-machine read, an
+  // SSE connect, or an explicit session op. Anonymous reads therefore carry
+  // no Set-Cookie and stay CDN-cacheable. Dirty claims persist at the end,
+  // to the current (possibly rotated or just-established) sid.
   app.use('*', async (c, next) => {
     c.set('stator', {
       origin: config.origin,
@@ -194,14 +276,15 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     c.set('statorStore', config.store)
     // Stash the signing key so the cookie jar's signed methods can reach it.
     if (config.secret !== undefined) c.set('statorSecret', config.secret)
-    const { sessionId, isNew } = getOrCreateSessionId(c)
-    const session = getSessionState(c)
-    if (!isNew && session) {
-      session.claims = (await config.store.persistence.get(sessionId, CLAIMS_KEY)) ?? undefined
+    sessionUse(c)
+    const resumed = resumeSession(c)
+    if (resumed) {
+      resumed.claims = (await config.store.persistence.get(resumed.sid, CLAIMS_KEY)) ?? undefined
     }
     await next()
-    // Same session object (rotation mutates `.sid` in place), so persist to the
-    // current — possibly rotated — id.
+    // Re-read: the session may have been established mid-request. Rotation
+    // mutates `.sid` in place, so this persists to the current id.
+    const session = getSessionState(c)
     if (session?.claimsDirty) {
       await config.store.persistence.set(session.sid, CLAIMS_KEY, session.claims, {
         ttlSeconds: config.store.sessionTtlSeconds,
@@ -260,7 +343,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       const payload = await buildInspectPayload({
         store: config.store,
         routes: config.routes,
-        sessionId: getSessionState(c)?.sid,
+        // Inspecting IS session use — the route shows the caller's own
+        // session, so establish one for a first-contact dev visit.
+        sessionId: getOrCreateSessionId(c).sessionId,
         buildId: config.buildId,
       })
       c.header('Cache-Control', 'no-cache')
@@ -591,24 +676,61 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  // 404 cascades by default: a matched GET route that 404s doesn't
+  // permanently claim the path — a lower-priority `[...name]`/`404`
+  // catch-all (if one exists) gets a turn, same priority order `matchers`
+  // is already sorted in. Only once every candidate 404s does the LAST
+  // (lowest-priority) one's response actually go out — so a route's own
+  // not-found body/headers/status still reach the client, this just stops
+  // the FIRST match from being final when a catch-all could actually
+  // serve it. `cascadeCandidates` (not the full `matchAllPaths` list) is
+  // what narrows "the next matching route" to specifically mean a
+  // catch-all — see its own doc comment for why that boundary matters.
   app.get('*', async (c, next) => {
-    const matched = matchPath(matchers, c.req.path)
-    if (!matched?.route.GET) return next()
-    const getRoute = matched.route.GET
-    // Brand decides the GET plane: data routes never touch the HTML path
-    // (no client-runtime injection, no live meta — a raw Response out).
-    if (isStatorQueryRoute(getRoute)) {
-      return runQueryRoute(c, matched.route, getRoute, config.store, matched.params)
-    }
-    return handleGet(
-      c,
-      matched.route,
-      getRoute,
-      matched.params,
-      config.store,
-      config.headExtras,
-      config.buildId,
+    const candidates = cascadeCandidates(
+      matchAllPaths(matchers, c.req.path).filter(
+        (
+          m,
+        ): m is PathMatch & {
+          route: DiscoveredRoute & { GET: NonNullable<DiscoveredRoute['GET']> }
+        } => !!m.route.GET,
+      ),
     )
+    if (candidates.length === 0) return next()
+
+    let lastNotFound: (() => Response) | undefined
+    for (const matched of candidates) {
+      const getRoute = matched.route.GET
+      // Brand decides the GET plane: data routes never touch the HTML path
+      // (no client-runtime injection, no live meta — a raw Response out).
+      if (isStatorQueryRoute(getRoute)) {
+        const response = await runQueryRoute(
+          c,
+          matched.route,
+          getRoute,
+          config.store,
+          matched.params,
+          config.caching,
+        )
+        if (response.status !== 404) return response
+        lastNotFound = () => response
+        continue
+      }
+
+      const candidate = await renderGetCandidate(
+        c,
+        matched.route,
+        getRoute,
+        matched.params,
+        config.store,
+        config.headExtras,
+        config.buildId,
+        config.caching,
+      )
+      if (candidate.status !== 404) return candidate.commit()
+      lastNotFound = candidate.commit
+    }
+    return lastNotFound ? lastNotFound() : next()
   })
 
   return app
@@ -672,7 +794,24 @@ function injectIntoDocument(html: string, parts: { head?: string; bodyEnd?: stri
   return out
 }
 
-async function handleGet(
+/** A rendered GET candidate, not yet committed to the shared Hono `Context`.
+ *  Cascading (see `matchAllPaths`/the GET dispatch loop) speculatively tries
+ *  several routes for one path — `applyRenderedEffects` writes headers,
+ *  cookies, and status directly onto `c`, cumulatively, so calling it for a
+ *  candidate that turns out to 404 would leak into whatever candidate wins
+ *  next (worse: `applyRenderedEffects` only calls `c.status(...)` when the
+ *  status isn't 200, so a losing 404 candidate followed by a winning 200 one
+ *  would ship 200 content under a stale 404 status — confirmed the hard way
+ *  designing this). Splitting render (safe to call speculatively, side-effect
+ *  free on `c`) from commit (writes to `c`, only ever called once, for
+ *  whichever candidate the dispatch loop actually decided to serve) is what
+ *  makes cascading safe. */
+interface GetCandidate {
+  status: number
+  commit: () => Response
+}
+
+async function renderGetCandidate(
   c: Context,
   discovered: DiscoveredRoute,
   route: RouteDefinition,
@@ -680,64 +819,100 @@ async function handleGet(
   store: MachineStore,
   headExtras?: (filePath: string) => string | Promise<string>,
   buildId?: string,
-): Promise<Response> {
-  {
-    const { sessionId } = getOrCreateSessionId(c)
-    const literalPath = c.req.path
-    const routeKey = `GET ${literalPath}`
-    const request = { ...buildRouteRequest(c, discovered.paramNames), params }
-
-    const runtime = new SessionRuntime(sessionId, store)
-    try {
-      await runtime.loadGraph(route.reads)
-      const result = await renderRoute(route, routeKey, sessionId, runtime, request)
-      let html = result.html
-
-      const headHtml: string[] = []
-      if (headExtras) {
-        const extra = await headExtras(discovered.filePath)
-        if (extra) headHtml.push(extra)
-      }
-      if (route.live) {
-        headHtml.push('<meta name="stator-live" content="true">')
-        // The build this page was rendered against — the client echoes it on
-        // /__sse connect so the server can reload a page from a stale build.
-        // `buildId` is a framework-generated UUID (no HTML-special chars).
-        if (buildId) {
-          headHtml.push(`<meta name="stator-build" content="${buildId}">`)
-        }
+  caching?: { sMaxAge: number; staleWhileRevalidate: number },
+): Promise<GetCandidate> {
+  // Lazy layer 1: only a session-machine read forces establishment. An
+  // app-only (or read-free) page renders against the resumed sid when a
+  // cookie arrived, or an inert placeholder — loadGraph loads session
+  // machines only, so the placeholder never reaches the store.
+  const needsSession = route.reads.some((def) => def.lifecycle === 'session')
+  const sessionId = needsSession
+    ? getOrCreateSessionId(c).sessionId
+    : (peekSessionId(c) ?? ANONYMOUS_SID)
+  const literalPath = c.req.path
+  const routeKey = `GET ${literalPath}`
+  const request = { ...buildRouteRequest(c, discovered.paramNames), params }
+
+  const runtime = new SessionRuntime(sessionId, store)
+  try {
+    await runtime.loadGraph(route.reads)
+    const result = await renderRoute(route, routeKey, sessionId, runtime, request)
+    let html = result.html
+
+    const headHtml: string[] = []
+    if (headExtras) {
+      const extra = await headExtras(discovered.filePath)
+      if (extra) headHtml.push(extra)
+    }
+    if (route.live) {
+      headHtml.push('<meta name="stator-live" content="true">')
+      // The build this page was rendered against — the client echoes it on
+      // /__sse connect so the server can reload a page from a stale build.
+      // `buildId` is a framework-generated UUID (no HTML-special chars).
+      if (buildId) {
+        headHtml.push(`<meta name="stator-build" content="${buildId}">`)
       }
+    }
 
-      // Auto-inject the client runtime (delegated events + patch application).
-      // Apps never hand-include it — a forgotten <script> is a silently dead
-      // page (events fire nothing, no patches apply). Idempotent: skipped if the
-      // document already references it, so a layout that still carries the tag
-      // (or two passes sharing a doc) never loads it twice.
-      const bodyHtml: string[] = []
-      if (!html.includes('/static/client.js')) {
-        bodyHtml.push('<script src="/static/client.js"></script>')
-      }
+    // Auto-inject the client runtime (delegated events + patch application).
+    // Apps never hand-include it — a forgotten <script> is a silently dead
+    // page (events fire nothing, no patches apply). Idempotent: skipped if the
+    // document already references it, so a layout that still carries the tag
+    // (or two passes sharing a doc) never loads it twice.
+    const bodyHtml: string[] = []
+    if (!html.includes('/static/client.js')) {
+      bodyHtml.push('<script src="/static/client.js"></script>')
+    }
 
-      html = injectIntoDocument(html, {
-        head: headHtml.join(''),
-        bodyEnd: bodyHtml.join(''),
-      })
-      applyRenderedEffects(c, result.response)
-
-      // A fresh machine that fired its initial entry effect on load must be
-      // persisted (so the next request hydrates instead of re-firing) and its
-      // effect scheduled off-lock, after the response. The common GET (no entry
-      // effect) skips both and stays a pure read.
-      const entryFired = runtime.entryFiredMachines()
-      if (entryFired.size > 0) {
-        await runtime.persistTouched(entryFired)
-        scheduleSessionEffects(runtime, store, sessionId)
-      }
+    html = injectIntoDocument(html, {
+      head: headHtml.join(''),
+      bodyEnd: bodyHtml.join(''),
+    })
+
+    // Fired regardless of whether this candidate ends up winning: an entry
+    // effect firing is a fact about the MACHINE having been loaded for the
+    // first time (shared, cross-cutting state), not about which route's
+    // response the caller ultimately serves — a discarded losing candidate
+    // still genuinely loaded whatever it read.
+    const entryFired = runtime.entryFiredMachines()
+    if (entryFired.size > 0) {
+      await runtime.persistTouched(entryFired)
+      scheduleSessionEffects(runtime, store, sessionId)
+    }
 
-      return c.html(html)
-    } finally {
-      runtime.dispose()
+    // 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
+    // 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
+    // headers may reach `c` (the same reason `applyRenderedEffects` is
+    // deferred to `commit` rather than called here).
+    const use = sessionUse(c)
+    const deriveCacheControl =
+      !!caching &&
+      !needsSession &&
+      !use.used &&
+      !use.claimsRead &&
+      result.response.status < 300 &&
+      result.response.cookies.length === 0 &&
+      !result.response.headers.has('cache-control')
+
+    return {
+      status: result.response.status,
+      commit: () => {
+        applyRenderedEffects(c, result.response)
+        if (deriveCacheControl) {
+          c.header(
+            'Cache-Control',
+            `public, max-age=0, s-maxage=${caching!.sMaxAge}, stale-while-revalidate=${caching!.staleWhileRevalidate}`,
+          )
+        }
+        return c.html(html)
+      },
     }
+  } finally {
+    runtime.dispose()
   }
 }
 

package/src/server/query-route.ts

@@ -12,7 +12,7 @@ import type {
   QueryRouteResult,
   RouteContext,
 } from './routing.ts'
-import { getOrCreateSessionId } from './session.ts'
+import { getOrCreateSessionId, peekSessionId, sessionUse } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 
@@ -24,6 +24,7 @@ const queryLog = scopedLogger('query')
 const DATA_CONTENT_TYPES: Record<string, string> = {
   '.json': 'application/json; charset=utf-8',
   '.xml': 'application/xml; charset=utf-8',
+  '.atom': 'application/atom+xml; charset=utf-8',
   '.txt': 'text/plain; charset=utf-8',
   '.ics': 'text/calendar; charset=utf-8',
   '.csv': 'text/csv; charset=utf-8',
@@ -55,8 +56,30 @@ export async function runQueryRoute(
   /** Path params from the framework's own matcher (the GET catch-all
    *  bypasses Hono's per-route param extraction). */
   params?: Record<string, string>,
+  /** Layer-3 derived Cache-Control values (absent → never emitted). */
+  caching?: { sMaxAge: number; staleWhileRevalidate: number },
 ): Promise<Response> {
-  const { sessionId } = getOrCreateSessionId(c)
+  // Lazy layer 1: only session-machine reads establish; an app-only data
+  // route (a feed, a sitemap) renders sessionless and stays CDN-cacheable.
+  const needsSession = route.reads.some((def) => def.lifecycle === 'session')
+
+  // The revision ledger: when the route declares a cheap fingerprint, the
+  // ETag derives from it and a match answers 304 BEFORE the handler — the
+  // designed upgrade the body-hash ETag always pointed at. The fingerprint
+  // runs outside any session machinery, so the derived-caching proof holds.
+  let revisionEtag: string | undefined
+  if (route.revision) {
+    const rev = await route.revision()
+    revisionEtag = `"r-${createHash('sha1').update(String(rev)).digest('base64url').slice(0, 16)}"`
+    if ((c.req.header('if-none-match') ?? '').includes(revisionEtag)) {
+      const notModified = new Response(null, { status: 304, headers: { ETag: revisionEtag } })
+      applyDerivedCaching(c, notModified, { caching, needsSession })
+      return notModified
+    }
+  }
+  const sessionId = needsSession
+    ? getOrCreateSessionId(c).sessionId
+    : (peekSessionId(c) ?? '@anonymous')
   const request = params
     ? { ...buildRouteRequest(c, discovered.paramNames), params }
     : buildRouteRequest(c, discovered.paramNames)
@@ -99,12 +122,54 @@ export async function runQueryRoute(
       scheduleSessionEffects(runtime, store, sessionId)
     }
 
-    return synthesizeDataResponse(c, result)
+    const res = synthesizeDataResponse(c, result)
+    // A revision route's responses carry the revision ETag (overriding the
+    // body hash) so the cheap 304 path and full responses validate against
+    // one token.
+    if (revisionEtag) {
+      try {
+        res.headers.set('etag', revisionEtag)
+      } catch {
+        // Immutable headers (proxied Response) — the handler's call.
+      }
+    }
+    applyDerivedCaching(c, res, { caching, needsSession })
+    return res
   } finally {
     runtime.dispose()
   }
 }
 
+/** 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
+ *  entry's lifetime). */
+function applyDerivedCaching(
+  c: Context,
+  res: Response,
+  opts: { caching?: { sMaxAge: number; staleWhileRevalidate: number }; needsSession: boolean },
+): void {
+  const use = sessionUse(c)
+  if (
+    !opts.caching ||
+    opts.needsSession ||
+    use.used ||
+    use.claimsRead ||
+    res.status >= 400 ||
+    res.headers.has('cache-control')
+  ) {
+    return
+  }
+  try {
+    res.headers.set(
+      'cache-control',
+      `public, max-age=0, s-maxage=${opts.caching.sMaxAge}, stale-while-revalidate=${opts.caching.staleWhileRevalidate}`,
+    )
+  } catch {
+    // Immutable headers (proxied Response) — the handler's call.
+  }
+}
+
 /** The URL's extension (`/rss.xml` → `.xml`). A leading dot alone
  *  (`/.well-known`) is not an extension. */
 function urlExtension(path: string): string | undefined {

package/src/server/route-discovery.ts

@@ -35,6 +35,14 @@ export interface DiscoveredRoute {
   PUT?: ApiRouteDefinition
   PATCH?: ApiRouteDefinition
   DELETE?: ApiRouteDefinition
+  /** True for a `404.stator`/`404.ts` file — sugar for a `[...name]`
+   *  catch-all (same synthesized pattern, same matcher), except
+   *  `sortRoutes` forces it to the absolute lowest priority: below even a
+   *  real `[...name]` at the same depth. It's the last resort, only ever
+   *  reached once nothing else — including a genuine catch-all a request
+   *  matched first — could actually serve the request (a 404 cascades by
+   *  default; see the GET dispatch loop in http.ts). */
+  isNotFoundFallback?: boolean
 }
 
 /**
@@ -47,6 +55,11 @@ export interface DiscoveredRoute {
  *   - `routes/[a]/[b].ts`       → `/:a/:b`
  *   - `routes/foo/[...rest].ts` → `/foo/*rest` (catch-all: terminal, matches
  *     zero+ segments, param is the raw remainder incl. slashes)
+ *   - `routes/foo/404.ts`       → sugar for `routes/foo/[...___].ts` — a
+ *     catch-all without needing to know the bracket-rest convention, EXCEPT
+ *     `sortRoutes` also forces it to the absolute lowest match priority,
+ *     below even a real `[...rest]` at the same depth — see
+ *     `DiscoveredRoute.isNotFoundFallback`.
  *
  * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
  * GET is a `defineRoute` (page renderer) or a `defineApiRoute` declaring
@@ -123,11 +136,12 @@ export async function discoverRoutes(
       continue
     }
 
-    const { urlPath, paramNames } = filePathToRoute(absDir, filePath)
+    const { urlPath, paramNames, isNotFoundFallback } = filePathToRoute(absDir, filePath)
     routes.push({
       urlPath,
       paramNames,
       filePath,
+      ...(isNotFoundFallback ? { isNotFoundFallback } : {}),
       GET: get,
       POST: post,
       PUT: put,
@@ -169,6 +183,10 @@ function mergeByUrlPath(routes: DiscoveredRoute[]): DiscoveredRoute[] {
 /**
  * Sort routes most-specific-first (Astro's model). At match time the first
  * matcher that matches wins, so order encodes priority:
+ *   - a `404.stator`/`404.ts` file (`isNotFoundFallback`) ranks absolute
+ *     last, below even a real `[...name]` at the same depth — it's the
+ *     final resort, only reached once nothing else (a genuine catch-all
+ *     included) could serve the request
  *   - routes without a rest/catch-all segment rank before those with one
  *   - per segment, left to right: static (0) > suffixed param `:id.json` (1)
  *     > bare param (2) > rest (3) — a suffixed param outranks a bare one so
@@ -186,6 +204,10 @@ export function sortRoutes(routes: DiscoveredRoute[]): DiscoveredRoute[] {
       )
 
   return [...routes].sort((a, b) => {
+    const aFallback = !!a.isNotFoundFallback
+    const bFallback = !!b.isNotFoundFallback
+    if (aFallback !== bFallback) return aFallback ? 1 : -1 // 404 fallback always last
+
     const ka = kinds(a.urlPath)
     const kb = kinds(b.urlPath)
     const aRest = ka.includes(3)
@@ -230,7 +252,7 @@ async function walkRouteFiles(dir: string): Promise<string[]> {
 export function filePathToRoute(
   absDir: string,
   filePath: string,
-): { urlPath: string; paramNames: string[] } {
+): { urlPath: string; paramNames: string[]; isNotFoundFallback: boolean } {
   const ext = extname(filePath)
   const rel = relative(absDir, filePath)
   const dirSegments = dirname(rel)
@@ -240,9 +262,18 @@ export function filePathToRoute(
   // sibling `<name>.stator.ts` files, which must map to the same URL as the
   // `<name>.stator` source did in dev.
   const fileBase = basename(rel, ext).replace(/\.stator$/, '')
-  const segments = fileBase === 'index' ? dirSegments : [...dirSegments, fileBase]
+  // `404` is sugar for a synthesized `[...name]` at this exact position —
+  // reuses the rest-segment branch below verbatim, so it gets the same
+  // matcher/regex a real catch-all would. `sortRoutes` is what actually
+  // forces it below a real `[...name]` at the same depth; this alone would
+  // just be an ordinary (if oddly-named) catch-all.
+  const isNotFoundFallback = fileBase === '404'
+  const segments =
+    fileBase === 'index'
+      ? dirSegments
+      : [...dirSegments, isNotFoundFallback ? '[...__stator_notfound__]' : fileBase]
 
-  if (segments.length === 0) return { urlPath: '/', paramNames: [] }
+  if (segments.length === 0) return { urlPath: '/', paramNames: [], isNotFoundFallback }
 
   const paramNames: string[] = []
   const urlSegments = segments.map((seg) => {
@@ -272,5 +303,5 @@ export function filePathToRoute(
     return seg
   })
 
-  return { urlPath: `/${urlSegments.join('/')}`, paramNames }
+  return { urlPath: `/${urlSegments.join('/')}`, paramNames, isNotFoundFallback }
 }

package/src/server/routing.ts

@@ -198,6 +198,7 @@ export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
       __isStatorQueryRoute: true,
       reads: config.reads ? [...config.reads] : [],
       handler: config.handler,
+      revision: config.revision,
     }
   }
   return {
@@ -248,6 +249,7 @@ export interface QueryRouteDefinition {
     request: RouteRequest,
     helpers: QueryRouteHelpers,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  revision?: () => string | number | Promise<string | number>
 }
 
 export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef> = readonly []> {
@@ -259,6 +261,12 @@ export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineD
     request: RouteRequest,
     helpers: QueryRouteHelpers<TReads>,
   ) => Promise<QueryRouteResult> | QueryRouteResult
+  /** The revision ledger: a CHEAP fingerprint of everything the body depends
+   *  on (e.g. `() => String(maxUpdatedAt())` — one indexed SELECT). When
+   *  present, the ETag derives from it and a matching `If-None-Match`
+   *  answers 304 WITHOUT invoking the handler — a polling crawler costs the
+   *  fingerprint, not the render. Must change whenever the body could. */
+  revision?: () => string | number | Promise<string | number>
 }
 
 export function isStatorQueryRoute(v: unknown): v is QueryRouteDefinition {

package/src/server/session.ts

@@ -23,9 +23,18 @@ export interface SessionState {
   claimsDirty: boolean
 }
 
+/** Layer-3 provability tracking: did this request USE the session plane
+ *  (establish/dispatch/session-read) or READ claims? Either makes the
+ *  response unprovable as anonymous-identical, so no derived Cache-Control. */
+export interface SessionUse {
+  used: boolean
+  claimsRead: boolean
+}
+
 declare module 'hono' {
   interface ContextVariableMap {
     statorSession: SessionState
+    statorSessionUse: SessionUse
   }
 }
 
@@ -34,6 +43,40 @@ export function getSessionState(c: Context): SessionState | undefined {
   return c.get('statorSession')
 }
 
+/** The request's session-use flags (created on first access). */
+export function sessionUse(c: Context): SessionUse {
+  let use = c.get('statorSessionUse')
+  if (!use) {
+    use = { used: false, claimsRead: false }
+    c.set('statorSessionUse', use)
+  }
+  return use
+}
+
+/** 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 {
+  return getSessionState(c)?.sid ?? getCookie(c, SESSION_COOKIE) ?? null
+}
+
+/** Resume an EXISTING session from the arriving cookie (populate the shared
+ *  state, no cookie write) — or return null for first contact. Resuming is
+ *  not establishment: laziness governs CREATION only. */
+export function resumeSession(c: Context): SessionState | null {
+  const established = getSessionState(c)
+  if (established) return established
+  const cookieSid = getCookie(c, SESSION_COOKIE)
+  if (cookieSid === undefined) return null
+  const state: SessionState = {
+    sid: cookieSid,
+    isNew: false,
+    claims: undefined,
+    claimsDirty: false,
+  }
+  c.set('statorSession', state)
+  return state
+}
+
 /** Secure cookie flag — set when running behind HTTPS. Enabled by
  *  NODE_ENV=production; can be overridden via STATOR_SECURE_COOKIE. */
 function shouldUseSecureCookie(): boolean {
@@ -65,22 +108,26 @@ export function setSessionCookie(c: Context, sessionId: string): void {
   })
 }
 
+/**
+ * ESTABLISH the session — the lazy-creation trigger (dispatches, session-
+ * machine reads, SSE connects, explicit session ops call this; anonymous
+ * page/data GETs never do). Idempotent per request: the first caller
+ * establishes, everyone after reads the same state. A first-contact visitor
+ * gets a fresh sid + Set-Cookie HERE and nowhere earlier — the whole
+ * cacheable-read-path layer 1.
+ */
 export function getOrCreateSessionId(c: Context): {
   sessionId: string
   isNew: boolean
 } {
-  // Idempotent per request: the first caller (middleware or handler) establishes
-  // the session; everyone after reads the same one. Closes the double-create bug.
-  const established = c.get('statorSession')
-  if (established) return { sessionId: established.sid, isNew: established.isNew }
-
-  const cookieSid = getCookie(c, SESSION_COOKIE)
-  const sessionId = cookieSid ?? randomUUID()
-  const isNew = cookieSid === undefined
-  if (isNew) setSessionCookie(c, sessionId)
+  sessionUse(c).used = true
+  const resumed = resumeSession(c)
+  if (resumed) return { sessionId: resumed.sid, isNew: resumed.isNew }
 
-  c.set('statorSession', { sid: sessionId, isNew, claims: undefined, claimsDirty: false })
-  return { sessionId, isNew }
+  const sessionId = randomUUID()
+  setSessionCookie(c, sessionId)
+  c.set('statorSession', { sid: sessionId, isNew: true, claims: undefined, claimsDirty: false })
+  return { sessionId, isNew: true }
 }
 
 /**

package/src/template/html-attributes.ts

@@ -94,6 +94,11 @@ export interface ElementSpecificAttributes {
     autofocus?: boolean
     accept?: string
     multiple?: boolean
+    /** Associates this element with a `<form>` elsewhere in the document by
+     *  id — the standard way to submit an element that can't live inside
+     *  the form's own DOM subtree (e.g. a per-row control alongside a
+     *  page-wide bulk-action form). `button` already carries this. */
+    form?: string
   }
   label: { for?: string }
   form: {
@@ -101,6 +106,11 @@ export interface ElementSpecificAttributes {
     method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
     enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
     novalidate?: boolean
+    /** Native inline event-handler attribute — a literal JS source string
+     *  (`"return confirm(...)"`), distinct from the `on:submit={...}`
+     *  Stator directive. Useful for a plain, no-hydration `confirm()`
+     *  guard that doesn't otherwise need an island. */
+    onsubmit?: string
   }
   select: {
     name?: string