@statorjs/stator 1.6.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.6.0",
+  "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.6.0"
+    "@statorjs/stator": "1.6.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

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/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/http.ts

@@ -11,11 +11,12 @@ 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'
@@ -68,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, '\\$&')
@@ -204,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)
     }
@@ -295,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,
@@ -398,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
+  )
+}