@statorjs/stator 2.10.0 → 2.11.0-next.1

package/src/components/images.ts

@@ -0,0 +1,253 @@
+import { DEFAULT_IMAGE_WIDTHS } from '../server/images.ts'
+import { currentImages } from '../server/render-context.ts'
+
+/**
+ * `getImage()`/`getPicture()` — pure math over provided dimensions, no
+ * markup (endpoint in `server/images.ts`). The `<Image>`/`<Picture>` markup
+ * components are `image.stator`/`picture.stator` in this directory; these
+ * two plus `SOURCE_TYPES` (the format→mime-type map) stay exported here as
+ * the public escape hatch for a custom art-direction component.
+ *
+ * `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
+  }
+
+/** 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[]
+}
+
+/** `<source type>` for each delivery format — exported alongside `getPicture`
+ *  so a hand-rolled `<picture>` (art direction the first-party `<Picture>`
+ *  doesn't cover) can build its own `<source>` tags from `getImage`/
+ *  `getPicture` output without re-deriving this mapping. */
+export const SOURCE_TYPES: Record<ImageFormat, string> = {
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  webp: 'image/webp',
+  avif: 'image/avif',
+}
+
+/** One resolved `<source>` candidate, most-specific (art-directed) first. */
+export interface ResolvedPictureSource {
+  media?: string
+  format: ImageFormat
+  srcset: string
+  sizes: string
+}
+
+export interface ResolvedPicture {
+  /** `<source>` candidates — empty when `src` is remote or no candidate
+   *  produced a srcset, in which case only `image` (the plain `<img>`) applies. */
+  sources: ResolvedPictureSource[]
+  /** The fallback `<img>`'s own resolved data — same shape `getImage()` returns,
+   *  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). */
+  image: ResolvedImage
+}
+
+/** Pure `<picture>` math: every `<source>` candidate's resolved srcset plus
+ *  the fallback `<img>`'s own resolved data — no markup. `<Picture>` renders
+ *  this; a custom art-direction component that needs a different `<picture>`
+ *  shape than `<Picture>` offers can call this directly instead. */
+export function getPicture(props: PictureProps): ResolvedPicture {
+  const { formats = ['avif', 'webp'], sources: artSources = [], sizes = '100vw', ...rest } = props
+  const imageProps = { ...rest, sizes } as ImageProps
+  const image = getImage(imageProps)
+  if (isRemote(rest.src)) return { sources: [], image }
+
+  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) => ({
+      format,
+      srcset: getImage({ ...imageProps, format }).srcset,
+      sizes,
+    }))
+    .filter((s) => s.srcset !== null)
+
+  return { sources: [...art, ...plain] as ResolvedPictureSource[], image }
+}

package/src/components/index.ts

@@ -1,2 +1,18 @@
+// Compiled sibling, not the raw `.stator` source — keep fresh with
+// `pnpm build:components`.
+export { default as Image } from './image.stator.ts'
+export type {
+  GetImageOptions,
+  ImageFormat,
+  ImageLoading,
+  ImageProps,
+  PictureProps,
+  PictureSource,
+  ResolvedImage,
+  ResolvedPicture,
+  ResolvedPictureSource,
+} from './images.ts'
+export { getImage, getPicture, SOURCE_TYPES } from './images.ts'
 export type { JsonLdProps } from './json-ld.ts'
 export { JsonLd, ldToString } from './json-ld.ts'
+export { default as Picture } from './picture.stator.ts'

package/src/components/picture.stator

@@ -0,0 +1,17 @@
+---
+import { getPicture, SOURCE_TYPES, type PictureProps } from './images.ts'
+import Image from './image.stator'
+
+const p = Stator.props<PictureProps>()
+const { sources } = getPicture(p)
+---
+{sources.length === 0 ? (
+  <Image {...p} />
+) : (
+  <picture>
+    {each(sources, (s) => (
+      <source media={s.media} type={SOURCE_TYPES[s.format]} srcset={s.srcset} sizes={s.sizes} />
+    ))}
+    <Image {...p} />
+  </picture>
+)}

package/src/components/picture.stator.ts

@@ -0,0 +1,21 @@
+import {
+  classList,
+  defer,
+  each,
+  html,
+  itemBind,
+  match,
+  on,
+  read,
+  spreadAttrs,
+  styleList,
+  when,
+} from '@statorjs/stator/template'
+import Image from './image.stator.ts'
+import { getPicture, type PictureProps, SOURCE_TYPES } from './images.ts'
+
+export default function (props: PictureProps) {
+  const p = props
+  const { sources } = getPicture(p)
+  return html`${sources.length === 0 ? html`${Image({ ...p })}` : html`<picture>${each(sources, (s) => html`<source media="${s.media}" type="${SOURCE_TYPES[s.format]}" srcset="${s.srcset}" sizes="${s.sizes}" />`)}${Image({ ...p })}</picture>`}`
+}

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[]
@@ -73,8 +90,8 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   host?: string
   /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
