@webjsdev/server 0.8.84 → 0.8.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.84",
+  "version": "0.8.86",
   "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/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/dev/server.js

@@ -273,7 +273,9 @@ export async function startServer(opts) {
   // shells via listener-core.js, so live-reload + the dev error overlay behave
   // identically on both). Built before the handler so its onReload / onDevError
   // callbacks can fan out through it.
-  const hub = new SseHub();
+  // A Bun hot host, or a server outside the dev supervisor (`--no-hot`, an
+  // embedder), applies an edit in place; a supervised Node child is restarted.
+  const hub = new SseHub({ inPlace: dev && (!!hotKey || process.env.__WEBJS_DEV_CHILD !== '1') });
   // Pages render the stream's state into a meta tag (#1516), so the relay can
   // re-check a page against the server on every reconnect.
   if (dev) setDevReloadState(() => ({ boot: DEV_BOOT_ID, seq: hub.seq }));

package/src/dev-reload-worker.js

@@ -36,6 +36,18 @@
  */
 export const RELOAD_QUIET_MS = 2000;
 
+/**
+ * The quiet window for a batch made only of in-process frames from a server
+ * that reloads IN PLACE (#1575): Bun's one long-lived dev server, or any
+ * `--no-hot` server. No restart follows such a frame, so nothing is worth
+ * waiting 2000ms for, and that wait was most of the save-to-paint time (3.8s
+ * measured in a hosted preview). 300ms still folds a save's few frames and a
+ * quick burst into one reload. A batch holding any restart signal (a changed
+ * boot id, a stale page, a frame from a restarting server) keeps the full
+ * `RELOAD_QUIET_MS`, since the restarted process is still warming.
+ */
+export const RELOAD_QUIET_IN_PLACE_MS = 300;
+
 /**
  * The longest a reload is ever held, measured from the FIRST signal of a batch
  * (#1397). A quiet window alone would freeze the page on stale content for a
@@ -116,6 +128,19 @@ export function pageIsStale(page, boot, seq) {
 }
 
 /** A reload frame's `seq` (#1507), or null when it carries none. @param {string} data */
+/**
+ * Whether a `reload` frame comes from a server that reloads in place (#1575).
+ * Absent or unreadable means it may restart, the safe (slower) reading.
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function frameInPlace(data) {
+  try {
+    const o = JSON.parse(data);
+    return !!(o && o.inPlace === true);
+  } catch (_) { return false; }
+}
+
 function reloadSeq(data) {
   try {
     const o = JSON.parse(data);
@@ -190,6 +215,8 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
   let batchAll = false;
   /** @type {Set<any>} tabs whose page fell behind, reloaded on their own */
   const batchPorts = new Set();
+  /** Whether the batch holds a signal from a server that restarts (#1575). */
+  let batchRestart = false;
 
   function emitReload() {
     if (quietTimer !== null) { timers.clearTimeout(quietTimer); quietTimer = null; }
@@ -200,6 +227,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
     const targets = batchAll ? Array.from(ports.keys()) : Array.from(batchPorts).filter((p) => ports.has(p));
     batchAll = false;
     batchPorts.clear();
+    batchRestart = false;
     for (const p of targets) {
       // The tab applies this reload, so from here its page reflects the state
       // the relay knows now; a later hello compares against that.
@@ -219,11 +247,13 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
    * @param {string} verdict
    * @param {any} [port]  reload only this tab (its page fell behind); omitted, every tab
    */
-  function requestReload(verdict, port) {
+  function requestReload(verdict, port, inPlace) {
     if (port === undefined) batchAll = true; else batchPorts.add(port);
     if (rank(verdict) < rank(batchVerdict)) batchVerdict = VERDICT_STRENGTH[rank(verdict)];
+    // One restart signal anywhere in the batch keeps the long window (#1575).
+    if (!inPlace) batchRestart = true;
     if (quietTimer !== null) timers.clearTimeout(quietTimer);
-    quietTimer = timers.setTimeout(emitReload, RELOAD_QUIET_MS);
+    quietTimer = timers.setTimeout(emitReload, batchRestart ? RELOAD_QUIET_MS : RELOAD_QUIET_IN_PLACE_MS);
     if (capTimer === null) capTimer = timers.setTimeout(emitReload, RELOAD_MAX_HOLD_MS);
   }
 
@@ -278,7 +308,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
       lastError = null;
       const n = reloadSeq(e.data);
       if (n !== null) lastSeq = n;
-      requestReload(parseVerdict(e.data));
+      requestReload(parseVerdict(e.data), undefined, frameInPlace(e.data));
     });
     es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
     // The stream dropped (a restarting server, a network blip, a host that

package/src/listener-core.js

@@ -351,7 +351,13 @@ export function loadWsModule(file, dev) {
  * tab was hidden can tell, on reconnecting, that it missed an edit.
  */
 export class SseHub {
-  constructor() {
+  /**
+   * @param {{ inPlace?: boolean }} [opts] `inPlace`: this server applies an
+   *   edit without restarting its process (#1575), so its reload frames say so
+   *   and the browser relay need not wait for a restart to settle.
+   */
+  constructor({ inPlace = false } = {}) {
+    this.inPlace = inPlace;
     /** @type {Set<{ send: (s: string) => void, close: () => void }>} */
     this.clients = new Set();
     /** Reload frames sent by this process (#1507). */
@@ -399,7 +405,7 @@ export class SseHub {
   reload(verdict) {
     const v = verdict && typeof verdict.v === 'string' ? verdict : { v: 'reload' };
     this.seq++;
-    this._raw(`event: reload\ndata: ${JSON.stringify({ ...v, seq: this.seq })}\n\n`);
+    this._raw(`event: reload\ndata: ${JSON.stringify({ ...v, seq: this.seq, ...(this.inPlace ? { inPlace: true } : {}) })}\n\n`);
   }
 
   /** Push a dev-error overlay frame (#264) to every open tab. @param {object} frame */

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/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 } }