@statorjs/stator 2.10.0-next.1 → 2.11.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.10.0-next.1",
+  "version": "2.11.0-next.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"
@@ -78,6 +82,7 @@
     "postcss": "^8.5.15",
     "postcss-selector-parser": "^7.1.4",
     "schema-dts": "^1.1.5",
+    "sharp": "^0.33.5",
     "typescript": "^5.6.0",
     "zod": "^3.23.0"
   },
@@ -95,7 +100,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.10.0-next.1"
+    "@statorjs/stator": "2.11.0-next.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/cli/commands/dev.ts

@@ -20,9 +20,12 @@ export async function run(ctx: CliContext): Promise<void> {
     persistence: config.persistence,
     sessions: config.sessions,
     dev: config.dev,
+    images: config.images,
     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

@@ -90,11 +90,14 @@ export async function run(ctx: CliContext): Promise<void> {
     persistence: config.persistence,
     sessions: config.sessions,
     realtime: config.realtime,
+    images: config.images,
     trustedOrigins: config.trustedOrigins,
     origin: config.origin,
     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/components/images.ts

@@ -0,0 +1,260 @@
+import { DEFAULT_IMAGE_WIDTHS } from '../server/images.ts'
+import { currentImages } from '../server/render-context.ts'
+import { html } from '../template/html.ts'
+import type { HtmlFragment } from '../template/types.ts'
+
+/**
+ * `getImage()` + `<Image>`/`<Picture>` — the render half of framework image
+ * support (spec `images-are-part-of-stator-*`; endpoint in `server/images.ts`).
+ *
+ * `src` is the PUBLIC URL of the original: an image-endpoint path
+ * (`/media/2026/08/x.jpg`) gets derived variants — the endpoint's contract is
+ * that the URL's extension is the delivery format and `?w=` resizes — while a
+ * remote URL (`http…`) passes through untouched (the framework never proxies
+ * or transforms remote origins).
+ *
+ * Dimensions are REQUIRED, always, and always come from the caller: the
+ * framework never probes at render (renders are synchronous; intrinsic size
+ * is write-time data your upload handler stores via `probeImage`). Provide
+ * `width`+`height`, or `width`+`aspectRatio` and the height is derived. That
+ * rule is what makes every `<Image>` CLS-safe by construction.
+ */
+
+export type ImageFormat = 'jpg' | 'png' | 'webp' | 'avif'
+
+export type GetImageOptions = {
+  src: string
+  /** Intrinsic dimensions — BOTH required, always from data (`probeImage` at
+   *  upload), never probed at render. That rule is what makes every `<Image>`
+   *  CLS-safe by construction. (An earlier cut also accepted
+   *  `width`+`aspectRatio` and derived the height; it had no consumers, and
+   *  spending the word `aspectRatio` on "the shape my source happens to be"
+   *  blocked it from meaning "the shape I want" — which is `crop`, below.) */
+  width: number
+  height: number
+  /** Delivery format for src/srcset URLs — defaults to the URL's extension. */
+  format?: ImageFormat
+  /** Candidate srcset widths; filtered to those below the intrinsic width.
+   *  Defaults to the CONFIGURED `images.widths` when rendering inside an app
+   *  with images configured (read from the render state — no drift), else the
+   *  shipped default. */
+  widths?: number[]
+  /** Cover-crop the delivered variants to this ratio (width / height): `1` is
+   *  square, `16 / 9` widescreen. The ratio must be on the endpoint's crop
+   *  allowlist (`images.aspectRatios`) — an unlisted one throws rather than
+   *  silently emitting URLs the endpoint would 400. Omit for the source's own
+   *  shape. Cropping is what `<picture>` art direction does per breakpoint;
+   *  as a plain prop it also covers the common case of one fixed geometry
+   *  (a thumbnail grid), which previously needed an always-true media query. */
+  crop?: number
+}
+
+export interface ResolvedImage {
+  src: string
+  srcset: string | null
+  width: number
+  height: number
+}
+
+/** Widths for srcset candidates: the explicit prop wins, then the CONFIGURED
+ *  endpoint allowlist (carried on the render state, so components can't emit
+ *  a `?w=` the endpoint rejects), then the shipped default — the same one the
+ *  endpoint defaults to, imported, not copied. */
+function effectiveWidths(explicit: number[] | undefined): number[] {
+  return explicit ?? currentImages()?.widths ?? DEFAULT_IMAGE_WIDTHS
+}
+
+const isRemote = (src: string): boolean => /^[a-z][a-z0-9+.-]*:|^\/\//i.test(src)
+
+const withFormat = (src: string, format: ImageFormat | undefined): string => {
+  if (!format) return src
+  const dot = src.lastIndexOf('.')
+  return dot === -1 ? src : `${src.slice(0, dot)}.${format}`
+}
+
+/** A crop ratio must be on the endpoint's allowlist or its URLs would 400 —
+ *  a render error, never a silent drop. Validated once, up front, for both the
+ *  plain `crop` prop and every art-directed source. */
+function assertCropAllowed(crop: number): void {
+  const allowed = currentImages()?.aspectRatios
+  if (allowed && !allowed.some((a) => Math.abs(a - crop) < 1e-9)) {
+    throw new Error(
+      `stator: crop ${crop} is not in images.aspectRatios ` +
+        `(${allowed.map((a) => a.toFixed(4)).join(', ')}) — the endpoint would reject its URLs. ` +
+        `Add it to the config allowlist or use a listed ratio.`,
+    )
+  }
+}
+
+export function getImage(opts: GetImageOptions): ResolvedImage {
+  const { src, width, height, format, widths, crop } = opts
+  const ext = src.slice(src.lastIndexOf('.') + 1).toLowerCase()
+  // Remote URLs pass through; GIF and SVG serve as originals only — the
+  // endpoint refuses to transform either (animation doesn't survive naive
+  // resizing; a vector document has no pixels to resample).
+  if (isRemote(src) || ext === 'gif' || ext === 'svg') {
+    return { src, srcset: null, width, height }
+  }
+  const base = withFormat(src, format)
+  const candidates = effectiveWidths(widths).filter((w) => w < width)
+
+  if (crop === undefined) {
+    const srcset =
+      candidates.length > 0 ? candidates.map((w) => `${base}?w=${w} ${w}w`).join(', ') : null
+    return { src: base, srcset, width, height }
+  }
+
+  assertCropAllowed(crop)
+  // A crop URL must name an allowlisted width; with none below the intrinsic
+  // width there is no valid variant to ask for, so the original serves
+  // uncropped (CSS `object-fit` still covers) rather than emitting a 400.
+  if (candidates.length === 0) return { src: base, srcset: null, width, height }
+  const box = (w: number) => ({ w, h: Math.round(w / crop) })
+  const srcset = candidates.map((w) => `${base}?w=${w}&h=${box(w).h} ${w}w`).join(', ')
+  // Dimensions describe the resource actually in `src` — the largest rung —
+  // so the reserved box carries the CROPPED ratio, not the source's.
+  const largest = box(Math.max(...candidates))
+  return {
+    src: `${base}?w=${largest.w}&h=${largest.h}`,
+    srcset,
+    width: largest.w,
+    height: largest.h,
+  }
+}
+
+/**
+ * Loading control: either the `priority` shorthand OR the native attributes it
+ * stands for, never both — `<Image priority loading="lazy">` has no defensible
+ * meaning, so the type refuses it instead of resolving it silently.
+ *
+ * `priority` earns its place by teaching: it says "there is one image on this
+ * page worth flagging", which two independent attributes don't. But it bakes
+ * in a hero-shaped assumption — a thumbnail grid wants the whole first row
+ * eager with only the first at high priority, which the rollup cannot express.
+ * So the underlying attributes are first-class, typed exactly as
+ * `HTMLAttributes<'img'>` types them (native names, native enums).
+ */
+export type ImageLoading =
+  | { priority?: boolean; loading?: never; fetchpriority?: never }
+  | {
+      priority?: never
+      loading?: 'eager' | 'lazy'
+      fetchpriority?: 'high' | 'low' | 'auto'
+    }
+
+export type ImageProps = GetImageOptions &
+  ImageLoading & {
+    /** Required — an image without alt text is a compile error on purpose.
+     *  Decorative images say so explicitly with `alt=""`. */
+    alt: string
+    sizes?: string
+    /** Orthogonal to the priority question, so it sits outside that union —
+     *  folding it in would repeat the over-coupling one level up. */
+    decoding?: 'sync' | 'async' | 'auto'
+    class?: string
+  }
+
+export function Image(props: ImageProps): HtmlFragment {
+  const {
+    alt,
+    class: className,
+    sizes = '100vw',
+    priority,
+    loading = priority ? 'eager' : 'lazy',
+    fetchpriority = priority ? 'high' : undefined,
+    decoding = 'async',
+  } = props
+  const img = getImage(props)
+  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}"
+  />`
+}
+
+/** An art-directed source: under `media`, serve a different GEOMETRY — the
+ *  `crop` ratio the endpoint cover-crops to, same vocabulary and same
+ *  allowlist as the plain `crop` prop. Reach for `sources` when the geometry
+ *  VARIES by breakpoint; a single fixed crop is just `crop` on the component. */
+export interface PictureSource {
+  media: string
+  /** width / height of the crop. `1` = square, `16 / 9` = widescreen. */
+  crop: number
+  sizes?: string
+  widths?: number[]
+}
+
+export type PictureProps = ImageProps & {
+  /** Modern-format `<source>` chain, most-preferred first. The stored format
+   *  stays the `<img>` fallback. */
+  formats?: ImageFormat[]
+  /** Art direction — this is where `<picture>` earns its difficulty: each
+   *  entry crosses with every format (media × type sources, most specific
+   *  first), and the plain-format chain follows for non-matching viewports. */
+  sources?: PictureSource[]
+}
+
+const SOURCE_TYPES: Record<ImageFormat, string> = {
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+  avif: 'image/avif',
+}
+
+export function Picture(props: PictureProps): HtmlFragment {
+  const { formats = ['avif', 'webp'], sources: artSources = [], sizes = '100vw', ...rest } = props
+  // The fallback <img> is built from the same props the sources were — `crop`
+  // included, so its reserved box describes the cropped output rather than the
+  // source's own shape.
+  const imageProps = { ...rest, sizes } as ImageProps
+  if (isRemote(rest.src)) return Image(imageProps)
+
+  const storedExt = rest.src.slice(rest.src.lastIndexOf('.') + 1).toLowerCase() as ImageFormat
+
+  // Art-directed sources come FIRST (the browser takes the first media+type
+  // match), each crossed with every modern format plus the stored format —
+  // without the stored-format row, a browser supporting none of the modern
+  // formats would fall past the media condition to the uncropped fallback.
+  // Cropping is just `getImage` with a different `crop`, so art direction and
+  // the plain chain share one code path.
+  const art = artSources.flatMap((source) =>
+    [...formats, storedExt]
+      .filter((f, i, all) => all.indexOf(f) === i && f in SOURCE_TYPES)
+      .map((format) => ({
+        media: source.media,
+        format: format as ImageFormat,
+        srcset: getImage({
+          ...imageProps,
+          format: format as ImageFormat,
+          crop: source.crop,
+          widths: source.widths ?? rest.widths,
+        }).srcset,
+        sizes: source.sizes ?? sizes,
+      }))
+      .filter((s) => s.srcset !== null),
+  )
+  const plain = formats
+    .map((format) => ({
+      media: undefined,
+      format,
+      srcset: getImage({ ...imageProps, format }).srcset,
+      sizes,
+    }))
+    .filter((s) => s.srcset !== null)
+
+  const all = [...art, ...plain]
+  if (all.length === 0) return Image(imageProps)
+  return html`<picture
+    >${all.map(
+      (s) =>
+        html`<source media="${s.media ?? undefined}" type="${SOURCE_TYPES[s.format]}" srcset="${s.srcset}" sizes="${s.sizes}" />`,
+    )}${Image(imageProps)}</picture
+  >`
+}

package/src/components/index.ts

@@ -1,2 +1,12 @@
+export type {
+  GetImageOptions,
+  ImageFormat,
+  ImageLoading,
+  ImageProps,
+  PictureProps,
+  PictureSource,
+  ResolvedImage,
+} from './images.ts'
+export { getImage, Image, Picture } from './images.ts'
 export type { JsonLdProps } from './json-ld.ts'
 export { JsonLd, ldToString } from './json-ld.ts'

package/src/config.ts

@@ -97,12 +97,76 @@ 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.
      *  Precedence: `LOG_LEVEL` env > this > default. */
     level?: LogLevel
   }
+  /** Image serving. Present → the framework mounts an image endpoint over
+   *  `dir` (originals + on-demand variants: the URL's extension is the
+   *  delivery format, `?w=` resizes from the allowlist). Absent → no routes,
+   *  no transformer loaded — image-free apps pay nothing. */
+  images?: {
+    /** Directory holding the original images (dated subpaths welcome) —
+     *  runtime-written data like a SQLite file, NOT under `static/` (builds
+     *  recreate `dist/static`). Relative paths resolve against the cwd. */
+    dir: string
+    /** URL prefix the endpoint serves under. Default: `/<basename(dir)>`
+     *  (`dir: 'media'` → `/media`). */
+    path?: string
+    /** The `?w=` allowlist, and the default `srcset` widths `getImage`
+     *  emits. An allowlist because an open resize parameter is a
+     *  denial-of-service invitation. Default: `[400, 800, 1200, 1600]`. */
+    widths?: number[]
+    /** Crop aspect allowlist (width/height) for `?w=&h=` cover-crops and
+     *  `<Picture>` art direction. Default: square, 4:3, 3:2, 16:9 and their
+     *  portrait duals. The variant space stays |widths| x |aspectRatios|. */
+    aspectRatios?: number[]
+    /** Swap the transformer (default: sharp). See `ImageTransformer`. */
+    transformer?: import('./server/images.ts').ImageTransformer
+    /** Max concurrent encodes across ALL variants (default: 2). A cold-cache
+     *  gallery page fans out many transforms at once; the semaphore keeps a
+     *  small host from OOMing under AVIF encodes. */
+    concurrency?: number
+    /** libvips worker threads per encode (default: sharp's default, which is
+     *  the REPORTED core count — on a shared-cpu host that's the physical
+     *  machine's, so a fractional vCPU fans out 8+ encoder threads. Set `1`
+     *  on small hosts.) */
+    threads?: number
+    /** Per-request encode deadline in ms (default: 15000; 0 disables). Past
+     *  it the response 302s to the stored original — real pixels now — while
+     *  the encode keeps filling the variant cache for the next request. */
+    encodeTimeoutMs?: number
+    /** Freshness lifetime in seconds (default: 0 — every use revalidates via
+     *  the content-hash ETag; a cheap 304 per image per view). */
+    maxAge?: number
+    /** Serve-stale window in seconds (default: 0). >0 emits
+     *  `stale-while-revalidate` — repeat views render instantly from cache
+     *  while the browser revalidates in the background; a changed image heals
+     *  on the NEXT view. The bounded-regret middle of the dial. */
+    staleWhileRevalidate?: number
+    /** Appends `immutable` to a nonzero maxAge. NO server-side recovery
+     *  exists once an immutable response is cached — only for apps whose
+     *  image URLs are write-once by construction (replacement = new URL). */
+    immutable?: boolean
+  }
   // observers?: Observer[] — top-level when the observability spec lands.
 }
 

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

@@ -12,6 +12,7 @@ import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
 import { loadDotenv } from './env.ts'
 import { buildHonoApp } from './http.ts'
+import { type ImageTransformer, resolveImagesConfig } from './images.ts'
 import { logger, setLogLevel } from './logger.ts'
 import { MachineStore } from './machine-store.ts'
 import { discoverMiddleware } from './middleware.ts'
@@ -61,6 +62,22 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
      *  `LOG_LEVEL` env takes precedence over this. */
     level?: LogLevel
   }
+  /** Image serving — present mounts the image endpoint over `images.dir`
+   *  (extension = delivery format, `?w=` allowlist, disk-cached variants).
+   *  Absent → no routes, no transformer loaded. Mirrors `StatorConfig.images`. */
+  images?: {
+    dir: string
+    path?: string
+    widths?: number[]
+    aspectRatios?: number[]
+    transformer?: ImageTransformer
+    concurrency?: number
+    threads?: number
+    encodeTimeoutMs?: number
+    maxAge?: number
+    staleWhileRevalidate?: number
+    immutable?: boolean
+  }
   /** Origins allowed to make cross-site writes despite the CSRF guard (exact or
    *  wildcard-subdomain). Mirrors `StatorConfig.trustedOrigins`. */
   trustedOrigins?: readonly string[]
@@ -89,6 +106,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 {
@@ -144,7 +164,9 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     : undefined
   const bootDef = config.bootFile ? await discoverBoot(config.bootFile) : undefined
   const inspector = resolved.inspector
+  const images = config.images ? resolveImagesConfig(config.images) : undefined
   const app = await buildHonoApp({
+    images,
     routes,
     store,
     staticDir,
@@ -163,6 +185,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/dev-native.ts

@@ -29,6 +29,7 @@ import { discoverMachines } from './discovery.ts'
 import { wireAppEffects } from './effects.ts'
 import { loadDotenv } from './env.ts'
 import { buildHonoApp, contentTypeFor } from './http.ts'
+import { resolveImagesConfig } from './images.ts'
 import { logger, setLogLevel } from './logger.ts'
 import { codeHashOf, codeInputsOf } from './machine-hash.ts'
 import { MachineStore } from './machine-store.ts'
@@ -133,6 +134,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
   const machinesDir = real(resolve(config.machinesDir))
   const routesDir = real(resolve(config.routesDir))
   const staticDir = config.staticDir ? real(resolve(config.staticDir)) : resolve(root, 'static')
+  const images = config.images ? resolveImagesConfig(config.images) : undefined
   // One build-id per successful BUILD, not per process. Connected pages reload
   // through the dev signal, but a page whose channel was released while it sat
   // in the background (or dropped over a blip) never sees that signal — it
@@ -428,6 +430,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     const middleware = await discoverMiddleware(resolve(root, 'middleware.ts'), bust)
     await remapRoutes()
     app = await buildHonoApp({
+      images,
       routes,
       store,
       staticDir,