@statorjs/stator 2.5.1 → 2.7.0

package/README.md

@@ -29,7 +29,7 @@ pnpm add @statorjs/stator hono
 | `@statorjs/stator/build`    | `buildApp`, `loadProductionHead`, `syncTypes` |
 | `@statorjs/stator/components` | built-ins (`<JsonLd>`) |
 
-`compiler` and `vite` subpaths exist but are internal — their shape may change in minor releases.
+`compiler` and `vite` subpaths exist but are internal — their shape may change in minor releases. Neither is a plugin surface: Stator reads no `vite.config.*` and accepts no bundler plugins.
 
 ## Minimal app
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.5.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).",
+  "version": "2.7.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",
   "repository": {
@@ -17,8 +17,7 @@
     "state-machine",
     "ssr",
     "sse",
-    "islands",
-    "vite"
+    "islands"
   ],
   "files": [
     "src",
@@ -71,6 +70,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.13.0",
+    "chokidar": "^4.0.3",
     "esbuild": "^0.24.0",
     "hono": "^4.6.0",
     "ioredis": "^5.10.1",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.5.1"
+    "@statorjs/stator": "2.7.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/build.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto'
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
-import { join, relative, resolve, sep } from 'node:path'
-import { compile } from '../compiler/index.ts'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { compile, regionResolverFor } from '../compiler/index.ts'
+import { hashMachines } from '../server/machine-hash.ts'
+import { bundleIslands, routeIslandMap, walkFiles } from './islands.ts'
+import { sourceId } from './source-id.ts'
 
 /**
  * Production build: compile a `.stator` app to a `dist/` of plain `.ts` that the
@@ -13,17 +16,17 @@ import { compile } from '../compiler/index.ts'
  *      client entry as a sibling `*.stator.client.ts`
  *   3. rewrite `.stator` import specifiers (`'./x.stator'` → `'./x.stator.ts'`)
  *   4. write the concatenated scoped CSS to `dist/static/components.css`
- *   5. when the app has client components: bundle every island entry in one
- *      Vite build (hashed output under `dist/static/assets/`, server-machine
- *      imports stubbed to `{ name }` via `machineStub`), walk each route's
- *      import graph to find which islands it reaches, and write
- *      `dist/stator-manifest.json` mapping route files → island script URLs
+ *   5. when the app has client components: bundle every island entry through
+ *      the `bundleIslands` seam (hashed output written under
+ *      `dist/static/assets/`, server-machine imports stubbed to `{ name }`),
+ *      walk each route's import graph to find which islands it reaches, and
+ *      write `dist/stator-manifest.json` mapping route files → island script URLs
  *
  * The prod server runs `createApp` over `dist/` with the `headExtras` hook
  * from `loadProductionHead(dist)` — it links `components.css` and injects the
  * manifest's `<script type="module">` tags per route. File discovery + dynamic
- * import work unchanged on the precompiled output; Vite is needed only at
- * build time, and only when islands exist.
+ * import work unchanged on the precompiled output; the island bundler is
+ * needed only at build time, and only when islands exist.
  */
 
 export interface BuildConfig {
@@ -46,6 +49,13 @@ export interface BuildResult {
   hasCss: boolean
   /** Number of client components bundled for the browser. */
   islands: number
+  /** Machines hashed for the snapshot hydration policy, and how long it took. */
+  machines: number
+  machineHashMs: number
+  /** Machine files (relative to `machines/`) whose code hash differs from the
+   *  previous build's manifest — their sessions reset on deploy. `undefined`
+   *  when there was no previous manifest to compare against. */
+  resetMachines?: string[]
 }
 
 /** Shape of `dist/stator-manifest.json` (always written — carries `buildId`). */
@@ -57,6 +67,10 @@ export interface StatorManifest {
   islands: Record<string, string>
   /** Route file (dist-relative) → script URLs for every island it reaches. */
   routes: Record<string, string[]>
+  /** Machine file (relative to `machines/`) → code hash. Consumed by
+   *  `stator start` for the snapshot hydration policy; the build fails if a
+   *  machine's closure cannot be bundled, so this lands in CI, not at boot. */
+  machines: Record<string, string>
 }
 
 const NEVER_COPY = new Set(['node_modules', 'tests', 'test', '__tests__'])
@@ -79,6 +93,12 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
   const outDir = resolve(config.outDir)
   const dirs = config.dirs ?? (await discoverSourceDirs(root, outDir))
 
+  // Remember the previous build's machine hashes (if any) so the build can
+  // report which machines' sessions this deploy resets.
+  const previous = await readFile(join(outDir, 'stator-manifest.json'), 'utf8')
+    .then((t) => (JSON.parse(t) as Partial<StatorManifest>).machines)
+    .catch(() => undefined)
+
   await rm(outDir, { recursive: true, force: true })
   await mkdir(outDir, { recursive: true })
   for (const d of dirs) {
@@ -95,14 +115,19 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
   if (await exists(bootSrc)) await cp(bootSrc, join(outDir, 'boot.ts'))
 
   // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
-  const statorFiles = await walk(outDir, (f) => f.endsWith('.stator'))
+  // The sources are deleted only after the whole set compiles — cross-file
+  // region validation reads sibling `.stator` files mid-compile.
+  const statorFiles = await walkFiles(outDir, (f) => f.endsWith('.stator'))
   let css = ''
   const islands: Array<{ rel: string; entry: string }> = []
   for (const file of statorFiles) {
     const source = await readFile(file, 'utf8')
-    const rel = relative(outDir, file)
-    const kind = /(^|[\\/])routes[\\/]/.test(rel) ? ('route' as const) : ('component' as const)
-    const result = compile(source, { id: rel, kind })
+    const { id: rel, kind } = sourceId(outDir, file)
+    const result = compile(source, {
+      id: rel,
+      kind,
+      resolveRegions: regionResolverFor(file, source),
+    })
     await writeFile(`${file}.ts`, result.serverCode)
     if (result.isClient) {
       // The generated client entry, written as a sibling so the authored
@@ -110,12 +135,12 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
       await writeFile(`${file}.client.ts`, result.clientCode)
       islands.push({ rel, entry: `${file}.client.ts` })
     }
-    await rm(file)
     if (result.css) css += `/* ${rel} */\n${result.css}\n`
   }
+  for (const file of statorFiles) await rm(file)
 
   // Rewrite `.stator` import specifiers to the compiled `.stator.ts` sibling.
-  const tsFiles = await walk(outDir, (f) => f.endsWith('.ts'))
+  const tsFiles = await walkFiles(outDir, (f) => f.endsWith('.ts'))
   for (const file of tsFiles) {
     const code = await readFile(file, 'utf8')
     const rewritten = code.replace(/(['"])([^'"]+\.stator)\1/g, '$1$2.ts$1')
@@ -127,115 +152,79 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     await writeFile(join(outDir, 'static', 'components.css'), css)
   }
 
+  // Machine code hashes for the snapshot hydration policy: one esbuild pass
+  // over dist/machines. Throws (failing the build) if a closure can't bundle.
+  const machinesDir = join(outDir, 'machines')
+  const machineFiles = (
+    await walkFiles(machinesDir, (f) => /\.(ts|js)$/.test(f)).catch(() => [] as string[])
+  ).filter((f) => resolve(f, '..') === resolve(machinesDir))
+  const t0 = performance.now()
+  const hashed = await hashMachines(machineFiles, { machinesDir })
+  const machineHashMs = Math.round(performance.now() - t0)
+  const machines: Record<string, string> = {}
+  for (const file of machineFiles.sort()) {
+    machines[relative(machinesDir, file).replace(/\\/g, '/')] = hashed.get(file)!.hash
+  }
+  const resetMachines = previous
+    ? Object.keys(machines).filter((k) => previous[k] !== machines[k])
+    : undefined
+
   // Always write the manifest — it carries the build-id even for an app with no
   // islands (a live route without islands still needs the reload handshake).
   const manifest: StatorManifest =
     islands.length > 0
-      ? { buildId: randomUUID(), ...(await buildClientAssets(outDir, islands)) }
-      : { buildId: randomUUID(), islands: {}, routes: {} }
+      ? { buildId: randomUUID(), ...(await buildClientAssets(outDir, islands)), machines }
+      : { buildId: randomUUID(), islands: {}, routes: {}, machines }
   await writeFile(join(outDir, 'stator-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
 
-  return { outDir, compiled: statorFiles.length, hasCss: Boolean(css), islands: islands.length }
+  return {
+    outDir,
+    compiled: statorFiles.length,
+    hasCss: Boolean(css),
+    islands: islands.length,
+    machines: machineFiles.length,
+    machineHashMs,
+    ...(resetMachines ? { resetMachines } : {}),
+  }
 }
 
 /**
- * Bundle every island entry in one Vite build and derive the manifest.
- * Vite is imported lazily — server-only apps never need it at build time.
+ * Bundle every island entry through the seam, write the emitted files under
+ * `static/assets/`, and derive the route → island-script manifest.
  */
 async function buildClientAssets(
   outDir: string,
   islands: Array<{ rel: string; entry: string }>,
-): Promise<Omit<StatorManifest, 'buildId'>> {
-  const [{ build: viteBuild }, { machineStub }] = await Promise.all([
-    import('vite'),
-    import('../vite/stub.ts'),
-  ])
-
-  const input: Record<string, string> = {}
-  for (const island of islands) {
-    input[island.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_')] = island.entry
-  }
-
-  const assetsDir = join(outDir, 'static', 'assets')
-  await viteBuild({
+): Promise<Pick<StatorManifest, 'islands' | 'routes'>> {
+  const bundle = await bundleIslands({
     root: outDir,
-    logLevel: 'warn',
-    configFile: false,
-    plugins: [machineStub({ machinesDir: join(outDir, 'machines') })],
-    build: {
-      outDir: assetsDir,
-      emptyOutDir: true,
-      manifest: true,
-      rollupOptions: {
-        input,
-        output: {
-          entryFileNames: '[name]-[hash].js',
-          chunkFileNames: 'chunks/[name]-[hash].js',
-          assetFileNames: '[name]-[hash][extname]',
-        },
-      },
-    },
+    machinesDir: join(outDir, 'machines'),
+    entries: islands.map((i) => ({ rel: i.rel, file: i.entry })),
   })
 
-  // Vite's manifest keys inputs by root-relative path; map back to islands.
-  const viteManifest = JSON.parse(
-    await readFile(join(assetsDir, '.vite', 'manifest.json'), 'utf8'),
-  ) as Record<string, { file: string; isEntry?: boolean }>
-  const islandUrls: Record<string, string> = {}
-  for (const island of islands) {
-    const key = relative(outDir, island.entry).replace(/\\/g, '/')
-    const entry = viteManifest[key]
-    if (!entry) throw new Error(`stator: island "${island.rel}" missing from Vite manifest`)
-    islandUrls[island.rel] = `/static/assets/${entry.file}`
+  const assetsDir = join(outDir, 'static', 'assets')
+  await rm(assetsDir, { recursive: true, force: true })
+  for (const asset of bundle.assets) {
+    const target = join(assetsDir, asset.fileName)
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, asset.source)
   }
 
-  // Per-route reachability: walk each route file's relative-import graph
-  // (post-rewrite, so island shells appear as `<island>.ts`) and record which
-  // islands it reaches. Mirrors the dev server's module-graph walk.
-  const shellToIsland = new Map(islands.map((i) => [resolve(outDir, `${i.rel}.ts`), i.rel]))
-  const routeFiles = await walk(join(outDir, 'routes'), (f) => f.endsWith('.ts'))
+  // Per-route reachability over the rewritten dist tree: island shells appear
+  // as `<island>.stator.ts`.
+  const shells = new Map(islands.map((i) => [resolve(outDir, `${i.rel}.ts`), i.rel]))
+  const byRoute = await routeIslandMap({
+    routesDir: join(outDir, 'routes'),
+    baseDir: outDir,
+    shells,
+  })
   const routes: Record<string, string[]> = {}
-  for (const routeFile of routeFiles) {
-    const reached = new Set<string>()
-    await walkImports(routeFile, outDir, new Set(), (file) => {
-      const island = shellToIsland.get(file)
-      if (island) reached.add(island)
-    })
-    if (reached.size > 0) {
-      routes[relative(outDir, routeFile).replace(/\\/g, '/')] = [...reached]
-        .sort()
-        .map((rel) => islandUrls[rel]!)
-    }
-  }
-
-  return { islands: islandUrls, routes }
-}
-
-const IMPORT_SPECIFIER_RE = /(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g
-
-/** Depth-first walk of a file's relative-import graph, bounded to `outDir`. */
-async function walkImports(
-  file: string,
-  outDir: string,
-  seen: Set<string>,
-  visit: (file: string) => void,
-): Promise<void> {
-  if (seen.has(file)) return
-  seen.add(file)
-  visit(file)
-  let code: string
-  try {
-    code = await readFile(file, 'utf8')
-  } catch {
-    return
-  }
-  for (const match of code.matchAll(IMPORT_SPECIFIER_RE)) {
-    const spec = match[1]!
-    if (!spec.startsWith('.')) continue
-    const target = resolve(join(file, '..'), spec)
-    if (!target.startsWith(outDir)) continue
-    await walkImports(target, outDir, seen, visit)
+  for (const [routeFile, rels] of byRoute) {
+    routes[relative(outDir, routeFile).replace(/\\/g, '/')] = rels.map(
+      (rel) => bundle.islandUrls[rel]!,
+    )
   }
+  return { islands: bundle.islandUrls, routes }
 }
 
 async function exists(path: string): Promise<boolean> {
@@ -246,14 +235,3 @@ async function exists(path: string): Promise<boolean> {
     return false
   }
 }
-
-async function walk(dir: string, match: (file: string) => boolean): Promise<string[]> {
-  const out: string[] = []
-  const entries = await readdir(dir, { withFileTypes: true })
-  for (const e of entries) {
-    const full = join(dir, e.name)
-    if (e.isDirectory()) out.push(...(await walk(full, match)))
-    else if (match(full)) out.push(full)
-  }
-  return out
-}

package/src/build/head.ts

@@ -13,9 +13,14 @@ import type { StatorManifest } from './build.ts'
  * Everything is optional — a server-only app without styles gets an empty hook,
  * and a build with no `buildId` in its manifest just skips the reload handshake.
  */
-export async function loadProductionHead(
-  distDir: string,
-): Promise<{ headExtras: (filePath: string) => string; buildId?: string }> {
+export async function loadProductionHead(distDir: string): Promise<{
+  headExtras: (filePath: string) => string
+  buildId?: string
+  /** Machine file → code hash from the build manifest; pass to `createApp` as
+   *  `machineHashes` so hydration compares against what was built. Absent on
+   *  a dist built before hashes existed — `createApp` then hashes live. */
+  machines?: Record<string, string>
+}> {
   const dist = resolve(distDir)
 
   let cssTag = ''
@@ -28,12 +33,14 @@ export async function loadProductionHead(
 
   let routes: StatorManifest['routes'] = {}
   let buildId: string | undefined
+  let machines: Record<string, string> | undefined
   try {
     const manifest = JSON.parse(
       await readFile(join(dist, 'stator-manifest.json'), 'utf8'),
     ) as StatorManifest
     routes = manifest.routes ?? {}
     buildId = manifest.buildId
+    machines = manifest.machines
   } catch {
     // no manifest
   }
@@ -45,5 +52,5 @@ export async function loadProductionHead(
       .filter(Boolean)
       .join('\n')
   }
-  return { headExtras, buildId }
+  return { headExtras, buildId, ...(machines ? { machines } : {}) }
 }

package/src/build/index.ts

@@ -6,5 +6,14 @@
 export type { BuildConfig, BuildResult, StatorManifest } from './build.ts'
 export { buildApp } from './build.ts'
 export { loadProductionHead } from './head.ts'
+export type {
+  BundleIslandsOptions,
+  IslandAsset,
+  IslandBundle,
+  IslandBundler,
+  IslandEntry,
+} from './islands.ts'
+export { bundleIslands, routeIslandMap } from './islands.ts'
+export { sourceId } from './source-id.ts'
 export type { SyncResult } from './sync.ts'
 export { syncTypes } from './sync.ts'

package/src/build/islands.ts

@@ -0,0 +1,228 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import type { Rollup } from 'vite'
+
+/**
+ * The island-bundling seam — Lock 1 of the Vite exit (spec
+ * `toolchain-adapter-seam-and-the-vite-exit`).
+ *
+ * `bundleIslands` is a pure inputs→outputs function: island entries in; emitted
+ * files, a rel→URL map, and the list of source modules that went in, out.
+ * Nothing is written or served here — `buildApp` writes the assets under
+ * `dist/static/assets/`, the native dev server keeps them in memory. That is
+ * what makes the bundler a one-implementation swap (Vite today; esbuild is the
+ * Option E candidate) with the same core feeding both sides.
+ *
+ * The entry contract is deliberately tiny: an entry is either the island's
+ * `.stator` SOURCE (the bundler compiles its `<script>` to the client module)
+ * or a prebuilt client entry module. Server-machine imports inside an island
+ * collapse to `{ name }` identity stubs; the machine body never ships.
+ */
+
+export interface IslandEntry {
+  /** App-relative `.stator` path, `/`-separated — the island's manifest identity. */
+  rel: string
+  /** Absolute entry file: the `.stator` source, or a prebuilt client entry. */
+  file: string
+}
+
+export interface IslandAsset {
+  /** Path relative to the assets root (entries, shared chunks, emitted assets). */
+  fileName: string
+  source: string | Uint8Array
+}
+
+export interface IslandBundle {
+  /** Island rel → public URL of its entry script. */
+  islandUrls: Record<string, string>
+  assets: IslandAsset[]
+  /** Absolute path of every source module in the bundle (queries and stub
+   *  prefixes stripped, `/`-separated) — lets a watcher decide whether an edit
+   *  needs a rebundle without knowing anything about the bundler. */
+  modules: string[]
+}
+
+export interface BundleIslandsOptions {
+  /** Resolution root (the app dir, or dist) — must reach node_modules. */
+  root: string
+  /** Directory whose modules are stubbed to `{ name }` in browser bundles. */
+  machinesDir: string
+  entries: IslandEntry[]
+  /** URL prefix the assets are served under. Default `/static/assets/`. */
+  publicPath?: string
+  /** Seam contract: `true` appends an INLINE sourcemap to each emitted chunk
+   *  (a `sourceMappingURL=data:` comment — self-contained, so in-memory dev
+   *  serving needs no extra `.map` routes and browser devtools show island
+   *  source). Default off — production bundles ship unmapped. */
+  sourcemap?: boolean
+}
+
+export type IslandBundler = (opts: BundleIslandsOptions) => Promise<IslandBundle>
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+const stripQuery = (id: string): string => {
+  const q = id.indexOf('?')
+  return q === -1 ? id : id.slice(0, q)
+}
+
+/** Implementation #1: one Vite build over every island entry. Vite is imported
+ *  lazily — server-only apps never load it. */
+export const bundleIslands: IslandBundler = async (opts) => {
+  const [{ build: viteBuild }, { CLIENT_QUERY, MACHINE_STUB_PREFIX, machineStub, stator }] =
+    await Promise.all([import('vite'), import('../vite/index.ts')])
+  const publicPath = opts.publicPath ?? '/static/assets/'
+
+  const input: Record<string, string> = {}
+  const byFile = new Map<string, IslandEntry>()
+  for (const entry of opts.entries) {
+    const file = resolve(entry.file)
+    input[entry.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_')] = file.endsWith('.stator')
+      ? `${file}?${CLIENT_QUERY}`
+      : file
+    byFile.set(norm(file), entry)
+  }
+
+  const result = await viteBuild({
+    root: opts.root,
+    // Assets referenced by URL from island code (`new URL(...)`, CSS `url()`)
+    // render against `base`, so it must be where the assets are served from.
+    base: publicPath,
+    logLevel: 'warn',
+    configFile: false,
+    plugins: [stator(), machineStub({ machinesDir: resolve(opts.machinesDir) })],
+    build: {
+      write: false,
+      // Seam contract: a URL-referenced asset (`new URL('./x.wasm',
+      // import.meta.url)`) is always emitted as a hashed FILE, never inlined
+      // as a data: URL — deterministic for callers and identical to what an
+      // esbuild implementation (file loader) produces.
+      assetsInlineLimit: 0,
+      sourcemap: opts.sourcemap ? 'inline' : false,
+      rollupOptions: {
+        input,
+        output: {
+          entryFileNames: '[name]-[hash].js',
+          chunkFileNames: 'chunks/[name]-[hash].js',
+          assetFileNames: '[name]-[hash][extname]',
+        },
+      },
+    },
+  })
+  const outputs = (Array.isArray(result) ? result : [result]).filter(
+    (r): r is Rollup.RollupOutput => 'output' in r,
+  )
+
+  const islandUrls: Record<string, string> = {}
+  const assets: IslandAsset[] = []
+  const modules = new Set<string>()
+  const sourcePathOf = (id: string): string | null => {
+    const raw = id.startsWith(MACHINE_STUB_PREFIX) ? id.slice(MACHINE_STUB_PREFIX.length) : id
+    if (raw.startsWith('\0')) return null
+    return norm(stripQuery(raw))
+  }
+  for (const out of outputs) {
+    for (const item of out.output) {
+      if (item.type === 'chunk') {
+        assets.push({ fileName: item.fileName, source: item.code })
+        for (const id of Object.keys(item.modules)) {
+          const p = sourcePathOf(id)
+          if (p) modules.add(p)
+        }
+        if (item.isEntry && item.facadeModuleId) {
+          const entry = byFile.get(norm(stripQuery(item.facadeModuleId)))
+          if (entry) islandUrls[entry.rel] = publicPath + item.fileName
+        }
+      } else {
+        assets.push({ fileName: item.fileName, source: item.source })
+      }
+    }
+  }
+  for (const entry of opts.entries) {
+    if (!islandUrls[entry.rel])
+      throw new Error(`stator: island "${entry.rel}" missing from the bundle output`)
+  }
+  return { islandUrls, assets, modules: [...modules] }
+}
+
+/**
+ * Per-route island reachability: walk each route file's relative-import graph
+ * (bounded to `baseDir`) and record which island shells it reaches. `shells`
+ * maps an island's server-side module file (the `.stator` source in dev, the
+ * compiled `.stator.ts` in dist) to the island's rel. Returns absolute route
+ * file → sorted island rels, only for routes that reach at least one island.
+ */
+export async function routeIslandMap(opts: {
+  routesDir: string
+  baseDir: string
+  shells: Map<string, string>
+}): Promise<Map<string, string[]>> {
+  const baseDir = resolve(opts.baseDir)
+  const routes = new Map<string, string[]>()
+  const routeFiles = await walkFiles(opts.routesDir, (f) => /\.(ts|js|stator)$/.test(f)).catch(
+    () => [] as string[],
+  )
+  for (const routeFile of routeFiles) {
+    const reached = new Set<string>()
+    await walkImports(routeFile, baseDir, new Set(), (file) => {
+      const island = opts.shells.get(file)
+      if (island) reached.add(island)
+    })
+    if (reached.size > 0) routes.set(routeFile, [...reached].sort())
+  }
+  return routes
+}
+
+const IMPORT_SPECIFIER_RE = /(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g
+
+/** Absolute targets of a file's relative import specifiers, bounded to
+ *  `baseDir` (a static regex read — no module evaluation; an unreadable file
+ *  yields none). Specifiers carry explicit extensions by convention. */
+export async function localImports(file: string, baseDir: string): Promise<string[]> {
+  let code: string
+  try {
+    code = await readFile(file, 'utf8')
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const match of code.matchAll(IMPORT_SPECIFIER_RE)) {
+    const spec = match[1]!
+    if (!spec.startsWith('.')) continue
+    const target = resolve(join(file, '..'), spec)
+    if (target.startsWith(baseDir)) out.push(target)
+  }
+  return out
+}
+
+/** Depth-first walk of a file's relative-import graph, bounded to `baseDir`. */
+export async function walkImports(
+  file: string,
+  baseDir: string,
+  seen: Set<string>,
+  visit: (file: string) => void,
+): Promise<void> {
+  if (seen.has(file)) return
+  seen.add(file)
+  visit(file)
+  for (const target of await localImports(file, baseDir)) {
+    await walkImports(target, baseDir, seen, visit)
+  }
+}
+
+/** Recursive file listing. `skipDir` prunes a directory by name. */
+export async function walkFiles(
+  dir: string,
+  match: (file: string) => boolean,
+  skipDir?: (name: string) => boolean,
+): Promise<string[]> {
+  const out: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  for (const e of entries) {
+    const full = join(dir, e.name)
+    if (e.isDirectory()) {
+      if (skipDir?.(e.name)) continue
+      out.push(...(await walkFiles(full, match, skipDir)))
+    } else if (match(full)) out.push(full)
+  }
+  return out
+}

package/src/build/source-id.ts

@@ -0,0 +1,15 @@
+import { relative } from 'node:path'
+
+/**
+ * The identity a `.stator` file compiles under, derived from its path relative
+ * to the app (or dist) root: `id` seeds the scope hash and labels diagnostics,
+ * `kind` selects the route-page vs component capability set. Every compile
+ * path — `buildApp`, the native dev server's CSS scan, and the dev loader — must
+ * agree on this, or markup compiled on one thread won't match CSS scoped on
+ * another. Always `/`-separated so ids (and manifest keys) are stable across
+ * operating systems.
+ */
+export function sourceId(base: string, file: string): { id: string; kind: 'route' | 'component' } {
+  const id = relative(base, file).replace(/\\/g, '/')
+  return { id, kind: /(^|\/)routes\//.test(id) ? 'route' : 'component' }
+}

package/src/cli/commands/build.ts

@@ -10,6 +10,16 @@ export async function run(ctx: CliContext): Promise<void> {
   const result = await buildApp({ root: ctx.root, outDir: resolve(ctx.root, 'dist') })
   process.stdout.write(
     `stator build: ${result.compiled} components → ${result.outDir}` +
-      `${result.islands ? ` (${result.islands} island${result.islands === 1 ? '' : 's'})` : ''}\n`,
+      `${result.islands ? ` (${result.islands} island${result.islands === 1 ? '' : 's'})` : ''}` +
+      ` · ${result.machines} machine${result.machines === 1 ? '' : 's'} hashed in ${result.machineHashMs} ms\n`,
   )
+  // Deploy awareness: which machines' sessions this build resets (see the
+  // snapshot hydration policy — sessions never outlive the code that made them).
+  if (result.resetMachines) {
+    process.stdout.write(
+      result.resetMachines.length
+        ? `  machine code changed — sessions reset on deploy for: ${result.resetMachines.join(', ')}\n`
+        : '  no machine code changed — sessions carry over\n',
+    )
+  }
 }