@webjsdev/server 0.8.85 → 0.8.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.85",
+  "version": "0.8.87",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",

package/src/action-middleware.js

@@ -22,9 +22,10 @@
  * The framework ships no middleware; it only runs the chain. Server-only.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { shared } from './process-shared.js';
 
 /** Per-request accumulated context, readable by the action via actionContext(). */
-const als = new AsyncLocalStorage();
+const als = shared('action-middleware-als', () => new AsyncLocalStorage());
 
 /** Shared empty context returned outside an action (a direct server-to-server call). */
 const EMPTY = Object.freeze({});

package/src/action-seed-bun.js

@@ -36,7 +36,7 @@
  *   serverFileRe: RegExp,
  * }} helpers
  */
-export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe }) {
+export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe, rewriteAliases = (s) => s }) {
   Bun.plugin({
     name: 'webjs-action-seed',
     setup(build) {
@@ -60,7 +60,7 @@ export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverF
           // Fail-open: any faceting error serves the raw source (no seeding for
           // this module), the Bun analog of the Node hook's `nextLoad` fallback.
         }
-        return { contents: src, loader };
+        return { contents: rewriteAliases(src, absPath), loader };
       });
     },
   });

package/src/action-seed.js

@@ -69,18 +69,21 @@ import { hashFile } from './actions.js';
 import { isStreamable } from './action-stream.js';
 import { serverRuntime } from './listener-core.js';
 import { redactStringsAndTemplates } from './js-scan.js';
+import { shared } from './process-shared.js';
 
 /** Ambient per-render seed collector. `Map<key, value>` or undefined. */
-const als = new AsyncLocalStorage();
+const als = shared('action-seed-als', () => new AsyncLocalStorage());
 
-/** Whether seed COLLECTION is on (the `webjs.seed` switch). */
-let _seedEnabled = false;
-/** Dev mode, threaded from `dev.js` at boot. Gates the determinism assertion. */
-let _devMode = false;
-/** Whether the load hook is installed at all (so identity is available). */
-let _hookInstalled = false;
-/** Idempotency guard: `module.registerHooks` must run at most once. */
-let _registered = false;
+/**
+ * The hook's switches, shared by every copy of this module in the process
+ * (#1590): under `bun --hot` an app's `'use server'` facade imports a fresh copy
+ * after a reload, and it must see the switches the running server set.
+ *   seedEnabled: whether seed COLLECTION is on (the `webjs.seed` switch).
+ *   devMode: dev mode, threaded from `dev.js` at boot; gates the determinism assertion.
+ *   hookInstalled: whether the load hook is installed at all (so identity is available).
+ *   registered: idempotency guard, `module.registerHooks` must run at most once.
+ */
+const _flags = shared('action-seed-flags', () => ({ seedEnabled: false, devMode: false, hookInstalled: false, registered: false }));
 
 /**
  * `action function -> { file, fnName }` for every export the hook wrapped.
@@ -103,10 +106,10 @@ let _registered = false;
  *
  * @type {WeakMap<Function, { file: string, fnName: string }[]>}
  */
-const _identity = new WeakMap();
+const _identity = shared('action-identity', () => new WeakMap());
 
 /** Memoized `absPath -> hash` so a hot action call does not re-hash per call. */
-const _hashCache = new Map();
+const _hashCache = shared('action-hash-cache', () => new Map());
 
 /** This module's own URL, embedded into the generated facade's import. */
 const SELF_URL = import.meta.url;
@@ -118,7 +121,7 @@ const SELF_URL = import.meta.url;
  * @returns {boolean}
  */
 export function seedingEnabled() {
-  return _seedEnabled && _hookInstalled;
+  return _flags.seedEnabled && _flags.hookInstalled;
 }
 
 /**
@@ -128,7 +131,7 @@ export function seedingEnabled() {
  * @returns {boolean}
  */
 export function identityHookInstalled() {
-  return _hookInstalled;
+  return _flags.hookInstalled;
 }
 
 /**
@@ -204,7 +207,7 @@ async function recordSeed(collector, file, fnName, args, value) {
     // legitimate second call with different arguments has a different key and
     // cannot false-fire. In its OWN try/catch so a diagnostic failure can never
     // skip `collector.set` and turn observability into a dropped seed.
-    if (_devMode && collector.has(key)) {
+    if (_flags.devMode && collector.has(key)) {
       try { await assertDeterministic(collector.get(key), value, hash, fnName); } catch { /* never affect the seed */ }
     }
     collector.set(key, value);
@@ -214,7 +217,7 @@ async function recordSeed(collector, file, fnName, args, value) {
 }
 
 /** Warned-once ids, keyed `hash/fn` so the Set is bounded by the action count. */
