@webjsdev/server 0.8.60 → 0.8.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.60",
+  "version": "0.8.62",
   "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",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/core": "^0.7.48",
+    "@webjsdev/core": "^0.7.50",
     "ws": "^8.20.0"
   },
   "publishConfig": {

package/src/actions.js

@@ -245,7 +245,7 @@ export async function isServerAction(file) {
 
 /**
  * @param {ActionIndex} idx
- * @param {string} urlPath - a browser-visible URL path like `/actions/foo.server.js`
+ * @param {string} urlPath A browser-visible URL path like `/actions/foo.server.js`
  */
 export function resolveServerModule(idx, urlPath) {
   const abs = join(idx.appDir, urlPath.split('/').join(sep));

package/src/base-path.js

@@ -54,6 +54,16 @@
  * or a hostile value fails safe to "no base path" rather than poisoning
  * every emitted URL.
  *
+ * This function is PORTED into the CLI, as `readAppBasePath`
+ * (`packages/cli/lib/doctor.js`), because doctor must run when
+ * `@webjsdev/server` does not resolve from the app dir at all (#954). The port
+ * is deliberate, so the two are kept honest by
+ * `test/cli/base-path-parity.test.mjs`, which runs one input table through both
+ * and asserts they agree. Edit this body and that test reds until the port
+ * follows. The ordering below matters most: the `//host` rejection sits BEFORE
+ * the leading-slash collapse, and reordering it on either side is an origin
+ * escape the parity table catches.
+ *
  * @param {unknown} raw the configured value
  * @returns {string} `''` or `/segment[/segment...]`
  */

package/src/check.js

@@ -7,6 +7,7 @@ import {
   extractWebComponentClassBodies,
   matchClosingBrace,
   parsePropEntries,
+  classifyActionHole,
 } from './js-scan.js';
 import { buildModuleGraph, transitiveDeps, resolveImport } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
@@ -190,7 +191,7 @@ function isServerActionFile(filePath, content) {
 /**
  * Check whether a file resides under a components/ directory (shared or
  * module-scoped).
- * @param {string} relPath - path relative to appDir
+ * @param {string} relPath Path relative to appDir
  * @returns {boolean}
  */
 function isComponentFile(relPath) {
@@ -1396,26 +1397,14 @@ export async function checkConventions(appDir) {
         // with no hole in it. That distinction is the whole carve-out: the
         // framework's own website renders this exact shape as a code sample.
         const { redacted, literals } = redactToPlaceholders(content);
-        // A hole binds an action when the literal segment IMMEDIATELY before it
-        // ends inside a start tag at the attribute that tag can really bind:
-        // `action=` on a `<form>` (#1155), or `formaction=` on a `<button>` /
-        // `<input>` submitter (#1207). Reading the segment rather than the whole
-        // template is what keeps `<div action=${x}>` out. The tag and the
-        // attribute are matched as a PAIR, so `<form formaction=${x}>` and
-        // `<button action=${x}>` stay out too: both are refused at render time,
-        // and neither is this rule's failure mode.
+        // Both binding shapes count the same here: `action=` on a `<form>`
+        // (#1155) and `formaction=` on a `<button>` / `<input>` submitter
+        // (#1207) each put the named action behind a form submission, and a
+        // GET-declared action cannot serve either. `classifyActionHole` owns
+        // the tag-and-attribute pairing (js-scan.js).
         const bound = new Set();
         for (const m of redacted.matchAll(/__STR_(\d+)__\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
-          const before = literals[Number(m[1])] || '';
-          // The last `<` opens the tag the hole sits in. Requiring no `>`
-          // after it keeps the match inside that one start tag.
-          const tagAt = before.lastIndexOf('<');
-          if (tagAt < 0) continue;
-          const tag = before.slice(tagAt);
-          if (tag.includes('>')) continue;
-          const bindsForm = /^<form\b/i.test(tag) && /\saction=$/i.test(tag);
-          const bindsSubmitter = /^<(?:button|input)\b/i.test(tag) && /\sformaction=$/i.test(tag);
-          if (!bindsForm && !bindsSubmitter) continue;
+          if (!classifyActionHole(literals[Number(m[1])] || '')) continue;
           bound.add(m[2]);
         }
         if (!bound.size) continue;

package/src/component-elision.js

@@ -238,8 +238,13 @@ const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
 
 /** Side-effect or named import of the client router subpath. */
 const CLIENT_ROUTER_SUBPATH_RE = /['"]@webjsdev\/core\/client-router['"]/;
-/** Client-only named APIs from the `@webjsdev/core` main entry. */
-const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientRouter', 'revalidate'];
+/**
+ * Client-only named APIs from the `@webjsdev/core` main entry. Exported so
+ * `test/elision/lifecycle-coverage.test.js` can guard it the way it guards
+ * REACTIVE_IMPORTS: a router function the barrel re-exports but this list omits
+ * is not recognized as client work, so a component using it is wrongly elided.
+ */
+export const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientRouter', 'revalidate', 'loadFrame'];
 
 /** Identifiers that only exist in a browser; their presence means client work. */
 const CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|customElements|matchMedia|addEventListener)\b/;
@@ -313,7 +318,7 @@ const PURE_DATA_CONSTRUCTORS = new Set([
   'BigInt64Array', 'BigUint64Array',
 ]);
 
-function hasModuleScopeSideEffect(src, literals) {
+export function hasModuleScopeSideEffect(src, literals) {
   let redacted = src;
   if (!literals) {
     const r = redactToPlaceholders(src);

package/src/dev.js

@@ -14,7 +14,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
-import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
+import { ssrPage, ssrNotFound, setClientRouterEnabled, setMetadataIconRoutes } from './ssr.js';
 import { runFormAction, reportFormSubmittedAsGet } from './form-dispatch.js';
 import { handleApi } from './api.js';
 import {
@@ -91,6 +91,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
+import { validateAppWebjsConfig } from './webjs-config-validate.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
 import { setAssetUrlProvider, setFormActionResolver } from '@webjsdev/core';
@@ -370,6 +371,34 @@ export async function readBasePathFromApp(appDir) {
   }
 }
 
+/**
+ * Read the app package.json and warn once about anything wrong with its `webjs`
+ * block (#1300). One aggregated warning, listing every problem, so a config with
+ * three typos does not produce three log lines.
+ *
+ * Never throws and never exits. See `webjs-config-validate.js` for why warning
+ * is the ruling and why this does not replace the CLI's `doctor.gate` check.
+ *
+ * @param {string} appDir
+ * @param {{ warn?: (...args: any[]) => void }} logger
+ * @returns {Promise<void>}
+ */
+export async function warnOnInvalidWebjsConfig(appDir, logger) {
+  let problems;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    problems = validateAppWebjsConfig(pkg);
+  } catch {
+    return;
+  }
+  if (!problems.length) return;
+  logger?.warn?.(
+    `[webjs] the "webjs" block in package.json has ${problems.length} problem(s), ` +
+      `each ignored at its default: ${problems.join('; ')}. ` +
+      `See https://webjs.dev/docs/configuration`,
+  );
+}
+
 /**
  * Read the cross-origin allowlist (`webjs.allowedOrigins`) from the app's
  * package.json. These hosts / origins are accepted by the action CSRF check
@@ -532,6 +561,17 @@ export async function createRequestHandler(opts) {
   await applyEnvValidation(appDir, { dev: !!opts.dev });
   const dev = !!opts.dev;
   const logger = opts.logger || defaultLogger({ dev });
+  // Boot-time `webjs` config validation (#1300). The published JSON Schema used
+  // to reach users only through the scaffold's .vscode `$ref`, so a typo'd key
+  // was caught in an editor and nowhere else: the key was dropped, the feature
+  // stayed at its default, and nothing said so. This runs it once per boot, from
+  // the one entry point dev, prod, and an embedded host all share.
+  //
+  // It WARNS and continues, never throws. A typo costs one feature sitting at
+  // its default; a hard boot failure over a schema quibble costs the whole app.
+  // A missing / unreadable / unparseable package.json is a silent no-op, like
+  // every other `webjs.*` reader in this file.
+  await warnOnInvalidWebjsConfig(appDir, logger);
   // Boot-time instrumentation hook (#848): run the optional app-root
   // instrumentation.{js,ts} register() ONCE, after env validation and before
   // the route table / action index are built, so observability plumbing starts
@@ -702,6 +742,12 @@ export async function createRequestHandler(opts) {
   // like env.js / readiness.js), not a router stem. Resolve it once and stash it
   // on the route table so ssrOpts + the browser-servable gate reach it uniformly.
   routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+  // Auto-linked favicons: tell the head builder which icon metadata routes
+  // exist, so `app/icon.*` is linked when the app declares no metadata.icons.
+  // Bound here rather than threaded through ssrOpts, matching
+  // setClientRouterEnabled; re-bound in doRebuild so adding or deleting the
+  // file takes effect without a restart.
+  setMetadataIconRoutes(routeTable.metadataRoutes);
 
   // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
   // dev so an editor's tsserver always has up-to-date route types without the
@@ -1167,6 +1213,8 @@ export async function createRequestHandler(opts) {
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
     state.routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+    // Adding or deleting app/icon.* changes whether the head auto-links it.
+    setMetadataIconRoutes(state.routeTable.metadataRoutes);
     // Refresh the generated route types (#258) so adding/removing a route file
     // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
     // best-effort (see emitRouteTypes).

package/src/form-dispatch.js

@@ -359,7 +359,7 @@ export function reportFormSubmittedAsGet(url, req, onError, logger, dev, route)
   }
   if (!willReport) return;
   const err = new Error(
-    `A form submission reached ${url.pathname} as a GET with the \`${FORM_ACTION_FIELD}\` identity in the query string, so no server action ran. The submitter's enclosing <form> binds no action.`,
+    `A form submission reached ${url.pathname} as a GET with the \`${FORM_ACTION_FIELD}\` identity in the query string, so no server action ran. A BOUND submitter carries its own formmethod="post" and a bound form is refused a method="get" outright, so look instead for a PLAIN submitter's formmethod="get", or a hand-authored form carrying the reserved field: a plain submitter's own formmethod wins by native precedence and WebJs honours it rather than refusing it.`,
   );
   /** @type {any} */ (err).code = 'WEBJS_FORM_SUBMITTED_AS_GET';
   /** @type {any} */ (err).method = req.method;

package/src/headers.js

@@ -53,7 +53,10 @@ const HSTS_VALUE = 'max-age=63072000; includeSubDomains';
  * (`webjs.headers`). Returns a normalized array of compiled rules, each
  * pairing a URLPattern against the configured header directives. A
  * malformed or absent config yields an empty array (no per-path rules),
- * never a throw: a broken config must not take the app down.
+ * never a throw: a broken config must not take the app down. Each malformed
+ * rule or directive is DROPPED with a one-line warning, matching
+ * `redirects.js`, so a single typo neither disables the valid rules around it
+ * nor disappears without a word.
  *
  * Shape consumed:
  *   "webjs": { "headers": [ { "source": "/embed/:path*",
@@ -67,33 +70,61 @@ const HSTS_VALUE = 'max-age=63072000; includeSubDomains';
  * @returns {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>}
  */
 export function compileHeaderRules(pkg) {
-  const raw =
-    pkg &&
-    typeof pkg === 'object' &&
-    /** @type {any} */ (pkg).webjs &&
-    /** @type {any} */ (pkg).webjs.headers;
-  if (!Array.isArray(raw)) return [];
+  // Read the block explicitly rather than off an `&&` chain. A chain SHORT-
+  // CIRCUITS, so its value is whatever link failed (a non-object `pkg` yields
+  // the boolean `false` from the `typeof` test), and deciding "the key is
+  // present" from that residue warns about a `headers` nobody wrote and prints
+  // a value that is not in their config.
+  const block = pkg && typeof pkg === 'object' ? /** @type {any} */ (pkg).webjs : undefined;
+  const hasBlock = !!block && typeof block === 'object' && !Array.isArray(block);
+  const raw = hasBlock ? block.headers : undefined;
+  if (!Array.isArray(raw)) {
+    // An ABSENT key is the default and says nothing. A PRESENT one of the wrong
+    // type discards the whole config, so it says so: the schema types this key
+    // `array` but the boot config check only inspects boolean / integer / enum
+    // leaves, so `"headers": {…}` is caught by nothing else.
+    if (hasBlock && 'headers' in block) warnDrop('headers must be an array', raw);
+    return [];
+  }
   /** @type {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>} */
   const rules = [];
   for (const entry of raw) {
-    if (!entry || typeof entry !== 'object') continue;
+    if (!entry || typeof entry !== 'object') {
+      warnDrop('entry must be an object', entry);
+      continue;
+    }
     const source = /** @type {any} */ (entry).source;
     const list = /** @type {any} */ (entry).headers;
-    if (typeof source !== 'string' || !Array.isArray(list)) continue;
+    if (typeof source !== 'string' || !source) {
+      warnDrop('source must be a non-empty string', entry);
+      continue;
+    }
+    if (!Array.isArray(list)) {
+      warnDrop(`headers must be an array on "${source}"`, entry);
+      continue;
+    }
     let pattern;
     try {
       // Match on the pathname only. A bare path string is the common
       // Next-style usage; URLPattern treats it as the pathname component.
       pattern = new URLPattern({ pathname: source });
     } catch {
-      continue; // skip an invalid pattern rather than crash the request
+      // Skip an invalid pattern rather than crash the request.
+      warnDrop(`invalid source pattern "${source}"`, entry);
+      continue;
     }
     /** @type {Array<{ key: string, value: string | null }>} */
     const directives = [];
     for (const d of list) {
-      if (!d || typeof d !== 'object') continue;
+      if (!d || typeof d !== 'object') {
+        warnDrop(`directive must be an object on "${source}"`, d);
+        continue;
+      }
       const key = /** @type {any} */ (d).key;
-      if (typeof key !== 'string' || !key) continue;
+      if (typeof key !== 'string' || !key) {
+        warnDrop(`directive key must be a non-empty string on "${source}"`, d);
+        continue;
+      }
       const v = /** @type {any} */ (d).value;
       // null / undefined / false means REMOVE the header on a match.
       const value = v === null || v === undefined || v === false ? null : String(v);
@@ -109,17 +140,49 @@ export function compileHeaderRules(pkg) {
       try {
         new Headers().set(key, value === null ? 'x' : value);
       } catch {
-        // eslint-disable-next-line no-console
-        console.warn(`[webjs] dropping invalid webjs.headers directive for key "${key}"`);
+        warnDrop(`invalid header name or value for key "${key}"`, d);
         continue;
       }
       directives.push({ key, value });
     }
-    if (directives.length) rules.push({ pattern, directives });
+    // A rule with nothing left to apply is dropped, and SAYS so. Two ways to
+    // get here and both were silent: an authored `"headers": []`, which the
+    // schema permits (no `minItems`) and the boot config check never sees
+    // (it does not descend into `headers`), and a rule whose every directive
+    // was just dropped, where the per-directive warnings above name the
+    // directives but never say the rule itself went with them.
+    if (!directives.length) {
+      warnDrop(`no valid directives left on "${source}"`, entry);
+      continue;
+    }
+    rules.push({ pattern, directives });
   }
   return rules;
 }
 
+/**
+ * One line per dropped config, rule, or directive, matching `redirects.js`'s
+ * warnDrop verbatim in shape. Every drop in `compileHeaderRules` goes through
+ * this, at all three levels: a wrong-typed `webjs.headers` key, a rule, and a
+ * directive. A config typo that silently does nothing is the failure this whole
+ * surface exists to end, and a `source` misspelled as `sources` used to vanish
+ * here with no diagnostic at all.
+ *
+ * The one thing that does NOT warn is an ABSENT `webjs.headers`, which is the
+ * default rather than a mistake.
+ *
+ * Defined BELOW `compileHeaderRules`, like the one in `redirects.js`. Putting
+ * it above wedged this docblock between that function's JSDoc and its
+ * declaration, so the JSDoc bound to the helper instead and the reader lost
+ * its `@param` / `@returns` entirely.
+ *
+ * @param {string} reason @param {unknown} entry
+ */
+function warnDrop(reason, entry) {
+  // eslint-disable-next-line no-console
+  console.warn(`[webjs] dropping invalid webjs.headers config (${reason}):`, entry);
+}
+
 /**
  * Apply the security defaults and the per-path config to a Response,
  * returning a Response carrying the merged headers. The input Response

package/src/js-scan.js

@@ -470,7 +470,13 @@ export function extractWebComponentClassBodies(content) {
         bodies.push({
           body: content.slice(bodyStart, end),
           factoryProps,
-          factoryArg
+          factoryArg,
+          // Offsets into `content`. Callers pass the position-preserving MASK,
+          // so these index the RAW source identically, which is how a caller
+          // that needs the body's real template text gets it without asking
+          // this lexer to handle raw source (#1307).
+          bodyStart,
+          bodyEnd: end,
         });
       }
     }
@@ -640,7 +646,7 @@ export function matchClosingParenthesis(s, start) {
  * (the closing `}` arrived while still in template state), so depth could
  * never return to zero and a class body holding `` html`…${x}…` `` was
  * unmatchable. Every caller passes a masked source in which holes are already
- * blanked, so the bug is invisible until one passes raw source.
+ * blanked, so the bug is invisible until one passes raw source (#1307).
  *
  * @param {string} s
  * @param {number} start
@@ -717,3 +723,44 @@ export function redactToPlaceholders(src) {
   return { redacted: out, literals };
 }
 
+/**
+ * The attribute position a template hole commits to, read from the literal
+ * segment immediately before it. Returns the attribute NAME only; a caller
+ * pairs it with the tag the hole sits in.
+ *
+ * @param {string} literalBefore
+ * @returns {'action' | 'formaction' | null}
+ */
+function trailingActionAttr(literalBefore) {
+  if (/\sformaction=$/i.test(literalBefore)) return 'formaction';
+  if (/\saction=$/i.test(literalBefore)) return 'action';
+  return null;
+}
+
+/**
+ * Classify a template hole by the start tag and attribute it commits: `'form'`
+ * for `<form action=` (#1155), `'submitter'` for `<button|input formaction=`
+ * (#1207), and `null` for anything else.
+ *
+ * Reading the segment immediately before the hole rather than the whole
+ * template is what keeps `<div action=${x}>` out. The tag and the attribute are
+ * matched as a PAIR, so `<form formaction=${x}>` and `<button action=${x}>`
+ * stay out too: both are refused at render time, and neither is a binding.
+ *
+ * @param {string} literalBefore the literal segment immediately before the hole
+ * @returns {'form' | 'submitter' | null}
+ */
+export function classifyActionHole(literalBefore) {
+  const attr = trailingActionAttr(literalBefore);
+  if (!attr) return null;
+  // The last `<` opens the tag the hole sits in. Requiring no `>` after it
+  // keeps the match inside that one start tag.
+  const tagAt = literalBefore.lastIndexOf('<');
+  if (tagAt < 0) return null;
+  const tag = literalBefore.slice(tagAt);
+  if (tag.includes('>')) return null;
+  if (attr === 'action' && /^<form\b/i.test(tag)) return 'form';
+  if (attr === 'formaction' && /^<(?:button|input)\b/i.test(tag)) return 'submitter';
+  return null;
+}
+

package/src/redirects.js

@@ -231,16 +231,27 @@ const ALLOWED_STATUS = new Set([301, 302, 303, 307, 308]);
  * @returns {Array<{ pattern: URLPattern, destination: string, status: number }>}
  */
 export function compileRedirectRules(pkg) {
-  const raw =
-    pkg &&
-    typeof pkg === 'object' &&
-    /** @type {any} */ (pkg).webjs &&
-    /** @type {any} */ (pkg).webjs.redirects;
-  if (!Array.isArray(raw)) return [];
+  // Read the block explicitly, not off an `&&` chain, for the reason spelled
+  // out in `headers.js`: a chain short-circuits to whatever link failed, so
+  // deciding key presence from it warns about a `redirects` nobody wrote.
+  const block = pkg && typeof pkg === 'object' ? /** @type {any} */ (pkg).webjs : undefined;
+  const hasBlock = !!block && typeof block === 'object' && !Array.isArray(block);
+  const raw = hasBlock ? block.redirects : undefined;
+  if (!Array.isArray(raw)) {
+    // An ABSENT key is the default and says nothing. A PRESENT one of the wrong
+    // type discards the whole config, so it says so, matching `headers.js`.
+    // Nothing else reports it: the schema types this key `array` and the boot
+    // config check inspects only scalar leaves.
+    if (hasBlock && 'redirects' in block) warnDrop('redirects must be an array', raw);
+    return [];
+  }
   /** @type {Array<{ pattern: URLPattern, destination: string, status: number }>} */
   const rules = [];
   for (const entry of raw) {
-    if (!entry || typeof entry !== 'object') continue;
+    if (!entry || typeof entry !== 'object') {
+      warnDrop('entry must be an object', entry);
+      continue;
+    }
     const source = /** @type {any} */ (entry).source;
     const destination = /** @type {any} */ (entry).destination;
     if (typeof source !== 'string' || !source) {
@@ -294,7 +305,7 @@ function resolveStatus(entry) {
 /** @param {string} reason @param {unknown} entry */
 function warnDrop(reason, entry) {
   // eslint-disable-next-line no-console
-  console.warn(`[webjs] dropping invalid webjs.redirects entry (${reason}):`, entry);
+  console.warn(`[webjs] dropping invalid webjs.redirects config (${reason}):`, entry);
 }
 
 /**

package/src/ssr.js

@@ -1360,6 +1360,54 @@ let _clientRouterEnabled = true;
 export function setClientRouterEnabled(enabled) { _clientRouterEnabled = enabled !== false; }
 function clientRouterEnabled() { return _clientRouterEnabled; }
 
+// 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 above, 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.
+/** @type {{ icon: boolean, apple: boolean }} */
+let _metadataIconRoutes = { icon: false, apple: false };
+
+/**
+ * Record the icon metadata routes the app defines.
+ *
+ * @param {Iterable<{ stem: 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 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
+ * SERVED: the listener strips the base path before matching, so under
+ * `webjs.basePath` the route answers at `<basePath>/icon`. 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}
+ */
+function autoMetadataRouteIcons() {
+  const { icon, apple } = _metadataIconRoutes;
+  if (!icon && !apple) return null;
+  const bp = basePath();
+  /** @type {{ icon?: string, apple?: string }} */
+  const out = {};
+  if (icon) out.icon = withBasePath('/icon', bp);
+  if (apple) out.apple = withBasePath('/apple-icon', bp);
+  return out;
+}
+
 function wrapHead(opts) {
   // CSP nonce: if provided, all inline <script> tags get nonce="…" so they
   // pass strict Content-Security-Policy headers. The nonce is extracted from
@@ -1837,10 +1885,21 @@ function wrapHead(opts) {
   //   - apple   → <link rel="apple-touch-icon">
   //   - shortcut→ <link rel="shortcut icon">
   //   - other   → <link rel="…" href="…"> using the entry's `rel` field
-  if (m.icons) {
-    const buckets = typeof m.icons === 'string' || Array.isArray(m.icons)
-      ? { icon: m.icons }
-      : m.icons;
+  //
+  // With no `icons` declared, an `app/icon.*` / `app/apple-icon.*` metadata
+  // ROUTE is linked automatically (Next parity). Those routes served their
+  // bytes and nothing referenced them before, so writing the file that every
+  // other framework treats as "this is my favicon" produced a blank tab and no
+  // diagnostic. A declared `icons` SUPPRESSES the routes rather than merging
+  // with them, which is also what Next does: it merges static icon files only
+  // when the resolved metadata has no `icons` of its own. Suppressing matters
+  // here because the file is frequently a placeholder an app has outgrown, and
+  // an author who names their icons has said which ones they want.
+  const declaredOrRouteIcons = m.icons || autoMetadataRouteIcons();
+  if (declaredOrRouteIcons) {
+    const buckets = typeof declaredOrRouteIcons === 'string' || Array.isArray(declaredOrRouteIcons)
+      ? { icon: declaredOrRouteIcons }
+      : declaredOrRouteIcons;
     /** @param {string} rel @param {unknown} entry */
     const pushIcon = (rel, entry) => {
       if (!entry) return;

package/src/webjs-config-validate.js

@@ -0,0 +1,123 @@
+/**
+ * Boot-time validation of the app's `webjs` package.json block (#1300).
+ *
+ * `webjs-config.schema.json` used to reach users through exactly one wire, the
+ * scaffold's `.vscode/settings.json` `$ref`, so a typo'd key was caught only for
+ * a VS Code user with `package.json` open. Everywhere else the key was silently
+ * dropped and the feature stayed at its default with no diagnostic, which is the
+ * exact gap the `WebjsConfig` type's own docblock claims to close.
+ *
+ * The validator now also runs at boot, from `createRequestHandler`, so `webjs
+ * dev`, `webjs start`, and an embedded host all get it from one call site.
+ *
+ * IT WARNS, NEVER THROWS. A typo costs one feature sitting at its default; a
+ * hard boot failure over a schema quibble costs the whole app, on a deploy, at
+ * the worst possible moment. That is also Next's posture (unknown and invalid
+ * options warn and the boot continues, only required or migrated options are
+ * fatal), and WebJs has no required keys at all since every one is optional with
+ * a default.
+ *
+ * This is deliberately SEPARATE from `readDoctorPolicy`'s hand-written
+ * `webjs.doctor.gate` validation in the CLI (#1257), which stays. That one runs
+ * where `@webjsdev/server` may not resolve (#954), checks gate keys against the
+ * real `DOCTOR_CODES` set (membership this schema cannot express), and fails
+ * CLOSED because a silently-ignored gate leaves CI un-gated while the
+ * package.json looks gated. One function cannot honour both failure modes, so
+ * do not "clean up" the apparent duplication.
+ *
+ * Depth stays at the top level on purpose: key membership, `enum`, and
+ * `boolean` / `integer` leaves. Descending into nested objects would have to
+ * reckon with the free-form `headers`, `redirects`, and `csp` shapes, which is a
+ * behaviour change of its own with real false-positive risk, so `webjs.dev.beforee`
+ * stays uncaught for now.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * A tiny structural validator standing in for ajv (which the repo does not
+ * ship). It checks exactly three things and no others: key membership under
+ * `additionalProperties: false`, `enum` membership, and the `boolean` /
+ * `integer` leaf types.
+ *
+ * So a value is type-checked only when its schema declares `type: "boolean"` or
+ * `type: "integer"`, or an `enum`. Today that is 9 of the 17 top-level keys; the
+ * other 8 (`headers`, `redirects`, `allowedOrigins`, `basePath`, `csp`, `dev`,
+ * `start`, `doctor`) pass whatever they hold, `csp` because its schema is a
+ * `oneOf` with no `type` at all and the rest because theirs is `array`,
+ * `string`, or `object`. That is enough for the case this exists to close, a
+ * typo'd top-level key silently dropped, plus the leaf kinds a schema can decide
+ * unambiguously.
+ *
+ * Describe this by what it checks. Do not describe it by what a reader does
+ * with a value this passes over, which varies per reader and per branch within
+ * one reader and is wrong somewhere as soon as it is summarized.
+ *
+ * @param {Record<string, unknown>} schema the webjs-block schema
+ * @param {Record<string, unknown>} value a candidate `webjs` object
+ * @returns {string[]} a list of validation errors (empty = valid)
+ */
+export function validateWebjsBlock(schema, value) {
+  /** @type {string[]} */
+  const errors = [];
+  const props = schema.properties || {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (schema.additionalProperties === false && !(key in props)) {
+      errors.push(`unknown key "${key}"`);
+      continue;
+    }
+    const def = /** @type {any} */ (props[key]);
+    if (!def) continue;
+    if (def.enum && !def.enum.includes(raw)) {
+      errors.push(`"${key}" must be one of ${JSON.stringify(def.enum)}`);
+    }
+    if (def.type === 'boolean' && typeof raw !== 'boolean') {
+      errors.push(`"${key}" must be a boolean`);
+    }
+    if (def.type === 'integer' && !Number.isInteger(raw)) {
+      errors.push(`"${key}" must be an integer`);
+    }
+  }
+  return errors;
+}
+
+/** @type {Record<string, unknown> | null} */
+let cachedSchema = null;
+
+/**
+ * Load the published `webjs-config.schema.json` that sits at this package's
+ * root. Memoized for the process lifetime, since it ships inside the tarball and
+ * cannot change under a running server. An unreadable or unparseable schema
+ * yields `null`, which makes validation a no-op rather than a boot failure.
+ *
+ * @returns {Record<string, unknown> | null}
+ */
+function loadSchema() {
+  if (cachedSchema) return cachedSchema;
+  try {
+    const path = fileURLToPath(new URL('../webjs-config.schema.json', import.meta.url));
+    cachedSchema = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  return cachedSchema;
+}
+
+/**
+ * Validate the `webjs` block of a parsed package.json against the published
+ * schema.
+ *
+ * Returns `[]` for an app with no `webjs` block and for one whose `webjs` is not
+ * a plain object, since neither is a typo this can usefully report and the
+ * readers already treat both as "unconfigured".
+ *
+ * @param {unknown} pkg a parsed package.json (or anything)
+ * @returns {string[]} one message per problem (empty = nothing to say)
+ */
+export function validateAppWebjsConfig(pkg) {
+  const block = /** @type {any} */ (pkg)?.webjs;
+  if (!block || typeof block !== 'object' || Array.isArray(block)) return [];
+  const schema = loadSchema();
+  if (!schema) return [];
+  return validateWebjsBlock(schema, block);
+}