@statorjs/stator 2.7.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.7.0",
+  "version": "2.8.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",
@@ -95,7 +95,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.7.0"
+    "@statorjs/stator": "2.8.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build/islands-esbuild.ts

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { BundleIslandsOptions, IslandAsset, IslandBundler } from './islands.ts'
+
+/**
+ * Implementation #2 of the island-bundling seam (spike for Option E of the
+ * Vite exit): one esbuild build over every island entry, `splitting: true` so
+ * shared modules — the client runtime above all — land in shared chunks
+ * instead of duplicating per island.
+ *
+ * Same contract as the Vite implementation in `islands.ts`: entries are
+ * `.stator` sources (compiled to their client module here) or prebuilt client
+ * entry modules; server-machine imports collapse to `{ name }` stubs; nothing
+ * is written — callers own the assets.
+ */
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+
+const STUB_NS = 'stator-machine-stub'
+
+/** Extensions an island may reference by URL; emitted as hashed files (the
+ *  seam contract — never inlined), mirroring Vite's `assetsInlineLimit: 0`. */
+const FILE_LOADERS: Record<string, 'file'> = Object.fromEntries(
+  ['.wasm', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.woff', '.woff2'].map((e) => [
+    e,
+    'file' as const,
+  ]),
+)
+
+export const bundleIslandsEsbuild: IslandBundler = async (opts: BundleIslandsOptions) => {
+  const [{ build }, { compile, regionResolverFor }] = await Promise.all([
+    import('esbuild'),
+    import('../compiler/index.ts'),
+  ])
+  const publicPath = opts.publicPath ?? '/static/assets/'
+  const root = resolve(opts.root)
+  const machinesDir = resolve(opts.machinesDir)
+  const outDir = resolve(root, '.stator-island-out') // virtual — write: false
+  const inMachinesDir = (abs: string): boolean =>
+    abs === machinesDir || abs.startsWith(machinesDir + sep)
+
+  const entryPoints = opts.entries.map((entry) => ({
+    in: resolve(entry.file),
+    out: entry.rel.replace(/\.stator$/, '').replace(/[\\/]/g, '_'),
+  }))
+  const byFile = new Map(opts.entries.map((e) => [norm(resolve(e.file)), e]))
+
+  // Rollup/Vite rewrite `new URL('./x', import.meta.url)` to an emitted asset;
+  // esbuild does not, so the seam does it here: each URL-referenced relative
+  // asset becomes an import (the file loader emits it hashed and exports its
+  // public URL, root-absolute under `publicPath`, so the `new URL` still
+  // resolves). Only string-literal relative specifiers — same limit as Vite.
+  const URL_ASSET_RE = /new\s+URL\(\s*(['"])(\.{1,2}\/[^'"\n]+)\1\s*,\s*import\.meta\.url\s*\)/g
+  const rewriteUrlAssets = (code: string): string => {
+    let n = 0
+    const imports: string[] = []
+    const out = code.replace(URL_ASSET_RE, (_m, _q: string, spec: string) => {
+      const id = `__stator_url_asset_${n++}`
+      imports.push(`import ${id} from ${JSON.stringify(spec)}`)
+      return `new URL(${id}, import.meta.url)`
+    })
+    return imports.length === 0 ? code : `${imports.join('\n')}\n${out}`
+  }
+
+  const statorPlugin = {
+    name: 'stator-client',
+    setup(b: import('esbuild').PluginBuild) {
+      b.onLoad({ filter: /\.stator$/ }, async (args) => {
+        const source = await readFile(args.path, 'utf8')
+        const kind = /[\\/]routes[\\/].*\.stator$/.test(args.path) ? 'route' : 'component'
+        const result = compile(source, {
+          id: args.path,
+          kind,
+          resolveRegions: regionResolverFor(args.path, source),
+        })
+        return {
+          contents: result.isClient ? rewriteUrlAssets(result.clientCode) : 'export {}',
+          loader: 'ts',
+          resolveDir: dirname(args.path),
+        }
+      })
+      b.onLoad({ filter: /\.(ts|mts|js|mjs)$/ }, async (args) => {
+        const source = await readFile(args.path, 'utf8')
+        const rewritten = rewriteUrlAssets(source)
+        if (rewritten === source) return undefined
+        return {
+          contents: rewritten,
+          loader: args.path.endsWith('js') ? 'js' : 'ts',
+          resolveDir: dirname(args.path),
+        }
+      })
+    },
+  }
+
+  const machineStubPlugin = {
+    name: 'stator-machine-stub',
+    setup(b: import('esbuild').PluginBuild) {
+      b.onResolve({ filter: /^[./]/ }, (args) => {
+        if (args.namespace === STUB_NS) return null
+        const base = isAbsolute(args.path) ? args.path : resolve(args.resolveDir, args.path)
+        const abs = [base, `${base}.ts`, `${base}.js`].find(inMachinesDir)
+        if (!abs) return null
+        return { path: abs, namespace: STUB_NS }
+      })
+      b.onLoad({ filter: /.*/, namespace: STUB_NS }, async (args) => {
+        let name: unknown
+        try {
+          const mod = (await import(pathToFileURL(args.path).href)) as {
+            default?: { name?: unknown }
+          }
+          name = mod.default?.name
+        } catch (err) {
+          throw new Error(
+            `stator: cannot stub server-machine import "${args.path}" for the client bundle — ` +
+              `importing it in Node failed: ${(err as Error).message}`,
+          )
+        }
+        if (typeof name !== 'string') {
+          throw new Error(
+            `stator: cannot stub "${args.path}" — it does not default-export a machine with a name. ` +
+              `Only machine defs may be imported from the machines directory in client code.`,
+          )
+        }
+        return { contents: `export default { name: ${JSON.stringify(name)} }\n`, loader: 'js' }
+      })
+    },
+  }
+
+  const result = await build({
+    absWorkingDir: root,
+    entryPoints,
+    outdir: outDir,
+    bundle: true,
+    splitting: true,
+    format: 'esm',
+    write: false,
+    metafile: true,
+    minify: true,
+    publicPath,
+    sourcemap: opts.sourcemap ? 'inline' : false,
+    entryNames: '[name]-[hash]',
+    chunkNames: 'chunks/[name]-[hash]',
+    assetNames: '[name]-[hash]',
+    loader: FILE_LOADERS,
+    logLevel: 'warning',
+    plugins: [machineStubPlugin, statorPlugin],
+  })
+
+  const assets: IslandAsset[] = result.outputFiles.map((f) => {
+    const fileName = norm(relative(outDir, f.path))
+    return fileName.endsWith('.js')
+      ? { fileName, source: f.text }
+      : { fileName, source: f.contents }
+  })
+
+  const modules = new Set<string>()
+  for (const key of Object.keys(result.metafile.inputs)) {
+    if (key.startsWith(`${STUB_NS}:`)) modules.add(norm(key.slice(STUB_NS.length + 1)))
+    else modules.add(norm(resolve(root, key)))
+  }
+
+  const islandUrls: Record<string, string> = {}
+  for (const [outPath, meta] of Object.entries(result.metafile.outputs)) {
+    if (!meta.entryPoint) continue
+    const entry = byFile.get(norm(resolve(root, meta.entryPoint)))
+    if (entry) islandUrls[entry.rel] = publicPath + norm(relative(outDir, resolve(root, outPath)))
+  }
+  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] }
+}

package/src/build/islands-vite.ts

@@ -0,0 +1,88 @@
+import { resolve } from 'node:path'
+import type { Rollup } from 'vite'
+import type { BundleIslandsOptions, IslandAsset, IslandBundler } from './islands.ts'
+
+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 bundleIslandsVite: IslandBundler = async (opts: BundleIslandsOptions) => {
+  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, BundleIslandsOptions['entries'][number]>()
+  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 the
+      // 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] }
+}

package/src/build/islands.ts

@@ -1,6 +1,5 @@
 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
@@ -59,89 +58,23 @@ export interface BundleIslandsOptions {
 
 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. */
+/**
+ * The seam's one export: dispatches to an implementation. Vite (impl #1,
+ * `islands-vite.ts`) is the default; `STATOR_ISLAND_BUNDLER=esbuild` selects
+ * impl #2 (`islands-esbuild.ts`, the Option E candidate — Spike 1). Both run
+ * the same contract tests; the default flips (and #1 is deleted) when the
+ * Phase 2 gate in the toolchain-adapter spec passes.
+ */
 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`)
+  const choice = process.env.STATOR_ISLAND_BUNDLER ?? 'vite'
+  if (choice === 'esbuild') {
+    const { bundleIslandsEsbuild } = await import('./islands-esbuild.ts')
+    return bundleIslandsEsbuild(opts)
   }
-  return { islandUrls, assets, modules: [...modules] }
+  if (choice !== 'vite')
+    throw new Error(`stator: unknown STATOR_ISLAND_BUNDLER "${choice}" (vite | esbuild)`)
+  const { bundleIslandsVite } = await import('./islands-vite.ts')
+  return bundleIslandsVite(opts)
 }
 
 /**

package/src/server/http.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, stat } from 'node:fs/promises'
 import { dirname, extname, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { build } from 'esbuild'
@@ -282,6 +282,38 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         return c.text('forbidden', 403)
       }
       try {
+        const st = await stat(full)
+        if (!st.isFile()) return c.text('not found', 404)
+
+        // Caching contract: `/static/assets/*` is the framework's hashed-output
+        // namespace (island bundles, emitted URL assets) — content-addressed by
+        // construction, so a year of `immutable` is correct. Everything else
+        // under `/static/` is user files with stable names: always revalidate,
+        // but revalidation is a bodyless 304 (ETag from size+mtime, plus
+        // Last-Modified for validators that only speak dates).
+        const etag = `"${st.size.toString(16)}-${Math.trunc(st.mtimeMs).toString(16)}"`
+        c.header(
+          'Cache-Control',
+          rel.startsWith('assets/')
+            ? 'public, max-age=31536000, immutable'
+            : 'public, max-age=0, must-revalidate',
+        )
+        c.header('ETag', etag)
+        c.header('Last-Modified', st.mtime.toUTCString())
+
+        const inm = c.req.header('if-none-match')
+        if (inm) {
+          if (inm.split(',').some((t) => t.trim().replace(/^W\//, '') === etag)) {
+            return c.body(null, 304)
+          }
+        } else {
+          const ims = Date.parse(c.req.header('if-modified-since') ?? '')
+          // HTTP dates have second precision; compare mtime truncated to match.
+          if (!Number.isNaN(ims) && Math.trunc(st.mtimeMs / 1000) * 1000 <= ims) {
+            return c.body(null, 304)
+          }
+        }
+
         const buf = await readFile(full)
         c.header('Content-Type', contentTypeFor(rel))
         return c.body(buf)
@@ -684,10 +716,13 @@ export function contentTypeFor(path: string): string {
   if (ext === '.png') return 'image/png'
   if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
   if (ext === '.webp') return 'image/webp'
+  if (ext === '.avif') return 'image/avif'
   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'
+  if (ext === '.ttf') return 'font/ttf'
+  if (ext === '.otf') return 'font/otf'
   return 'application/octet-stream'
 }

package/src/server/route-discovery.ts

@@ -41,10 +41,12 @@ export interface DiscoveredRoute {
  * Walk the routes directory recursively and build URL patterns from file
  * paths. Conventions:
  *
- *   - `routes/foo.ts`         → `/foo`
- *   - `routes/foo/index.ts`   → `/foo`
- *   - `routes/foo/[id].ts`    → `/foo/:id`  (path param `id`)
- *   - `routes/[a]/[b].ts`     → `/:a/:b`
+ *   - `routes/foo.ts`           → `/foo`
+ *   - `routes/foo/index.ts`     → `/foo`
+ *   - `routes/foo/[id].ts`      → `/foo/:id`   (path param `id`)
+ *   - `routes/[a]/[b].ts`       → `/:a/:b`
+ *   - `routes/foo/[...rest].ts` → `/foo/*rest` (catch-all: terminal, matches
+ *     zero+ segments, param is the raw remainder incl. slashes)
  *
  * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
  * GET is a `defineRoute` (page renderer) or a `defineApiRoute` declaring