@statorjs/stator 2.10.0 → 2.11.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.10.0",
+  "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",
@@ -82,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"
   },
@@ -99,7 +100,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.10.0"
+    "@statorjs/stator": "2.11.0-next.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/cli/commands/dev.ts

@@ -20,6 +20,7 @@ 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,

package/src/cli/commands/start.ts

@@ -90,6 +90,7 @@ 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,

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

@@ -119,6 +119,54 @@ export interface StatorConfig {
      *  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/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[]
@@ -147,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,

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,

package/src/server/dev-vite.ts

@@ -13,6 +13,7 @@ import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.
 import { resolveAppConfig } from './config-compat.ts'
 import type { DevApp, DevAppConfig } from './dev.ts'
 import { loadDotenv } from './env.ts'
+import { resolveImagesConfig } from './images.ts'
 import { logger, setLogLevel } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
@@ -73,6 +74,7 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
   const loader = (file: string) => vite.ssrLoadModule(file) as Promise<Record<string, unknown>>
 
   const root = resolve(config.root)
+  const images = config.images ? resolveImagesConfig(config.images) : undefined
   const machinesDir = resolve(config.machinesDir)
   const routesDir = resolve(config.routesDir)
   const resolved = resolveAppConfig(config)
@@ -201,6 +203,7 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
       routes,
       store,
       staticDir: config.staticDir,
+      images,
       headExtras,
       inspector: inspectorOn,
       inspect: true,

package/src/server/dev.ts

@@ -41,6 +41,20 @@ export interface DevAppConfig {
     cookie?: { sameSite?: 'Lax' | 'Strict' }
   }
   /** Dev-only tooling. */
+  /** Image serving — mirrors `StatorConfig.images`. */
+  images?: {
+    dir: string
+    path?: string
+    widths?: number[]
+    aspectRatios?: number[]
+    transformer?: import('./images.ts').ImageTransformer
+    concurrency?: number
+    threads?: number
+    encodeTimeoutMs?: number
+    maxAge?: number
+    staleWhileRevalidate?: number
+    immutable?: boolean
+  }
   dev?: {
     /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
     inspector?: boolean

package/src/server/http.ts

@@ -9,6 +9,7 @@ import { applyRenderedEffects, runApiRoute } from './api-route.ts'
 import { crossSiteGuard } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
 import { record, replayFor } from './event-dedupe.ts'
+import { type ImagesRenderInfo, type ResolvedImagesConfig, serveImage } from './images.ts'
 import { buildInspectPayload } from './inspect.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -37,6 +38,9 @@ export interface HttpConfig {
   routes: DiscoveredRoute[]
   store: MachineStore
   staticDir?: string
+  /** Resolved image-serving config — present mounts the endpoint at
+   *  `images.path` (see server/images.ts). */
+  images?: ResolvedImagesConfig
   /** Optional hook to inject extra `<head>` HTML for a GET route, keyed by the
    *  route's file path. The dev server uses this to inline collected scoped CSS
    *  (SSR head injection). Inserted at the `</head>` boundary. */
@@ -233,6 +237,11 @@ function parseRouteKey(
 
 export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   const app = new Hono()
+  // Render-side view of the images config: `<Image>`/`<Picture>` read this
+  // from the render state so their URLs can't drift from the endpoint.
+  const imagesInfo = config.images
+    ? { widths: config.images.widths, aspectRatios: config.images.aspectRatios }
+    : undefined
   const clientJs = await bundleClient()
 
   // Request logger: one line per request with method, path, status, duration.
@@ -408,6 +417,25 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     })
   }
 
+  if (config.images) {
+    const images = config.images
+    app.get(`${images.path}/*`, (c) => {
+      let rel: string
+      try {
+        rel = decodeURIComponent(c.req.path.slice(images.path.length + 1))
+      } catch {
+        return c.text('not found', 404) // malformed percent-encoding is a 404, not a 500
+      }
+      return serveImage(
+        images,
+        rel,
+        c.req.query('w'),
+        c.req.query('h'),
+        c.req.header('if-none-match') ?? null,
+      )
+    })
+  }
+
   // SSE endpoint. The connection's runtime + renderState stay alive for
   // the connection's lifetime — this is the one place per-session state
   // outlives a request, because the connection *is* one (very long) request.
@@ -460,7 +488,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
 
       const runtime = new SessionRuntime(sessionId, config.store)
       await runtime.loadGraph(route.reads)
