@webjsdev/server 0.9.0 → 0.10.1

package/src/cookie-store.js

@@ -0,0 +1,269 @@
+/**
+ * The Next.js `cookies()` store: one per request, read from the request's
+ * `Cookie` header and writable from anywhere server-side in that request (a
+ * server action, a route handler, middleware, a page render). A write is
+ * visible to later reads in the same request and is applied to the outgoing
+ * response as `Set-Cookie` by the request handler (`applyPendingCookies`),
+ * so `cookies().set(...)` works with no `Response` in hand, as in Next.
+ *
+ * The shape and the serializer are ports of Next's `RequestCookies` /
+ * `ResponseCookies` (`@edge-runtime/cookies`): `get(name)` returns
+ * `{ name, value }`, `set(name, value, options)` or `set({ name, value, ... })`
+ * with `maxAge` in SECONDS, `path` defaulting to `/`, and `delete(name)`
+ * (or `delete(name, { path, domain })`) expiring the cookie.
+ *
+ * @module cookie-store
+ */
+
+/**
+ * @typedef {{
+ *   name: string, value: string, expires?: Date | number, maxAge?: number,
+ *   domain?: string, path?: string, secure?: boolean, httpOnly?: boolean,
+ *   sameSite?: 'lax' | 'strict' | 'none' | 'Lax' | 'Strict' | 'None' | boolean,
+ *   partitioned?: boolean, priority?: 'low' | 'medium' | 'high',
+ * }} ResponseCookie
+ */
+
+/**
+ * Parse a `Cookie` request header into name -> value (first occurrence wins,
+ * values percent-decoded when they decode cleanly).
+ * @param {string | null} header
+ * @returns {Map<string, string>}
+ */
+export function parseCookieHeader(header) {
+  /** @type {Map<string, string>} */
+  const map = new Map();
+  if (!header) return map;
+  for (const pair of header.split(/;\s*/)) {
+    if (!pair) continue;
+    const eq = pair.indexOf('=');
+    const name = (eq === -1 ? pair : pair.slice(0, eq)).trim();
+    if (!name || map.has(name)) continue;
+    const raw = eq === -1 ? 'true' : pair.slice(eq + 1).trim();
+    let value = raw;
+    try { value = decodeURIComponent(raw); } catch { /* keep raw */ }
+    map.set(name, value);
+  }
+  return map;
+}
+
+/**
+ * Serialize a cookie as a `Set-Cookie` value (port of Next's stringifyCookie).
+ * @param {ResponseCookie} c
+ * @returns {string}
+ */
+export function stringifyCookie(c) {
+  const sameSite = c.sameSite === true ? 'strict' : c.sameSite;
+  const attrs = [
+    c.path && `Path=${c.path}`,
+    (c.expires || c.expires === 0) && `Expires=${(typeof c.expires === 'number' ? new Date(c.expires) : c.expires).toUTCString()}`,
+    typeof c.maxAge === 'number' && `Max-Age=${c.maxAge}`,
+    c.domain && `Domain=${c.domain}`,
+    c.secure && 'Secure',
+    c.httpOnly && 'HttpOnly',
+    sameSite && `SameSite=${sameSite}`,
+    c.partitioned && 'Partitioned',
+    c.priority && `Priority=${c.priority}`,
+  ].filter(Boolean);
+  const head = `${c.name}=${encodeURIComponent(c.value ?? '')}`;
+  return attrs.length ? `${head}; ${attrs.join('; ')}` : head;
+}
+
+/**
+ * Next's normalizeCookie: a numeric `expires` becomes a Date, `maxAge` also
+ * sets `expires`, and `path` defaults to `/`.
+ * @param {ResponseCookie} cookie
+ * @returns {ResponseCookie}
+ */
+function normalizeCookie(cookie) {
+  const c = { ...cookie };
+  if (typeof c.expires === 'number') c.expires = new Date(c.expires);
+  if (c.maxAge) c.expires = new Date(Date.now() + c.maxAge * 1000);
+  if (c.path == null) c.path = '/';
+  return c;
+}
+
+/**
+ * A request's cookie store. `pending` holds the `Set-Cookie` values to apply
+ * to the response, keyed by name so the last write to a name wins.
+ */
+export class CookieStore {
+  /** @param {string | null} cookieHeader */
+  constructor(cookieHeader) {
+    /** @type {Map<string, string>} */
+    this.map = parseCookieHeader(cookieHeader);
+    /** @type {Map<string, string>} */
+    this.pending = new Map();
+    /**
+     * Set once the response's headers are decided (`sealCookies`). A write
+     * after that could never reach the browser, so it throws instead of being
+     * dropped, as Next refuses a cookie write during render.
+     */
+    this.sealed = false;
+  }
+
+  /** @param {string} op */
+  assertWritable(op) {
+    if (!this.sealed) return;
+    throw new Error(`[webjs] cookies().${op}() ran after the response headers were sent, so the cookie can never reach the browser. This happens inside a streamed render (a component under Suspense or <webjs-suspense>). Set cookies in a server action, a route handler, middleware, or the page render before anything streams.`);
+  }
+
+  /**
+   * @param {string | { name: string }} [arg]
+   * @returns {{ name: string, value: string } | undefined}
+   */
+  get(arg) {
+    const name = typeof arg === 'string' ? arg : arg && arg.name;
+    if (name == null || !this.map.has(name)) return undefined;
+    return { name, value: /** @type {string} */ (this.map.get(name)) };
+  }
+
+  /**
+   * @param {string | { name: string }} [arg]
+   * @returns {{ name: string, value: string }[]}
+   */
+  getAll(arg) {
+    const all = [...this.map].map(([name, value]) => ({ name, value }));
+    const name = typeof arg === 'string' ? arg : arg && arg.name;
+    return name == null ? all : all.filter((c) => c.name === name);
+  }
+
+  /** @param {string} name */
+  has(name) { return this.map.has(name); }
+
+  get size() { return this.map.size; }
+
+  /**
+   * `set(name, value, options?)` or `set({ name, value, ...options })`.
+   * @param {string | ResponseCookie} a
+   * @param {string} [value]
+   * @param {Omit<ResponseCookie, 'name' | 'value'>} [options]
+   */
+  set(a, value, options) {
+    this.assertWritable('set');
+    const cookie = typeof a === 'string' ? { ...(options || {}), name: a, value: String(value ?? '') } : { ...a, value: String(a.value ?? '') };
+    if (!cookie.name) throw new Error('cookies().set: a cookie name is required');
+    const c = normalizeCookie(/** @type {ResponseCookie} */ (cookie));
+    this.map.set(c.name, c.value);
+    this.pending.set(c.name, stringifyCookie(c));
+    return this;
+  }
+
+  /**
+   * Expire a cookie: `delete(name)`, `delete(name, { path, domain })` or
+   * `delete({ name, path, domain })`. A cookie set on a path or domain is only
+   * cleared by a `Set-Cookie` naming the same one, so both forms carry them.
+   * @param {string | { name: string, path?: string, domain?: string }} a
+   * @param {{ path?: string, domain?: string, secure?: boolean, httpOnly?: boolean, sameSite?: ResponseCookie['sameSite'], partitioned?: boolean }} [options]
+   */
+  delete(a, options) {
+    this.assertWritable('delete');
+    const opts = typeof a === 'string' ? { ...(options || {}), name: a } : a;
+    this.map.delete(opts.name);
+    // A `maxAge` or `expires` the caller passed (options shared with `set`)
+    // would otherwise outlive the deletion: `normalizeCookie` lets `maxAge`
+    // replace the epoch `expires`, and the cookie stayed alive for that long.
+    const { maxAge: _maxAge, expires: _expires, ...scope } = /** @type {any} */ (opts);
+    this.pending.set(opts.name, stringifyCookie(normalizeCookie({ ...scope, value: '', expires: new Date(0) })));
+    return this;
+  }
+
+  /** @returns {IterableIterator<[string, { name: string, value: string }]>} */
+  [Symbol.iterator]() {
+    return [...this.map].map(([name, value]) => /** @type {[string, { name: string, value: string }]} */ ([name, { name, value }]))[Symbol.iterator]();
+  }
+
+  toString() {
+    return [...this.map].map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join('; ');
+  }
+}
+
+/**
+ * The view `cookies()` returns: the store's methods, also awaitable, so both
+ * `cookies().get('x')` and `(await cookies()).get('x')` (Next 15) work.
+ * @param {CookieStore} store
+ */
+export function cookiesView(store) {
+  const view = {
+    get: store.get.bind(store),
+    getAll: store.getAll.bind(store),
+    has: store.has.bind(store),
+    set: (/** @type {any} */ a, /** @type {any} */ v, /** @type {any} */ o) => { store.set(a, v, o); return view; },
+    delete: (/** @type {any} */ a, /** @type {any} */ o) => { store.delete(a, o); return view; },
+    toString: () => store.toString(),
+    [Symbol.iterator]: () => store[Symbol.iterator](),
+  };
+  Object.defineProperty(view, 'size', { get: () => store.size, enumerable: true });
+  const p = Promise.resolve(view);
+  for (const key of Reflect.ownKeys(view)) {
+    if (key === 'size') continue;
+    Object.defineProperty(p, key, { value: /** @type {any} */ (view)[key], enumerable: false, configurable: true });
+  }
+  Object.defineProperty(p, 'size', { get: () => store.size, enumerable: false });
+  return /** @type {Promise<typeof view> & typeof view} */ (/** @type {unknown} */ (p));
+}
+
+/**
+ * Add the store's pending `Set-Cookie` values to a response. The response is
+ * always re-created rather than mutated: a `Response.redirect()` (and any
+ * fetched response) has immutable headers, and a handler may return one
+ * module-level Response for every request, which would otherwise collect this
+ * visitor's session cookie and hand it to the next one.
+ * @param {Response} res
+ * @param {CookieStore | null | undefined} store
+ * @returns {Response}
+ */
+export function applyPendingCookies(res, store) {
+  if (!store || !store.pending.size) return res;
+  const headers = new Headers(res.headers);
+  for (const v of store.pending.values()) headers.append('set-cookie', v);
+  try {
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  } catch {
+    // A status a Response cannot be constructed with (outside 200 to 599)
+    // keeps the old in-place append.
+    for (const v of store.pending.values()) res.headers.append('set-cookie', v);
+    return res;
+  }
+}
+
+/**
+ * Next.js's `RequestCookies` (`request.cookies` in middleware and a route
+ * handler) over a request's cookie store (#1686). Reads are the store's.
+ * `set`, `delete` and `clear` change only the cookies the rest of THIS request
+ * sees, the page's `cookies()` included, and send nothing to the browser: in
+ * Next a response cookie goes on the response (`NextResponse.cookies.set`),
+ * which in WebJs is `cookies().set()`.
+ * @param {CookieStore} store
+ */
+export function requestCookiesView(store) {
+  /** @param {unknown} a */
+  const nameOf = (a) => String(a && typeof a === 'object' ? /** @type any */ (a).name : a);
+  const view = {
+    /** @param {any} a */
+    get: (a) => store.get(a),
+    /** @param {any} [a] */
+    getAll: (a) => store.getAll(a),
+    /** @param {string} name */
+    has: (name) => store.has(name),
+    get size() { return store.size; },
+    /**
+     * @param {string | { name: string, value: string }} a
+     * @param {string} [value]
+     */
+    set(a, value) {
+      const v = a && typeof a === 'object' ? a.value : value;
+      store.map.set(nameOf(a), String(v ?? ''));
+      return view;
+    },
+    /** @param {string | string[]} names */
+    delete(names) {
+      const removed = (Array.isArray(names) ? names : [names]).map((n) => store.map.delete(nameOf(n)));
+      return Array.isArray(names) ? removed : removed[0];
+    },
+    clear() { store.map.clear(); return view; },
+    [Symbol.iterator]: () => store[Symbol.iterator](),
+    toString: () => store.toString(),
+  };
+  return view;
+}

