@statorjs/stator 1.5.2 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "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 (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.5.2"
+    "@statorjs/stator": "1.6.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/client-id.ts

@@ -8,3 +8,12 @@ export const clientId: string =
   typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
     : `c${Math.random().toString(36).slice(2)}`
+
+/** Per-dispatch idempotency key: the server replays a duplicate POST's cached
+ *  response instead of re-applying it, which is what makes retrying a lost
+ *  response safe. Stable across retries of the SAME dispatch, never reused. */
+export function newEventId(): string {
+  return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+    ? crypto.randomUUID()
+    : `e${Math.random().toString(36).slice(2)}`
+}

package/src/client/dispatch.ts

@@ -1,7 +1,8 @@
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { applyDirectives, applyPatches } from '../wire/apply.ts'
 import type { WireEnvelope } from '../wire/index.ts'
-import { clientId } from './client-id.ts'
+import { newEventId } from './client-id.ts'
+import { type DispatchError, postEvent } from './transport.ts'
 
 export interface DispatchResult {
   /** The POST reached the server and returned 200. */
@@ -12,6 +13,8 @@ export interface DispatchResult {
   /** Patches applied to THIS page (a committed event may patch zero slots
    *  here if the touched machines aren't bound on the current route). */
   patchCount: number
+  /** Present only when `ok` is false — how the POST failed. */
+  error?: DispatchError
 }
 
 /**
@@ -30,28 +33,14 @@ export async function dispatch<D extends AnyMachineDef>(
   machine: D,
   event: EventOf<D>,
 ): Promise<DispatchResult> {
-  let res: Response
-  try {
-    res = await fetch('/__events', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        'X-Stator-Route': `GET ${location.pathname}${location.search}`,
-        'X-Stator-Client': clientId,
-      },
-      credentials: 'same-origin',
-      body: JSON.stringify({ machine: machine.name, event }),
-    })
-  } catch (err) {
-    console.error('stator: dispatch network error', err)
-    return { ok: false, committed: false, patchCount: 0 }
+  const result = await postEvent(
+    { machine: machine.name, event, eventId: newEventId() },
+    `GET ${location.pathname}${location.search}`,
+  )
+  if (!result.ok) {
+    return { ok: false, committed: false, patchCount: 0, error: result.error }
   }
-  if (!res.ok) {
-    console.error('stator: dispatch failed', res.status)
-    return { ok: false, committed: false, patchCount: 0 }
-  }
-  const data = (await res.json()) as WireEnvelope
+  const data = (await result.res.json()) as WireEnvelope
   applyPatches(data.patches ?? [])
   applyDirectives(data.directives ?? [])
   return {

package/src/client/index.ts

@@ -5,9 +5,11 @@
  */
 
 export { bind, effect } from './bind.ts'
+export type { DispatchResult } from './dispatch.ts'
 export { dispatch } from './dispatch.ts'
 export { defineElement, StatorElement } from './element.ts'
 export type { ClientBehavior, LegacyMachineConfig } from './machine.ts'
 export { machine } from './machine.ts'
+export type { DispatchError } from './transport.ts'
 export type { ClientInstance, ClientInstanceBase } from './use.ts'
 export { use } from './use.ts'

package/src/client/inspector.ts

@@ -155,6 +155,21 @@ function mount(): void {
     )
   })
 