-      const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request)
+      const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request, {
+        images: imagesInfo,
+      })
 
       // The handler parks on `finished` until the connection ends. Both ways
       // out resolve it: the client aborting, and the server hanging up on a
@@ -616,6 +646,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // resolve defer slots here (that would kick their I/O under the lock).
         const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request, {
           resolveDeferred: false,
+          images: imagesInfo,
         })
 
         const touched = runtime.processEvent(body.machine, body.event)
@@ -726,6 +757,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         config.headExtras,
         config.buildId,
         config.caching,
+        imagesInfo,
       )
       if (candidate.status !== 404) return candidate.commit()
       lastNotFound = candidate.commit
@@ -820,6 +852,7 @@ async function renderGetCandidate(
   headExtras?: (filePath: string) => string | Promise<string>,
   buildId?: string,
   caching?: { sMaxAge: number; staleWhileRevalidate: number },
+  images?: ImagesRenderInfo,
 ): 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
@@ -836,7 +869,7 @@ async function renderGetCandidate(
   const runtime = new SessionRuntime(sessionId, store)
   try {
     await runtime.loadGraph(route.reads)
-    const result = await renderRoute(route, routeKey, sessionId, runtime, request)
+    const result = await renderRoute(route, routeKey, sessionId, runtime, request, { images })
     let html = result.html
 
     const headHtml: string[] = []

package/src/server/images.ts

@@ -0,0 +1,426 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+
+/**
+ * Framework image serving — the promotion of the pattern proven in
+ * `examples/indie-blog` (spec `images-are-part-of-stator-*`). Mounted only
+ * when `stator.config.ts` declares `images: { dir }`; an unconfigured app has
+ * no routes here and never loads a transformer.
+ *
+ * The contract, unchanged from the proof: the URL's **extension is the
+ * delivery format** (request `x.webp` of a stored `x.jpg` and the endpoint
+ * converts — it never lies about an extension; there is no Accept-header or
+ * user-agent negotiation, ever), `?w=` resizes to an allowlisted width, and
+ * `?w=&h=` cover-crops to an exact box — BOTH dimensions must come from the
+ * allowlist, so the variant space stays bounded (widths² at worst, never an
+ * open crop parameter). Variants cache on disk beside the originals
+ * (`.variants/`), regenerated when the original is newer. GIFs serve as
+ * originals only — animation does not survive naive resizing.
+ */
+
+/**
+ * The transformer seam: pure bytes-in/bytes-out, so the default (sharp) is
+ * swappable for another library. The framework owns everything around it —
+ * path resolution, the disk cache, conditional GET — adapters only transform.
+ */
+export interface ImageTransformer {
+  /** Intrinsic dimensions. Called at WRITE time by app upload handlers (via
+   *  `probeImage`), never during a render — dimensions are data, not IO. */
+  probe(bytes: Uint8Array): Promise<{ width: number | null; height: number | null }>
+  /** Resize (optional) and/or re-encode to `format`. Width alone never
+   *  enlarges; width+height is an exact cover-cropped box (art direction
+   *  needs predictable geometry, so enlargement is allowed there). */
+  transform(
+    input: Uint8Array,
+    opts: { width?: number; height?: number; format: 'jpeg' | 'png' | 'webp' | 'avif' },
+  ): Promise<Uint8Array>
+}
+
+/** Impl #1: sharp, imported lazily so image-free processes never load it.
+ *  `threads` caps the libvips worker pool (process-global — libvips has one
+ *  pool). sharp's default is the REPORTED core count, which on a shared-cpu
+ *  host is the physical machine's (8+ on Fly shared-cpu-1x) — every encode
+ *  then fans out that many threads' worth of encoder buffers and CPU demand
+ *  on a fractional vCPU. A big AVIF encode under that fan-out is what
+ *  swap-thrashed a 512MB host into a lockup. 0 = leave sharp's default. */
+export function sharpTransformer(threads = 0): ImageTransformer {
+  const load = async () => {
+    const { default: sharp } = await import('sharp')
+    if (threads > 0) sharp.concurrency(threads)
+    return sharp
+  }
+  return {
+    async probe(bytes) {
+      const sharp = await load()
+      const meta = await sharp(bytes).metadata()
+      // Report DISPLAY dimensions: EXIF orientations 5-8 transpose the
+      // raster, and these dims feed width/height attributes (the CLS box)
+      // for pixels that transform() serves upright — raw stored dims would
+      // reserve a sideways box for every portrait phone photo.
+      const swap = (meta.orientation ?? 1) >= 5
+      return {
+        width: (swap ? meta.height : meta.width) ?? null,
+        height: (swap ? meta.width : meta.height) ?? null,
+      }
+    },
+    async transform(input, opts) {
+      const sharp = await load()
+      // rotate() with no args bakes the EXIF orientation into the pixels
+      // (and re-encoding drops the tag) — without it every variant of a
+      // portrait phone photo comes out sideways, because encoders write the
+      // raster as stored and the orientation tag is what dies in transit.
+      let pipeline = sharp(input).rotate()
+      if (opts.width !== undefined && opts.height !== undefined) {
+        pipeline = pipeline.resize({ width: opts.width, height: opts.height, fit: 'cover' })
+      } else if (opts.width !== undefined) {
+        pipeline = pipeline.resize({ width: opts.width, withoutEnlargement: true })
+      }
+      // AVIF effort 2 (sharp's default is 4): the encoder's CPU/density
+      // trade, NOT a visual-quality knob. On-demand serving means a real
+      // visitor is waiting on the first encode — measured 16s at effort 4 on
+      // a shared-cpu host vs a few seconds at 2, for files a few percent
+      // larger. A build step would choose density; an on-demand endpoint
+      // chooses the visitor.
+      const encoded =
+        opts.format === 'avif' ? pipeline.avif({ effort: 2 }) : pipeline.toFormat(opts.format)
+      return new Uint8Array(await encoded.toBuffer())
+    },
+  }
+}
+
+export const DEFAULT_IMAGE_WIDTHS = [400, 800, 1200, 1600]
+
+/** Crop aspect allowlist (width/height): square, the photographic landscape
+ *  trio, and their portrait duals. A crop `?w=&h=` is valid iff `w` is an
+ *  allowlisted width AND `h === round(w / a)` for an allowlisted aspect — the
+ *  variant space stays finite (|widths| x |aspects|) while the aspects people
+ *  actually shoot in (16:9, 3:2, 4:3) all work. (The first cut required
+ *  `h ∈ widths`, which silently forbade every non-square aspect — caught in
+ *  review before the URL grammar froze.) */
+export const DEFAULT_IMAGE_ASPECT_RATIOS = [1, 4 / 3, 3 / 2, 16 / 9, 3 / 4, 2 / 3, 9 / 16]
+
+/** What the render side needs to emit URLs the endpoint will accept — carried
+ *  on the render state so `<Image>`/`<Picture>` can't drift from config. */
+export interface ImagesRenderInfo {
+  widths: number[]
+  aspectRatios: number[]
+}
+
+export const IMAGE_CONTENT_TYPES: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+}
+
+const TRANSCODE_TARGETS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif'])
+
+/** Originals-only formats: served verbatim, never a transcode SOURCE either.
+ *  GIF because animation doesn't survive naive resizing; SVG because it's a
+ *  vector document, not pixels — nothing to probe, resize, or rasterize
+ *  (found via an imported favicon living in the media store, where an
+ *  uploading admin legitimately puts it). */
+const ORIGINAL_ONLY_SOURCES = new Set(['gif', 'svg'])
+
+/** SVG is the one format that can execute script when navigated to directly
+ *  (fine inside <img>/favicon contexts, which ignore scripts). Serve it like
+ *  GitHub serves avatars: scripts and external loads neutralized, inline
+ *  styles allowed, sniffing pinned. */
+const SVG_SECURITY_HEADERS = {
+  'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+  'X-Content-Type-Options': 'nosniff',
+}
+
+/** Cold-cache stampede guard: N concurrent requests for the same missing
+ *  variant share one encode instead of N. Keyed by cache path. */
+const inflight = new Map<string, Promise<void>>()
+
+/** sha1-16 of an original's bytes, memoized per path with `(size, mtime)` as
+ *  the recompute key — mtime demoted from identity to cache hint, its correct
+ *  role. Same shape and truncation as the query-route `revision()` ledger. */
+const hashCache = new Map<string, { size: number; mtimeMs: number; hash: string }>()
+function originalHash(full: string): string {
+  const st = statSync(full)
+  const hit = hashCache.get(full)
+  if (hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.hash
+  const hash = createHash('sha1').update(readFileSync(full)).digest('hex').slice(0, 16)
+  hashCache.set(full, { size: st.size, mtimeMs: st.mtimeMs, hash })
+  return hash
+}
+
+/** The freshness dial (spec: image-caching, adjudicated 2026-08-30 — a dial,
+ *  not an immutable boolean, because over-caching has no server-side
+ *  recovery). Defaults preserve the conservative revalidation contract;
+ *  `staleWhileRevalidate` trades must-revalidate for background self-healing
+ *  (SWR forbids what must-revalidate demands, so they never co-emit);
+ *  `immutable` appends only on top of an explicit long maxAge. */
+function cacheControlValue(config: ResolvedImagesConfig): string {
+  const { maxAge, staleWhileRevalidate: swr, immutable } = config
+  if (maxAge === 0 && swr === 0) return 'public, max-age=0, must-revalidate'
+  let value = `public, max-age=${maxAge}`
+  if (swr > 0) value += `, stale-while-revalidate=${swr}`
+  if (immutable && maxAge > 0) value += ', immutable'
+  return value
+}
+
+/** Global encode semaphore — DIFFERENT variants queue behind a small number
+ *  of concurrent transforms. Without it, one cold-cache gallery page fans a
+ *  dozen simultaneous sharp encodes (AVIF is memory-brutal) and OOM-kills a
+ *  small host — found the first hour tonysull.co ran on a 512MB Fly machine.
+ *  Module-level on purpose: the resource being protected (CPU/memory) is
+ *  process-wide, whatever app object serves the request. */
+let activeTransforms = 0
+const transformQueue: Array<() => void> = []
+function acquireTransformSlot(limit: number): Promise<void> {
+  return new Promise((resolve) => {
+    if (activeTransforms < limit) {
+      activeTransforms += 1
+      resolve()
+    } else {
+      transformQueue.push(() => {
+        activeTransforms += 1
+        resolve()
+      })
+    }
+  })
+}
+function releaseTransformSlot(): void {
+  activeTransforms -= 1
+  transformQueue.shift()?.()
+}
+
+export interface ResolvedImagesConfig {
+  dir: string
+  /** URL prefix (leading slash, no trailing). */
+  path: string
+  widths: number[]
+  aspectRatios: number[]
+  transformer: ImageTransformer
+  /** Max concurrent encodes across ALL variants (default 2). */
+  concurrency: number
+  /** libvips worker threads per encode (default 0 = sharp's default). */
+  threads: number
+  /** Encode deadline per request (default 15000ms; 0 disables). Past it the
+   *  response degrades to a 302 at the stored original — honest bytes now —
+   *  while the encode keeps filling the cache for the next request. */
+  encodeTimeoutMs: number
+  /** Freshness lifetime in seconds (default 0 = revalidate every use). */
+  maxAge: number
+  /** Serve-stale window in seconds (default 0). >0 lets a cache render its
+   *  copy instantly and revalidate in the background — bounded regret. */
+  staleWhileRevalidate: number
+  /** Append `immutable` to a long maxAge — the no-recovery marker; only for
+   *  apps whose image URLs are write-once by construction. */
+  immutable: boolean
+}
+
+export function resolveImagesConfig(config: {
+  dir: string
+  path?: string
+  widths?: number[]
+  aspectRatios?: number[]
+  transformer?: ImageTransformer
+  concurrency?: number
+  threads?: number
+  encodeTimeoutMs?: number
+  maxAge?: number
+  staleWhileRevalidate?: number
+  immutable?: boolean
+}): ResolvedImagesConfig {
+  const dir = resolve(config.dir)
+  const path = (config.path ?? `/${basename(dir)}`).replace(/\/$/, '')
+  const threads = Math.max(0, config.threads ?? 0)
+  return {
+    dir,
+    path: path.startsWith('/') ? path : `/${path}`,
+    widths: config.widths ?? DEFAULT_IMAGE_WIDTHS,
+    aspectRatios: config.aspectRatios ?? DEFAULT_IMAGE_ASPECT_RATIOS,
+    transformer: config.transformer ?? sharpTransformer(threads),
+    concurrency: Math.max(1, config.concurrency ?? 2),
+    threads,
+    encodeTimeoutMs: Math.max(0, config.encodeTimeoutMs ?? 15_000),
+    maxAge: Math.max(0, config.maxAge ?? 0),
+    staleWhileRevalidate: Math.max(0, config.staleWhileRevalidate ?? 0),
+    immutable: config.immutable ?? false,
+  }
+}
+
+/** Write-time probe for app upload handlers — the render never does this.
+ *  Defaults to the sharp transformer; pass your configured one if you swapped
+ *  it. (First dogfood finding: an earlier signature took the whole resolved
+ *  config, which apps don't hold — bytes + optional transformer is the shape
+ *  an upload handler actually has in hand.) */
+export async function probeImage(
+  bytes: Uint8Array,
+  transformer: ImageTransformer = sharpTransformer(),
+): Promise<{ width: number | null; height: number | null }> {
+  return transformer.probe(bytes)
+}
+
+/** Find the stored original for a requested relative path, whatever its
+ *  extension — containment-checked against the images dir. */
+function resolveOriginal(
+  config: ResolvedImagesConfig,
+  rel: string,
+): { full: string; ext: string } | null {
+  const dot = rel.lastIndexOf('.')
+  if (dot === -1) return null
+  // No dotfile path segments: keeps the `.variants/` cache (and anything
+  // hidden) unreachable through the endpoint — no variants-of-variants.
+  if (rel.split('/').some((seg) => seg.startsWith('.'))) return null
+  const base = rel.slice(0, dot)
+  for (const ext of Object.keys(IMAGE_CONTENT_TYPES)) {
+    const full = resolve(config.dir, `${base}.${ext}`)
+    if (!full.startsWith(config.dir + sep)) return null
+    if (existsSync(full)) return { full, ext }
+  }
+  return null
+}
+
+/**
+ * Serve one image request: `rel` is the path under the endpoint prefix,
+ * `widthParam` the raw `?w=` value (undefined = original size). Returns a
+ * complete `Response` — 200 with caching headers, 304 on a validator match,
+ * 400 for an off-allowlist width, 404 otherwise.
+ */
+export async function serveImage(
+  config: ResolvedImagesConfig,
+  rel: string,
+  widthParam: string | undefined,
+  heightParam: string | undefined,
+  ifNoneMatch: string | null,
+): Promise<Response> {
+  let width: number | undefined
+  if (widthParam !== undefined) {
+    width = Number(widthParam)
+    if (!config.widths.includes(width)) {
+      return new Response(`w must be one of ${config.widths.join(', ')}`, { status: 400 })
+    }
+  }
+  let height: number | undefined
+  if (heightParam !== undefined) {
+    // A crop needs both axes: `w` from the width allowlist, `h` derived from
+    // an allowlisted aspect — the finite-variant DoS bound, |widths|x|aspects|.
+    height = Number(heightParam)
+    const w = width
+    if (w === undefined || !config.aspectRatios.some((a) => height === Math.round(w / a))) {
+      return new Response('h requires w, and w/h must match an allowlisted aspect', { status: 400 })
+    }
+  }
+
+  const dot = rel.lastIndexOf('.')
+  const requestedExt = rel.slice(dot + 1).toLowerCase()
+  const contentType = IMAGE_CONTENT_TYPES[requestedExt]
+  if (!contentType) return new Response('not found', { status: 404 })
+
+  const original = resolveOriginal(config, rel)
+  if (!original) return new Response('not found', { status: 404 })
+
+  // Content-hash validators (spec: image-caching). ETags are per-URL and the
+  // transform params ARE the URL, so hash(original) is the complete entropy;
+  // the params suffix on variants is labeling for humans, not identity. The
+  // encoder is deliberately excluded (an upgrade must not mass-bust visually
+  // identical pixels) — which breaks the byte-identity promise a strong ETag
+  // makes, so variants carry WEAK validators; originals stay strong.
+  let hash: string
+  try {
+    hash = originalHash(original.full)
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+  const sameFormat =
+    IMAGE_CONTENT_TYPES[original.ext] === contentType && width === undefined && height === undefined
+  const sizeLabel = `${width ?? 'orig'}${height !== undefined ? `x${height}` : ''}`
+  const etag = sameFormat ? `"${hash}"` : `W/"${hash}-${sizeLabel}-${requestedExt}"`
+  const headers = {
+    'Content-Type': contentType,
+    ETag: etag,
+    'Cache-Control': cacheControlValue(config),
+    ...(requestedExt === 'svg' ? SVG_SECURITY_HEADERS : undefined),
+  }
+  // Early 304 — validators derive from the ORIGINAL, so a match answers
+  // before any encode work (or even a variant file) exists.
+  const bare = etag.replace(/^W\//, '')
+  if (ifNoneMatch?.split(',').some((t) => t.trim().replace(/^W\//, '') === bare)) {
+    return new Response(null, { status: 304, headers })
+  }
+
+  let file: string
+  if (sameFormat) {
+    file = original.full
+  } else {
+    if (!TRANSCODE_TARGETS.has(requestedExt) || ORIGINAL_ONLY_SOURCES.has(original.ext)) {
+      return new Response('not found', { status: 404 })
+    }
+    // The source-hash lives IN the cache filename: freshness is a pure
+    // existence check — a changed original hashes to a different name and
+    // simply misses. (Replaces mtime comparison, which mtime-preserving and
+    // mtime-resetting copies each fooled in one direction. Stale-hash
+    // siblings are identifiable garbage for a future `stator images gc`.)
+    const cache = join(
+      config.dir,
+      '.variants',
+      `${rel.slice(0, dot)}-${hash.slice(0, 8)}-${sizeLabel}.${requestedExt}`,
+    )
+    if (!existsSync(cache)) {
+      let job = inflight.get(cache)
+      if (!job) {
+        const format =
+          requestedExt === 'jpg' ? 'jpeg' : (requestedExt as 'jpeg' | 'png' | 'webp' | 'avif')
+        job = (async () => {
+          await acquireTransformSlot(config.concurrency)
+          try {
+            const out = await config.transformer.transform(
+              new Uint8Array(await readFile(original.full)),
+              { width, height, format },
+            )
+            mkdirSync(dirname(cache), { recursive: true })
+            const { writeFile } = await import('node:fs/promises')
+            await writeFile(cache, out)
+          } finally {
+            releaseTransformSlot()
+          }
+        })().finally(() => inflight.delete(cache))
+        inflight.set(cache, job)
+      }
+      // The on-demand contract is "first requester sees a SMALL delay" —
+      // enforce it. A pathological encode (large AVIF on a starved host) can
+      // take 30s+ or swap-thrash the machine; past the deadline this request
+      // degrades to the stored original (a redirect, so the Content-Type
+      // stays honest) while the encode keeps running to fill the cache. The
+      // browser renders real pixels now; the next visitor gets the variant.
+      if (config.encodeTimeoutMs > 0) {
+        const finished = await new Promise<boolean>((done) => {
+          const timer = setTimeout(() => done(false), config.encodeTimeoutMs)
+          const settle = () => {
+            clearTimeout(timer)
+            done(true) // rejection included — the `await job` below rethrows it
+          }
+          job.then(settle, settle)
+        })
+        if (!finished) {
+          return new Response(null, {
+            status: 302,
+            headers: {
+              Location: `${config.path}/${rel.slice(0, dot)}.${original.ext}`,
+              'Cache-Control': 'no-store',
+            },
+          })
+        }
+      }
+      await job
+    }
+    file = cache
+  }
+
+  try {
+    return new Response(new Uint8Array(await readFile(file)), { headers })
+  } catch {
+    return new Response('not found', { status: 404 })
+  }
+}

package/src/server/index.ts

@@ -52,6 +52,13 @@ export {
 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'

package/src/server/render-context.ts

@@ -139,6 +139,7 @@ export function makeScope(prefix: string): Scope {
 }
 
 export interface RenderState {
+  images?: import('./images.ts').ImagesRenderInfo
   sessionId: SessionId
   routeKey: string
   bindings: Map<SlotId, Binding>
@@ -186,6 +187,14 @@ export function createRenderState(sessionId: SessionId, routeKey: string): Rende
 
 let currentRenderState: RenderState | null = null
 
+/** The images config as the render side sees it (set by renderRoute from
+ *  HttpConfig). Components read it so their srcset widths and crop aspects
+ *  can't drift from what the endpoint accepts; null outside a configured
+ *  render (tests, apps without `images`). */
+export function currentImages(): import('./images.ts').ImagesRenderInfo | null {
+  return currentRenderState?.images ?? null
+}
+
 export function getCurrentRenderState(): RenderState | null {
   return currentRenderState
 }

package/src/server/render.ts

@@ -95,6 +95,8 @@ export interface RenderRouteOptions {
    *  passes false: it runs under the session lock and must not kick defer I/O;
    *  its defer slots emit inert placeholders that the diff never touches. */
   resolveDeferred?: boolean
+  /** Endpoint widths/aspects for `<Image>`/`<Picture>` (see RenderState.images). */
+  images?: import('./images.ts').ImagesRenderInfo
 }
 
 export async function renderRoute(
@@ -107,6 +109,7 @@ export async function renderRoute(
 ): Promise<RenderResult> {
   const state = createRenderState(sessionId, routeKey)
   state.resolveDeferred = opts.resolveDeferred ?? true
+  state.images = opts.images
   const { ctx: responseCtx, effects } = createResponseContext()
   const renderCtx: RouteRenderContext = {
     response: responseCtx,