@weft-js/start 0.1.1 → 0.1.3

package/src/vite.mjs

@@ -25,875 +25,174 @@
 // routes' CSS stays out of the page. In dev the links stand in for Vite's injected `<style>`s and HMR updates them.
 // A build keeps each chunk's sheet for client navigation and writes a shared sheet (what every route has) and one sheet
 // per route for the rest, hashed and cached for good. Each page carries the part of those its first paint needs
-// (`firstPaint`) and links them at the end of its shell, where they block nothing above and hold whatever streams after. `site: { criticalCss: false }` splits by chunk and inlines up to 48 KB, as links past that;
-// `site: { inlineCss: false }` keeps plain links.
-
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync,realpathSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { createHash } from 'node:crypto'
-import { isCSSRequest, parseSync, searchForWorkspaceRoot } from 'vite'
-import { scanRoutes, routeTypes } from './routes.mjs'
-import { solve } from '@weft-js/core/hydration'
-import { readMigrations } from './migrations.mjs'
-import { scanRequired } from './live-target.mjs'
-import { pieces } from '@weft-js/core/node-purge'
-import { planSheets, reach } from './sheets.mjs'
-import { INLINE_CSS_MAX } from './inline.mjs'
-
-/** This folder, wherever the package is installed. */
-const here = dirname(fileURLToPath(import.meta.url))
-const V = {
-  routes: 'virtual:weft/routes',
-  app: 'virtual:weft/app',
-  server: 'virtual:weft/entry-server',
-  client: 'virtual:weft/entry-client',
-  fns: 'virtual:weft/fns',
-  context: 'virtual:weft/context',
-  auth: 'virtual:weft/auth',
-  migrations: 'virtual:weft/migrations',
-  media: 'virtual:weft/media',
-  realtime: 'virtual:weft/realtime',
-  extensions: 'virtual:weft/extensions',
-}
-const SERVER_EXPORTS = new Set(['load', 'meta', 'prerender'])
-const DEFAULT_FONTS = ['Inter:400,700']
-const SHEET = '/@weft-sheet/'
-const ASSETS = '?weft-assets'
-const ISLAND = 'virtual:weft/island/'
-const PRELOAD = 'Per page, from the HTML: an island that loads with the page, or a lazy one in about the first 900px, is modulepreloaded (fetched, not run). The rest load when needed. Save-Data: lazy ones are not preloaded, and wait for interaction.'
-const NOT_ASSET = /\.[cm]?[jt]sx?$/
-const INLINE_SHEETS = '__WEFT_INLINE_SHEETS__'
-const SHEET_PIECES = '__WEFT_SHEET_PIECES__'
+// (`firstPaint`) and links them at the end of its shell, where they block nothing above and hold whatever streams after.
+// `site: { criticalCss: false }` splits by chunk and puts them in the HTML (`inlineSheets`, inline.mjs): whole while the
+// document fits the first flight, else the rules the page's HTML reaches, with the sheets behind them as links that
+// don't hold the paint. `site: { inlineCss: false }` keeps plain links.
+
+import { existsSync } from 'node:fs'
+import { relative } from 'node:path'
+import { createState } from './vite/state.mjs'
+import { shapeSignature } from './vite/route-modules.mjs'
+import { entryCandidate, entryCssSignature, entryWatchLifecycle } from './vite/shape-entry-css.mjs'
+import { V } from './vite/shared.mjs'
+import { configHook, writeBundle, renderChunk, configResolved } from './vite/config-hooks.mjs'
+import { configureServer, hotUpdate } from './vite/dev-hooks.mjs'
+import { resolveId, load, transform, api } from './vite/module-hooks.mjs'
+export { assetsOnly } from './vite/assets.mjs'
+export { inlineSheets, sheetPieces } from './vite/sheets.mjs'
+export { stripServerExports } from './vite/syntax.mjs'
+export { isServerModule, fnId, withIds, clientStubs } from './vite/server-functions.mjs'
+export { scanRoutes, routeTypes } from './routes.mjs'
+export { here as startDir } from './vite/shared.mjs'
 
 /**
- * The client build's stylesheets a page can carry, `{ href: css }`, read by the server build so every preset has them
- * with no file system. Left out: a sheet over the page's limit, one a relative `url()` would break, and one that could
- * close its `<style>`.
+ * A signature of what a save means for the shapes, or undefined when it doesn't parse. A broken save takes ordinary HMR
+ * and its overlay: reloading onto it would leave the tab on the server's error page, which no fix reaches.
  */