+  window.addEventListener('stator:dispatch-error', (e: Event) => {
+    const { machine, phase, status, timestamp } = (e as CustomEvent).detail
+    addEntry(
+      'up',
+      `<div class="stator-inspector-summary">
+        <span class="stator-inspector-time">${fmtTime(timestamp)}</span>
+        <span class="stator-inspector-arrow">✕</span>
+        <span class="stator-inspector-machine">${escapeHtml(machine ?? 'form')}</span>
+        <span class="stator-inspector-event-type">${escapeHtml(phase)}</span>
+        <span class="stator-inspector-params">${status != null ? escapeHtml(String(status)) : ''}</span>
+      </div>`,
+      (e as CustomEvent).detail,
+    )
+  })
+
   window.addEventListener('stator:patches-received', (e: Event) => {
     const { patches, source, durationMs, timestamp } = (e as CustomEvent).detail
     const timing = durationMs != null ? `${durationMs}ms` : ''

package/src/client/runtime.ts

@@ -19,10 +19,35 @@
 
 import { applyDirectives, applyPatches } from '../wire/apply.ts'
 import type { WireEnvelope } from '../wire/index.ts'
-import { clientId } from './client-id.ts'
+import { clientId, newEventId } from './client-id.ts'
+import { emitDispatchError, fetchWithTimeout, postEvent, TimeoutError } from './transport.ts'
 
 const EVENT_TYPES = ['click', 'submit', 'change', 'input'] as const
 
+/* ------------------------------------------------------------------ */
+/* In-flight affordance                                                */
+/* ------------------------------------------------------------------ */
+
+/** `data-stator-pending` marks the element whose event POST is in flight
+ *  (CSS hook: `[data-stator-pending]`). Counted per element so rapid repeat
+ *  dispatches keep the attribute until the LAST one settles. */
+const pendingCounts = new WeakMap<Element, number>()
+
+function beginPending(el: Element): void {
+  pendingCounts.set(el, (pendingCounts.get(el) ?? 0) + 1)
+  el.setAttribute('data-stator-pending', '')
+}
+
+function endPending(el: Element): void {
+  const count = (pendingCounts.get(el) ?? 1) - 1
+  if (count <= 0) {
+    pendingCounts.delete(el)
+    el.removeAttribute('data-stator-pending')
+  } else {
+    pendingCounts.set(el, count)
+  }
+}
+
 /* ------------------------------------------------------------------ */
 /* Observability hooks                                                 */
 /* ------------------------------------------------------------------ */
@@ -42,44 +67,29 @@ function init(): void {
   initLiveChannel()
 }
 
-function initLiveChannel(): void {
+function initLiveChannel(): { close(): void } | undefined {
   const meta = document.querySelector('meta[name="stator-live"][content="true"]')
   if (!meta) return
 
   const routeKey = `GET ${location.pathname}${location.search}`
   const url = `/__sse?route=${encodeURIComponent(routeKey)}&client=${encodeURIComponent(clientId)}`
-  const sse = new EventSource(url, { withCredentials: true })
 
-  let everOpened = false
-  let lastSeen = Date.now()
-  sse.addEventListener('open', () => {
-    if (everOpened) {
-      // Reconnect — reload rather than risk stale state.
-      location.reload()
-      return
-    }
-    everOpened = true
-  })
-
-  // Zombie watchdog. A half-open connection (device sleep, silent NAT drop)
-  // never fires `error` — EventSource just sits "open" and silent forever,
-  // and the page quietly stops being live. The server sends an observable
-  // ping every 25s; two missed pings while the page is VISIBLE means the
-  // channel is dead, and a reload re-syncs (same strategy as reconnect).
-  // Hidden tabs wait for visibility — no reloading pages nobody is watching.
-  const STALE_MS = 65_000
-  const staleReload = (): void => {
-    if (!everOpened || document.hidden) return
-    if (Date.now() - lastSeen > STALE_MS) {
-      console.warn('stator: SSE channel stale — reloading to re-sync')
-      sse.close()
-      location.reload()
-    }
+  // Connection-state signal: `data-stator-connection` on the root element
+  // (CSS hook for offline banners etc.) plus a `stator:connection-state`
+  // event. Change-guarded — EventSource fires `error` on every failed
+  // auto-reconnect attempt, and only transitions are worth announcing.
+  let connectionState: string | undefined
+  const setConnectionState = (state: 'connected' | 'disconnected' | 'stale'): void => {
+    if (state === connectionState) return
+    connectionState = state
+    document.documentElement.setAttribute('data-stator-connection', state)
+    emit('stator:connection-state', { state, timestamp: Date.now() })
   }
-  setInterval(staleReload, 10_000)
-  document.addEventListener('visibilitychange', staleReload)
 
-  sse.addEventListener('message', (e) => {
+  let sse: EventSource | null = null
+  let lastSeen = Date.now()
+
+  const onMessage = (e: MessageEvent): void => {
     lastSeen = Date.now()
     let data: WireEnvelope
     try {
@@ -103,13 +113,57 @@ function initLiveChannel(): void {
     if (data.directives && data.directives.length > 0) {
       applyDirectives(data.directives)
     }
-  })
+  }
 
-  sse.addEventListener('error', () => {
-    if (sse.readyState === EventSource.CLOSED) {
-      console.warn('stator: SSE permanently closed')
+  // Reconnect = resync, never reload. Every fresh /__sse connection gets the
+  // server's initial sync (every binding's current value, keyed lists reset
+  // wholesale), so a rebuilt channel converges the DOM in place — and the
+  // browser's own auto-reconnect on the same instance re-runs that server
+  // path too, its sync arriving as an ordinary message. Directives fired
+  // during an outage (e.g. a navigate) are not replayed; resync converges
+  // state only.
+  const connect = (): void => {
+    sse?.close()
+    const es = new EventSource(url, { withCredentials: true })
+    sse = es
+    lastSeen = Date.now() // fresh grace period — no instant re-stale loop
+    es.addEventListener('open', () => setConnectionState('connected'))
+    es.addEventListener('message', onMessage)
+    es.addEventListener('error', () => {
+      setConnectionState('disconnected')
+      if (es.readyState === EventSource.CLOSED) {
+        console.warn('stator: SSE permanently closed')
+      }
+    })
+  }
+
+  // Zombie watchdog. A half-open connection (device sleep, silent NAT drop)
+  // never fires `error` — EventSource just sits "open" and silent forever,
+  // and the page quietly stops being live. The server sends an observable
+  // ping every 25s; two missed pings while the page is VISIBLE means the
+  // channel is dead, and a rebuilt connection re-syncs. Hidden tabs wait for
+  // visibility — no churn for pages nobody is watching.
+  const STALE_MS = 65_000
+  const checkStale = (): void => {
+    if (document.hidden) return
+    if (Date.now() - lastSeen > STALE_MS) {
+      console.warn('stator: SSE channel stale — reconnecting to re-sync')
+      setConnectionState('stale')
+      connect()
     }
-  })
+  }
+  const watchdog = setInterval(checkStale, 10_000)
+  document.addEventListener('visibilitychange', checkStale)
+
+  connect()
+
+  return {
+    close(): void {
+      clearInterval(watchdog)
+      document.removeEventListener('visibilitychange', checkStale)
+      sse?.close()
+    },
+  }
 }
 
 function handleEvent(e: Event): void {
@@ -131,7 +185,7 @@ function handleEvent(e: Event): void {
           console.error('stator: malformed event descriptor on form', form, descriptorAttr)
           return
         }
-        void dispatchEvent(descriptor)
+        void dispatchEvent(descriptor, form)
         return
       }
       // Opt-in interception via `data-stator-enhance`. Plain forms without
@@ -168,13 +222,13 @@ function handleEvent(e: Event): void {
     return
   }
 
-  void dispatchEvent(descriptor)
+  void dispatchEvent(descriptor, el)
 }
 
-async function dispatchEvent(descriptor: {
-  machine: string
-  event: { type: string }
-}): Promise<void> {
+async function dispatchEvent(
+  descriptor: { machine: string; event: { type: string } },
+  el?: Element,
+): Promise<void> {
   const routeKey = `GET ${location.pathname}${location.search}`
 
   emit('stator:event-sent', {
@@ -185,28 +239,14 @@ async function dispatchEvent(descriptor: {
   })
 
   const startedAt = performance.now()
-  let res: Response
+  if (el) beginPending(el)
   try {
-    res = await fetch('/__events', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json',
-        'X-Stator-Route': routeKey,
-        'X-Stator-Client': clientId,
-      },
-      credentials: 'same-origin',
-      body: JSON.stringify(descriptor),
-    })
-  } catch (err) {
-    console.error('stator: network error during dispatch', err)
-    return
+    const result = await postEvent({ ...descriptor, eventId: newEventId() }, routeKey)
+    if (!result.ok) return
+    await applyEnvelopeFromResponse(result.res, startedAt, 'post')
+  } finally {
+    if (el) endPending(el)
   }
-  if (!res.ok) {
-    console.error('stator: event POST failed', res.status, await res.text())
-    return
-  }
-  await applyEnvelopeFromResponse(res, startedAt, 'post')
 }
 
 /**
@@ -217,23 +257,30 @@ async function dispatchEvent(descriptor: {
 async function submitForm(form: HTMLFormElement): Promise<void> {
   const formData = new FormData(form)
   const startedAt = performance.now()
-  let res: Response
+  beginPending(form)
   try {
-    res = await fetch(form.action, {
-      method: 'POST',
-      headers: { Accept: 'application/json' },
-      credentials: 'same-origin',
-      body: formData,
-    })
-  } catch (err) {
-    console.error('stator: network error during form submit', err)
-    return
-  }
-  if (!res.ok) {
-    console.error('stator: form submit failed', res.status, await res.text())
-    return
+    let res: Response
+    try {
+      res = await fetchWithTimeout(form.action, {
+        method: 'POST',
+        headers: { Accept: 'application/json' },
+        credentials: 'same-origin',
+        body: formData,
+      })
+    } catch (err) {
+      console.error('stator: network error during form submit', err)
+      emitDispatchError({ phase: err instanceof TimeoutError ? 'timeout' : 'network' }, {})
+      return
+    }
+    if (!res.ok) {
+      console.error('stator: form submit failed', res.status, await res.text())
+      emitDispatchError({ phase: 'http', status: res.status }, {})
+      return
+    }
+    await applyEnvelopeFromResponse(res, startedAt, 'post')
+  } finally {
+    endPending(form)
   }
-  await applyEnvelopeFromResponse(res, startedAt, 'post')
 }
 
 async function applyEnvelopeFromResponse(
@@ -268,3 +315,8 @@ if (document.readyState === 'loading') {
 } else {
   init()
 }
+
+// Exported for tests only — the runtime self-initializes above, and the
+// client bundle (esbuild IIFE) ignores exports. Re-calling init() is safe:
+// addEventListener dedupes an identical listener reference.
+export { init, initLiveChannel }

package/src/client/transport.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared POST transport for the two `/__events` callers — the delegated page
+ * runtime and island `dispatch()`. Lives apart from runtime.ts because that
+ * module self-initializes on import; islands importing `dispatch` must not
+ * drag the page runtime (and its document-wide listeners) into their bundle.
+ *
+ * Failure contract: network errors, timeouts, and non-2xx responses resolve
+ * (never throw) as `{ ok: false, error }`, and a `stator:dispatch-error`
+ * CustomEvent fires on window once per dispatch when the failure is final.
+ */
+
+import { clientId } from './client-id.ts'
+
+/** App-level deadline for event POSTs — browsers' own connection timeouts are
+ *  far too long to leave an interaction hanging on a flaky link. */
+export const FETCH_TIMEOUT_MS = 10_000
+
+/** Backoff before each retry of a network/timeout failure. Retries carry the
+ *  same eventId, so a duplicate that actually reached the server replays. */
+export const RETRY_DELAYS_MS = [300, 1000]
+
+export interface DispatchError {
+  phase: 'network' | 'timeout' | 'http'
+  /** HTTP status — present only for `phase: 'http'`. */
+  status?: number
+}
+
+/** Thrown by `fetchWithTimeout` when the deadline aborts the request, so
+ *  callers can tell a dead-slow connection from an unreachable one. */
+export class TimeoutError extends Error {
+  constructor() {
+    super(`request exceeded ${FETCH_TIMEOUT_MS}ms`)
+    this.name = 'TimeoutError'
+  }
+}
+
+function emit(name: string, detail: unknown): void {
+  window.dispatchEvent(new CustomEvent(name, { detail }))
+}
+
+export function emitDispatchError(
+  error: DispatchError,
+  context: { machine?: string; event?: { type: string } },
+): void {
+  emit('stator:dispatch-error', { ...context, ...error, timestamp: Date.now() })
+}
+
+/** `fetch` with the app-level deadline applied via AbortController. */
+export async function fetchWithTimeout(input: string, init: RequestInit): Promise<Response> {
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort()
+  }, FETCH_TIMEOUT_MS)
+  try {
+    return await fetch(input, { ...init, signal: controller.signal })
+  } catch (err) {
+    throw timedOut ? new TimeoutError() : err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export type PostEventResult = { ok: true; res: Response } | { ok: false; error: DispatchError }
+
+/**
+ * POST an event descriptor to `/__events`. Resolves — never throws — and
+ * emits `stator:dispatch-error` once when a failure is final. Network and
+ * timeout failures retry with backoff, but ONLY when the body carries an
+ * `eventId` (the server's replay cache is what makes a duplicate safe —
+ * keyed-list patches are not idempotent). Non-2xx responses are terminal
+ * immediately: the server saw the event and answered.
+ */
+export async function postEvent(
+  body: { machine: string; event: { type: string }; eventId?: string },
+  routeKey: string,
+): Promise<PostEventResult> {
+  let error: DispatchError
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const res = await fetchWithTimeout('/__events', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          'X-Stator-Route': routeKey,
+          'X-Stator-Client': clientId,
+        },
+        credentials: 'same-origin',
+        body: JSON.stringify(body),
+      })
+      if (res.ok) return { ok: true, res }
+      error = { phase: 'http', status: res.status }
+      console.error('stator: event POST failed', res.status, await res.text())
+      break
+    } catch (err) {
+      error = { phase: err instanceof TimeoutError ? 'timeout' : 'network' }
+      const delay = RETRY_DELAYS_MS[attempt]
+      if (delay === undefined || !body.eventId) {
+        console.error('stator: network error during dispatch', err)
+        break
+      }
+      console.warn(`stator: dispatch ${error.phase} — retrying in ${delay}ms`)
+      await new Promise((r) => setTimeout(r, delay))
+    }
+  }
+  emitDispatchError(error, body)
+  return { ok: false, error }
+}

package/src/engine/index.ts

@@ -13,6 +13,7 @@ export { defineMachine } from './define-machine.ts'
 export type {
   Action,
   ActionHelpers,
+  AfterEntry,
   AnyMachineDef,
   Capabilities,
   Effect,
@@ -20,6 +21,7 @@ export type {
   EffectMeta,
   EmitDeclaration,
   EmitsConfig,
+  EntryEffect,
   EventObject,
   EventOf,
   Guard,

package/src/server/api-route.ts

@@ -121,9 +121,17 @@ export async function runApiRoute(
       scheduleSessionEffects(runtime, store, effectsSessionId)
 
       // Escape hatch: handler returned a real Response. Pass through.
-      if (result instanceof Response) return result
+      if (isResponseLike(result)) return result
 
       const envelope = result as ApiRouteEnvelope
+      if (envelope.patches === undefined && envelope.directives === undefined) {
+        // Neither Response-shaped nor envelope-shaped: synthesizing an empty
+        // envelope would silently discard whatever the handler meant to send.
+        apiLog.warn(
+          { path: c.req.path },
+          'api route returned a value that is neither a Response nor a {patches, directives} envelope — treating it as an empty envelope',
+        )
+      }
       return synthesizeResponse(c, request, envelope)
     } finally {
       runtime.dispose()
@@ -131,6 +139,22 @@ export async function runApiRoute(
   })
 }
 
+/** `instanceof Response` alone misses Response objects from another realm or
+ *  a wrapping library (Vite SSR loaders, @hono/node-server's lightweight
+ *  class) — and a miss here silently reinterprets the handler's Response as
+ *  an envelope. Duck-type the shape the passthrough actually needs. */
+export function isResponseLike(v: unknown): v is Response {
+  if (v instanceof Response) return true
+  const r = v as Response | null
+  return (
+    typeof r === 'object' &&
+    r !== null &&
+    typeof r.status === 'number' &&
+    typeof r.headers?.get === 'function' &&
+    typeof r.arrayBuffer === 'function'
+  )
+}
+
 /** The Referer header is attacker-controllable, so redirecting back to it is an
  *  open-redirect vector. Return a same-origin relative path (pathname+search)
  *  when the referer matches this request's origin, else '/'. */

package/src/server/create-app.ts

@@ -1,5 +1,7 @@
 import { resolve } from 'node:path'
 import { serve } from '@hono/node-server'
+import type { AnyMachineDef, EventOf } from '../engine/index.ts'
+import { dispatchToApp } from './app-dispatch.ts'
 import type { AppStore } from './app-store.ts'
 import { installGracefulShutdown } from './banner.ts'
 import { discoverMachines } from './discovery.ts'
@@ -38,9 +40,16 @@ export interface StatorApp {
   listen(port: number): Promise<void>
   /** For tests — get the underlying Hono fetch handler. */
   fetch: (request: Request) => Response | Promise<Response>
-  /** The machine registry + app actors — pass to `dispatchToApp` for
-   *  server-originated events (webhooks, cron). */
+  /** The machine registry + app actors. Kept exposed for advanced use;
+   *  prefer the `dispatchToApp` method for server-originated events. */
   store: MachineStore
+  /** Server-originated dispatch to an APP-lifecycle machine — the entry
+   *  point for webhooks and cron. Same contract as the standalone
+   *  `dispatchToApp(store, …)`, bound to this app's store. */
+  dispatchToApp<D extends AnyMachineDef>(
+    machine: D,
+    event: EventOf<D>,
+  ): Promise<{ committed: boolean }>
 }
 
 export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
@@ -100,5 +109,6 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     },
     fetch: (request: Request) => app.fetch(request),
     store,
+    dispatchToApp: (machine, event) => dispatchToApp(store, machine, event),
   }
 }

package/src/server/dev.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { createServer as createHttpServer } from 'node:http'
 import { relative, resolve } from 'node:path'
@@ -5,12 +6,14 @@ import { getRequestListener } from '@hono/node-server'
 import type { Hono } from 'hono'
 import { createServer as createViteServer, type ViteDevServer } from 'vite'
 import { compile } from '../compiler/index.ts'
+import type { AnyMachineDef, EventOf } from '../engine/index.ts'
 import { machineStub, stator } from '../vite/index.ts'
 import type { AppStore } from './app-store.ts'
 import { findFreePort, installGracefulShutdown, printDevBanner } from './banner.ts'
 import { logger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
+import { isStatorQueryRoute } from './routing.ts'
 import type { Store } from './store.ts'
 
 /**
@@ -47,6 +50,16 @@ export interface DevAppConfig {
 export interface DevApp {
   fetch: (request: Request) => Response | Promise<Response>
   vite: ViteDevServer
+  /** Server-originated dispatch to an APP-lifecycle machine (webhooks, cron)
+   *  — the dev counterpart of `StatorApp.dispatchToApp`. Closes over the
+   *  current store (surviving machine-edit rebuilds) and runs through the
+   *  Vite-loaded runtime, so SSE fan-out reaches live connections; a
+   *  natively-imported `dispatchToApp` would be a second module instance
+   *  whose connection registry is empty. */
+  dispatchToApp<D extends AnyMachineDef>(
+    machine: D,
+    event: EventOf<D>,
+  ): Promise<{ committed: boolean }>
   listen: (port: number) => Promise<void>
   close: () => Promise<void>
 }
@@ -153,6 +166,19 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   }
   const rebuildRoutes = async (): Promise<void> => {
     routes = await runtime.discoverRoutes(routesDir, loader)
+    // Vite serves `public/` at the root ahead of Hono in dev, so a static
+    // file at a data route's URL silently wins. Warn at discovery time.
+    // (The brand is a plain property, so this native-import check works on
+    // defs the Vite-loaded runtime created.)
+    for (const r of routes) {
+      if (!r.GET || !isStatorQueryRoute(r.GET) || r.paramNames.length > 0) continue
+      if (existsSync(resolve(root, 'public', r.urlPath.slice(1)))) {
+        console.warn(
+          `stator: public/${r.urlPath.slice(1)} shadows the data route ${r.urlPath} in dev — ` +
+            `the static file wins. Rename one of them.`,
+        )
+      }
+    }
   }
   const rebuildServer = async (): Promise<void> => {
     app = await runtime.buildHonoApp({
@@ -204,6 +230,9 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
   return {
     fetch: (request) => app.fetch(request),
     vite,
+    // `store` is read at call time, not captured — a machine-edit rebuild
+    // swaps it and the method follows.
+    dispatchToApp: (machine, event) => runtime.dispatchToApp(store, machine, event),
     listen(port: number): Promise<void> {
       // Vite's middlewares serve client modules + HMR to the browser; anything
       // it doesn't handle (routes, /__events, /__sse) falls through to Hono.

package/src/server/event-dedupe.ts

@@ -0,0 +1,54 @@
+/**
+ * In-process replay cache for `/__events` idempotency keys. A retried POST
+ * whose first attempt committed (but whose response was lost on the wire)
+ * must not re-apply — keyed-list patches are positional and not idempotent —
+ * so the exact response body is cached per (session, eventId) and replayed
+ * verbatim on a duplicate.
+ *
+ * Module-level and in-process, like the SSE connection registry and timers:
+ * single-replica is a stated 1.0 constraint, and the cache carries the same
+ * non-durable contract (a restart forgets it — the retry window is seconds,
+ * the cost of a lost entry is one duplicate apply, and durable delivery is
+ * 1.x inbox work).
+ */
+
+/** Ample for the retry window (client retries at ~0.3s/1s); bounds memory. */
+const MAX_PER_SESSION = 32
+const SESSION_IDLE_MS = 30 * 60_000
+
+interface SessionCache {
+  /** eventId → serialized response body, insertion-ordered for eviction. */
+  byId: Map<string, string>
+  lastTouched: number
+}
+
+const sessions = new Map<string, SessionCache>()
+
+export function replayFor(sessionId: string, eventId: string): string | undefined {
+  const cache = sessions.get(sessionId)
+  if (!cache) return undefined
+  cache.lastTouched = Date.now()
+  return cache.byId.get(eventId)
+}
+
+export function record(sessionId: string, eventId: string, body: string): void {
+  let cache = sessions.get(sessionId)
+  if (!cache) {
+    sweepIdle()
+    cache = { byId: new Map(), lastTouched: 0 }
+    sessions.set(sessionId, cache)
+  }
+  cache.lastTouched = Date.now()
+  cache.byId.set(eventId, body)
+  if (cache.byId.size > MAX_PER_SESSION) {
+    const oldest = cache.byId.keys().next().value
+    if (oldest !== undefined) cache.byId.delete(oldest)
+  }
+}
+
+function sweepIdle(): void {
+  const cutoff = Date.now() - SESSION_IDLE_MS
+  for (const [id, cache] of sessions) {
+    if (cache.lastTouched < cutoff) sessions.delete(id)
+  }
+}

package/src/server/http.ts

@@ -8,13 +8,15 @@ import { z } from 'zod'
 import { applyRenderedEffects, runApiRoute } from './api-route.ts'
 import { isBlockedCrossSite } from './csrf.ts'
 import { scheduleSessionEffects } from './effects.ts'
+import { record, replayFor } from './event-dedupe.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
+import { runQueryRoute } from './query-route.ts'
 import { initialSyncPatches, recompute } from './recompute.ts'
 import { renderRoute } from './render.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
-import type { RouteDefinition } from './routing.ts'
+import { isStatorQueryRoute, type RouteDefinition } from './routing.ts'
 import { getOrCreateSessionId } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
@@ -44,6 +46,8 @@ const eventSchema = z.object({
       type: z.string(),
     })
     .passthrough(),
+  /** Client-generated idempotency key — see server/event-dedupe.ts. */
+  eventId: z.string().min(1).max(128).optional(),
 })
 
 /** Compiled matcher: turns `/p/:id` into a regex that captures params. */
@@ -65,7 +69,14 @@ function compileMatcher(route: DiscoveredRoute): RouteMatcher {
       // Absorb the preceding `/` and match the (possibly empty) remainder.
       pattern = `${pattern.replace(/\/$/, '')}(?:/(.*))?`
     } else if (seg.startsWith(':')) {
-      pattern += '([^/]+)'
+      // A param may carry a literal suffix (`:id.json`): the capture stops
+      // before the suffix, lazily, so `/p/a.b.json` yields id `a.b`.
+      const dot = seg.indexOf('.')
+      if (dot === -1) {
+        pattern += '([^/]+)'
+      } else {
+        pattern += `([^/]+?)${seg.slice(dot).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`
+      }
       if (i < parts.length - 1) pattern += '/'
     } else {
       pattern += seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -201,6 +212,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       return c.text(`unknown route "${routeKey}"`, 404)
     }
     const route = matched.route.GET
+    if (isStatorQueryRoute(route)) {
+      return c.text(`route "${routeKey}" is a data route — data routes are not live`, 400)
+    }
     if (!route.live) {
       return c.text(`route "${routeKey}" is not declared live: true`, 400)
     }
@@ -292,6 +306,11 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
       return c.json({ error: `unknown route "${routeKey}"` }, 404)
     }
     const route = matched.route.GET
+    // A data route serves no HTML, so no page runtime ever posts under its
+    // key — a request that does is malformed or hand-crafted.
+    if (isStatorQueryRoute(route)) {
+      return c.json({ error: `route key "${routeKey}" targets a data route` }, 404)
+    }
     const request = {
       ...buildRouteRequest(c, matched.route.paramNames),
       params: matched.params,
@@ -321,6 +340,17 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     }
 
     return withSessionLock(sessionId, async () => {
+      // Idempotent replay: a duplicate POST (client retry after a lost
+      // response) returns the original response body verbatim instead of
+      // re-applying — keyed-list patches are positional, not idempotent.
+      // Checked under the session lock so a retry racing its first attempt
+      // queues behind it and always sees the recorded body.
+      if (body.eventId) {
+        const cached = replayFor(sessionId, body.eventId)
+        if (cached !== undefined) {
+          return c.body(cached, 200, { 'Content-Type': 'application/json' })
+        }
+      }
       const runtime = new SessionRuntime(sessionId, config.store)
       try {
         await runtime.loadGraph([...route.reads, originDef])
@@ -358,7 +388,9 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         // normal event path in server/effects.ts.
         scheduleSessionEffects(runtime, config.store, sessionId)
 
-        return c.json({ patches, directives: [], committed: touched.size > 0 })
+        const envelope = { patches, directives: [], committed: touched.size > 0 }
+        if (body.eventId) record(sessionId, body.eventId, JSON.stringify(envelope))
+        return c.json(envelope)
       } finally {
         runtime.dispose()
       }
@@ -382,14 +414,13 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
   app.get('*', async (c, next) => {
     const matched = matchPath(matchers, c.req.path)
     if (!matched?.route.GET) return next()
-    return handleGet(
-      c,
-      matched.route,
-      matched.route.GET,
-      matched.params,
-      config.store,
-      config.headExtras,
-    )
+    const getRoute = matched.route.GET
+    // Brand decides the GET plane: data routes never touch the HTML path
+    // (no client-runtime injection, no live meta — a raw Response out).
+    if (isStatorQueryRoute(getRoute)) {
+      return runQueryRoute(c, matched.route, getRoute, config.store, matched.params)
+    }
+    return handleGet(c, matched.route, getRoute, matched.params, config.store, config.headExtras)
   })
 
   return app

package/src/server/index.ts

@@ -39,6 +39,7 @@ export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
 export { logger, scopedLogger } from './logger.ts'
 export { MachineStore } from './machine-store.ts'
+export { runQueryRoute } from './query-route.ts'
 export { recompute } from './recompute.ts'
 export { RedisAppStore, RedisStore } from './redis-store.ts'
 export type { RenderResult } from './render.ts'
@@ -75,8 +76,12 @@ export type {
   ApiRouteHelpers,
   ApiRouteResult,
   DefineApiRouteConfig,
+  DefineQueryRouteConfig,
   DefineRouteConfig,
   Directive,
+  QueryRouteDefinition,
+  QueryRouteHelpers,
+  QueryRouteResult,
   RouteContext,
   RouteCookieOptions,
   RouteDefinition,
@@ -88,6 +93,7 @@ export {
   defineApiRoute,
   defineRoute,
   isStatorApiRoute,
+  isStatorQueryRoute,
   isStatorRoute,
 } from './routing.ts'
 export { getOrCreateSessionId, SESSION_COOKIE } from './session.ts'

package/src/server/query-route.ts

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto'
+import type { Context } from 'hono'
+import { isResponseLike } from './api-route.ts'
+import { scheduleSessionEffects } from './effects.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+import type { DiscoveredRoute } from './route-discovery.ts'
+import { buildRouteRequest } from './route-request.ts'
+import type { QueryRouteDefinition, QueryRouteResult, RouteContext } from './routing.ts'
+import { getOrCreateSessionId } from './session.ts'
+import { withSessionLock } from './session-lock.ts'
+import { SessionRuntime } from './session-runtime.ts'
+
+const queryLog = scopedLogger('query')
+
+/** Default Content-Type by URL extension for data GET responses. The URL —
+ *  not the file on disk — carries the extension (`rss.xml.ts` serves
+ *  `/rss.xml`), so inference reads the request path. */
+const DATA_CONTENT_TYPES: Record<string, string> = {
+  '.json': 'application/json; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.ics': 'text/calendar; charset=utf-8',
+  '.csv': 'text/csv; charset=utf-8',
+}
+
+/** Second-level file extensions (`feed.xml.ts`) that mark a route file as
+ *  unambiguously a data route — discovery hard-errors on malformed exports
+ *  in one instead of skipping it as a utility. `.stator.ts` keeps its own,
+ *  different second-level meaning and is not in this set. */
+export const dataFileExtensions: ReadonlySet<string> = new Set(
+  Object.keys(DATA_CONTENT_TYPES).map((e) => e.slice(1)),
+)
+
+/**
+ * Run a data GET route: hydrate the reads graph, run the read-only handler,
+ * synthesize the response.
+ *
+ * Lock discipline: hydration happens under the session lock so the snapshot
+ * is coherent ACROSS machines (no half-committed view of a concurrent POST),
+ * and the lock is released before the handler runs — the handler cannot
+ * dispatch, so there is nothing to interleave with, and handler I/O never
+ * holds the lock.
+ */
+export async function runQueryRoute(
+  c: Context,
+  discovered: DiscoveredRoute,
+  route: QueryRouteDefinition,
+  store: MachineStore,
+  /** Path params from the framework's own matcher (the GET catch-all
+   *  bypasses Hono's per-route param extraction). */
+  params?: Record<string, string>,
+): Promise<Response> {
+  const { sessionId } = getOrCreateSessionId(c)
+  const request = params
+    ? { ...buildRouteRequest(c, discovered.paramNames), params }
+    : buildRouteRequest(c, discovered.paramNames)
+
+  const runtime = new SessionRuntime(sessionId, store)
+  try {
+    await withSessionLock(sessionId, () => runtime.loadGraph(route.reads))
+
+    // Same shape as a page's render context: proxies keyed by machine name.
+    // Session machines come from the hydrated runtime, app machines resolve
+    // through the long-lived app-instance fallback.
+    const machines: RouteContext = {}
+    for (const def of route.reads) {
+      const proxy = runtime.proxyFor(def.name)
+      if (!proxy) {
+        throw new Error(`stator: route reads "${def.name}" but it's not loaded into the runtime`)
+      }
+      machines[def.name] = proxy
+    }
+
+    let result: QueryRouteResult
+    try {
+      result = await route.handler(request, { machines })
+    } catch (err) {
+      queryLog.error({ err: String(err), path: c.req.path }, 'data route handler threw')
+      return c.text('Internal Server Error', 500)
+    }
+
+    // A fresh machine whose hydrate fired a load entry effect: persist so the
+    // next request restores instead of re-firing, and schedule the effect
+    // off-lock. The common query is a pure read and skips both (mirrors GET
+    // page handling).
+    const entryFired = runtime.entryFiredMachines()
+    if (entryFired.size > 0) {
+      await runtime.persistTouched(entryFired)
+      scheduleSessionEffects(runtime, store, sessionId)
+    }
+
+    return synthesizeDataResponse(c, result)
+  } finally {
+    runtime.dispose()
+  }
+}
+
+/** The URL's extension (`/rss.xml` → `.xml`). A leading dot alone
+ *  (`/.well-known`) is not an extension. */
+function urlExtension(path: string): string | undefined {
+  const last = path.slice(path.lastIndexOf('/') + 1)
+  const dot = last.lastIndexOf('.')
+  return dot > 0 ? last.slice(dot).toLowerCase() : undefined
+}
+
+/**
+ * Response synthesis for data GET results:
+ *   - Response-like → passthrough, Content-Type filled from the URL extension
+ *     only when the handler set none.
+ *   - string → body as-is, Content-Type from the URL extension
+ *     (`text/plain` fallback).
+ *   - anything else → JSON, always — a plain value is data, whatever the URL
+ *     looks like.
+ *
+ * Synthesized responses carry a strong body-hash ETag and answer
+ * `If-None-Match` with 304, so polling consumers stop paying for unchanged
+ * bodies. (The designed upgrade — 304 from the machine-revision ledger
+ * WITHOUT invoking the handler — rides the same header contract.)
+ */
+function synthesizeDataResponse(c: Context, result: QueryRouteResult): Response {
+  const ext = urlExtension(c.req.path)
+  const inferred = ext ? DATA_CONTENT_TYPES[ext] : undefined
+
+  if (isResponseLike(result)) {
+    if (inferred && !result.headers.get('content-type')) {
+      try {
+        result.headers.set('content-type', inferred)
+      } catch {
+        // Immutable headers (e.g. a proxied response) — the handler's call.
+      }
+    }
+    return result
+  }
+
+  const isString = typeof result === 'string'
+  const body = isString ? result : (JSON.stringify(result) ?? 'null')
+  const contentType = isString
+    ? (inferred ?? 'text/plain; charset=utf-8')
+    : 'application/json; charset=utf-8'
+
+  const etag = `"${createHash('sha1').update(body).digest('base64url')}"`
+  if ((c.req.header('if-none-match') ?? '').includes(etag)) {
+    return new Response(null, { status: 304, headers: { ETag: etag } })
+  }
+  return new Response(body, { headers: { 'Content-Type': contentType, ETag: etag } })
+}

package/src/server/route-discovery.ts

@@ -2,18 +2,21 @@ import { readdir } from 'node:fs/promises'
 import { basename, dirname, extname, relative, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { ModuleLoader } from './discovery.ts'
+import { dataFileExtensions } from './query-route.ts'
 import {
   type ApiRouteDefinition,
   isStatorApiRoute,
+  isStatorQueryRoute,
   isStatorRoute,
+  type QueryRouteDefinition,
   type RouteDefinition,
 } from './routing.ts'
 
 const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
 
 /** HTTP methods a route file may export. GET goes through `defineRoute`
- *  (page rendering); the rest go through `defineApiRoute` (mutation/API
- *  handlers). */
+ *  (page rendering) or `defineApiRoute({ method: 'GET' })` (data route);
+ *  the rest go through `defineApiRoute` (command handlers). */
 export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
 export type HttpMethod = (typeof HTTP_METHODS)[number]
 
@@ -24,8 +27,9 @@ export interface DiscoveredRoute {
    *  Empty for static routes. */
   paramNames: string[]
   filePath: string
-  /** GET route (page render). At most one. */
-  GET?: RouteDefinition
+  /** GET route: a page (defineRoute) or a data route (defineApiRoute with
+   *  method: 'GET'), discriminated by brand. At most one. */
+  GET?: RouteDefinition | QueryRouteDefinition
   /** API routes by method. */
   POST?: ApiRouteDefinition
   PUT?: ApiRouteDefinition
@@ -43,12 +47,15 @@ export interface DiscoveredRoute {
  *   - `routes/[a]/[b].ts`     → `/:a/:b`
  *
  * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
- * GET is a `defineRoute` (page renderer); the others are `defineApiRoute`.
+ * GET is a `defineRoute` (page renderer) or a `defineApiRoute` declaring
+ * `method: 'GET'` (data route); the others are `defineApiRoute` commands.
  *
- * Files that don't export anything route-shaped are silently skipped. With
- * recursive walking, the routes tree often contains utility files
- * (templates, helpers) that aren't routes, and throwing on them would
- * force separate trees.
+ * Files that don't export anything under an HTTP-method name are silently
+ * skipped. With recursive walking, the routes tree often contains utility
+ * files (templates, helpers) that aren't routes, and throwing on them would
+ * force separate trees. A file that DOES export an HTTP-method name but with
+ * the wrong constructor is a hard error, never a skip — a skip here surfaces
+ * as an unexplained 404 and a dev banner counting one route short.
  */
 export async function discoverRoutes(
   dir: string,
@@ -61,25 +68,39 @@ export async function discoverRoutes(
   for (const filePath of files) {
     const mod = await load(filePath)
 
-    // GET is a page route, POST/PUT/PATCH/DELETE are API routes.
-    const get = isStatorRoute(mod.GET) ? (mod.GET as RouteDefinition) : undefined
+    // GET is a page (defineRoute) or a data route (defineApiRoute with
+    // method: 'GET'); POST/PUT/PATCH/DELETE are command API routes.
+    const get =
+      isStatorRoute(mod.GET) || isStatorQueryRoute(mod.GET)
+        ? (mod.GET as RouteDefinition | QueryRouteDefinition)
+        : undefined
     const post = isStatorApiRoute(mod.POST) ? (mod.POST as ApiRouteDefinition) : undefined
     const put = isStatorApiRoute(mod.PUT) ? (mod.PUT as ApiRouteDefinition) : undefined
     const patch = isStatorApiRoute(mod.PATCH) ? (mod.PATCH as ApiRouteDefinition) : undefined
     const del = isStatorApiRoute(mod.DELETE) ? (mod.DELETE as ApiRouteDefinition) : undefined
 
-    if (!get && !post && !put && !patch && !del) continue
-
     // Catch the easy mistake: GET defined with `defineApiRoute`, or a
     // mutation method defined with `defineRoute`. Throw with a clear hint.
+    // These run BEFORE the not-a-route skip below: a file whose only export
+    // is a mis-constructed method name must error, not vanish as a utility.
     if (mod.GET && !get) {
       throw new Error(
-        `stator: ${filePath} exports GET but it is not a defineRoute. ` +
-          `GET handlers must be created with defineRoute(); use defineApiRoute() for POST/PUT/PATCH/DELETE.`,
+        isStatorApiRoute(mod.GET)
+          ? `stator: ${filePath} exports GET from defineApiRoute() without method: 'GET'. ` +
+              `A GET is a page (defineRoute) or a data route (defineApiRoute({ method: 'GET', … })).`
+          : `stator: ${filePath} exports GET but it is neither a defineRoute (page) nor a ` +
+              `defineApiRoute({ method: 'GET' }) (data route).`,
       )
     }
     for (const m of ['POST', 'PUT', 'PATCH', 'DELETE'] as const) {
-      if (mod[m] && !isStatorApiRoute(mod[m])) {
+      if (!mod[m]) continue
+      if (isStatorQueryRoute(mod[m])) {
+        throw new Error(
+          `stator: ${filePath} exports ${m} created with method: 'GET' — the declared method ` +
+            `must match the export name. Data routes are GET-only.`,
+        )
+      }
+      if (!isStatorApiRoute(mod[m])) {
         throw new Error(
           `stator: ${filePath} exports ${m} but it is not a defineApiRoute. ` +
             `${m} handlers must be created with defineApiRoute(); defineRoute() is GET-only.`,
@@ -87,6 +108,19 @@ export async function discoverRoutes(
       }
     }
 
+    if (!get && !post && !put && !patch && !del) {
+      // An extension-named file (feed.xml.ts) is unambiguously a route file —
+      // exporting nothing route-shaped from one is a mistake, not a utility.
+      const secondExt = extname(basename(filePath, extname(filePath))).slice(1)
+      if (dataFileExtensions.has(secondExt)) {
+        throw new Error(
+          `stator: ${filePath} is named like a data route (.${secondExt}${extname(filePath)}) ` +
+            `but exports no route. Export GET = defineApiRoute({ method: 'GET', … }) or rename the file.`,
+        )
+      }
+      continue
+    }
+
     const { urlPath, paramNames } = filePathToRoute(absDir, filePath)
     routes.push({
       urlPath,
@@ -134,7 +168,9 @@ function mergeByUrlPath(routes: DiscoveredRoute[]): DiscoveredRoute[] {
  * Sort routes most-specific-first (Astro's model). At match time the first
  * matcher that matches wins, so order encodes priority:
  *   - routes without a rest/catch-all segment rank before those with one
- *   - per segment, left to right: static (0) > named param (1) > rest (2)
+ *   - per segment, left to right: static (0) > suffixed param `:id.json` (1)
+ *     > bare param (2) > rest (3) — a suffixed param outranks a bare one so
+ *     `/p/:id.json` wins `/p/abc.json` before `/p/:id` can swallow it
  *   - more segments before fewer
  *   - ties alphabetically by urlPath
  */
@@ -143,13 +179,15 @@ export function sortRoutes(routes: DiscoveredRoute[]): DiscoveredRoute[] {
     urlPath
       .split('/')
       .filter(Boolean)
-      .map((seg) => (seg.startsWith('*') ? 2 : seg.startsWith(':') ? 1 : 0))
+      .map((seg) =>
+        seg.startsWith('*') ? 3 : seg.startsWith(':') ? (seg.includes('.') ? 1 : 2) : 0,
+      )
 
   return [...routes].sort((a, b) => {
     const ka = kinds(a.urlPath)
     const kb = kinds(b.urlPath)
-    const aRest = ka.includes(2)
-    const bRest = kb.includes(2)
+    const aRest = ka.includes(3)
+    const bRest = kb.includes(3)
     if (aRest !== bRest) return aRest ? 1 : -1 // no-rest first
     const len = Math.min(ka.length, kb.length)
     for (let i = 0; i < len; i++) {
@@ -213,11 +251,21 @@ export function filePathToRoute(
       paramNames.push(name)
       return `*${name}`
     }
-    const m = seg.match(/^\[(.+)\]$/)
+    // Param, optionally with a literal extension suffix: `[id].json` →
+    // `:id.json` (param `id`; the URL literally ends in `.json`). This is the
+    // data-route extension convention composing with dynamic segments — the
+    // suffix stays out of the captured value at match time.
+    const m = seg.match(/^\[([^\]]+)\](\.[\w.]+)?$/)
     if (m) {
       const name = m[1]!
+      if (name.startsWith('...')) {
+        throw new Error(
+          `stator: rest segment [${name}]${m[2] ?? ''} cannot carry an extension suffix — ` +
+            `a rest param spans whole segments.`,
+        )
+      }
       paramNames.push(name)
-      return `:${name}`
+      return `:${name}${m[2] ?? ''}`
     }
     return seg
   })

package/src/server/routing.ts

@@ -167,13 +167,29 @@ export interface DefineApiRouteConfig<TReads extends ReadonlyArray<AnyMachineDef
   ) => Promise<ApiRouteResult> | ApiRouteResult
 }
 
+/** `method: 'GET'` discriminates: with it, the handler is a read-only data
+ *  route typed with `{ machines }`; without it, a command route typed with
+ *  `{ dispatch, rotateSession }` — exactly as before. */
+export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
+  config: DefineQueryRouteConfig<TReads>,
+): QueryRouteDefinition
 export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
   config: DefineApiRouteConfig<TReads>,
-): ApiRouteDefinition {
+): ApiRouteDefinition
+export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
+  config: DefineQueryRouteConfig<TReads> | DefineApiRouteConfig<TReads>,
+): QueryRouteDefinition | ApiRouteDefinition {
+  if ('method' in config && config.method === 'GET') {
+    return {
+      __isStatorQueryRoute: true,
+      reads: config.reads ? [...config.reads] : [],
+      handler: config.handler,
+    }
+  }
   return {
     __isStatorApiRoute: true,
     reads: config.reads ? [...config.reads] : [],
-    handler: config.handler,
+    handler: (config as DefineApiRouteConfig<TReads>).handler,
   }
 }
 
@@ -184,3 +200,52 @@ export function isStatorApiRoute(v: unknown): v is ApiRouteDefinition {
     (v as Record<string, unknown>).__isStatorApiRoute === true
   )
 }
+
+/* ------------------------------------------------------------------ */
+/* Data GET routes (defineApiRoute with method: 'GET')                 */
+/* ------------------------------------------------------------------ */
+
+/** Helpers available inside a data GET handler. Read-only by construction:
+ *  there is no `dispatch` here, and that structural absence is what makes
+ *  handler reads safe — a handler that cannot dispatch has nothing to
+ *  interleave with effect completions or other sessions' commits. */
+export interface QueryRouteHelpers {
+  /** Read proxies keyed by machine name — the same shape a page's render
+   *  context uses (selector + context reads; no send). */
+  machines: RouteContext
+}
+
+/** What a data GET handler may return: a raw `Response` (passed through
+ *  verbatim, `Content-Type` filled from the URL extension only when the
+ *  handler set none), a string (`Content-Type` from the URL extension,
+ *  `text/plain` fallback), or any JSON-serializable value (always
+ *  `application/json`). */
+export type QueryRouteResult = Response | string | object
+
+export interface QueryRouteDefinition {
+  readonly __isStatorQueryRoute: true
+  reads: AnyMachineDef[]
+  handler: (
+    request: RouteRequest,
+    helpers: QueryRouteHelpers,
+  ) => Promise<QueryRouteResult> | QueryRouteResult
+}
+
+export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef>> {
+  /** The capability discriminant: `'GET'` declares a read-only data route.
+   *  Discovery cross-checks it against the export name. */
+  method: 'GET'
+  reads?: TReads
+  handler: (
+    request: RouteRequest,
+    helpers: QueryRouteHelpers,
+  ) => Promise<QueryRouteResult> | QueryRouteResult
+}
+
+export function isStatorQueryRoute(v: unknown): v is QueryRouteDefinition {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as Record<string, unknown>).__isStatorQueryRoute === true
+  )
+}