package/src/core-exports.js

@@ -0,0 +1,190 @@
+/**
+ * The `@webjsdev/core` export surface, read from the installed package's own
+ * source at check time.
+ *
+ * `core-imports-exist` and the dev overlay need to know which names each
+ * `@webjsdev/core` specifier really exports, as a runtime VALUE and as a
+ * TYPE. A hand-kept list would rot the first time core gains an export, so
+ * this reads the package the app actually resolves: `package.json` `exports`
+ * names the subpaths, each subpath's source module (the `source` condition, or
+ * a `default` that is a source file) names its runtime exports, and its
+ * `types` declaration names the types. `export * from` is followed on both
+ * sides. The root specifier is the union of `index.js` and `index-browser.js`,
+ * so a server-only export (`renderToString`) and a browser-only one both count.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { redactStringsAndTemplates } from './js-scan.js';
+
+/**
+ * @typedef {{ runtime: Set<string>, types: Set<string>, hasDefault: boolean }} ModuleSurface
+ * @typedef {{ dir: string, subpaths: Map<string, ModuleSurface> }} CoreSurface
+ */
+
+/** @type {Map<string, CoreSurface>} */
+const SURFACE_CACHE = new Map();
+
+/**
+ * Locate the `@webjsdev/core` package directory the app resolves, falling
+ * back to the copy this server package sits beside (the monorepo layout and a
+ * flat `node_modules/@webjsdev/` install alike).
+ * @param {string} [appDir]
+ * @returns {string | null}
+ */
+export function resolveCoreDir(appDir) {
+  if (appDir) {
+    try {
+      const req = createRequire(join(appDir, 'package.json'));
+      return dirname(req.resolve('@webjsdev/core/package.json'));
+    } catch { /* not resolvable from the app; fall through */ }
+  }
+  const sibling = resolve(dirname(fileURLToPath(import.meta.url)), '../../core');
+  return existsSync(join(sibling, 'package.json')) ? sibling : null;
+}
+
+/**
+ * Read (and cache per core directory) the whole core export surface.
+ * @param {string} [appDir]
+ * @returns {CoreSurface | null}
+ */
+export function coreSurface(appDir) {
+  const dir = resolveCoreDir(appDir);
+  if (!dir) return null;
+  const hit = SURFACE_CACHE.get(dir);
+  if (hit) return hit;
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')); } catch { return null; }
+  /** @type {Map<string, ModuleSurface>} */
+  const subpaths = new Map();
+  const exportsField = pkg.exports && typeof pkg.exports === 'object' ? pkg.exports : {};
+  for (const [key, entry] of Object.entries(exportsField)) {
+    if (!key.startsWith('.') || key === './package.json' || key.endsWith('/')) continue;
+    const spec = key === '.' ? '@webjsdev/core' : '@webjsdev/core' + key.slice(1);
+    const { sources, types } = entryFiles(dir, key, entry);
+    /** @type {ModuleSurface} */
+    const surface = { runtime: new Set(), types: new Set(), hasDefault: false };
+    for (const file of sources) {
+      const r = moduleExports(file, false, new Set());
+      for (const n of r.names) surface.runtime.add(n);
+      if (r.hasDefault) surface.hasDefault = true;
+    }
+    if (types) for (const n of moduleExports(types, true, new Set()).names) surface.types.add(n);
+    subpaths.set(spec, surface);
+  }
+  const out = { dir, subpaths };
+  SURFACE_CACHE.set(dir, out);
+  return out;
+}
+
+/**
+ * The source and declaration files one `exports` entry maps to. A built
+ * `dist/` default is skipped in favour of the `source` condition, since the
+ * bundle's export list is the source's.
+ * @param {string} dir
+ * @param {string} key
+ * @param {unknown} entry
+ * @returns {{ sources: string[], types: string | null }}
+ */
+function entryFiles(dir, key, entry) {
+  /** @type {string[]} */
+  const sources = [];
+  let types = null;
+  if (typeof entry === 'string') {
+    sources.push(join(dir, entry));
+  } else if (entry && typeof entry === 'object') {
+    const e = /** @type {Record<string, unknown>} */ (entry);
+    const src = typeof e.source === 'string' ? e.source
+      : typeof e.default === 'string' && !e.default.includes('/dist/') ? e.default
+        : typeof e.import === 'string' ? e.import : null;
+    if (src) sources.push(join(dir, src));
+    if (typeof e.types === 'string') types = join(dir, e.types);
+  }
+  if (key === '.') {
+    const browser = join(dir, 'index-browser.js');
+    if (existsSync(browser) && !sources.includes(browser)) sources.push(browser);
+    if (!sources.length) sources.push(join(dir, 'index.js'));
+  }
+  return { sources: sources.filter((f) => existsSync(f)), types: types && existsSync(types) ? types : null };
+}
+
+/**
+ * The names one module exports, following `export * from` relative edges.
+ * Comments and string / template bodies are masked first, except that the
+ * `from '...'` specifier is read back from the raw source at the same offset.
+ * @param {string} file
+ * @param {boolean} dts  read declaration syntax (`interface`, `type`, `declare`)
+ * @param {Set<string>} seen
+ * @returns {{ names: Set<string>, hasDefault: boolean }}
+ */
+function moduleExports(file, dts, seen) {
+  const names = new Set();
+  let hasDefault = false;
+  if (seen.has(file)) return { names, hasDefault };
+  seen.add(file);
+  let src;
+  try { src = readFileSync(file, 'utf8'); } catch { return { names, hasDefault }; }
+  const scan = redactStringsAndTemplates(src);
+  const decl = dts
+    ? /\bexport\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\*?|const|let|var|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/g
+    : /\bexport\s+(?:async\s+)?(?:function\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = decl.exec(scan))) names.add(m[1]);
+  if (/\bexport\s+default\b/.test(scan)) hasDefault = true;
+  const clause = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
+  while ((m = clause.exec(scan))) {
+    for (const part of m[1].split(',')) {
+      const p = part.trim().replace(/^type\s+/, '');
+      if (!p) continue;
+      const alias = p.split(/\s+as\s+/);
+      const name = (alias[1] || alias[0]).trim();
+      if (name === 'default') hasDefault = true;
+      else if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+  const star = /\bexport\s+(?:type\s+)?\*\s*(?:as\s+([A-Za-z_$][\w$]*)\s*)?from\s*(['"])([^'"]*)\2/g;
+  while ((m = star.exec(scan))) {
+    if (m[1]) { names.add(m[1]); continue; }
+    // The specifier body is a plain string, kept verbatim by the mask.
+    const target = resolveRelative(file, m[3], dts);
+    if (!target) continue;
+    for (const n of moduleExports(target, dts, seen).names) names.add(n);
+  }
+  return { names, hasDefault };
+}
+
+/**
+ * Resolve a relative `export * from` specifier; in a declaration file `x.js`
+ * means the sibling `x.d.ts`.
+ * @param {string} from
+ * @param {string} spec
+ * @param {boolean} dts
+ * @returns {string | null}
+ */
+function resolveRelative(from, spec, dts) {
+  if (!spec.startsWith('.')) return null;
+  const abs = resolve(dirname(from), spec);
+  if (dts) {
+    const candidates = [abs.replace(/\.m?js$/, '.d.ts'), abs, abs + '.d.ts'];
+    for (const c of candidates) if (c.endsWith('.ts') && existsSync(c)) return c;
+    return null;
+  }
+  return existsSync(abs) ? abs : null;
+}
+
+/**
+ * Whether `name` is a TYPE somewhere in core with no runtime value anywhere,
+ * the shape a plain (non-`type`) import of it fails on at load.
+ * @param {CoreSurface} surface
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isTypeOnlyAnywhere(surface, name) {
+  let inTypes = false;
+  for (const s of surface.subpaths.values()) {
+    if (s.runtime.has(name)) return false;
+    if (s.types.has(name)) inTypes = true;
+  }
+  return inTypes;
+}

package/src/csrf.js

@@ -97,6 +97,23 @@ export function requestHost(req) {
   return hostOf(req.url);
 }
 
+/**
+ * The request's `Origin` as a clean `scheme://host[:port]` for a refusal
+ * message, so the message never echoes arbitrary header text. An origin
+ * carries no path, query or credentials, so nothing secret can reach it.
+ * @param {string | null} origin
+ */
+function originLabel(origin) {
+  if (!origin) return 'no Origin';
+  if (origin === 'null') return 'Origin null (a sandboxed frame or a file: page)';
+  try { return `Origin ${new URL(origin).origin}`; } catch { return 'an unparseable Origin'; }
+}
+
+/** What to do about a refused request, appended to every reason. */
+const ORIGIN_FIX = 'A browser form posted from this app passes; a hand-built request (curl, fetch in a test) '
+  + 'should send no Origin, or the origin of the host it addresses. A trusted other origin goes in '
+  + '"webjs": { "allowedOrigins": [...] } in package.json.';
+
 /** Is the request's `Origin` host in the configured allowlist? */
 function originAllowed(req, allowedOrigins) {
   const origin = req.headers.get('origin');
@@ -116,7 +133,8 @@ function originAllowed(req, allowedOrigins) {
  * Cross-origin (CSRF) verification for a state-changing action request.
  * @param {Request} req
  * @param {string[]} [allowedOrigins] hosts or full origins allowed cross-site
- * @returns {{ ok: boolean, reason?: string }}
+ * @returns {{ ok: boolean, reason?: string }} on a refusal, `reason` names the
+ *   headers that caused it and the fix, safe to send back in the 403
  */
 export function verifyOrigin(req, allowedOrigins = []) {
   // Primary: the Sec-Fetch-Site fetch-metadata header (browser-set, not
@@ -127,7 +145,7 @@ export function verifyOrigin(req, allowedOrigins = []) {
     // 'same-site' or 'cross-site': reject unless the source origin is trusted.
     return originAllowed(req, allowedOrigins)
       ? { ok: true }
-      : { ok: false, reason: `cross-origin request (Sec-Fetch-Site: ${secFetchSite})` };
+      : { ok: false, reason: `the browser marked it Sec-Fetch-Site: ${secFetchSite.slice(0, 32)} (${originLabel(req.headers.get('origin'))}, host ${requestHost(req).slice(0, 255) || '(none)'}), and that origin is not in webjs.allowedOrigins. ${ORIGIN_FIX}` };
   }
   // Fallback (no Sec-Fetch-Site, older browser): compare Origin host to host.
   const origin = req.headers.get('origin');
@@ -137,7 +155,7 @@ export function verifyOrigin(req, allowedOrigins = []) {
   if (sourceHost && host && sourceHost === host) return { ok: true };
   return originAllowed(req, allowedOrigins)
     ? { ok: true }
-    : { ok: false, reason: `origin ${sourceHost || '(none)'} does not match host ${host || '(none)'}` };
+    : { ok: false, reason: `${originLabel(origin)} does not match this request's host ${host.slice(0, 255) || '(none)'}. ${ORIGIN_FIX}` };
 }
 
 /**

package/src/dev/bun-app-source.js

@@ -12,8 +12,17 @@
  * plugin's `onLoad` is not served from that copy, so it is always fresh.
  *
  * The trade is that `bun --hot` does not watch a module a plugin served
- * (#1550), so the dev server's own watcher asks for the registry reset itself
- * (`pokeHotSentinel` in `dev/hot-host.js`) after an edit to any app module.
+ * (#1550). The dev server's own watcher sees the edit instead, and the served
+ * source carries the module versions (#1689): `rewriteAppSource` records each
+ * module's import edges and points an import of an edited module, or of a
+ * module above one, at its absolute path plus `?webjs-v=<n>`
+ * (`dev/esm-hot-hooks.js` holds the versions). Bun keys a module by its query,
+ * so the edited chain evaluates fresh while every other module keeps its
+ * instance and its module-scope state. Only what versions cannot place (a
+ * new or deleted file, the extensionless temp file `sed -i` renames over a
+ * module)
+ * still asks `bun --hot` for a registry reset (`pokeHotSentinel` in
+ * `dev/hot-host.js`).
  *
  * The filter matches app modules only: never `node_modules`, and never a
  * `*.server.*` module, which the `'use server'` seed plugin serves. When dev
@@ -23,8 +32,9 @@
  * @module dev/bun-app-source
  */
 import { readFileSync, existsSync, statSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
-import { expandImportAlias } from '../module-graph.js';
+import { resolve as resolvePath, isAbsolute } from 'node:path';
+import { expandImportAlias, importSpecifierRanges, resolveImport } from '../module-graph.js';
+import { moduleVersion, recordModuleImport, recordModuleLoad, isVersionedModule } from './esm-hot-hooks.js';
 
 const ROOTS = Symbol.for('webjs.dev.bunAppSourceRoots');
 
@@ -61,7 +71,7 @@ export function registerBunAppSource(appDir) {
         const abs = args.path.split('?')[0];
         // A read failure (the file is gone) propagates, which Bun reports as
         // the load error it would have raised itself.
-        return { contents: rewriteAppAliases(readFileSync(abs, 'utf8'), abs), loader: /\.m?ts$/.test(abs) ? 'ts' : 'js' };
+        return { contents: rewriteAppSource(readFileSync(abs, 'utf8'), abs), loader: /\.m?ts$/.test(abs) ? 'ts' : 'js' };
       });
     },
   });
@@ -97,3 +107,83 @@ export function rewriteAppAliases(src, file) {
     try { return existsSync(abs) && statSync(abs).isFile() ? `${lead}${q}${abs}${q}` : m; } catch { return m; }
   });
 }
+
+/**
+ * Everything the dev server does to an app module's source on Bun before Bun
+ * sees it: the `#` alias rewrite, then the module versions (#1689). Every Bun
+ * plugin that serves app source in dev calls this one function (this file's,
+ * the `'use server'` seed plugin's passthrough, the source-locations plugin),
+ * so a module is versioned whichever of them serves it. A no-op outside a
+ * registered app root, so production source is untouched.
+ *
+ * @param {string} src
+ * @param {string} file  absolute path of the module, no query
+ * @returns {string}
+ */
+export function rewriteAppSource(src, file) {
+  return versionServedImports(rewriteAppAliases(src, file), file);
+}
+
+/**
+ * Record each import edge of an app module and point every import of a
+ * bumped module at its absolute path plus `?webjs-v=<n>` (`&webjs-v=<n>` on a
+ * specifier that already has a query), the Bun half of the Node resolve hook in
+ * `dev/esm-hot-hooks.js`. Static imports, `export … from` and string-literal
+ * dynamic imports count. A type-only clause, a specifier inside a string,
+ * template or comment, and a bare specifier are left alone, and so is a target
+ * that does not exist, so Bun reports a missing module exactly as before. The
+ * absolute path rather than the written spelling, because it is the key Bun
+ * gives the module anyway, and a query on `./x.js` naming `x.ts` would be one
+ * more resolver path to trust.
+ *
+ * @param {string} src  source after the alias rewrite
+ * @param {string} file  absolute path of the module, no query
+ * @returns {string}
+ */
+export function versionServedImports(src, file) {
+  if (!isVersionedModule(file)) return src;
+  recordModuleLoad(file);
+  const g = /** @type {any} */ (globalThis);
+  const roots = g[ROOTS] instanceof Set ? [...g[ROOTS]] : [];
+  const appDir = roots.find((r) => file.startsWith(r + '/'));
+  if (!appDir) return src;
+  /** @type {Array<{ start: number, end: number, text: string }>} */
+  const edits = [];
+  const seen = new Set();
+  for (const { start, end, spec } of importSpecifierRanges(src)) {
+    if (seen.has(start)) continue;
+    seen.add(start);
+    const target = serverTarget(spec, file, appDir);
+    if (!target) continue;
+    recordModuleImport(file, target);
+    const n = moduleVersion(target);
+    if (!n) continue;
+    let exists = false;
+    try { exists = statSync(target).isFile(); } catch { /* missing: leave it */ }
+    if (!exists) continue;
+    const text = spec.includes('?') ? `${spec}&webjs-v=${n}` : `${target}?webjs-v=${n}`;
+    edits.push({ start, end, text });
+  }
+  if (!edits.length) return src;
+  edits.sort((a, b) => b.start - a.start);
+  let out = src;
+  for (const { start, end, text } of edits) out = out.slice(0, start) + text + out.slice(end);
+  return out;
+}
+
+/**
+ * The file an app module's import specifier names, or null for a bare
+ * specifier. An absolute specifier is a filesystem path here (the alias
+ * rewrite produces them), not the app-root path a browser specifier is, so it
+ * is taken as is rather than through `resolveImport`.
+ * @param {string} spec
+ * @param {string} file
+ * @param {string} appDir
+ * @returns {string | null}
+ */
+function serverTarget(spec, file, appDir) {
+  const bare = spec.split('?')[0];
+  if (isAbsolute(bare)) return bare;
+  if (!bare.startsWith('.') && !expandImportAlias(bare, appDir)) return null;
+  return resolveImport(bare, file, appDir);
+}