@statorjs/stator 2.5.1 → 2.7.0

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

@@ -0,0 +1,129 @@
+/**
+ * describeMachine — a machine def serialized to plain data.
+ *
+ * The def already IS the statechart: states, per-state `on` maps, guards,
+ * effects, emits, selectors and `serverOnly` are all present at runtime (only
+ * the event-union *type* is erased). This walks that structure into a
+ * JSON-able description — the SHAPE half of introspection. Consumers: the dev
+ * inspector's machine view; later the manifest, `stator check`, and viz.
+ *
+ * Closures stay opaque by design: a guard/action/effect reports presence,
+ * never its body. The walk normalizes the three authored transition forms
+ * (bare action fn, config object, ordered candidate array) exactly as
+ * `actor.send` does.
+ */
+
+import type {
+  AnyMachineDef,
+  EventObject,
+  Lifecycle,
+  OnMap,
+  StateNode,
+  Transition,
+  TransitionConfig,
+} from './types.ts'
+
+export interface TransitionDescription {
+  /** Target state; absent = self-transition (action only, no state change). */
+  to?: string
+  guarded: boolean
+  action: boolean
+  emits: string[]
+  effect: boolean
+}
+
+export interface StateDescription {
+  /** Event type → ordered guarded candidates (first whose guard passes wins). */
+  on: Record<string, TransitionDescription[]>
+  entry: boolean
+  after: Array<{ delay: number | 'dynamic'; send: string }>
+}
+
+export interface MachineDescription {
+  name: string
+  lifecycle: Lifecycle
+  persist: boolean
+  initial: string
+  states: Record<string, StateDescription>
+  /** Machine-level fallback handlers (consulted when the state declares none). */
+  on: Record<string, TransitionDescription[]>
+  /** Every event type the chart handles somewhere (state ∪ machine level), sorted. */
+  events: string[]
+  serverOnly: string[]
+  emits: string[]
+  selectors: string[]
+  reads: string[]
+  subscribes: Array<{ from: string; event: string; dispatch: string }>
+  /** The def's initial context (the shape a fresh instance starts from). */
+  context: unknown
+}
+
+type AnyTransition = Transition<unknown, EventObject, string>
+type AnyOnMap = OnMap<unknown, EventObject, string>
+
+function describeTransitions(value: AnyTransition | AnyTransition[]): TransitionDescription[] {
+  const candidates = Array.isArray(value) ? value : [value]
+  return candidates.map((entry) => {
+    // A bare function is sugar for `{ do: fn }` — same normalization as actor.send.
+    const config: TransitionConfig<unknown, EventObject, string> =
+      typeof entry === 'function' ? { do: entry } : entry
+    const emits =
+      config.emit === undefined ? [] : Array.isArray(config.emit) ? [...config.emit] : [config.emit]
+    return {
+      ...(config.to !== undefined ? { to: config.to } : {}),
+      guarded: config.when !== undefined,
+      action: config.do !== undefined,
+      emits,
+      effect: config.effect !== undefined,
+    }
+  })
+}
+
+function describeOn(on: AnyOnMap | undefined): Record<string, TransitionDescription[]> {
+  const out: Record<string, TransitionDescription[]> = {}
+  for (const [type, value] of Object.entries(on ?? {})) {
+    if (value !== undefined) out[type] = describeTransitions(value as AnyTransition)
+  }
+  return out
+}
+
+/** Serialize a def to plain JSON-able data. Pure; never invokes app code. */
+export function describeMachine(def: AnyMachineDef): MachineDescription {
+  const states: Record<string, StateDescription> = {}
+  for (const [name, node] of Object.entries(
+    def.states as Record<string, StateNode<unknown, EventObject, string>>,
+  )) {
+    states[name] = {
+      on: describeOn(node.on),
+      entry: node.entry !== undefined,
+      after: (node.after ?? []).map((a) => ({
+        delay: typeof a.delay === 'number' ? a.delay : 'dynamic',
+        send: a.send.type,
+      })),
+    }
+  }
+  const on = describeOn(def.on)
+  const events = new Set<string>(Object.keys(on))
+  for (const state of Object.values(states)) {
+    for (const type of Object.keys(state.on)) events.add(type)
+  }
+  return {
+    name: def.name,
+    lifecycle: def.lifecycle,
+    persist: def.persist,
+    initial: def.initial,
+    states,
+    on,
+    events: [...events].sort(),
+    serverOnly: [...def.serverOnly],
+    emits: Object.keys(def.emits),
+    selectors: Object.keys(def.selectors),
+    reads: def.reads.map((d) => d.name),
+    subscribes: def.subscribes.map((s) => ({
+      from: s.from.name,
+      event: s.event,
+      dispatch: typeof s.dispatch === 'string' ? s.dispatch : s.dispatch.type,
+    })),
+    context: def.context,
+  }
+}

package/src/engine/index.ts

@@ -10,6 +10,12 @@ export type { Actor, AnyActor, CreateActorOptions } from './actor.ts'
 export { createActor } from './actor.ts'
 export type { DefineMachineConfig } from './define-machine.ts'
 export { defineMachine } from './define-machine.ts'
+export type {
+  MachineDescription,
+  StateDescription,
+  TransitionDescription,
+} from './describe.ts'
+export { describeMachine } from './describe.ts'
 export type {
   Action,
   ActionHelpers,
@@ -19,6 +25,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)
+}