-  /** Extra `<head>` HTML per GET route. A production build uses this to link the
-   *  prebuilt `components.css`; ignored if omitted. */
+  /** Extra `<head>` HTML per GET route. A production build uses this to link
+   *  that route's own prebuilt scoped-CSS artifact; ignored if omitted. */
   headExtras?: (filePath: string) => string | Promise<string>
   /** Path to the app's `middleware.ts` (if any). Loaded and validated; its
    *  default export must be `defineMiddleware`/`dangerouslyDefineMiddleware`. */
@@ -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

@@ -16,6 +16,7 @@ import {
   routeIslandMap,
   walkFiles,
 } from '../build/islands.ts'
+import { bareSpecifiersOf, externalCss } from '../build/route-css.ts'
 import { sourceId } from '../build/source-id.ts'
 import { CompileError, compile, formatCompileError, regionResolverFor } from '../compiler/index.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
@@ -29,6 +30,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'
@@ -58,8 +60,8 @@ import { InMemoryStore } from './store.ts'
  *    graph serving and renders the error (with its code frame) in an overlay.
  *  - **Scoped CSS + island scripts** — islands bundle through the
  *    `bundleIslands` seam (Vite today, never on the SSR path) and are served
- *    from memory with the concatenated scoped CSS, on the same URLs and with
- *    the same `<head>` shape as production.
+ *    from memory with the concatenated scoped CSS, local and `node_modules`
+ *    alike, on the same URLs and with the same `<head>` shape as production.
  *
  * See spec `toolchain-adapter-seam-and-the-vite-exit`.
  */
@@ -133,6 +135,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
@@ -162,6 +165,9 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
   const versions = new Map<string, number>()
   const forward = new Map<string, Set<string>>()
   const importers = new Map<string, Set<string>>()
+  // Bare specifiers each app file imports directly, feeding the CSS
+  // aggregate below via each package's own sibling `.css` (`externalCss`).
+  const externalSpecs = new Map<string, Set<string>>()
   let seq = 0
   const acks = new Map<number, () => void>()
   port1.on('message', (m: { type?: string; id?: number }) => {
@@ -272,11 +278,16 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     }
   }
   const updateEdges = async (files: string[]): Promise<void> => {
-    for (const f of files) setEdges(f, new Set((await localImports(f, root)).filter(isAppFile)))
+    for (const f of files) {
+      const [local, external] = await Promise.all([localImports(f, root), bareSpecifiersOf(f)])
+      setEdges(f, new Set(local.filter(isAppFile)))
+      externalSpecs.set(f, new Set(external))
+    }
   }
   const buildGraph = async (): Promise<void> => {
     forward.clear()
     importers.clear()
+    externalSpecs.clear()
     await updateEdges(await walkFiles(root, (f) => APP_EXT.test(f), skipDir))
   }
   /** The changed files plus everything that (transitively) imports them. */
@@ -312,10 +323,17 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     }
   }
   let css = ''
-  const regenCss = (): void => {
-    css = ''
+  const regenCss = async (): Promise<void> => {
+    let next = ''
     for (const [file, info] of infos)
-      if (info.css) css += `/* ${sourceId(root, file).id} */\n${info.css}\n`
+      if (info.css) next += `/* ${sourceId(root, file).id} */\n${info.css}\n`
+    const packages = new Set<string>()
+    for (const specs of externalSpecs.values()) for (const spec of specs) packages.add(spec)
+    for (const spec of [...packages].sort()) {
+      const text = await externalCss(spec, root)
+      if (text) next += `/* ${spec} */\n${text}\n`
+    }
+    css = next
   }
 
   // ── Islands: bundled through the seam, held in memory ──────────────────────
@@ -428,6 +446,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,
@@ -446,7 +465,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
 
   await scanAll()
   await buildGraph()
-  regenCss()
+  await regenCss()
   await rebundleIslands()
   await rebuildStore()
   await rebuildServer()
@@ -475,7 +494,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
       }
       const affected = affectedBy(files)
       await bumpVersions(affected)
-      regenCss()
+      await regenCss()
       const needsBundle =
         structural || files.some((f) => islandGraph.has(norm(f)) || infos.get(f)?.isClient)
       if (needsBundle) {

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[] = []