-export function inlineSheets(outDir, base, limit = INLINE_CSS_MAX) {
-  const dir = join(outDir, 'assets')
-  if (!existsSync(dir)) return {}
-  const sheets = {}
-  for (const name of readdirSync(dir).filter(f => f.endsWith('.css'))) {
-    const css = readFileSync(join(dir, name), 'utf8')
-    if (css.length <= limit && !/<\/style|<!--/i.test(css) && !/url\(\s*(?!["']?(?:\/|data:|https?:|#|%23))/.test(css)) sheets[`${base}assets/${name}`] = css
-  }
-  return sheets
-}
-
-/** How long a replaced sheet stays in the build, for pages cached before the deploy that replaced it: a CDN's longest day. */
-const KEEP_SHEETS_MS = 30 * 864e5
-
-/**
- * Writes the build's combined stylesheets beside the chunks' own. A route's list is what its chunks import, the entry's
- * included, plus the sheets of the islands in the files it imports.
- */
-function combineSheets(dir, bundle, manifest, abs, islands) {
-  const chunks = Object.values(bundle).filter(f => f.type === 'chunk')
-  const holding = id => chunks.filter(c => c.moduleIds.some(m => m.split('?')[0] === id))
-  const sheetsOf = (start, seen = new Set()) => start.flatMap(c => {
-    if (seen.has(c)) return []
-    seen.add(c)
-    return [...(c.viteMetadata?.importedCss ?? []), ...sheetsOf(c.imports.map(i => bundle[i]).filter(Boolean), seen)]
-  })
-  const entry = sheetsOf(chunks.filter(c => c.isEntry))
-  const routes = manifest.routes.map(r => {
-    const levels = [...manifest.layouts.filter(l => r.layouts.includes(l.id)).map(l => abs(l.file)), abs(r.file)]
-    const files = reach(levels)
-    const held = islands.filter(i => files.has(i.file)).map(i => i.file)
-    return [...new Set([...entry, ...sheetsOf([...levels, ...held].flatMap(holding))])]
-  }).filter(list => list.length)
-  const plan = planSheets(routes, name => readFileSync(join(dir, name), 'utf8'))
-  for (const [name, css] of Object.entries(plan.files)) writeFileSync(join(dir, name), css)
-  return plan
-}
-
-/**
- * The first-paint table of the build's sheets (node/purge.mjs), and the last builds' combined sheets kept beside them: a
- * page cached across a deploy links the ones it was built with. `.weft/sheets` carries them, so CI has to keep that folder.
- */
-export function sheetPieces(outDir, base, plan, keep, root) {
-  const dir = join(outDir, 'assets')
-  const href = name => `${base}${name}`
-  const names = [...new Set([plan.shared, ...plan.routes].filter(Boolean).flatMap(s => s.has))]
-  const sheets = names.map(n => [href(n), readFileSync(join(outDir, n), 'utf8')]).filter(([, css]) => !/<\/style|<!--/i.test(css))
-  const old = join(root, '.weft/sheets')
-  mkdirSync(old, { recursive: true })
-  for (const f of Object.keys(plan.files)) writeFileSync(join(old, f.replace('assets/', '')), plan.files[f])
-  for (const f of readdirSync(old)) {
-    if (Date.now() - statSync(join(old, f)).mtimeMs > KEEP_SHEETS_MS) rmSync(join(old, f))
-    else if (!existsSync(join(dir, f))) writeFileSync(join(dir, f), readFileSync(join(old, f)))
+const parsed = (signature, file) => {
+  try {
+    return signature(file)
+  } catch {
+    return undefined
+  }
+}
+
+/** Reload when an edit changes shape metadata embedded in the client route module. */
+export function shapeHotUpdate(state, modes, next) {
+  return async function (update) {
+    if (this.environment.config.consumer === 'client') {
+      const pending =
+        state.shapeScanActive === state.shapeScanGeneration && state.shapeScanActive !== undefined
+      if (pending) state.shapeScanGeneration++
+      const owners = [...(state.shapeOverrideDependencies ?? [])].flatMap(([file, routes]) =>
+        entryCandidate(new Set([file]), update.file) ? [...routes] : [],
+      )
+      if (owners.length) {
+        if (
+          update.type === 'update' &&
+          entryCandidate(state.shapeEntryMissing, update.file) &&
+          existsSync(update.file)
+        )
+          await this.environment.pluginContainer.watchChange(update.file, { event: 'create' })
+        const graph = this.environment.moduleGraph
+        for (const file of owners) {
+          const id = `\0virtual:weft/shape-override/${encodeURIComponent(file)}.tsx`
+          const asset = graph.getModuleById(id)
+          if (asset) graph.invalidateModule(asset)
+        }
+        const mod = graph.getModuleById('\0' + V.routes)
+        if (mod) graph.invalidateModule(mod)
+        state.vite?.ws.send({ type: 'full-reload' })
+        return []
+      }
+      const rel = relative(state.root, update.file).split('\\').join('/')
+      const entrySignatures = state.shapeEntrySignatures
+      if (entrySignatures?.has(update.file)) {
+        const signature = parsed(entryCssSignature, update.file)
+        const previous = entrySignatures.get(update.file)
+        if (signature !== undefined) entrySignatures.set(update.file, signature)
+        if (signature !== undefined && previous !== signature) {
+          const graph = this.environment.moduleGraph
+          const mod = graph.getModuleById('\0' + V.routes)
+          if (mod) graph.invalidateModule(mod)
+          state.vite?.ws.send({ type: 'full-reload' })
+          return []
+        }
+      }
+      const candidateEvent =
+        (update.type === 'create' || update.type === 'delete') &&
+        entryCandidate(state.shapeEntryCandidates, update.file)
+      const missingUpdate =
+        update.type === 'update' && entryCandidate(state.shapeEntryMissing, update.file)
+      if (candidateEvent || missingUpdate) {
+        // A watched missing path may arrive as an update; Vite clears negative resolution on create.
+        if (missingUpdate && existsSync(update.file))
+          await this.environment.pluginContainer.watchChange(update.file, { event: 'create' })
+        const graph = this.environment.moduleGraph
+        const mod = graph.getModuleById('\0' + V.routes)
+        if (mod) graph.invalidateModule(mod)
+        state.vite?.ws.send({ type: 'full-reload' })
+        return []
+      }
+      const levels = [...state.manifest.routes, ...state.manifest.layouts]
+      if (levels.some((level) => level.file === rel) || state.clientEntry?.() === update.file) {
+        const mode = parsed(shapeSignature, update.file)
+        const before = modes.get(rel)
+        if (mode !== undefined) modes.set(rel, mode)
+        if (mode !== undefined && before !== mode) {
+          const graph = this.environment.moduleGraph
+          const mod = graph.getModuleById('\0' + V.routes)
+          if (mod) graph.invalidateModule(mod)
+          state.vite?.ws.send({ type: 'full-reload' })
+          return []
+        }
+      }
+      if (pending) {
+        const graph = this.environment.moduleGraph
+        const mod = graph.getModuleById('\0' + V.routes)
+        if (mod) graph.invalidateModule(mod)
+        state.vite?.ws.send({ type: 'full-reload' })
+        return []
+      }
+    }
+    return next.call(this, update)
   }
-  const shape = s => s && { href: href(s.file), has: s.has.map(href) }
-  return { ...pieces(sheets, keep), shared: shape(plan.shared), routes: plan.routes.map(shape) }
 }
 
 /**
- * @param {{ root?: string, site?: import('@weft-js/core/ssr').Site, routesDir?: string, timeout?: number, fonts?: string[], hydration?: 'lazy' | 'partial' | 'full' }} [options]
+ * @param {{ root?: string, site?: import('@weft-js/core/ssr').Site, routesDir?: string, timeout?: number, hold?: number, fonts?: string[], hydration?: 'lazy' | 'partial' | 'full' }} [options]
  */
 export default function weftStart(options = {}) {
-  let root = options.root ?? process.cwd()
-  let dev = false
-  let manifest
-  let build = ''
-  let serverModules = []
-  let vite
-  // To see what an edit changed: a route or layout file's server exports, and a server module's client stubs.
-  const loaders = new Map()
-  const stubs = new Map()
-  let compile
-  let plan
-  let sheetPlan
-  let planned = 0
-  const facts = new Map()
-  /** Partial hydration's view of the project (PLAN §11), redone in dev when a file it read changed. */
-  const hydration = async ctx => {
-    if (options.hydration === 'full' || !compile) return undefined
-    if (plan && !dev) return plan
-    if (plan && Date.now() - planned < 200) return plan
-    planned = Date.now()
-    if (plan) {
-      const p = await plan
-      if (!p.stamps.some(f => statSync(f, { throwIfNoEntry: false })?.mtimeMs !== facts.get(f)?.mtime)) return p
-    }
-    const entries = [...manifest.routes, ...manifest.layouts].map(r => abs(r.file))
-    plan = solve({ entries, lazy: (options.hydration ?? 'lazy') === 'lazy', transform: compile, rel: f => relative(root, f).split('\\').join('/'), cache: facts, resolve: async (spec, from) => (await ctx.resolve(spec, from, { skipSelf: true }))?.id })
-    const done = await plan
-    try {
-      mkdirSync(join(root, '.weft'), { recursive: true })
-      writeFileSync(join(root, '.weft', 'hydration.json'), `${JSON.stringify({ islands: done.islands.map(i => i.id), loads: done.loads, preload: PRELOAD, diagnostics: done.diagnostics, files: done.report }, null, 2)}\n`)
-    } catch {}
-    return done
-  }
-  let words
-  const scan = () => {
-    serverModules = scanServerModules(root)
-    return (manifest = scanRoutes(root, options.routesDir ? resolve(root, options.routesDir) : undefined))
-  }
-  const abs = f => resolve(root, f)
-  const id = s => (s.startsWith('virtual:') ? '\0' + s : s)
-  let shapes
-  /** Research 31 §3: the shape table, when the project asks for shapes at all. Loads the server modules, once per edit. */
-  const shapeTable = async ctx => {
-    if (!usesShapes(root)) return undefined
-    const stamp = serverModules.map(f => statSync(abs(f)).mtimeMs).join()
-    if (shapes?.stamp === stamp) return shapes.table
-    try {
-      const { readShapes } = await import('./contract.mjs')
-      shapes = { stamp, table: await readShapes({ root, site: options.site }) }
-      return shapes.table
-    } catch (e) {
-      ctx.warn(`the query shapes couldn't be read, so skeletons only have last-seen shapes: ${e.message}`)
-    }
-  }
-  const clientEntry = () => (existsSync(join(root, 'src', 'entry.client.ts')) ? join(root, 'src', 'entry.client.ts') : V.client)
-
-  return {
-    name: 'weft:start',
-    enforce: 'pre',
-    config(config, env) {
-      root = config.root ? resolve(config.root) : root
-      dev = env.command === 'serve'
-      scan()
-      return {
-        environments: {
-          client: { build: { rollupOptions: { input: clientEntry() } } },
-          ssr: { build: { rollupOptions: { input: V.server } } },
-        },
-        // The router-core server bundle and Takumi's addon stay external to the SSR graph; Nitro traces them.
-        ssr: { noExternal: ['@weft-js/start', '@weft-js/warp', '@weft-js/warp-icons', '@weft-js/core'], external: ['@takumi-rs/core'] },
-        optimizeDeps: { exclude: ['@weft-js/start', '@weft-js/warp', '@weft-js/warp-icons', '@weft-js/core'] }, // they ship TSX for the weft plugin
-        // The runtime files of @weft-js/start, weft and Nitro are served from wherever they're installed (a linked package
-        // sits outside the app's root).
-        server: { fs: { allow: [searchForWorkspaceRoot(root), join(here, '..'), ...packageDirs(root)] } },
-        // One copy of the router: the app's route files and the generated entries import the same module.
-        resolve: { alias: [{ find: /^@weft-js\/start$/, replacement: join(here, 'index.ts') }, { find: /^@weft-js\/start\/(client|server)$/, replacement: join(here, '$1.tsx') }, { find: /^@weft-js\/start\/media$/, replacement: join(here, 'media.ts') }] },
-      }
-    },
-    writeBundle: {
-      order: 'post',
-      async handler(out, bundle) {
-        if (dev || this.environment?.config.consumer !== 'client' || options.site?.criticalCss === false || options.site?.inlineCss === false) return
-        sheetPlan = combineSheets(out.dir, bundle, manifest ?? scan(), abs, (await hydration(this))?.islands ?? [], options.site?.base ?? '/')
-      },
+  const state = createState(options)
+  const modes = new Map()
+  const configure = configureServer(state)
+  return [
+    {
+      name: 'weft:start',
+      enforce: 'pre',
+      config: configHook(state),
+      configResolved: configResolved(state),
+      api: api(state),
     },
-    renderChunk: {
-      order: 'post',
-      handler(code) {
-        const token = new RegExp(`["'\`]${INLINE_SHEETS}["'\`]`)
-        if (!token.test(code)) return null
-        const top = this.environment.getTopLevelConfig()
-        const client = resolve(root, top.environments.client.build.outDir)
-        code = code.replace(new RegExp(`["'\`]${SHEET_PIECES}["'\`]`), () => JSON.stringify(sheetPlan && sheetPieces(client, top.base ?? '/', sheetPlan, options.site?.criticalKeep, root)))
-        const sheets = options.site?.inlineCss === false ? {} : inlineSheets(client, top.base ?? '/', INLINE_CSS_MAX)
-        return { code: code.replace(token, () => JSON.stringify(sheets)), map: null }
-      },
+    {
+      name: 'weft:start:sheets',
+      enforce: 'pre',
+      writeBundle: writeBundle(state),
+      renderChunk: renderChunk(state),
     },
-    configResolved(config) {
-      build = createHash('sha256').update(String(Date.now())).digest('hex').slice(0, 8)
-      if (dev) build = 'dev'
-      root = config.root
-      const main = config.plugins.find(p => p.name === 'weft')
-      words = config.plugins.find(p => p.name === 'weft:purge')?.api
-      words?.add('data-weft styled') // gate.css reveals a mark a static page's HTML may hold alone
-      if (main?.api) {
-        compile = createRequire(join(here, 'vite.mjs'))('@weft-js/core/compiler').transform
-        main.api.islands = async (ctx, file) => (await hydration(ctx))?.files.get(file.replace(/\?.*$/, ''))
-      }
-    },
-    configureServer(server) {
-      vite = server
-      // A `<link>` to a virtual sheet (`weft:fonts`): Vite only serves those as modules.
-      const sheet = async (req, res, next) => {
-        const css = await server.environments.client.pluginContainer.load(decodeURIComponent(req.url.slice(1))).catch(() => undefined)
-        if (css == null) return next()
-        res.setHeader('content-type', 'text/css')
-        res.end(typeof css === 'string' ? css : css.code)
-      }
-      server.middlewares.use(SHEET, (req, res, next) => void sheet(req, res, next))
-      server.middlewares.use(waitingForAFix)
-      // A route file added or removed changes the virtual modules; edits to existing ones are ordinary HMR/reloads.
-      const dir = join(root, 'src')
-      if (!existsSync(dir)) return
-      const routesDir = relative(dir, join(root, manifest.dir)).split('\\').join('/')
-      const shape = () => JSON.stringify([manifest.routes.map(r => r.file), manifest.layouts.map(l => l.file), serverModules])
-      const changed = file => {
-        const rel = file.split('\\').join('/')
-        if (!rel.startsWith(routesDir + '/') && !isServerModule('src/' + rel)) return
-        // Saving a file can count as a rename, depending on the platform and the editor.
-        const before = shape()
-        scan()
-        if (shape() === before) return
-        for (const env of Object.values(server.environments)) {
-          for (const v of [V.routes, V.fns, V.context]) {
-            const m = env.moduleGraph.getModuleById('\0' + v)
-            if (m) env.moduleGraph.invalidateModule(m)
+    {
+      name: 'weft:start:dev',
+      enforce: 'pre',
+      configureServer(server) {
+        for (const level of [...state.manifest.routes, ...state.manifest.layouts]) {
+          try {
+            modes.set(level.file, shapeSignature(state.abs(level.file)))
+          } catch {
+            modes.set(level.file, 'invalid')
           }
         }
-        server.config.logger.info(`weft: full reload: ${rel} was added or removed, so the routes changed`, { timestamp: true })
-        server.ws.send({ type: 'full-reload' })
-      }
-      const w = watch(dir, { recursive: true }, (event, file) => { if (event === 'rename' && file) changed(file) })
-      // Not every runtime's recursive watch reports a new file, and Vite's watcher does.
-      for (const event of ['add', 'unlink']) server.watcher.on(event, file => { if (file.startsWith(dir)) changed(relative(dir, file)) })
-      // Close with the server (middleware mode, as `weft routes --meta` runs it, has no httpServer to listen on).
-      const close = server.close.bind(server)
-      server.close = () => (w.close(), close())
-    },
-    /**
-     * What an edit means for an open page, which keeps its state wherever it can. Components update themselves
-     * (@weft-js/core/hmr). Code that only runs on the server has nothing to swap: the page gets the server's new answer in place.
-     * Anything else that nothing above it can take is a full reload, and the terminal says why.
-     */
-    async hotUpdate({ file, modules }) {
-      const rel = relative(root, file).split('\\').join('/')
-      if (this.environment.config.consumer === 'server') {
-        // An edit can add or drop a stylesheet import: the next server load of the routes walks the graph again.
-        const m = this.environment.moduleGraph.getModuleById('\0' + V.routes)
-        if (m) this.environment.moduleGraph.invalidateModule(m)
-        // A static component or a server helper is in no browser's module graph, so nothing else would tell the tab.
-        if (!vite?.environments.client.moduleGraph.getModulesByFile(file)?.size && this.environment.moduleGraph.getModulesByFile(file)?.size) refresh(vite, rel)
-        return
-      }
-      const route = manifest.routes.some(r => r.file === rel) || manifest.layouts.some(l => l.file === rel)
-      if (route) {
-        const part = serverExports(readFileSync(file, 'utf8'), file)
-        // A level the server renders has no module in the page, and its `load` and `meta` are on the server too.
-        refresh(vite, rel, loaders.get(file) !== part, false)
-        loaders.set(file, part)
-      }
-      if (isServerModule(rel) && stubs.has(file) && modules.length) {
-        const before = stubs.get(file)
-        await Promise.all(modules.map(m => this.environment.transformRequest(m.url).catch(() => undefined)))
-        if (stubs.get(file) === before) return refresh(vite, rel), []
-      }
-      // A static route's stylesheet list: nothing runs it, so nothing has to take the update.
-      const live = modules.filter(m => !m.url.endsWith(ASSETS))
-      if (live.some(m => !reaches(m))) this.environment.logger.info(`weft: full reload: ${rel} exports more than components and nothing that imports it can take the update`, { timestamp: true })
-      if (live.length < modules.length) return live
-    },
-    resolveId: {
-      filter: { id: /^(virtual:weft\/|@weft-js\/start\/(db|auth|bus|list|rust|sidecar)(\/|$)|@weft-js\/(realtime-(redis|nats|durable-object)|db-[\w-]+)$|sharp$)/ },
-      handler(source, importer) {
-        // Sharp's addon can't be bundled, so it stays external and Nitro traces it, which it can only do from the app.
-        if (source === 'sharp') {
-          if (dev || !importer?.includes('plugin-media')) return
-          try { createRequire(join(root, 'package.json')).resolve('sharp') } catch {
-            this.warn('M017: `sharp` isn\'t a dependency of this app, so the built server can\'t load it for the media route.\n  fix: add `sharp` to dependencies')
-            return
+        const entry = state.clientEntry()
+        if (!entry.startsWith('virtual:')) {
+          const rel = relative(state.root, entry).split('\\').join('/')
+          try {
+            modes.set(rel, shapeSignature(entry))
+          } catch {
+            modes.set(rel, 'invalid')
           }
-          return { id: 'sharp', external: true }
-        }
-        if (source.startsWith('@weft-js/')) {
-          if (this.environment?.config.consumer === 'client') this.error(`Q012: \`${source}\` reached the client graph${importer ? ` from ${relative(root, importer)}` : ''}: the database, auth and buses run on the server only.\n  fix: import it from a server module (src/server/**, *.server.ts) or a route's \`load\``)
-          return
         }
-        const base = source.replace(/\?.*$/, '')
-        if (Object.values(V).includes(base) || base.startsWith(ISLAND)) return id(source)
+        const configured = configure(server)
+        entryWatchLifecycle(state, server, modes)
+        return configured
       },
+      hotUpdate: shapeHotUpdate(state, modes, hotUpdate(state)),
     },
-    load: {
-      filter: { id: /^\0virtual:weft\// },
-      async handler(raw) {
-        // `virtual:weft/entry-client?assets=client` (no src/entry.client.ts) is Nitro's assets plugin's to load.
-        if (/[?&]assets\b/.test(raw)) return
-        const which = raw.slice(1).replace(/\?.*$/, '')
-        const client = this.environment?.config.consumer === 'client'
-        if (which.startsWith(ISLAND)) {
-          const { islands } = await hydration(this)
-          const i = islands[Number(which.slice(ISLAND.length))]
-          return `export { $i${i.index} as default } from ${JSON.stringify(i.file)}\n`
-        }
-        if (which === V.routes) {
-          const p = await hydration(this)
-          return client ? clientRoutes(manifest, abs, p) : serverRoutes(manifest, abs, dev ? await devStyles(vite.environments.client, manifest, abs, clientEntry()) : undefined, p)
-        }
-        if (which === V.app) return appModule({ site: options.site ?? {}, build, dev, fonts: cardFonts(manifest, abs, options.fonts ?? DEFAULT_FONTS, root, options.site?.card?.fonts), timeout: options.timeout })
-        if (which === V.server) return serverEntry(clientEntry(), dev, root)
-        if (which === V.fns) return serverModules.map(f => `import ${JSON.stringify(abs(f))}`).join('\n') + '\n'
-        if (which === V.context || which === V.auth || which === V.realtime) {
-          const name = which.slice('virtual:weft/'.length)
-          const f = ['ts', 'mts', 'js', 'mjs'].map(x => `src/${name}.server.${x}`).find(x => existsSync(abs(x)))
-          if (which === V.realtime && busBound(root)) return busModule(f && abs(f), here)
-          return f ? `export { default } from ${JSON.stringify(abs(f))}\n` : 'export default undefined\n'
-        }
-        if (which === V.extensions) return extensionsModule(root, abs)
-        if (which === V.migrations) return dev ? `import { readMigrations } from ${JSON.stringify(join(here, 'migrations.mjs'))}\nexport default () => readMigrations(${JSON.stringify(root)})\n` : `const list = ${JSON.stringify(readMigrations(root))}\nexport default () => list\n`
-        if (which === V.media) return mediaModule(root, dev)
-        if (which === V.client) return `import { start } from ${JSON.stringify(join(here, 'client.tsx'))}\nimport * as routes from '${V.routes}'\nstart(routes)\n`
-      },
+    {
+      name: 'weft:start:modules',
+      enforce: 'pre',
+      resolveId: resolveId(state),
+      load: load(state),
+      transform: transform(state),
     },
-    transform: {
-      filter: { id: /\.[jt]sx?(\?weft-assets)?$|\/vite\/dist\/client\/client\.mjs$/ },
-      async handler(code, file) {
-        const path = file.replace(/\?.*$/, '')
-        if (file.endsWith(ASSETS)) return { code: await assetsOnly(this, code, path, root, words), map: null }
-        if (path.endsWith('/client.mjs')) return dev ? markLinks(root) + code : undefined
-        if (path.includes('/node_modules/')) return
-        const client = this.environment?.config.consumer === 'client'
-        const rel = relative(root, path).split('\\').join('/')
-        if (isServerModule(rel)) {
-          const out = client ? clientStubs(code, path, rel, await shapeTable(this)) : withIds(code, path, rel)
-          if (client && dev) stubs.set(path, out)
-          return out === code ? undefined : { code: out, map: null }
-        }
-        if (client && !rel.startsWith('..')) {
-          const q003 = definesFns(code, path)
-          if (q003) this.error(`Q003: ${rel} defines \`${q003.name}\` with \`${q003.kind}()\`, but it isn't a server module: its \`run\` and imports would ship to the client.\n  fix: move it to src/server/ or a *.server.ts file`)
-        }
-        if (!client) return
-        if (!manifest.routes.some(r => r.file === rel) && !manifest.layouts.some(l => l.file === rel)) return
-        if (dev) loaders.set(file, serverExports(code, file))
-        const out = stripServerExports(code, file)
-        // @weft-js/core/hmr saw the server exports and left this to Vite, but they're gone and the rest is components.
-        if (dev && out !== code && !/^export (?!default\b|\{ \S+\$shape as default\$shape \})/m.test(out) && !out.includes('import.meta.hot.accept(')) return { code: `${out}\nif (import.meta.hot) import.meta.hot.accept();\n`, map: null }
-        return out === code ? undefined : { code: out, map: null }
-      },
-    },
-    /** `weft routes`, tests: the scanned manifest, the generated route types and the server modules. */
-    api: { manifest: () => manifest ?? scan(), types: () => routeTypes(manifest ?? scan()), serverModules: () => (manifest ?? scan(), serverModules) },
-  }
-}
-
-/** Dev, in place of the bare JSON a page gets when its code won't load: this tab can't take an update, so it reloads. */
-const NOT_LOADING = `<!doctype html><meta charset="utf-8"><title>This page failed to load</title>
-<body style="font:16px system-ui;padding:2rem"><h1>This page failed to load</h1><p>The error is in the terminal. This tab reloads when you save a fix.</p>
-<script type="module">
-import { createHotContext } from '/@vite/client'
-const hot = createHotContext('/@weft/not-loading')
-for (const event of ['vite:afterUpdate', 'weft:refresh']) hot.on(event, () => location.reload())
-</script>`
-
-function waitingForAFix(req, res, next) {
-  if (!req.headers.accept?.includes('text/html')) return next()
-  const { writeHead, end } = res
-  const json = headers => /json/.test(String(Array.isArray(headers) ? headers.flat().join(' ') : headers && Object.entries(headers).flat().join(' ')) + res.getHeader('content-type'))
-  let failed = false
-  res.writeHead = function (status, ...rest) {
-    failed = status >= 500 && json(rest.at(-1))
-    if (!failed) return writeHead.call(this, status, ...rest)
-    res.statusCode = status
-    return this
-  }
-  const write = res.write
-  res.write = function (...args) { return failed ? true : write.apply(this, args) }
-  res.end = function (...args) {
-    if (!failed && !(res.statusCode >= 500 && !res.headersSent && json())) return end.apply(this, args)
-    res.setHeader('content-type', 'text/html')
-    res.removeHeader('content-length')
-    return end.call(this, NOT_LOADING)
-  }
-  next()
-}
-
-/** Whether an update to `mod` stops at a module that accepts it. */
-function reaches(mod, seen = new Set()) {
-  if (mod.isSelfAccepting || mod.acceptedHmrDeps?.size) return true
-  if (seen.has(mod)) return true
-  seen.add(mod)
-  return mod.importers.size > 0 && [...mod.importers].every(m => m.acceptedHmrDeps?.has(mod) || reaches(m, seen))
-}
-
-/** Ask open pages for the server's new answer, once the server's own reload has been told. A burst of saves is one ask. */
-const asking = new WeakMap()
-function refresh(vite, rel, say = true, queries = true) {
-  if (!vite) return
-  clearTimeout(asking.get(vite))
-  asking.set(vite, setTimeout(() => {
-    if (say) vite.config.logger.info(`weft: ${rel} runs on the server: refreshing the page's data, state kept`, { timestamp: true })
-    vite.ws.send({ type: 'custom', event: 'weft:refresh', data: { queries } })
-  }, 50))
-}
-
-function packageDirs(root) {
-  const req = createRequire(join(root, 'package.json'))
-  const own = createRequire(import.meta.url)
-  const out = []
-  for (const name of ['@weft-js/core/vite', 'nitro/package.json']) { // each at its package root
-    for (const r of [req, own]) {
-      try { out.push(dirname(realpathSync(r.resolve(name)))); break } catch {}
-    }
-  }
-  return out
-}
-
-/** The project asks for shapes: a `pending="shape"`, or a read of `.shape`. */
-function usesShapes(root) {
-  const src = join(root, 'src')
-  if (!existsSync(src)) return false
-  return readdirSync(src, { recursive: true, withFileTypes: true }).some(f => f.isFile() && /\.[jt]sx?$/.test(f.name) && /pending="shape"|\.shape\b/.test(readFileSync(join(f.parentPath, f.name), 'utf8')))
-}
-
-/**
- * `dev`: the stylesheets from `devStyles`; a build asks Nitro's manifest instead (the plugin's expression reads up to
- * the first `)`, which a path can hold). `meta` is read once per level that renders, before the first byte: that's
- * how the entry learns the request's levels (`routeCss`), outermost first, 404 and error pages included.
- */
-function serverRoutes(manifest, abs, dev, plan) {
-  const files = [...manifest.layouts.map(l => l.file), ...manifest.routes.map(r => r.file), ...manifest.routes.map(r => r.card).filter(Boolean), manifest.defaultCard].filter(Boolean)
-  const unique = [...new Set(files)]
-  const levels = new Set([...manifest.layouts, ...manifest.routes].map(r => r.file))
-  // A file with no default export renders nothing, and may leave no chunk for the manifest to find.
-  const renders = f => levels.has(f) && /\bdefault\b/.test(readFileSync(abs(f), 'utf8'))
-  const isStatic = f => plan?.statics.has(abs(f))
-  const clientAssets = file => `import.meta.vite.assets(${JSON.stringify({ import: file, environment: 'client' }).replaceAll(')', '\\u0029')})`
-  const css = f => dev ? JSON.stringify(dev.files[f] ?? []) : `${clientAssets(abs(f) + (isStatic(f) ? ASSETS : ''))}.css`
-  return [
-    ...unique.map((f, i) => `import * as m${i} from ${JSON.stringify(abs(f))}`),
-    `import { runtime } from ${JSON.stringify(join(here, 'data.ts'))}`,
-    `const matched = new WeakMap()
-const styled = (m, css) => !css.length ? m : { ...m, get meta() {
-  const scope = runtime.scope?.()
-  if (scope) matched.set(scope, [...(matched.get(scope) ?? []), ...css])
-  return m.meta
-} }
-export const routeCss = css => [...new Map([...${JSON.stringify(dev?.entry ?? [])}, ...css, ...(matched.get(runtime.scope?.()) ?? [])].map(c => [c.href, c])).values()]`,
-    `export const manifest = ${JSON.stringify({ dir: manifest.dir, routes: manifest.routes, layouts: manifest.layouts, defaultCard: manifest.defaultCard })}`,
-    // The built-in 404 and error pages have no state, and stand in only when the app has no route file for them.
-    `export const statics = ${JSON.stringify(!plan ? [] : [...[...manifest.layouts, ...manifest.routes].filter(r => isStatic(r.file)).map(r => r.id), ...['404', 'error'].filter(id => !manifest.routes.some(r => r.id === id))])}`,
-    `export const lazy = ${!!plan?.loads.some(l => l.when !== 'load')}`,
-    // The chunks a page's levels and islands will import, for the document's modulepreloads. Dev has no chunks.
-    `export const chunks = ${dev ? '{}' : `{ ${[...[...manifest.layouts, ...manifest.routes].filter(r => !isStatic(r.file) && renders(r.file)).map(r => [r.id, abs(r.file)]), ...(plan?.islands ?? []).map(i => [i.id, i.file]), ['$client', join(here, 'run.tsx')]].map(([id, file]) => `${JSON.stringify(id)}: ${clientAssets(file)}`).join(', ')} }`}`,
-    `export const modules = { ${unique.map((f, i) => `${JSON.stringify(f)}: ${renders(f) ? `styled(m${i}, ${css(f)})` : `m${i}`}`).join(', ')} }`,
-  ].join('\n')
-}
-
-/**
- * The CSS each module reaches in the client graph, as `?assets=client` can't say in dev: the entry's, and each route
- * and layout's. The client env transforms what the browser is about to ask for anyway, and `<link href>` to a module's
- * URL gets the compiled sheet (Tailwind's output too). A module that doesn't transform fails again when it's imported.
- */
-async function devStyles(env, manifest, abs, entry) {
-  const reachFrom = async start => {
-    const seen = new Set(), css = new Map()
-    const walk = async url => {
-      const mod = await env.moduleGraph.getModuleByUrl(url).catch(() => undefined) ?? await env.moduleGraph.ensureEntryFromUrl(url).catch(() => undefined)
-      if (!mod || seen.has(mod) || mod.id?.startsWith('\0virtual:weft/routes')) return // routes import every route
-      seen.add(mod)
-      await env.transformRequest(mod.url).catch(() => {})
-      for (const next of mod.importedModules) {
-        if (!next.id) continue
-        if (!isCSSRequest(next.id)) await walk(next.url)
-        else if (!/[?&](url|inline|raw)\b/.test(next.id)) css.set(next.url, { href: next.url[0] === '/' ? next.url : SHEET + encodeURIComponent(next.id) })
-      }
-    }
-    await walk(start)
-    return [...css.values()]
-  }
-  const files = {}
-  for (const { file } of [...manifest.layouts, ...manifest.routes]) files[file] = await reachFrom(abs(file))
-  return { entry: await reachFrom(entry.startsWith('virtual:') ? join(here, 'client.tsx') : entry), files }
-}
-
-/**
- * Vite's client, in dev: the fullstack plugin's patch hands a sheet to its `<link data-vite-dev-id>`, so the module
- * doesn't inject a second copy and CSS HMR swaps the link. The server only writes `href`, so the id is added here,
- * before the patched client reads the links.
- */
-const markLinks = root => `document.querySelectorAll('link[rel="stylesheet"]:not([data-vite-dev-id])').forEach(l => {
-  const href = l.getAttribute('href')
-  if (href.startsWith('${SHEET}')) l.setAttribute('data-vite-dev-id', decodeURIComponent(href.slice(${SHEET.length})))
-  else if (href.startsWith('/@fs/')) l.setAttribute('data-vite-dev-id', href.replace(/^\\/@fs(\\/(?=[A-Za-z]:))?/, ''))
-  else if (href[0] === '/' && href[1] !== '/') l.setAttribute('data-vite-dev-id', ${JSON.stringify(root)} + href)
-})
-`
-
-function clientRoutes(manifest, abs, plan) {
-  const table = manifest.routes.filter(r => r.kind === 'page').map(r => ({ id: r.id, pattern: r.pattern, layouts: r.layouts }))
-  const levels = [...manifest.layouts, ...manifest.routes]
-  const isStatic = r => plan?.statics.has(abs(r.file))
-  // A static route loads only what its module imports that isn't code: its stylesheets, for a navigation to it.
-  const loads = levels.map(r => `${JSON.stringify(r.id)}: () => import(${JSON.stringify(abs(r.file) + (isStatic(r) ? ASSETS : ''))})`)
-  // Straight from the file: a module of its own per island would be a chunk that only re-exports.
-  const islands = (plan?.islands ?? []).map(i => `${JSON.stringify(i.id)}: () => import(${JSON.stringify(i.file)}).then(({ $i${i.index}: d }) => ({ default: d }))`)
-  return `export const table = ${JSON.stringify(table)}\nexport const load = { ${loads.join(', ')} }\nexport const islands = { ${islands.join(', ')} }\n`
-}
-
-/**
- * A static module in the client build: what it imports that isn't code (stylesheets, images), and the same of the
- * modules it imports. Its class names go to the purge, which only sees client files.
- */
-async function assetsOnly(ctx, code, path, root, words) {
-  words?.add(code)
-  const ast = parse(path, code)
-  const out = []
-  for (const n of ast.program.body) {
-    if (!/^(ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration)$/.test(n.type) || !n.source || n.importKind === 'type' || n.exportKind === 'type') continue
-    const spec = n.source.value
-    if (/^@weft-js\/(?:core|start)($|\/)/.test(spec)) continue
-    const file = (await ctx.resolve(spec, path, { skipSelf: true }))?.id
-    if (!file) continue
-    const bare = file.replace(/\?.*$/, '')
-    if (!NOT_ASSET.test(bare)) out.push(`import ${JSON.stringify(spec)}`)
-    else if (!bare.includes('/node_modules/') && !isServerModule(relative(root, bare).split('\\').join('/'))) out.push(`import ${JSON.stringify(bare + ASSETS)}`)
-  }
-  if (code.includes('@weft-js/core/style')) out.push(`import 'virtual:weft/groups.css'`)
-  out.push('export default null') // a chunk of only CSS is dropped, and the server looks this one up
-  return out.join('\n') + '\n'
-}
-
-function serverEntry(clientEntry, dev, root) {
-  return `import { createHandler } from ${JSON.stringify(join(here, 'server.tsx'))}
-import { chunks, lazy, manifest, modules, routeCss, statics } from '${V.routes}'
-import '${V.fns}'
-import context from '${V.context}'
-import auth from '${V.auth}'
-import migrations from '${V.migrations}'
-import media from '${V.media}'
-import realtime from '${V.realtime}'
-import extensions from '${V.extensions}'
-import * as app from '${V.app}'
-import assets from '${clientEntry}?assets=client'
-import { preloads } from 'weft:fonts/preloads'
-const fetch = createHandler({ manifest, modules, statics, chunks, lazy, context, auth, migrations, media, realtime, liveRequired: ${JSON.stringify(scanRequired(root).map(r => r.name))}, extensions, site: app.site, build: app.build, dev: app.dev, fonts: app.fonts(), timeout: app.timeout, assets: { entry: assets.entry, js: assets.js, get css() { return routeCss(assets.css) }, fonts: preloads, inline: ${dev ? 'undefined' : `'${INLINE_SHEETS}'`}, pieces: ${dev ? 'undefined' : `'${SHEET_PIECES}'`} },
-  // H005–H008, Q002–Q014, A002–A004, F002–F003, M017 and R-codes found while serving: the server log, in dev and production.
-  onDiagnostic: d => console.warn(\`[weft] \${d.code} \${d.severity}\${d.route ? \` (\${d.route})\` : ''}: \${d.message.replace(/^[A-Z]{1,3}\\d{3}:? /, '')}\`) })
-export default { fetch }
-`
-}
-
-/**
- * A `server.extension` provider runs only for an app with `src/<key>.server.ts`, the file that says it wants it (P118):
- * the provider is loaded on the first request and handed that file's default export. No provider gives an empty list.
- */
-function extensionsModule(root, abs) {
-  const slot = join(root, '.weft', 'slots', 'server.extension.ts')
-  const keys = existsSync(slot) ? Object.entries(JSON.parse(/providers = (\{.*\}) as const/.exec(readFileSync(slot, 'utf8'))?.[1] ?? '{}')).filter(([, name]) => name).map(([key]) => key) : []
-  const files = keys.flatMap(key => {
-    const f = ['ts', 'mts', 'js', 'mjs'].map(x => `src/${key}.server.${x}`).find(x => existsSync(abs(x)))
-    return f ? [[key, abs(f)]] : []
-  })
-  if (!files.length) return 'export default []\n'
-  return `import { load } from 'weft:slot/server.extension'\n${files.map(([, f], i) => `import app${i} from ${JSON.stringify(f)}\n`).join('')}export default [${files.map(([key], i) => `{ key: ${JSON.stringify(key)}, load: () => load(${JSON.stringify(key)}).then(extend => extend(app${i})) }`).join(', ')}]\n`
-}
-
-/** Dev serves from the project; a built server from the directory it runs in (or `WEFT_MEDIA_DIR`). */
-function mediaModule(root, dev) {
-  const slot = join(root, '.weft', 'slots', 'media.server.ts')
-  if (!existsSync(slot) || readFileSync(slot, 'utf8').includes('provider = null')) return 'export default undefined\n'
-  const at = dev ? JSON.stringify(root) : 'undefined'
-  if (!existsSync(join(root, '.weft', 'slots', 'media.encode.ts'))) return `import { load } from 'weft:slot/media.server'\nexport default () => load().then(m => m.at(${at}))\n`
-  return `import { load } from 'weft:slot/media.server'
-import { load as encoder, providers } from 'weft:slot/media.encode'
-const encode = async () => Object.fromEntries(await Promise.all(Object.keys(providers).filter(k => providers[k]).map(async k => [k, await encoder(k)])))
-export default () => Promise.all([load(), encode()]).then(([m, e]) => m.at(${at}, e))
-`
-}
-
-const busBound = root => {
-  const slot = join(root, '.weft', 'slots', 'realtime.bus.ts')
-  return existsSync(slot) && readFileSync(slot, 'utf8').includes('provider = {')
-}
-
-/** A bus in `src/realtime.server.ts` wins over the plugin's, like any explicit choice. */
-const busModule = (file, from) => `import { load, provider } from 'weft:slot/realtime.bus'
-import { slotBus } from ${JSON.stringify(join(from, 'bus.ts'))}
-${file ? `import own from ${JSON.stringify(file)}` : 'const own = undefined'}
-export default { ...own, bus: own?.bus ?? slotBus(provider.plugin, load) }
-`
-
-function appModule({ site, build, dev, fonts, timeout }) {
-  return `export const site = ${JSON.stringify(site)}
-export const build = ${JSON.stringify(build)}
-export const dev = ${dev}
-export const timeout = ${timeout ?? 'undefined'}
-const raw = ${JSON.stringify(fonts)}
-let decoded
-export function fonts() {
-  return (decoded ??= raw.map(f => ({ ...f, data: Uint8Array.from(atob(f.data), c => c.charCodeAt(0)) })))
-}
-`
-}
-
-/**
- * The fonts every card can use, resolved at build and shipped inside the server bundle (research 20 §4.2: a render
- * never fetches fonts). `Inter:400,700` → `@fontsource/inter`'s latin WOFF2 files, from the app or from @weft-js/start.
- */
-function cardFonts(manifest, abs, defaults, root, own = {}) {
-  const specs = new Set(defaults)
-  for (const f of [...manifest.routes.map(r => r.card), manifest.defaultCard].filter(Boolean)) {
-    const m = /export\s+const\s+fonts\s*=\s*\[([^\]]*)\]/.exec(readFileSync(abs(f), 'utf8'))
-    if (m) for (const s of m[1].matchAll(/['"]([^'"]+)['"]/g)) specs.add(s[1])
-  }
-  const requires = [createRequire(join(root, 'package.json')), createRequire(import.meta.url)]
-  const out = []
-  // The app's own faces (`site.card.fonts`, filled in by the text plugin): the card's title and text look like the app.
-  for (const f of [own.display, own.body].filter(Boolean)) {
-    const path = join(root, f.src)
-    if (existsSync(path) && !out.some(x => x.name === f.family)) out.push({ name: f.family, weight: f.weight ?? 400, style: 'normal', data: readFileSync(path).toString('base64') })
-  }
-  for (const spec of specs) {
-    const [family, weights = '400'] = spec.split(':')
-    const pkg = family.toLowerCase().replace(/\s+/g, '-')
-    for (const w of weights.split(',')) {
-      const [weight, italic] = [Number.parseInt(w), /i(talic)?$/.test(w)]
-      const file = `@fontsource/${pkg}/files/${pkg}-latin-${weight}-${italic ? 'italic' : 'normal'}.woff2`
-      const path = requires.map(r => { try { return r.resolve(file) } catch { return undefined } }).find(Boolean)
-      if (!path) throw new Error(`weft: card font \`${spec}\` needs \`@fontsource/${pkg}\` installed (looked for ${file})`)
-      out.push({ name: family, weight, style: italic ? 'italic' : 'normal', data: readFileSync(path).toString('base64') })
-    }
-  }
-  return out
-}
-
-/**
- * The client build of a route module: `load`, `meta` and `prerender` removed (they run on the server; loaders can
- * hold database code and secrets), then imports nothing else uses. Exported for tests.
- */
-function serverCuts(code, file) {
-  const ast = parseSync(file, code, { lang: file.endsWith('.tsx') ? 'tsx' : file.endsWith('.ts') ? 'ts' : 'jsx', sourceType: 'module' })
-  const cuts = []
-  for (const node of ast.program.body) {
-    if (node.type !== 'ExportNamedDeclaration' || !node.declaration) continue
-    const d = node.declaration
-    const names = d.type === 'VariableDeclaration' ? d.declarations.map(x => x.id?.name) : [d.id?.name]
-    if (names.length && names.every(n => SERVER_EXPORTS.has(n))) cuts.push([node.start, node.end])
-  }
-  return cuts
-}
-
-const serverExports = (code, file) => serverCuts(code, file).map(([a, b]) => code.slice(a, b)).join('\n')
-
-/** The server-only exports of a route file, cut out of the client's copy. */
-export function stripServerExports(code, file = 'route.tsx') {
-  const cuts = serverCuts(code, file)
-  if (!cuts.length) return code
-  let out = code
-  for (const [a, b] of cuts.sort((x, y) => y[0] - x[0])) out = out.slice(0, a) + out.slice(b)
-  // Imports whose bindings are no longer used go too (a db client a loader imported must not reach the browser).
-  return pruneImports(out, file)
-}
-
-const parse = (file, code) => parseSync(file, code, { lang: file.endsWith('.tsx') ? 'tsx' : /\.[cm]?ts$/.test(file) ? 'ts' : 'jsx', sourceType: 'module' })
-
-/** The TS nodes that hold code; every other `TS*` node is a type, gone once TypeScript is stripped. */
-const TS_VALUE = /^TS((As|Satisfies|NonNull|Instantiation)Expression|TypeAssertion|Enum\w+|Module\w+|ImportEqualsDeclaration|ExternalModuleReference|ParameterProperty|ExportAssignment)$/
-const NAMED_MEMBER = /^(Property|MethodDefinition|PropertyDefinition|AccessorProperty)$/
-const binds = p => !p ? [] : p.type === 'Identifier' ? [p.name] : (p.properties ?? p.elements ?? [p.value ?? p.left ?? p.argument ?? p.parameter]).flatMap(binds)
-const declares = s => s.type === 'VariableDeclaration' ? s.declarations.flatMap(d => binds(d.id)) : /^(Function|Class)Declaration$/.test(s.type) && s.id ? [s.id.name] : []
-
-/**
- * The outer names `ast` reads at run time. Not types (`typeof x` in one reads nothing), property names, or what a
- * function or block binds itself: `optimistic: ({ input }) => …` doesn't use a top-level `input`. It errs towards a name
- * being used: a kept import is a bigger bundle, a dropped one a crash.
- */
-function valueNames(ast) {
-  const out = new Set()
-  const walk = (n, bound) => {
-    if (Array.isArray(n)) return n.forEach(x => walk(x, bound))
-    if (typeof n?.type !== 'string' || n.type === 'ImportDeclaration' || n.exportKind === 'type' || (n.type.startsWith('TS') && !TS_VALUE.test(n.type))) return
-    if (n.type === 'Identifier' || n.type === 'JSXIdentifier') { if (!bound.has(n.name)) out.add(n.name); return }
-    const inner = /^(Arrow)?Function/.test(n.type) ? [...(n.id ? [n.id.name] : []), ...n.params.flatMap(binds)] : n.type === 'BlockStatement' ? n.body.flatMap(declares) : []
-    const scope = inner.length ? new Set([...bound, ...inner]) : bound
-    const skip = n.computed ? undefined : n.type === 'MemberExpression' ? 'property' : NAMED_MEMBER.test(n.type) ? 'key' : undefined
-    for (const k in n) if (k !== skip && k !== 'parent' && n[k] && typeof n[k] === 'object') walk(n[k], scope)
-  }
-  walk(ast.program.body, new Set())
-  return out
-}
-
-/** Drop value import specifiers nothing in `out` reads (and imports left empty). */
-function pruneImports(out, file) {
-  const again = parse(file, out)
-  const imports = again.program.body.filter(n => n.type === 'ImportDeclaration' && n.specifiers.length)
-  const used = valueNames(again)
-  let rest = out
-  for (const imp of imports) rest = rest.slice(0, imp.start) + ' '.repeat(imp.end - imp.start) + rest.slice(imp.end)
-  const spelled = new Set(rest.match(/[A-Za-z_$][\w$]*/g)) // a type import is erased, so a type may keep it
-  for (const imp of imports.sort((x, y) => y.start - x.start)) {
-    const keep = imp.specifiers.filter(s => (imp.importKind === 'type' || s.importKind === 'type' ? spelled : used).has(s.local.name))
-    if (keep.length === imp.specifiers.length) continue
-    const text = keep.length ? rewriteImport(imp, keep, out) : ''
-    out = out.slice(0, imp.start) + text + out.slice(imp.end)
-  }
-  return out
+  ]
 }
-
-function rewriteImport(imp, keep, code) {
-  const def = keep.find(s => s.type === 'ImportDefaultSpecifier')
-  const ns = keep.find(s => s.type === 'ImportNamespaceSpecifier')
-  const named = keep.filter(s => s.type === 'ImportSpecifier').map(s => code.slice(s.start, s.end))
-  const parts = [def && def.local.name, ns && `* as ${ns.local.name}`, named.length && `{ ${named.join(', ')} }`].filter(Boolean)
-  return `import ${imp.importKind === 'type' ? 'type ' : ''}${parts.join(', ')} from ${code.slice(imp.source.start, imp.source.end)}`
-}
-
-// ---- server modules (research 27 §2) ------------------------------------------------------------------------------
-
-/** `src/server/**` and `*.server.ts(x)`: files whose `query`/`mutation` exports become client stubs. */
-export const isServerModule = rel => rel.startsWith('src/server/') || /\.server\.[cm]?[jt]sx?$/.test(rel)
-
-function scanServerModules(root) {
-  const out = []
-  const walk = dir => {
-    let list
-    try { list = readdirSync(join(root, dir), { withFileTypes: true }) } catch { return }
-    for (const d of list) {
-      const rel = `${dir}/${d.name}`
-      if (d.isDirectory()) { if (d.name !== 'node_modules' && !d.name.startsWith('.')) walk(rel) }
-      else if (/\.[cm]?[jt]sx?$/.test(d.name) && !/\.(test|spec)\./.test(d.name) && !d.name.endsWith('.d.ts') && isServerModule(rel)) out.push(rel)
-    }
-  }
-  walk('src')
-  return out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
-}
-
-const FN_KINDS = new Set(['query', 'mutation', 'stream', 'topic', 'channel', 'sharedState'])
-
-/** Local names bound to the `FN_KINDS` from @weft-js/start. */
-function fnLocals(ast) {
-  const locals = new Map()
-  for (const n of ast.program.body) {
-    if (n.type !== 'ImportDeclaration' || n.importKind === 'type' || !/^@weft-js\/start(\/data)?$/.test(n.source.value)) continue
-    for (const s of n.specifiers) if (s.type === 'ImportSpecifier' && s.importKind !== 'type' && FN_KINDS.has(s.imported.name ?? s.imported.value)) locals.set(s.local.name, s.imported.name ?? s.imported.value)
-  }
-  return locals
-}
-
-/** `export const name = query({ … })` statements: the call, its options object and the export name. */
-function fnExports(ast, locals) {
-  const out = []
-  for (const n of ast.program.body) {
-    if (n.type !== 'ExportNamedDeclaration' || n.declaration?.type !== 'VariableDeclaration') continue
-    for (const d of n.declaration.declarations) {
-      const call = d.init?.type === 'CallExpression' ? d.init : d.init?.type === 'TSAsExpression' || d.init?.type === 'TSSatisfiesExpression' ? d.init.expression : undefined
-      if (call?.type !== 'CallExpression' || call.callee.type !== 'Identifier' || !locals.has(call.callee.name)) continue
-      const obj = call.arguments[locals.get(call.callee.name) === 'sharedState' ? 1 : 0] // `sharedState(name, { … })`
-      if (obj?.type !== 'ObjectExpression' || d.id.type !== 'Identifier') continue
-      out.push({ node: n, name: d.id.name, callee: call.callee.name, obj, single: n.declaration.declarations.length === 1 })
-    }
-  }
-  return out
-}
-
-const prop = (obj, key) => obj.properties.find(p => p.type === 'Property' && !p.computed && (p.key.name ?? p.key.value) === key)
-/** A function's id: its name and a hash of its file, stable across builds. */
-export const fnId = (name, rel) => `${name}.${createHash('sha256').update(rel).digest('hex').slice(0, 6)}`
-
-/** The server build of a server module: each definition gets its `$id`. Exported for tests. */
-export function withIds(code, file, rel) {
-  const ast = parse(file, code)
-  const locals = fnLocals(ast)
-  const all = fnExports(ast, locals)
-  for (const f of all) {
-    const kind = locals.get(f.callee)
-    if ((kind === 'channel' || kind === 'sharedState') && !prop(f.obj, 'authorize')) {
-      const line = code.slice(0, f.obj.start).split('\n').length
-      throw Object.assign(new Error(`R001: ${rel}:${line} \`${f.name}\` has no \`authorize\`: anyone could join it.\n  fix: add \`authorize\` (\`() => true\` must be written out)`), { code: 'R001' })
-    }
-  }
-  const list = all.filter(f => !prop(f.obj, '$id'))
-  let out = code
-  for (const f of list.sort((a, b) => b.obj.start - a.obj.start)) out = out.slice(0, f.obj.start + 1) + ` $id: ${JSON.stringify(fnId(f.name, rel))},` + out.slice(f.obj.start + 1)
-  return out
-}
-
-/**
- * The client build of a server module: stubs (`query({ $id, shape })`, `mutation({ $id, optimistic })`), the top-level
- * declarations a kept `optimistic` reads as values, and the imports those use. Nothing else: no `run`, no database
- * client, no other export, and no types (they're erased, and `z.infer<typeof input>` would keep `input` and zod).
- * Exported for tests.
- */
-export function clientStubs(code, file, rel, shapes) {
-  const ast = parse(file, code)
-  const locals = fnLocals(ast)
-  const defs = new Map(fnExports(ast, locals).map(f => [f.node, f]))
-  const kept = [] // [start, text]
-  const candidates = []
-  const names = text => new Set(text.match(/[A-Za-z_$][\w$]*/g) ?? [])
-  for (const n of ast.program.body) {
-    if (n.type === 'ImportDeclaration') {
-      if (n.specifiers.length) kept.push([n.start, code.slice(n.start, n.end)]) // pruned below; side-effect imports go
-      continue
-    }
-    const f = defs.get(n)
-    if (f && f.single) {
-      const opt = prop(f.obj, 'optimistic')
-      const id = fnId(f.name, rel)
-      const kind = locals.get(f.callee)
-      if (kind === 'channel' || kind === 'sharedState') {
-        const initial = prop(f.obj, 'initial')
-        kept.push([n.start, `export const ${f.name} = ${f.callee}(${kind === 'sharedState' ? "'', " : ''}{ $id: ${JSON.stringify(id)}, $stub: 1${initial ? `, ${code.slice(initial.start, initial.end)}` : ''} })`])
-        continue
-      }
-      // The tree the schema gave when there's a table; else what was declared, as it was written.
-      const shape = shapes?.[id] !== undefined ? `shape: ${JSON.stringify(shapes[id])}` : prop(f.obj, 'shape') && code.slice(prop(f.obj, 'shape').start, prop(f.obj, 'shape').end)
-      kept.push([n.start, `export const ${f.name} = ${f.callee}({ $id: ${JSON.stringify(id)}${opt ? `, ${code.slice(opt.start, opt.end)}` : ''}${shape ? `, ${shape}` : ''} })`])
-      continue
-    }
-    const decl = n.type === 'ExportNamedDeclaration' ? n.declaration : n
-    if (!decl) continue
-    if (/^TS(TypeAlias|Interface)Declaration$/.test(decl.type) || n.exportKind === 'type') continue
-    if (/^TS(Enum|Module)Declaration$/.test(decl.type)) { // the kinds with code in them, kept like any helper
-      candidates.push({ n, declares: [decl.id.name] })
-      continue
-    }
-    const bound = decl.type === 'VariableDeclaration' ? decl.declarations.flatMap(d => [...names(code.slice(d.id.start, d.id.end))]) : decl.id ? [decl.id.name] : []
-    if (bound.length) candidates.push({ n, declares: bound })
-  }
-  // Helpers a kept `optimistic` reads (and what they read), in source order.
-  for (let grew = true; grew; ) {
-    grew = false
-    const used = valueNames(parse(file, kept.map(([, t]) => t).join('\n')))
-    for (const c of candidates.splice(0)) {
-      if (c.declares.some(d => used.has(d))) { kept.push([c.n.start, code.slice(c.n.start, c.n.end)]); grew = true }
-      else candidates.push(c)
-    }
-  }
-  const out = `// weft: client stubs for ${rel} (research 27 §2)\n` + kept.sort((a, b) => a[0] - b[0]).map(([, t]) => t).join('\n') + '\n'
-  return pruneImports(out, file)
-}
-
-/** Q003: a `query`/`mutation` defined in a file that isn't a server module (its name and kind), or undefined. */
-function definesFns(code, file) {
-  if (!/@weft-js\/start/.test(code) || !/\b(query|mutation|stream|topic|channel|sharedState)\b/.test(code)) return
-  const ast = parse(file, code)
-  const locals = fnLocals(ast)
-  if (!locals.size) return
-  const f = fnExports(ast, locals)[0]
-  if (f) return { name: f.name, kind: locals.get(f.callee) }
-  for (const [local, kind] of locals) if (new RegExp(`(?<![\\w$.])${local}\\s*\\(`).test(code)) return { name: local, kind }
-}
-
-export { scanRoutes, routeTypes, here as startDir }