-const _nonDeterministic = new Set();
+const _nonDeterministic = shared('action-seed-nondeterministic', () => new Set());
 
 /**
  * Warn (once per action function) when one render recorded two DIFFERENT results
@@ -276,7 +279,7 @@ export function __actionWrap(file, fnName, orig) {
   const list = _identity.get(orig) || [];
   if (!list.some((e) => e.file === file && e.fnName === fnName)) list.push({ file, fnName });
   _identity.set(orig, list);
-  if (!_seedEnabled) return orig;
+  if (!_flags.seedEnabled) return orig;
   const wrapped = seedProxy(file, fnName, orig);
   // The wrapper is a fresh object every time, so it shares the TARGET's list
   // rather than starting one of its own.
@@ -644,10 +647,10 @@ function seedLoadHook(url, context, nextLoad) {
  * @returns {Promise<void>}
  */
 export async function registerActionHooks(opts = {}) {
-  _seedEnabled = opts.seed !== false;
-  _devMode = opts.dev === true;
-  if (_registered) return;
-  _registered = true;
+  _flags.seedEnabled = opts.seed !== false;
+  _flags.devMode = opts.dev === true;
+  if (_flags.registered) return;
+  _flags.registered = true;
 
   if (serverRuntime() === 'bun') {
     // Once per PROCESS, not per module instance (#1575): `bun --hot` re-runs
@@ -656,12 +659,15 @@ export async function registerActionHooks(opts = {}) {
     // edit (the first one registered keeps answering anyway).
     const g = /** @type {any} */ (globalThis);
     const installed = Symbol.for('webjs.actionSeed.bunPlugin');
-    if (g[installed]) { _hookInstalled = true; return; }
+    if (g[installed]) { _flags.hookInstalled = true; return; }
     g[installed] = true;
     // Bun has no module.registerHooks; install the same facade via Bun.plugin.
     const { installBunSeedPlugin } = await import('./action-seed-bun.js');
-    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE });
-    _hookInstalled = true;
+    // Dev rewrites the app's `#` imports to absolute paths (#1575); the
+    // rewrite reads the app roots dev registered, so it is a no-op in prod.
+    const { rewriteAppAliases } = await import('./dev/bun-app-source.js');
+    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, rewriteAliases: rewriteAppAliases });
+    _flags.hookInstalled = true;
     return;
   }
 
@@ -676,7 +682,7 @@ export async function registerActionHooks(opts = {}) {
   }
 
   nodeModule.registerHooks({ load: seedLoadHook });
