@statorjs/stator 2.5.0 → 2.6.0

package/src/cli/commands/dev.ts

@@ -3,9 +3,13 @@ import { createDevApp } from '../../server/dev.ts'
 import { loadConfig, resolvePort } from '../config.ts'
 import type { CliContext } from '../run.ts'
 
-/** Run the dev server (Vite-backed today: live reload, compile-error overlay,
- *  inspector). Conventions for machines/routes/static; `stator.config.ts` for
- *  the store/session/port an app previously hand-wrote a `server.ts` for. */
+/** Run the dev server. Live reload, inspector, conventions for machines/routes/
+ *  static; `stator.config.ts` for the store/session/port an app previously
+ *  hand-wrote a `server.ts` for.
+ *
+ *  The app runs natively from its source tree, exactly as `stator start` runs a
+ *  build. `STATOR_VITE_DEV=1` keeps the previous Vite-embedded dev server for
+ *  one minor as an escape hatch. */
 export async function run(ctx: CliContext): Promise<void> {
   const config = await loadConfig(ctx.root)
   const app = await createDevApp({

package/src/cli/commands/start.ts

@@ -16,7 +16,7 @@ export async function run(ctx: CliContext): Promise<void> {
   }
 
   const config = await loadConfig(ctx.root)
-  const { headExtras, buildId } = await loadProductionHead(dist)
+  const { headExtras, buildId, machines } = await loadProductionHead(dist)
   const app = await createApp({
     machinesDir: resolve(dist, 'machines'),
     routesDir: resolve(dist, 'routes'),
@@ -31,6 +31,7 @@ export async function run(ctx: CliContext): Promise<void> {
     cors: config.cors,
     headExtras,
     buildId,
+    machineHashes: machines,
     middlewareFile: resolve(dist, 'middleware.ts'),
     bootFile: resolve(dist, 'boot.ts'),
   })

package/src/cli/run.ts

@@ -65,7 +65,7 @@ const ctx: CliContext = {
 const { loadDotenv } = await import('../server/env.ts')
 loadDotenv(ctx.root)
 
-// Dynamic import per command so `check` never loads the dev server's Vite, etc.
+// Dynamic import per command so `check` never loads the dev server's watcher, etc.
 const { run } = (await import(`./commands/${command}.ts`)) as {
   run: (ctx: CliContext) => Promise<void>
 }

package/src/cli/stator.js

@@ -23,5 +23,14 @@ if (typeof register !== 'function') {
 
 register('./loader.js', import.meta.url)
 
+// Apply sourcemaps to stack traces. Every transform in the owned pipeline (the
+// TS loader above, the dev loader's `.stator` compile) already EMITS an inline
+// map, but V8 ignores maps when capturing stacks unless the process opts in —
+// this is the runtime equivalent of `--enable-source-maps`, which a bin script
+// can't put on its own invocation. Covers dev and `stator start` alike.
+// (`.stator` traces resolve to the compiled server module — right file,
+// generated lines — until the compiler emits its own map to compose.)
+process.setSourceMapsEnabled?.(true)
+
 // The real CLI is TypeScript, transformed on import by the loader just registered.
 await import('./run.ts')

package/src/compiler/diagnostics.ts

@@ -63,3 +63,13 @@ export function locAt(source: string, offset: number, file?: string): Diagnostic
   const { line, column } = offsetToLineCol(source, offset)
   return { file, line, column, frame: codeFrame(source, line, column) }
 }
+
+/** Render a `CompileError` for a terminal or a dev overlay: the message, then
+ *  `file:line:column` and the code frame when the error is located. Plain text
+ *  on purpose — it is the one shape that survives crossing a loader/worker
+ *  thread, where an Error's custom properties (`loc`) are dropped. */
+export function formatCompileError(err: CompileError): string {
+  if (!err.loc) return err.message
+  const { file, line, column, frame } = err.loc
+  return `${err.message}\n\n${file ?? '<source>'}:${line}:${column}\n${frame}`
+}

package/src/compiler/index.ts

@@ -29,6 +29,7 @@ export type { DiagnosticLocation } from './diagnostics.ts'
 export {
   CompileError,
   codeFrame,
+  formatCompileError,
   locAt,
   offsetToLineCol,
 } from './diagnostics.ts'
@@ -36,7 +37,7 @@ export { generateDts } from './dts.ts'
 export { scopeHash } from './hash.ts'
 export type { LowerMeta, LowerOptions } from './lower.ts'
 export { lowerTemplate } from './lower.ts'
-export { componentImportSpecifier, declaredRegions } from './regions.ts'
+export { componentImportSpecifier, declaredRegions, regionResolverFor } from './regions.ts'
 export type { ParsedStator, ScannedRegions, SourceRegion } from './split.ts'
 export { scanRegions, splitStator } from './split.ts'
 export { scopeCss } from './styles.ts'

package/src/compiler/regions.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
 import ts from 'typescript'
 import { splitStator } from './split.ts'
 
@@ -77,3 +79,31 @@ export function componentImportSpecifier(
   }
   return null
 }
+
+/**
+ * Build a region resolver for a file: maps a component identifier used in
+ * `file` to the named regions its imported `.stator` declares, so `compile()`
+ * can reject a `child="x"` the callee never declares. Reads sibling files
+ * synchronously (resolution happens mid-compile). Returns null when the
+ * identifier isn't a `.stator` default import or the file can't be read.
+ *
+ * Shared by every compile path — the Vite plugin, `buildApp`, and the native
+ * dev loader — so the check is identical in dev and prod.
+ */
+export function regionResolverFor(
+  file: string,
+  source: string,
+): (componentName: string) => Set<string> | null {
+  const { frontmatter } = splitStator(source)
+  return (componentName) => {
+    const spec = componentImportSpecifier(frontmatter, componentName)
+    if (!spec) return null
+    const target = spec.startsWith('.') ? resolve(dirname(file), spec) : null
+    if (!target) return null
+    try {
+      return declaredRegions(readFileSync(target, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+}

package/src/engine/actor.ts

@@ -160,7 +160,8 @@ export function createActor<C extends object, E extends EventObject, S extends s
       effectId,
       kind: 'entry',
       stateKey,
-      run: (signal) => Promise.resolve(entry(ctxSnapshot, { effectId, signal })),
+      run: (signal, session) =>
+        Promise.resolve(entry(ctxSnapshot, { effectId, signal, ...(session ? { session } : {}) })),
     }
     if (opts.onEffect) {
       opts.onEffect(invocation)
@@ -289,8 +290,14 @@ export function createActor<C extends object, E extends EventObject, S extends s
           machineName: def.name,
           effectId,
           kind: 'transition',
-          run: (signal) =>
-            Promise.resolve(effect(ctxSnapshot, evSnapshot as never, { effectId, signal })),
+          run: (signal, session) =>
+            Promise.resolve(
+              effect(ctxSnapshot, evSnapshot as never, {
+                effectId,
+                signal,
+                ...(session ? { session } : {}),
+              }),
+            ),
         }
         if (opts.onEffect) {
           opts.onEffect(invocation)

package/src/engine/index.ts

@@ -19,6 +19,7 @@ export type {
   Effect,
   EffectInvocation,
   EffectMeta,
+  EffectSession,
   EmitDeclaration,
   EmitsConfig,
   EntryEffect,

package/src/engine/types.ts

@@ -61,6 +61,18 @@ export type Guard<C, E extends EventObject, R = Record<string, any>> = (
 export interface EffectMeta {
   effectId: string
   signal?: AbortSignal
+  /** The session this effect runs for — set by the server host for SESSION
+   *  machines only (app machines and client islands have none). Lets an entry
+   *  effect reload a durable fact by identity after a fresh start or a
+   *  snapshot reset, with no client round trip: `loadCart(meta.session.claims<Me>().userId)`. */
+  session?: EffectSession
+}
+
+/** The session an effect runs for. `claims` mirrors `stator(c).claims<T>()`:
+ *  the app-defined claims as of the moment the effect started, or `undefined`. */
+export interface EffectSession {
+  readonly id: string
+  claims<T = unknown>(): T | undefined
 }
 
 /**
@@ -127,7 +139,9 @@ export interface EffectInvocation {
   kind: 'entry' | 'transition'
   /** The owning state — set for entry effects, for exit-abort targeting. */
   stateKey?: string
-  run: (signal?: AbortSignal) => Promise<EventObject | null>
+  /** Run the effect. The host passes the abort signal and, for session
+   *  machines, the session — merged into the effect's `meta`. */
+  run: (signal?: AbortSignal, session?: EffectSession) => Promise<EventObject | null>
 }
 
 /** Object form of a transition. A bare `Action` is sugar for `{ do: fn }`.
@@ -216,6 +230,15 @@ export interface Snapshot<C> {
    *  effect (the load role is re-runnable by contract) instead of leaving the
    *  machine wedged waiting for a completion that died with another process. */
   pendingEntry?: { effectId: string }
+  /** Snapshot format version, stamped by the host on persist. Absent ⇒ the
+   *  original (current) format. Lets the shape itself evolve (hierarchy in
+   *  `value`) with a known-old snapshot recognisable as such. */
+  format?: number
+  /** Code hash of the machine that wrote this snapshot, stamped by the host on
+   *  persist. Hydration rejects a snapshot whose hash differs from the running
+   *  machine's — sessions never outlive the code that made them. Absent
+   *  (pre-existing snapshots) ⇒ mismatch. */
+  code?: string
 }
 
 export type Lifecycle = 'app' | 'session'

package/src/server/create-app.ts

@@ -84,6 +84,10 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   /** Build identifier for the deploy-aware reload handshake. `stator start`
    *  passes the id baked into the build manifest; absent → no handshake. */
   buildId?: string
+  /** Machine code hashes from the build manifest (`loadProductionHead(dist).machines`),
+   *  keyed by file relative to `machinesDir`. Omitted ⇒ hashed live at boot;
+   *  a discovered machine missing from a supplied map is a boot error. */
+  machineHashes?: Readonly<Record<string, string>>
 }
 
 export interface StatorApp {
@@ -120,7 +124,9 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
   // the scoped children (http/sse/…), which a bare `logger.level =` would miss.
   setLogLevel(process.env.LOG_LEVEL ?? resolved.logLevel ?? 'warn')
   setSessionSameSite(resolved.sameSite ?? 'Lax')
-  const { defs } = await discoverMachines(machinesDir)
+  const { defs } = await discoverMachines(machinesDir, undefined, {
+    ...(config.machineHashes ? { hashes: config.machineHashes } : {}),
+  })
   const sessionStore = resolved.session ?? new InMemoryStore()
   const store = new MachineStore(defs, sessionStore, {
     sessionTtlSeconds: resolved.sessionTtlSeconds,

package/src/server/dev-loader.mjs

@@ -0,0 +1,124 @@
+// Native dev-server module loader — the Vite exit's dev half. Three jobs, all
+// on Node's module-customization hooks thread:
+//
+//  1. `.stator` compile-on-load: a `.stator` import is read from the SOURCE tree,
+//     compiled by the framework compiler (server render module), and type-
+//     stripped by esbuild. No mirror, no on-disk `.stator.ts` — the server runs
+//     from the app's real files, so `import.meta.url`-relative paths (a SQLite
+//     file, a data dir) mean the same thing in dev as in the app's source.
+//  2. TS-on-import, like the CLI's shipped `cli/loader.js`.
+//  3. App-scoped `?v=` propagation — the one piece the prod loader lacks.
+//
+// Invalidation model — importer-only: every app module is imported at
+// `?v=<its own version>`. The dev server keeps a per-file version map, bumps
+// a changed file AND its transitive importers (a static reverse import graph),
+// and pushes the new versions here over a MessagePort before re-importing
+// entries. `resolve` stamps each app-local child with its current version, so
+// a changed subtree re-evaluates fresh while everything else keeps its cached
+// module instance — a `lib/db.ts` that opens a connection at top level runs
+// once per session, not once per edit, and the ESM registry (which never
+// releases a module) grows by the affected subtree instead of the whole app.
+//
+// The versioning boundary is CRITICAL: it applies only to files under the app
+// root (`initialize({ appDir })`) and never inside a `node_modules` directory.
+// Versioning framework internals would fork their singletons (render context,
+// registries) into a second instance and break `read()` — the same dual-
+// instance hazard as the old Vite fence, from the other side. Both checks are
+// needed: under pnpm the framework realpaths OUT of node_modules (so the app-
+// root allowlist catches it), under a flat install it sits INSIDE the app root
+// (so the node_modules denylist catches it).
+//
+// This module imports the TypeScript compiler source, so it must be registered
+// after a TS loader (the dev server registers `cli/loader.js` first).
+import { readFile } from 'node:fs/promises'
+import { sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { transform } from 'esbuild'
+import { sourceId } from '../build/source-id.ts'
+import { CompileError, compile, formatCompileError, regionResolverFor } from '../compiler/index.ts'
+
+const TS = /\.(?:ts|tsx|mts|cts)$/
+const STATOR = /\.stator$/
+/** Extensions whose app-local imports carry the build version. */
+const VERSIONED = /\.(?:stator|ts|tsx|mts|cts|js|mjs)$/
+
+/** Absolute (real) app root under which versioning applies. Unset ⇒ this loader
+ *  behaves like the prod TS loader plus `.stator` compile (no versioning). */
+let appDir
+/** Absolute file path → current version, pushed by the dev server. */
+const versions = new Map()
+
+export async function initialize(data) {
+  appDir = data?.appDir
+  const port = data?.port
+  if (!port) return
+  port.on('message', (msg) => {
+    if (msg?.type !== 'versions') return
+    for (const [file, v] of msg.entries) versions.set(file, v)
+    port.postMessage({ type: 'ack', id: msg.id })
+  })
+}
+
+const inApp = (path) =>
+  Boolean(appDir) && path.startsWith(appDir + sep) && !path.includes(`${sep}node_modules${sep}`)
+
+export async function resolve(specifier, context, nextResolve) {
+  const result = await nextResolve(specifier, context)
+  const url = new URL(result.url)
+  const own = TS.test(url.pathname) || STATOR.test(url.pathname)
+  const format = own ? 'module' : result.format
+  if (!VERSIONED.test(url.pathname) || format !== 'module') return result
+
+  // Stamp an app-local module with its current version (entries arrive already
+  // stamped by the dev server; children get theirs here).
+  if (url.protocol === 'file:' && !url.searchParams.has('v')) {
+    const path = fileURLToPath(url)
+    if (inApp(path)) {
+      url.searchParams.set('v', String(versions.get(path) ?? 1))
+      return { url: url.href, format, shortCircuit: true }
+    }
+  }
+  return own ? { ...result, format, shortCircuit: true } : result
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith('file:')) return nextLoad(url, context)
+  // `fileURLToPath` ignores the `?v=` query, so cache-busted URLs read the real file.
+  const path = fileURLToPath(url)
+
+  if (STATOR.test(path)) {
+    const source = await readFile(path, 'utf8')
+    const { id, kind } = appDir
+      ? sourceId(appDir, path)
+      : { id: path, kind: /[\\/]routes[\\/]/.test(path) ? 'route' : 'component' }
+    let result
+    try {
+      result = compile(source, { id, kind, resolveRegions: regionResolverFor(path, source) })
+    } catch (err) {
+      // Errors cross back to the main thread as plain Errors (custom props are
+      // dropped), so bake file:line:column + the code frame into the message.
+      throw err instanceof CompileError ? new Error(formatCompileError(err)) : err
+    }
+    const { code } = await transform(result.serverCode, {
+      loader: 'ts',
+      format: 'esm',
+      target: 'node20',
+      sourcemap: 'inline',
+      sourcefile: path,
+    })
+    return { format: 'module', source: code, shortCircuit: true }
+  }
+
+  if (TS.test(path)) {
+    const source = await readFile(path, 'utf8')
+    const { code } = await transform(source, {
+      loader: path.endsWith('x') ? 'tsx' : 'ts',
+      format: 'esm',
+      target: 'node20',
+      sourcemap: 'inline',
+      sourcefile: path,
+    })
+    return { format: 'module', source: code, shortCircuit: true }
+  }
+  return nextLoad(url, context)
+}