@statorjs/stator 2.12.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "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, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -47,6 +47,7 @@
       "types": "./src/server/dev.ts",
       "default": "./src/server/dev.ts"
     },
+    "./register": "./src/register.js",
     "./build": {
       "types": "./src/build/index.ts",
       "default": "./src/build/index.ts"
@@ -105,7 +106,7 @@
     "pino-pretty": "^13.2.0",
     "vite": "^6.4.5",
     "vitest": "^3.2.7",
-    "@statorjs/stator": "2.12.0"
+    "@statorjs/stator": "2.13.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/cli/commands/test.ts

@@ -3,6 +3,23 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { CliContext } from '../run.ts'
 
+/** `@statorjs/stator/register`, by absolute URL so it resolves whatever the
+ *  runner's working directory. */
+const REGISTER = new URL('../../register.js', import.meta.url).href
+
+/**
+ * The runner's environment: `NODE_OPTIONS` gains `--import` of Stator's
+ * loader, kept alongside anything already there. Stator ships TypeScript,
+ * and a runner hands `node_modules` to Node — so Stator, and every package
+ * built on it (direct or transitive, hoisted or not), would otherwise reach
+ * Node unloadable. Child processes and workers inherit it.
+ */
+export function testEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const flag = `--import ${REGISTER}`
+  const current = env.NODE_OPTIONS?.trim() ?? ''
+  return { ...env, NODE_OPTIONS: current.includes(flag) ? current : `${current} ${flag}`.trim() }
+}
+
 /**
  * Run the test suite. The runner is a deliberately swappable seam — today it
  * wraps the app's local Vitest; as the platform matures this becomes
@@ -22,7 +39,7 @@ export async function run(ctx: CliContext): Promise<void> {
   }
   const args = ctx.rest.length > 0 ? ctx.rest : ['run']
   await new Promise<void>((resolvePromise, reject) => {
-    const child = spawn(bin, args, { stdio: 'inherit', cwd: ctx.root })
+    const child = spawn(bin, args, { stdio: 'inherit', cwd: ctx.root, env: testEnv() })
     child.on('error', reject)
     child.on('exit', (code) =>
       code === 0 ? resolvePromise() : reject(new Error(`tests failed (exit ${code})`)),

package/src/cli/stator.js

@@ -21,16 +21,15 @@ if (typeof register !== 'function') {
   process.exit(1)
 }
 
-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 loader and source maps — the same registration `--import
+// @statorjs/stator/register` gives a process the CLI doesn't start. Source
+// maps: every transform in the owned pipeline (the TS loader, the dev
+// loader's `.stator` compile) already EMITS an inline map, but V8 ignores
+// maps when capturing stacks unless the process opts in — the runtime
+// equivalent of `--enable-source-maps`, which a bin script can't put on its
+// own invocation. (`.stator` traces resolve to the compiled server module —
+// right file, generated lines — until the compiler emits its own map.)
+await import('../register.js')
 
 // The real CLI is TypeScript, transformed on import by the loader just registered.
 await import('./run.ts')

package/src/register.js

@@ -0,0 +1,21 @@
+// `--import @statorjs/stator/register`: Stator's TS loader for any process
+// the `stator` CLI doesn't start — a test runner launched by an editor,
+// `npx vitest`, `node scripts/x.ts`. Stator ships TypeScript source, and Node
+// won't strip types inside node_modules (or, from a linked checkout, strips
+// only a subset), so anything that imports Stator, or a package built on it,
+// needs this loader. `stator dev`/`start`/`build` register it themselves and
+// `stator test` passes it to the runner. Plain JS so Node can import it with
+// no loader in place yet.
+import nodeModule from 'node:module'
+
+if (typeof nodeModule.register !== 'function') {
+  throw new Error(
+    `@statorjs/stator/register needs module.register — Node 18.19+ or 20.6+ (found ${process.version}).`,
+  )
+}
+
+nodeModule.register('./cli/loader.js', import.meta.url)
+
+// Every transform the loader makes emits an inline map; V8 only applies
+// them to stack traces when the process opts in.
+process.setSourceMapsEnabled?.(true)

package/src/server/dev-vite.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { createServer as createHttpServer } from 'node:http'
-import { relative, resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import { getRequestListener } from '@hono/node-server'
 import type { Hono } from 'hono'
 import { createServer as createViteServer, type ViteDevServer } from 'vite'
@@ -36,6 +36,36 @@ import { isStatorQueryRoute } from './routing.ts'
  * 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 app's direct dependencies that depend on Stator, for `ssr.noExternal`
+ * above. Transitional, like this whole module (removed with the Vite exit):
+ * the native dev server and production load one module graph, where the
+ * dual-instance trap can't happen. Direct dependencies only — a deeper one
+ * still loads (`@statorjs/stator/register` handles that) but as a second
+ * instance.
+ */
+function statorDependents(root: string): string[] {
+  const read = (path: string): Record<string, Record<string, string> | undefined> | null => {
+    try {
+      return JSON.parse(readFileSync(path, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+  const app = read(join(root, 'package.json'))
+  if (!app) return []
+  return Object.keys({ ...app.dependencies, ...app.devDependencies }).filter((name) => {
+    if (name === '@statorjs/stator') return false
+    const pkg = read(join(root, 'node_modules', name, 'package.json'))
+    return Boolean(
+      pkg &&
+        [pkg.dependencies, pkg.peerDependencies, pkg.optionalDependencies].some(
+          (deps) => deps && '@statorjs/stator' in deps,
+        ),
+    )
+  })
+}
+
 export async function createViteDevApp(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).
@@ -61,8 +91,11 @@ export async function createViteDevApp(config: DevAppConfig): Promise<DevApp> {
     // 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/] },
+    // The framework's own source is TS that Vite must transform, not
+    // externalize — and so must packages built on it, or they load through
+    // Node with a second Stator instance (the dual-instance trap: a
+    // component they render finds no render context).
+    ssr: { noExternal: [/@statorjs\/stator/, ...statorDependents(resolve(config.root))] },
     logLevel: 'warn',
   })