-  _hookInstalled = true;
+  _flags.hookInstalled = true;
 }
 
 /**

package/src/action-signal.js

@@ -9,8 +9,9 @@
  * `fetch(url, { signal: actionSignal() })` line is safe everywhere.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { shared } from './process-shared.js';
 
-const als = new AsyncLocalStorage();
+const als = shared('action-signal-als', () => new AsyncLocalStorage());
 
 /** A shared signal that never aborts, returned outside an action. */
 const NEVER = (() => {

package/src/broadcast.js

@@ -17,12 +17,13 @@
  *
  * @module broadcast
  */
+import { shared } from './process-shared.js';
 
 /**
  * Per-path WebSocket client registry.
  * @type {Map<string, Set<import('ws').WebSocket>>}
  */
-const pathClients = new Map();
+const pathClients = shared('broadcast-clients', () => new Map());
 
 /**
  * Register a WebSocket client for a path. Called internally by the

package/src/bun-transpiler-cache.js

@@ -0,0 +1,64 @@
+/**
+ * Evict Bun transpiler-cache entries written by @webjsdev/server 0.8.85 and
+ * 0.8.86 (#1575).
+ *
+ * Those versions resolved the app's `#` imports through a Bun runtime
+ * `onResolve` in dev. Bun caches the transpile of every source over 50KB on
+ * disk, keyed by the file's CONTENT, with the resolved import paths baked in,
+ * so a large app module kept a broken `file:/...` path (or an absolute path
+ * into whichever checkout first ran it) after the fix: same bytes, same key,
+ * same poisoned output, a 500 on every request that reaches it. Nothing in a
+ * fixed version writes such an entry any more, but the old entries outlive the
+ * upgrade.
+ *
+ * The cache is only a cache, so the cure is to empty it once per machine: the
+ * first WebJs server on Bun at or after this version removes the entries and
+ * leaves a marker beside them, and every later start sees the marker and does
+ * nothing. Bun rebuilds what it needs on the next load.
+ *
+ * @module bun-transpiler-cache
+ */
+import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const MARKER = 'webjs-1575-evicted';
+
+/**
+ * The directory Bun keeps its runtime transpiler cache in, or null when the
+ * cache is off (`BUN_RUNTIME_TRANSPILER_CACHE_PATH` set to `0` or empty).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ * @returns {string | null}
+ */
+export function bunTranspilerCacheDir(env = process.env, home = homedir()) {
+  const set = env.BUN_RUNTIME_TRANSPILER_CACHE_PATH;
+  if (set !== undefined) return set === '0' || set === '' ? null : set;
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'bun', '@t@');
+}
+
+/**
+ * Empty the Bun transpiler cache once per machine (see the module comment).
+ * Never throws: a cache it cannot read or write is left alone.
+ * @param {{ env?: NodeJS.ProcessEnv, home?: string, isBun?: boolean }} [opts]
+ * @returns {number} entries removed (0 when there was nothing to do)
+ */
+export function evictPoisonedBunTranspilerCache({ env = process.env, home = homedir(), isBun = !!process.versions.bun } = {}) {
+  if (!isBun) return 0;
+  const dir = bunTranspilerCacheDir(env, home);
+  if (!dir) return 0;
+  const marker = join(dirname(dir), MARKER);
+  try {
+    if (existsSync(marker)) return 0;
+    let removed = 0;
+    if (existsSync(dir)) {
+      for (const name of readdirSync(dir)) {
+        try { rmSync(join(dir, name), { recursive: true, force: true }); removed++; } catch { /* in use; leave it */ }
+      }
+    }
+    writeFileSync(marker, `emptied by @webjsdev/server at ${new Date().toISOString()} (#1575)\n`);
+    return removed;
+  } catch {
+    return 0;
+  }
+}

package/src/cache.js

@@ -14,6 +14,7 @@
  *
  * @module cache
  */
+import { shared } from './process-shared.js';
 
 /**
  * @typedef {Object} CacheStore
@@ -228,8 +229,13 @@ export function redisStore(opts = {}) {
   };
 }
 
-/** @type {CacheStore | null} */
-let _defaultStore = null;
+/**
+ * The default store lives in process-shared state (#1590), so an app module
+ * that imported a fresh copy of this package after a `bun --hot` reload reads
+ * and writes the same cache as the server.
+ * @type {{ store: CacheStore | null }}
+ */
+const _defaultStore = shared('cache-default-store', () => ({ store: null }));
 
 /**
  * Get the default cache store. Memory store unless explicitly set via
@@ -238,8 +244,8 @@ let _defaultStore = null;
  * @returns {CacheStore}
  */
 export function getStore() {
-  if (!_defaultStore) _defaultStore = memoryStore();
-  return _defaultStore;
+  if (!_defaultStore.store) _defaultStore.store = memoryStore();
+  return _defaultStore.store;
 }
 
 /**
@@ -253,5 +259,5 @@ export function getStore() {
  * @param {CacheStore} store
  */
 export function setStore(store) {
-  _defaultStore = store;
+  _defaultStore.store = store;
 }

package/src/context.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { parseCookies } from './csrf.js';
 import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
+import { shared } from './process-shared.js';
 
 /**
  * Per-request context backed by AsyncLocalStorage. Lets server-side code
@@ -39,7 +40,7 @@ import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
  */
 
 /** @type {AsyncLocalStorage<Store>} */
-const als = new AsyncLocalStorage();
+const als = shared('request-als', () => new AsyncLocalStorage());
 
 /**
  * Run `fn` with the given request bound as the current context.

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

@@ -22,7 +22,9 @@
  *
  * @module dev/bun-app-source
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { expandImportAlias } from '../module-graph.js';
 
 const ROOTS = Symbol.for('webjs.dev.bunAppSourceRoots');
 
@@ -59,8 +61,39 @@ 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: readFileSync(abs, 'utf8'), loader: /\.m?ts$/.test(abs) ? 'ts' : 'js' };
+        return { contents: rewriteAppAliases(readFileSync(abs, 'utf8'), abs), loader: /\.m?ts$/.test(abs) ? 'ts' : 'js' };
       });
     },
   });
 }
+
+/** Static `import`/`export … from '#x'` and `import('#x')` with a literal specifier. */
+const ALIAS_SPEC_RE = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])(#[^'"\s]+)\2/g;
+
+/**
+ * Rewrite the app's `#` import specifiers in a module's source to the absolute
+ * path they name (#1575), when that file exists. Bun's resolver serves a `#`
+ * import of a file created after it listed the directory as "Cannot find
+ * module" under `bun --hot`, and a runtime `onResolve` cannot stand in for it:
+ * its result reaches a dynamic `import()` as a broken `file:/...` path (the
+ * 0.8.85 / 0.8.86 regression). An absolute path resolves through neither.
+ * Anything that is not an app alias, or names no file yet, is left as written,
+ * so Bun reports a missing module exactly as before.
+ *
+ * @param {string} src
+ * @param {string} file  absolute path of the module
+ * @returns {string}
+ */
+export function rewriteAppAliases(src, file) {
+  if (!src.includes('#')) return src;
+  const g = /** @type {any} */ (globalThis);
+  const roots = g[ROOTS] instanceof Set ? [...g[ROOTS]] : [];
+  const appDir = roots.find((r) => file.startsWith(r + '/'));
+  if (!appDir || file.includes('/node_modules/')) return src;
+  return src.replace(ALIAS_SPEC_RE, (m, lead, q, spec) => {
+    const rel = expandImportAlias(spec, appDir);
+    if (!rel) return m;
+    const abs = resolvePath(appDir, rel);
+    try { return existsSync(abs) && statSync(abs).isFile() ? `${lead}${q}${abs}${q}` : m; } catch { return m; }
+  });
+}

package/src/dev/handler.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { registerBunAliasResolver } from './bun-alias-resolve.js';
 import { registerBunAppSource } from './bun-app-source.js';
+import { evictPoisonedBunTranspilerCache } from '../bun-transpiler-cache.js';
 import { serverRuntime } from '../listener-core.js';
 import { createHash } from 'node:crypto';
 import { join, relative, resolve, sep } from 'node:path';
@@ -135,6 +135,9 @@ export async function createRequestHandler(opts) {
   // on Bun. Doing it here pays the (one-time) amaro import up front and surfaces
   // a missing-amaro error at boot rather than on the first `.ts` request.
   await ensureStripper();
+  // Old (0.8.85 / 0.8.86) Bun transpiler-cache entries carry broken import
+  // paths keyed by unchanged file content; empty the cache once (#1575).
+  evictPoisonedBunTranspilerCache();
   const appDir = resolve(opts.appDir);
   // Load <appDir>/.env into process.env BEFORE anything else.
   // buildActionIndex below imports server-only files (lib/*.server.ts,
@@ -300,12 +303,6 @@ export async function createRequestHandler(opts) {
   // what a bound `<form action=${action}>` resolves through, so gating the hook
   // on seeding would mean `webjs.seed: false` silently broke every no-JS form.
   await registerActionHooks({ seed: await readSeedEnabled(appDir), dev });
-  // Bun's resolver keeps a stale directory listing for a `#` import under
-  // `bun --hot` (#1575); resolve the app's aliases ourselves in dev.
-  if (dev && serverRuntime() === 'bun') {
-    registerBunAliasResolver(appDir);
-    try { const real = realpathSync(appDir); if (real !== appDir) registerBunAliasResolver(real); } catch { /* appDir only */ }
-  }
 
   // Dev source locations (#1499): `WEBJS_SOURCE_LOCATIONS=1` (or
   // `webjs.dev.sourceLocations: true`) under `webjs dev`

package/src/dev/serve.js

@@ -361,7 +361,15 @@ export async function handleCore(req, ctx) {
 
   // Metadata routes: /sitemap.xml, /robots.txt, /icon, /opengraph-image, etc.
   if (method === 'GET' && state.routeTable.metadataRoutes) {
-    const meta = state.routeTable.metadataRoutes.find((r) => r.urlPath === path);
+    const meta = state.routeTable.metadataRoutes.find((r) => r.urlPath === path)
+      || (path === '/favicon.ico' ? faviconFallback(state.routeTable.metadataRoutes) : undefined);
+    if (meta && meta.static) {
+      // A static metadata file (`app/icon.svg`, `app/manifest.webmanifest`):
+      // the file's bytes with the convention's content type.
+      const res = await fileResponse(meta.file, { dev, immutable: versioned });
+      if (res.ok && meta.contentType) res.headers.set('content-type', meta.contentType);
+      return res;
+    }
     if (meta) {
       try {
         // The route gets `{ request, url, siteUrl, pages }` and may return a
@@ -633,6 +641,26 @@ export async function loadMiddleware(appDir, dev, logger) {
  * @param {string} abs
  * @param {{ dev: boolean, immutable: boolean }} opts
  */
+/**
+ * What answers `/favicon.ico` when neither `public/favicon.ico` nor
+ * `app/favicon.ico` exists: the app's own icon. Browsers and crawlers request
+ * `/favicon.ico` without reading the page's <head> (a feed reader, a bookmark
+ * import, a page served without HTML), so an app with only `app/icon.svg`
+ * would otherwise answer them with a 404. An `.ico` or raster file is
+ * preferred over SVG, which some of those clients cannot read; the dynamic
+ * `app/icon.ts` route is the last resort.
+ *
+ * @param {Array<{ stem: string, urlPath: string, static?: boolean, contentType?: string }>} routes
+ */
+export function faviconFallback(routes) {
+  const icons = routes.filter((r) => r.stem === 'icon' && (r.static || r.urlPath === '/icon'));
+  const rank = (/** @type {typeof icons[number]} */ r) => !r.static ? 9
+    : r.contentType === 'image/x-icon' ? 0
+      : r.contentType === 'image/png' ? 1
+        : r.contentType === 'image/svg+xml' ? 3 : 2;
+  return icons.sort((a, b) => rank(a) - rank(b))[0];
+}
+
 export async function fileResponse(abs, opts) {
   try {
     let data = await readFile(abs);

package/src/html-cache.js

@@ -30,6 +30,7 @@ import { createHash } from 'node:crypto';
 import { publishedBuildId, basePath } from './importmap.js';
 import { stripBasePath } from './base-path.js';
 import { dynamicAccessed, getRequest } from './context.js';
+import { shared } from './process-shared.js';
 
 /** Namespace prefix for every cached-HTML key, so a flush can target it. */
 const KEY_PREFIX = 'webjs:html:';
@@ -51,9 +52,12 @@ export const HTML_CACHE_MARKER = 'x-webjs-html-cache';
  * clear cannot enumerate keys), and the store TTL eventually reclaims the
  * orphaned entries. A single process clears its own memory store this way
  * synchronously; a Redis-backed multi-process deploy bumps per process and
- * leans on the TTL for the rest (a best-effort global flush).
+ * leans on the TTL for the rest (a best-effort global flush). Held in
+ * process-shared state (#1590), so a `revalidateAll()` from an app module that
+ * imported a fresh copy of this package after a `bun --hot` reload still
+ * reaches the server's keys.
  */
-let _generation = 0;
+const _generation = shared('html-cache-generation', () => ({ n: 0 }));
 
 /**
  * A fingerprint of the served app source, folded into every cache key (#318).
@@ -170,7 +174,7 @@ export function htmlCacheKey(url) {
   // the importmap-only build id misses. Empty (dev / no fingerprint) collapses
   // to the prior key shape, so an unconfigured app is byte-identical.
   const appfp = _appSourceFp ? `${_appSourceFp}:` : '';
-  return `${KEY_PREFIX}${build}:${appfp}${_generation}:${originKey(url)}:${url.pathname}${search}`;
+  return `${KEY_PREFIX}${build}:${appfp}${_generation.n}:${originKey(url)}:${url.pathname}${search}`;
 }
 
 /**
@@ -417,10 +421,10 @@ function warnDynamicRevalidateOnce(pathname) {
 
 /** Evict ALL cached HTML for this process. @returns {void} */
 export function revalidateAll() {
-  _generation++;
+  _generation.n++;
 }
 
 /** Internal: current generation, folded into keys by `htmlCacheKey`. */
 export function htmlCacheGeneration() {
-  return _generation;
+  return _generation.n;
 }

package/src/instrumentation.js

@@ -19,6 +19,7 @@ import { join } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { devImport } from './dev-import.js';
+import { shared } from './process-shared.js';
 
 /**
  * Per-boot handoff channel for a `register()`-registered error sink. An
@@ -29,7 +30,7 @@ import { devImport } from './dev-import.js';
  * context propagates across the `await register()` awaits.
  * @type {AsyncLocalStorage<{ onError: ((error: unknown, ctx?: any) => void) | null }>}
  */
-const _als = new AsyncLocalStorage();
+const _als = shared('instrumentation-als', () => new AsyncLocalStorage());
 
 /**
  * Register an error sink from inside `instrumentation.register()`. Composes with

package/src/process-shared.js

@@ -0,0 +1,34 @@
+/**
+ * Process-wide state for the parts of `@webjsdev/server` an app calls into.
+ *
+ * Under `bun --hot` a dev reload gives the app a fresh module registry while
+ * the first run's server keeps running (`dev/hot-host.js`, #1575). An app
+ * module that imports `@webjsdev/server` after a reload therefore gets a NEW
+ * copy of this package, whose module variables start empty, while the server
+ * that handles the request is still the first copy. Anything the two must
+ * agree on has to live outside the module: a request bound with the first
+ * copy's `AsyncLocalStorage` is invisible to the second copy's `getRequest()`,
+ * so `auth()`, `cookies()` and `headers()` inside a page or a `'use server'`
+ * function saw no request after the first edit and a signed-in page rendered
+ * as signed out (#1590).
+ *
+ * `shared(name, make)` returns the one value for `name` in this process,
+ * creating it on first use, keyed by `Symbol.for` exactly as core keys its own
+ * shared state. Use it for request-scoped storage and for any registry or
+ * store an app reads or writes through the package's API.
+ *
+ * @module process-shared
+ */
+
+/**
+ * @template T
+ * @param {string} name
+ * @param {() => T} make
+ * @returns {T}
+ */
+export function shared(name, make) {
+  const key = Symbol.for(`webjs.server.${name}`);
+  const g = /** @type {any} */ (globalThis);
+  if (!(key in g)) g[key] = make();
+  return g[key];
+}

package/src/router.js

@@ -26,7 +26,7 @@ import { findInstrumentationClient } from './instrumentation.js';
  *   middlewares: string[],
  * }} ApiRoute
  *
- * @typedef {{ stem: string, file: string, urlPath: string }} MetadataRoute
+ * @typedef {{ stem: string, file: string, urlPath: string, static?: boolean, contentType?: string }} MetadataRoute
  *
  * @typedef {{
  *   pages: PageRoute[],
@@ -60,6 +60,10 @@ import { findInstrumentationClient } from './instrumentation.js';
  *   app/sitemap.js                  → serves /sitemap.xml
  *   app/robots.js                   → serves /robots.txt
  *   app/icon.js                     → serves /icon (dynamic)
+ *   app/icon.svg | icon.png         → serves /icon.svg | /icon.png (static file)
+ *   app/apple-icon.png              → serves /apple-icon.png (static file)
+ *   app/favicon.ico                 → serves /favicon.ico (static file)
+ *   app/manifest.webmanifest        → serves /manifest.webmanifest (static file)
  *   app/opengraph-image.js          → serves /opengraph-image (dynamic)
  *
  * @param {string} appDir
@@ -114,6 +118,19 @@ export async function buildRouteTable(appDir) {
     // Private folders (any segment starting with _) are excluded from routing.
     if (dir !== '.' && dir.split('/').some((s) => s.startsWith('_'))) continue;
 
+    // Static metadata FILES at the app root (`app/icon.svg`, `app/icon.png`,
+    // `app/apple-icon.png`, `app/favicon.ico`, `app/manifest.webmanifest`):
+    // served as is at `/<file name>` and auto-linked into <head> like their
+    // `.ts` counterparts. Root only: an icon or manifest describes the whole
+    // app, and a nested copy has no meaning a browser would act on.
+    if (dir === '.') {
+      const staticMeta = staticMetadataFile(base);
+      if (staticMeta) {
+        metadataRoutes.push({ ...staticMeta, file, urlPath: '/' + base, static: true });
+        continue;
+      }
+    }
+
     // Match `<name>.<js|mjs|ts|mts>` conventions. Stem is the name without ext.
     const stem = stemOf(base);
     if (!stem) continue;
@@ -215,6 +232,37 @@ export async function buildRouteTable(appDir) {
  * @param {string} base
  * @returns {string | null}
  */
+/**
+ * The static metadata file conventions, keyed by file name pattern. Each maps
+ * to the metadata stem it stands for and the content type it is served with.
+ * @type {Array<[RegExp, string, Record<string, string>]>}
+ */
+const STATIC_METADATA_FILES = [
+  [/^icon\.(svg|png|ico|jpg|jpeg|webp|gif)$/, 'icon', {}],
+  [/^apple-icon\.(png|jpg|jpeg)$/, 'apple-icon', {}],
+  [/^favicon\.(ico)$/, 'favicon', {}],
+  [/^manifest\.(json|webmanifest)$/, 'manifest', { json: 'application/manifest+json', webmanifest: 'application/manifest+json' }],
+];
+
+/** @type {Record<string, string>} */
+const IMAGE_TYPES = {
+  svg: 'image/svg+xml', png: 'image/png', ico: 'image/x-icon', jpg: 'image/jpeg',
+  jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif',
+};
+
+/**
+ * Classify an app-root file name as a static metadata file, or null.
+ * @param {string} base
+ * @returns {{ stem: string, contentType: string } | null}
+ */
+export function staticMetadataFile(base) {
+  for (const [re, stem, types] of STATIC_METADATA_FILES) {
+    const m = re.exec(base);
+    if (m) return { stem, contentType: types[m[1]] || IMAGE_TYPES[m[1]] };
+  }
+  return null;
+}
+
 function stemOf(base) {
   const m = /^([A-Za-z0-9_.-]+)\.(?:m?[jt]s)$/.exec(base);
   return m ? m[1] : null;

package/src/session.js

@@ -22,6 +22,7 @@
 
 import { getStore } from './cache.js';
 import { markDynamicAccess } from './context.js';
+import { shared } from './process-shared.js';
 
 // -- Web Crypto helpers ------------------------------------------------------
 // Same shape as auth.js. We duplicate here rather than share a module
@@ -293,7 +294,7 @@ function serializeCookie(name, value, opts) {
 // ---------------------------------------------------------------------------
 
 /** @type {WeakMap<Request, Session>} */
-const sessionMap = new WeakMap();
+const sessionMap = shared('session-map', () => new WeakMap());
 
 // ---------------------------------------------------------------------------
 // Session middleware

package/src/ssr/head.js

@@ -1,3 +1,4 @@
+import { openSync, readSync, closeSync } from 'node:fs';
 import { basePath, buildImportMap, importMapTag, vendorPreconnectOrigins } from '../importmap.js';
 import { withBasePath } from '../base-path.js';
 import { escapeAttr, escapeHtml } from './escape.js';
@@ -10,62 +11,128 @@ import { embedScriptTag } from '../dev-embed.js';
 import { devReloadState } from '../dev-reload-state.js';
 import { openGraphPairs, twitterPairs, setMetadataImageRoutes } from './seo.js';
 
-// Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
-// Set at boot and on each route rebuild from the route table, the same shape
-// as setClientRouterEnabled, so no opt has to thread through every render
-// path. Empty by default, which keeps an app that declares its icons (or has
-// neither route) byte-identical.
+// Which icon and manifest metadata the app has: the `app/icon.*`,
+// `app/apple-icon.*` and `app/manifest.*` files (a static file such as
+// `app/icon.svg`, or a route such as `app/icon.ts`). Set at boot and on each
+// route rebuild from the route table, the same shape as setClientRouterEnabled,
+// so no opt has to thread through every render path. Empty by default, which
+// keeps an app that declares its icons (or has none) byte-identical.
 //
 // This sits in head.js rather than in a module of its own the way the
 // client-router flag does: `wrapHead` is the only reader, and module state
 // belongs with the code that uses and writes it. The flag moved out only
 // because it has a second reader in render.js.
-/** @type {{ icon: boolean, apple: boolean }} */
-let _metadataIconRoutes = { icon: false, apple: false };
+/** @typedef {{ url: string, type?: string, sizes?: string }} AutoIcon */
+/** @type {{ icon: AutoIcon[], apple: AutoIcon[], manifest: string | null }} */
+let _metadataIconRoutes = { icon: [], apple: [], manifest: null };
 
 /**
- * Record the icon metadata routes the app defines.
+ * The pixel size of a PNG file (`"180x180"`), read from its IHDR header, or
+ * undefined when the file is not a readable PNG. Only the first 24 bytes are
+ * read, once per route rebuild.
+ * @param {string} file
+ */
+function pngSizes(file) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(24);
+    if (readSync(fd, buf, 0, 24, 0) < 24) return undefined;
+    if (buf.readUInt32BE(0) !== 0x89504e47 || buf.toString('latin1', 12, 16) !== 'IHDR') return undefined;
+    return `${buf.readUInt32BE(16)}x${buf.readUInt32BE(20)}`;
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/**
+ * Record the icon and manifest metadata the app defines.
+ *
+ * A static file is linked with its type, plus its pixel size for a PNG and
+ * `sizes="any"` for an SVG. A route (`app/icon.ts`) is linked bare: it picks
+ * its own content type at request time, which is the reason to use one, so a
+ * declared type could contradict the bytes. When an app has both a static
+ * icon and an icon route, the static file wins the link: the route then
+ * stays reachable at its URL without becoming the favicon.
+ *
+ * Raster icons are linked before SVG. Google's favicon crawler takes the
+ * first usable icon and wants a square raster, and a browser that reads SVG
+ * picks it from the list regardless of order.
  *
- * @param {Iterable<{ stem: string }> | null | undefined} metadataRoutes
+ * @param {Iterable<{ stem: string, urlPath?: string, file?: string, static?: boolean, contentType?: string }> | null | undefined} metadataRoutes
  *   The route table's `metadataRoutes`, or nullish to clear.
  */
 export function setMetadataIconRoutes(metadataRoutes) {
-  const stems = new Set();
-  for (const r of metadataRoutes || []) if (r && r.stem) stems.add(r.stem);
-  _metadataIconRoutes = { icon: stems.has('icon'), apple: stems.has('apple-icon') };
-  // The share-image routes (#1564) are recorded from the same table so one
-  // call keeps both in step on boot and on every rebuild.
+  /** @type {Record<string, Array<{ stem: string, urlPath?: string, file?: string, static?: boolean, contentType?: string }>>} */
+  const byStem = { icon: [], 'apple-icon': [], manifest: [] };
+  for (const r of metadataRoutes || []) {
+    if (!r || !byStem[r.stem]) continue;
+    // Only the app-root ones describe the app. A route nested in a segment
+    // (`app/blog/icon.ts`) answers at its own URL but is not the favicon.
+    const url = r.urlPath || '/' + r.stem;
+    if (url.lastIndexOf('/') !== 0) continue;
+    byStem[r.stem].push({ ...r, urlPath: url });
+  }
+  /** @param {typeof byStem.icon} list @returns {AutoIcon[]} */
+  const links = (list) => {
+    const statics = list.filter((r) => r.static);
+    const chosen = statics.length ? statics : list.filter((r) => !r.static);
+    const rank = (/** @type {typeof list[number]} */ r) => (r.contentType === 'image/svg+xml' ? 1 : 0);
+    return chosen.sort((a, b) => rank(a) - rank(b)).map((r) => {
+      /** @type {AutoIcon} */
+      const out = { url: /** @type {string} */ (r.urlPath) };
+      if (r.static && r.contentType) out.type = r.contentType;
+      if (r.contentType === 'image/svg+xml') out.sizes = 'any';
+      else if (r.contentType === 'image/png' && r.file) {
+        const sizes = pngSizes(r.file);
+        if (sizes) out.sizes = sizes;
+      }
+      return out;
+    });
+  };
+  const manifest = byStem.manifest.find((r) => r.static) || byStem.manifest[0];
+  _metadataIconRoutes = {
+    icon: links(byStem.icon),
+    apple: links(byStem['apple-icon']),
+    manifest: manifest ? /** @type {string} */ (manifest.urlPath) : null,
+  };  // The og/twitter image routes ride the same rebuild hook (seo.js).
   setMetadataImageRoutes(metadataRoutes);
 }
 
 /**
- * The implicit `metadata.icons` an app's icon routes stand for, or null when
- * it has none. Base-path prefixed, because that is where the routes are
+ * The implicit `metadata.icons` an app's icon files and routes stand for, or
+ * null when it has none. Base-path prefixed, because that is where they are
  * SERVED: the listener strips the base path before matching, so under
- * `webjs.basePath` the route answers at `<basePath>/icon`. A user-authored
+ * `webjs.basePath` the icon answers at `<basePath>/icon.svg`. A user-authored
  * `icons` URL is deliberately left alone (it may be cross-origin, and the
  * author writes the path they mean), so only these framework-emitted ones
  * are prefixed.
  *
- * No `type` or `sizes` is emitted. A metadata route picks its own content
- * type at request time, which is the reason to use one, so declaring a type
- * here could contradict the bytes; and `sizes` is unknowable without reading
- * the response. Both are optional in HTML, and a browser sniffs the served
- * content type.
- *
- * @returns {{ icon?: string, apple?: string } | null}
+ * @returns {{ icon?: AutoIcon[], apple?: AutoIcon[] } | null}
  */
 function autoMetadataRouteIcons() {
   const { icon, apple } = _metadataIconRoutes;
-  if (!icon && !apple) return null;
+  if (!icon.length && !apple.length) return null;
   const bp = basePath();
-  /** @type {{ icon?: string, apple?: string }} */
+  const prefix = (/** @type {AutoIcon} */ i) => ({ ...i, url: withBasePath(i.url, bp) });
+  /** @type {{ icon?: AutoIcon[], apple?: AutoIcon[] }} */
   const out = {};
-  if (icon) out.icon = withBasePath('/icon', bp);
-  if (apple) out.apple = withBasePath('/apple-icon', bp);
+  if (icon.length) out.icon = icon.map(prefix);
+  if (apple.length) out.apple = apple.map(prefix);
   return out;
 }
 
+/**
+ * The app's `app/manifest.*` URL (base-path prefixed), or null.
+ * @returns {string | null}
+ */
+function autoManifestUrl() {
+  const { manifest } = _metadataIconRoutes;
+  return manifest ? withBasePath(manifest, basePath()) : null;
+}
+
 /**
  * HTML-safe-escape a JSON string for embedding inside a
  * `<script type="application/ld+json">` element.
@@ -787,9 +854,14 @@ export function wrapHead(opts) {
     }
   }
 
-  // manifest: a string URL → <link rel="manifest">
+  // manifest: a string URL → <link rel="manifest">. With none declared, an
+  // `app/manifest.*` file or route is linked automatically, the same way the
+  // icons are; `manifest: null` opts out.
   if (typeof m.manifest === 'string') {
     linkTags.push(`<link rel="manifest" href="${escapeAttr(absUrl(m.manifest))}">`);
+  } else if (m.manifest === undefined) {
+    const auto = autoManifestUrl();
+    if (auto) linkTags.push(`<link rel="manifest" href="${escapeAttr(auto)}">`);
   }
 
   // alternates: { canonical, languages: { '<hreflang>': url }, media: { '<media>': url } }

package/src/dev/bun-alias-resolve.js

@@ -1,71 +0,0 @@
-/**
- * Resolve the app's `#` subpath imports ourselves under `webjs dev` on Bun
- * (#1575).
- *
- * Bun caches a directory's entries when it resolves through it and, under
- * `bun --hot`, refreshes that cache only for a directory it watches. It does
- * not watch a directory that holds only modules a `Bun.plugin` served (an
- * `actions/` folder of `*.server.ts` files), and a `package.json "imports"`
- * specifier (`#modules/x/new.ts`) resolves through that stale listing, while a
- * relative one does not. So a file an agent added next to an action was
- * "Cannot find module" for the rest of the process, through every reload. This
- * `onResolve` expands the alias through the same map the module graph uses
- * (`expandImportAlias`) and hands Bun an absolute path that exists, which Bun
- * then loads normally (the seed plugin's `onLoad` still applies by path). A
- * specifier it cannot place falls through to Bun's own resolver, so an error
- * reads exactly as it would without it.
- *
- * Dev only (production never reloads) and Bun only (Node's resolver reads the
- * file system on every resolve).
- *
- * @module dev/bun-alias-resolve
- */
-import { existsSync, statSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
-import { expandImportAlias } from '../module-graph.js';
-
-const ROOTS = Symbol.for('webjs.dev.bunAliasRoots');
-
-/**
- * Resolve `spec` imported by `importer` against the app's `#` alias map, or
- * null when it is not an app alias or the target is not a file.
- *
- * @param {string} spec
- * @param {string} importer  absolute path, possibly with a query
- * @param {string} appDir  absolute
- * @returns {string | null}
- */
-export function resolveAppAlias(spec, importer, appDir) {
-  if (!spec.startsWith('#')) return null;
-  const from = String(importer || '').split('?')[0];
-  if (!from.startsWith(appDir + sep) || from.includes(`${sep}node_modules${sep}`)) return null;
-  const rel = expandImportAlias(spec, appDir);
-  if (!rel) return null;
-  const abs = resolve(appDir, rel);
-  try { return existsSync(abs) && statSync(abs).isFile() ? abs : null; } catch { return null; }
-}
-
-/**
- * Install the resolver for `appDir`, once per process.
- * @param {string} appDir  absolute
- */
-export function registerBunAliasResolver(appDir) {
-  const g = /** @type {any} */ (globalThis);
-  if (!g.Bun || typeof g.Bun.plugin !== 'function') return;
-  if (!(g[ROOTS] instanceof Set)) g[ROOTS] = new Set();
-  if (g[ROOTS].has(appDir)) return;
-  g[ROOTS].add(appDir);
-  g.Bun.plugin({
-    name: 'webjs-dev-alias',
-    setup(build) {
-      build.onResolve({ filter: /^#/ }, (args) => {
-        try {
-          const path = resolveAppAlias(args.path, args.importer, appDir);
-          return path ? { path } : undefined;
-        } catch {
-          return undefined;
-        }
-      });
-    },
-  });
-}