@statorjs/stator 2.5.0 → 2.6.0

package/src/server/dev.ts

@@ -1,44 +1,24 @@
-import { randomUUID } from 'node:crypto'
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { createServer as createHttpServer } from 'node:http'
-import { relative, resolve } from 'node:path'
-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 { ViteDevServer } from 'vite'
 import type { LogLevel } from '../config.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 { resolveAppConfig } from './config-compat.ts'
-import { loadDotenv } from './env.ts'
-import { logger, setLogLevel } from './logger.ts'
-import type { MachineStore } from './machine-store.ts'
-import type { DiscoveredRoute } from './route-discovery.ts'
-import { isStatorQueryRoute } from './routing.ts'
+import { createNativeDevApp as createNative, type NativeDevApp } from './dev-native.ts'
 import type { Store } from './store.ts'
 
 /**
- * Dev server: embeds Vite in middleware mode so `.stator` (and TS) modules are
- * compiled on the way in, loads machines + routes through `vite.ssrLoadModule`,
- * and injects each route's scoped component CSS into `<head>` at render time
- * (SSR head injection — independent of the client JS bundle).
+ * The dev entry. `createDevApp` boots the NATIVE dev server (`dev-native.ts`):
+ * the app runs from its source tree under Node's module loader exactly as
+ * `stator start` runs a build — no Vite in the server path, no dev/prod
+ * divergence, truthful `import.meta.url`s.
  *
- * Critically, the framework runtime itself is loaded *through Vite*
- * (`ssrLoadModule('@statorjs/stator/server')`), not imported natively — so the
- * render-context, machine defs, routes, and templates all share one module
- * instance. Importing the runtime natively here would create a second instance
- * whose render-context doesn't match the one the templates resolve against, and
- * `read()` would throw. (This mirrors how Astro/SvelteKit run SSR through Vite.)
- *
- * The production serve path (pre-built assets + manifest, no Vite) is a separate
- * follow-up; this is the dev half of Phase 3a.
+ * `STATOR_VITE_DEV=1` keeps the previous Vite-embedded dev server
+ * (`dev-vite.ts`) for one minor as an escape hatch while the native loop beds
+ * in. It is loaded lazily, so the default path never imports Vite.
  */
 
 export interface DevAppConfig {
-  /** Vite root — the app directory (must reach node_modules for resolution). */
+  /** The app directory (must reach node_modules for resolution). */
   root: string
   machinesDir: string
   routesDir: string
@@ -94,13 +74,15 @@ export interface DevAppConfig {
 
 export interface DevApp {
   fetch: (request: Request) => Response | Promise<Response>
-  vite: ViteDevServer
+  /** @deprecated The dev server no longer embeds Vite — this is `undefined`
+   *  (with a one-time warning) and will be removed in the next major. Under the
+   *  transitional `STATOR_VITE_DEV=1` escape hatch it is still the real
+   *  `ViteDevServer` for one minor. */
+  readonly vite: ViteDevServer | undefined
   /** 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. */
+   *  current store, surviving machine-edit rebuilds, so SSE fan-out reaches
+   *  live connections. */
   dispatchToApp<D extends AnyMachineDef>(
     machine: D,
     event: EventOf<D>,
@@ -112,293 +94,42 @@ export interface DevApp {
   close: () => Promise<void>
 }
 
-export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
-  // Load .env before anything reads process.env. No-op if the CLI already
-  // loaded it; covers a direct `createDevApp` call (a hand-written dev entry).
-  loadDotenv(resolve(config.root))
-  // One build-id per dev boot — a `tsx` restart is a new process → new id → the
-  // client reloads on reconnect (the restart-without-reload gap). An inner Vite
-  // rebuild keeps the same id (no full reload; islands hot-reload via Vite).
-  const devBuildId = randomUUID()
-  // Vite's HMR websocket defaults to 24678 for EVERY dev server — two
-  // stator apps side by side would fight over it (the loser's live reload
-  // silently dies). Probe a free one instead.
-  const hmrPort = await findFreePort(24678)
-  const vite = await createViteServer({
-    root: resolve(config.root),
-    appType: 'custom',
-    server: { middlewareMode: true, hmr: { port: hmrPort } },
-    // machineStub keeps server machines out of browser module graphs: island
-    // imports of a machine resolve to a `{ name }` stub (SSR loads are
-    // untouched — `options.ssr` gates it).
-    plugins: [stator(), machineStub({ machinesDir: resolve(config.machinesDir) })],
-    // The framework's own source is TS that Vite must transform, not externalize.
-    ssr: { noExternal: [/@statorjs\/stator/] },
-    logLevel: 'warn',
-  })
-
-  // Load the runtime through Vite so it shares an instance with the templates.
-  // (Type-only: the static import type is erased, so no second instance.)
-  const runtime = (await vite.ssrLoadModule(
-    '@statorjs/stator/server',
-  )) as typeof import('./index.ts')
-  const loader = (file: string) => vite.ssrLoadModule(file) as Promise<Record<string, unknown>>
-
-  const root = resolve(config.root)
-  const machinesDir = resolve(config.machinesDir)
-  const routesDir = resolve(config.routesDir)
-  const resolved = resolveAppConfig(config)
-  // Level precedence: LOG_LEVEL env > config > dev default (info). Apply to this
-  // module's logger AND the Vite-loaded runtime instance — SSE/http/effects log
-  // through the latter — via setLogLevel, which also covers the scoped children.
-  const logLevel = process.env.LOG_LEVEL ?? resolved.logLevel ?? 'info'
-  setLogLevel(logLevel)
-  runtime.setLogLevel(logLevel)
-  // The session cookie is written by the Vite-loaded runtime, so configure that
-  // instance's SameSite (the native one would set a different module's global).
-  runtime.setSessionSameSite(resolved.sameSite ?? 'Lax')
-  const inspectorOn = resolved.inspector ?? true
-
-  const resultCache = new Map<string, ReturnType<typeof compile>>()
-  const compiledFor = async (file: string) => {
-    let r = resultCache.get(file)
-    if (r === undefined) {
-      // Match the plugin's kind detection so route-page frontmatter
-      // (Stator.reads etc.) compiles under the route capability set.
-      const kind = /[\\/]routes[\\/].*\.stator$/.test(file) ? 'route' : 'component'
-      r = compile(await readFile(file, 'utf8'), { id: file, kind })
-      resultCache.set(file, r)
-    }
-    return r
-  }
-
-  const headExtras = async (routeFile: string) => {
-    const files = reachableStatorFiles(vite, routeFile)
-    let css = ''
-    const scripts: string[] = []
-    for (const f of files) {
-      const r = await compiledFor(f)
-      if (r.css) css += `/* ${f} */\n${r.css}\n`
-      if (r.isClient) {
-        // Vite's transform middleware compiles this URL because browsers send
-        // `Sec-Fetch-Dest: script` for module scripts (the `.stator` extension
-        // alone wouldn't match its JS-request check). curl-style probes must
-        // send that header or they'll see raw source and cry wolf.
-        const url = `/${relative(root, f).replace(/\\/g, '/')}?stator&type=client`
-        scripts.push(`<script type="module" src="${url}"></script>`)
-      }
-    }
-    const head: string[] = []
-    // Vite's HMR client — pages are rendered by Hono, not Vite's
-    // transformIndexHtml, so it isn't injected for us. Without it the browser
-    // has no socket to receive the full-reload signal on a source change.
-    head.push('<script type="module" src="/@vite/client"></script>')
-    // The dev inspector toolbar (off in production — only the dev server injects it).
-    if (inspectorOn) head.push('<script src="/@stator/inspector.js" defer></script>')
-    if (css.trim()) head.push(`<style data-stator-dev>\n${css.trim()}\n</style>`)
-    head.push(...scripts)
-    return head.join('\n')
-  }
-
-  // The app graph is rebuilt on a source change so edits don't need a restart.
-  let store: MachineStore
-  let routes: DiscoveredRoute[] = []
-  let machineCount = 0
-  let app: Hono
-
-  const rebuildStore = async (): Promise<void> => {
-    const { defs } = await runtime.discoverMachines(machinesDir, loader)
-    machineCount = defs.length
-    store = new runtime.MachineStore(defs, resolved.session ?? new runtime.InMemoryStore(), {
-      sessionTtlSeconds: resolved.sessionTtlSeconds,
-      appStore: resolved.app,
-    })
-    // Wire the effect scheduler before booting — a fresh app machine's
-    // initial-state entry effect fires during boot and needs a live scheduler.
-    runtime.wireAppEffects(store)
-    await store.bootAppMachines()
-    // Dev-only lint: a session machine whose `after` timer drives a loop with
-    // a data-loading entry effect is server-side polling that runs for
-    // sessions nobody is watching. Warn with the steer, don't block.
-    for (const f of runtime.findPollLoops(defs)) {
-      console.warn(
-        `stator: session machine "${f.machine}" self-reschedules through \`after\` ` +
-          `(${f.cycle.join(' → ')} via ${f.event}) with a data-loading entry effect on the loop. ` +
-          `This polls upstream for sessions nobody is watching. Prefer a client-owned clock ` +
-          `with a staleness guard — see the effects guide, "Who owns the clock".`,
-      )
-    }
-  }
-  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> => {
-    // Re-discover `middleware.ts` each rebuild so edits to it take effect. Loaded
-    // through the Vite runtime so its handlers share the runtime's instance.
-    const middleware = await runtime.discoverMiddleware(resolve(root, 'middleware.ts'), loader)
-    app = await runtime.buildHonoApp({
-      routes,
-      store,
-      staticDir: config.staticDir,
-      headExtras,
-      inspector: inspectorOn,
-      trustedOrigins: resolved.trustedOrigins,
-      sameSite: resolved.sameSite,
-      origin: resolved.origin,
-      secret: resolved.secret,
-      buildId: devBuildId,
-      cors: resolved.cors,
-      middleware,
-    })
-  }
-
-  await rebuildStore()
-  await rebuildRoutes()
-  await rebuildServer()
-
-  // Discover boot.ts ONCE per process (not per rebuild) — a long-lived source
-  // shouldn't restart on every edit. Runs in listen() below.
-  const bootDef = await runtime.discoverBoot(resolve(root, 'boot.ts'), loader)
-
-  // Live reload: on a relevant source change, re-discover and rebuild the app,
-  // then tell the browser to reload. A template/route edit keeps the store (and
-  // your session — cart contents and all) intact; only a machine edit resets it,
-  // since route `reads:` bind to machine defs by identity and must re-bind as a
-  // set. Rebuilds are serialized so overlapping saves can't race.
-  const isAppFile = (file: string): boolean => {
-    if (!/\.(stator|ts|js)$/.test(file)) return false
-    if (file.includes('/node_modules/') || file.includes('/dist/')) return false
-    if (file.startsWith(machinesDir) || file.startsWith(routesDir)) return true
-    return (vite.moduleGraph.getModulesByFile(file)?.size ?? 0) > 0
-  }
-  let reloadChain: Promise<void> = Promise.resolve()
-  const onChange = (file: string): void => {
-    const abs = resolve(file)
-    if (!isAppFile(abs)) return
-    reloadChain = reloadChain.then(async () => {
-      invalidateModuleTree(vite, abs)
-      resultCache.delete(abs)
-      try {
-        if (abs.startsWith(machinesDir)) await rebuildStore()
-        await rebuildRoutes()
-        await rebuildServer()
-        vite.ws.send({ type: 'full-reload' })
-        logger.info({ file: relative(root, abs) }, 'reloaded')
-      } catch (err) {
-        logger.error({ err: (err as Error).message, file: relative(root, abs) }, 'reload failed')
-      }
-    })
-  }
-  vite.watcher.on('change', onChange)
-  vite.watcher.on('add', onChange)
-  vite.watcher.on('unlink', onChange)
-
+let warnedVite = false
+/** The native app in the public `DevApp` shape: `vite` is a deprecated getter
+ *  that warns once and returns `undefined`. Exported for tests. */
+export function withDeprecatedVite(app: NativeDevApp): DevApp {
   return {
     fetch: (request) => app.fetch(request),
     get hono() {
-      return app
+      return app.hono
     },
-    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.
-      // The arrow re-reads `app` each request so a rebuild swaps in seamlessly.
-      const honoListener = getRequestListener((req) => app.fetch(req))
-      const server = createHttpServer((req, res) => {
-        vite.middlewares(req, res, () => honoListener(req, res))
-      })
-      // Busy port? Shift up like every modern dev server (the requested
-      // port is someone's other project, not an error).
-      return findFreePort(port).then(
-        (freePort) =>
-          new Promise((resolveFn) => {
-            server.listen(freePort, async () => {
-              printDevBanner({
-                port: freePort,
-                requestedPort: port,
-                machines: machineCount,
-                routes: routes.length,
-                inspector: true,
-              })
-              // Boot runs once the dev server is up (store is read at call time,
-              // so a later rebuild's store is used). Teardown composes into the
-              // shutdown below.
-              const teardown = await runtime.runBoot(bootDef, {
-                dispatchToApp: (machine, event) => runtime.dispatchToApp(store, machine, event),
-                config: {
-                  origin: resolved.origin,
-                  trustedOrigins: resolved.trustedOrigins ?? [],
-                  sameSite: resolved.sameSite ?? 'Lax',
-                  cors: resolved.cors,
-                },
-              })
-              installGracefulShutdown(async () => {
-                if (teardown) await teardown()
-                await vite.close()
-                await new Promise<void>((done) => server.close(() => done()))
-              })
-              resolveFn()
-            })
-          }),
-      )
+    dispatchToApp: (machine, event) => app.dispatchToApp(machine, event),
+    listen: (port) => app.listen(port),
+    close: () => app.close(),
+    get vite(): undefined {
+      if (!warnedVite) {
+        warnedVite = true
+        console.warn(
+          'stator: DevApp.vite is deprecated and returns undefined — the dev server no ' +
+            'longer embeds Vite. STATOR_VITE_DEV=1 keeps the Vite dev server for one minor.',
+        )
+      }
+      return undefined
     },
-    close: () => vite.close(),
   }
 }
 
-/** Invalidate a changed file and everything that (transitively) imports it, so
- *  the next `ssrLoadModule` re-executes them with fresh code. */
-function invalidateModuleTree(vite: ViteDevServer, file: string): void {
-  const seen = new Set<unknown>()
-  const stack: Array<{ importers: Set<unknown> }> = [
-    ...((vite.moduleGraph.getModulesByFile(file) ?? []) as Set<never>),
-  ]
-  while (stack.length) {
-    const mod = stack.pop()
-    if (!mod || seen.has(mod)) continue
-    seen.add(mod)
-    vite.moduleGraph.invalidateModule(mod as never)
-    for (const imp of mod.importers) stack.push(imp as never)
+export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  if (process.env.STATOR_VITE_DEV === '1') {
+    const { createViteDevApp } = await import('./dev-vite.ts')
+    return createViteDevApp(config)
   }
+  return withDeprecatedVite(await createNative(config))
 }
 
-/**
- * Walk the SSR module graph from a route's file and return every `.stator` file
- * reachable from it (route page + the components it renders). The caller compiles
- * each to collect scoped CSS and client-component module scripts.
- */
-function reachableStatorFiles(vite: ViteDevServer, entryFile: string): string[] {
-  const seen = new Set<string>()
-  const statorFiles = new Set<string>()
-
-  const visit = (node: { id: string | null; importedModules: Set<unknown> } | undefined): void => {
-    if (!node) return
-    const id = node.id ?? ''
-    if (seen.has(id)) return
-    seen.add(id)
-    const file = id.split('?')[0]!
-    if (/\.stator$/.test(file)) statorFiles.add(file)
-    for (const dep of node.importedModules) visit(dep as never)
-  }
+/** @deprecated `createDevApp` IS the native dev server now — use it. (This
+ *  alias always boots the native server, ignoring `STATOR_VITE_DEV`.) */
+export const createNativeDevApp = async (config: DevAppConfig): Promise<DevApp> =>
+  withDeprecatedVite(await createNative(config))
 
-  for (const node of vite.moduleGraph.getModulesByFile(entryFile) ?? []) {
-    visit(node as never)
-  }
-  return [...statorFiles]
-}
+export type { NativeDevApp } from './dev-native.ts'

package/src/server/discovery.ts

@@ -1,7 +1,8 @@
 import { readdir } from 'node:fs/promises'
-import { extname, resolve } from 'node:path'
+import { extname, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { type AnyMachineDef, isStatorMachine } from './define-machine.ts'
+import { hashMachines, setCodeHash } from './machine-hash.ts'
 
 export interface DiscoveryResult {
   defs: AnyMachineDef[]
@@ -14,9 +15,25 @@ export type ModuleLoader = (file: string) => Promise<Record<string, unknown>>
 
 const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
 
+export interface DiscoverMachinesOptions {
+  /**
+   * Code hashes for the hydration policy (see `snapshot-policy.ts`).
+   *  - omitted: computed live, one esbuild pass over the discovered files
+   *    (the dev servers, and `createApp` without a build manifest);
+   *  - a map keyed by machine FILE (relative to the machines dir, e.g.
+   *    `cart.ts`): consumed as-is — `stator start` from the build manifest,
+   *    whose hashes are per file because the build never executes a machine
+   *    to learn its name. A discovered machine with no entry is an error,
+   *    never a silent always-reset;
+   *  - `false`: skip hashing (unit tests assembling stores from defs).
+   */
+  hashes?: ReadonlyMap<string, string> | Readonly<Record<string, string>> | false
+}
+
 export async function discoverMachines(
   dir: string,
   load: ModuleLoader = nativeLoader,
+  opts: DiscoverMachinesOptions = {},
 ): Promise<DiscoveryResult> {
   const absDir = resolve(dir)
   // A missing conventional dir means "no machines yet" (e.g. early in a fresh
@@ -38,6 +55,19 @@ export async function discoverMachines(
 
   const defs: AnyMachineDef[] = []
   const seenNames = new Set<string>()
+  const supplied = opts.hashes
+  const byFile =
+    supplied === false || supplied === undefined
+      ? undefined
+      : supplied instanceof Map
+        ? supplied
+        : new Map(Object.entries(supplied))
+  // Live hashing: one esbuild pass over every machine file, before any import,
+  // so an unbundleable closure fails here with the file named.
+  const live =
+    supplied === undefined && files.length > 0
+      ? await hashMachines(files, { machinesDir: absDir })
+      : undefined
 
   for (const file of files) {
     const mod = await load(file)
@@ -52,6 +82,20 @@ export async function discoverMachines(
       throw new Error(`stator: duplicate machine name "${def.name}" in ${file}`)
     }
     seenNames.add(def.name)
+    if (byFile) {
+      const key = relative(absDir, file).replace(/\\/g, '/')
+      const hash = byFile.get(key)
+      if (hash === undefined) {
+        throw new Error(
+          `stator: no code hash for machine "${def.name}" (${key}) in the build manifest — ` +
+            `rebuild with \`stator build\`; a machine without a hash cannot hydrate safely.`,
+        )
+      }
+      setCodeHash(def, hash)
+    } else if (live) {
+      const { hash, inputs } = live.get(file)!
+      setCodeHash(def, hash, inputs)
+    }
     defs.push(def)
   }
 

package/src/server/effects.ts

@@ -2,6 +2,7 @@ import type { AnyMachineDef, EffectInvocation, EventObject } from '../engine/ind
 import { dispatchToApp } from './app-dispatch.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
+import { CLAIMS_KEY } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
 import { fanOut } from './sse.ts'
@@ -156,7 +157,15 @@ async function runSessionEffect(
   try {
     let completion: Awaited<ReturnType<EffectInvocation['run']>>
     try {
-      completion = await invocation.run(controller.signal)
+      // The session the effect runs for: its id and its claims as of now —
+      // loaded here (outside the lock, like the I/O the effect is about to do)
+      // so an entry effect can reload a durable fact by identity after a fresh
+      // start or a snapshot reset, with no client round trip.
+      const claims = (await store.persistence.get(sessionId, CLAIMS_KEY)) ?? undefined
+      completion = await invocation.run(controller.signal, {
+        id: sessionId,
+        claims: <T>() => claims as T | undefined,
+      })
     } catch (err) {
       // Backstop only — the type contract asks effects to catch and return
       // their failure event. Never crashes the host.

package/src/server/http.ts

@@ -653,7 +653,7 @@ async function handleGet(
   }
 }
 
-function contentTypeFor(path: string): string {
+export function contentTypeFor(path: string): string {
   const ext = extname(path).toLowerCase()
   if (ext === '.css') return 'text/css; charset=utf-8'
   if (ext === '.js' || ext === '.mjs') return 'application/javascript; charset=utf-8'
@@ -661,5 +661,11 @@ function contentTypeFor(path: string): string {
   if (ext === '.svg') return 'image/svg+xml'
   if (ext === '.png') return 'image/png'
   if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
+  if (ext === '.webp') return 'image/webp'
+  if (ext === '.gif') return 'image/gif'
+  if (ext === '.ico') return 'image/x-icon'
+  if (ext === '.wasm') return 'application/wasm'
+  if (ext === '.woff2') return 'font/woff2'
+  if (ext === '.woff') return 'font/woff'
   return 'application/octet-stream'
 }

package/src/server/index.ts

@@ -55,6 +55,7 @@ export { buildHonoApp } from './http.ts'
 export type { InstanceHandle } from './instance-proxy.ts'
 export { createInstanceProxy, defForProxy } from './instance-proxy.ts'
 export { logger, scopedLogger, setLogLevel } from './logger.ts'
+export { codeHashOf, codeInputsOf } from './machine-hash.ts'
 export { MachineStore } from './machine-store.ts'
 export type { MiddlewareDefinition } from './middleware.ts'
 export {