@webjsdev/core 0.7.45 → 0.7.47

package/src/router-client.js

@@ -14,6 +14,10 @@ import './webjs-suspense.js';
 // Ingest SSR action seeds (#472) from an incoming soft-nav document before its
 // components hydrate, so a navigated async component resolves from the seed.
 import { scanSeeds } from './action-seed-client.js';
+// A form-bound action's `invalidates` tags (#1155) ride the submission response
+// the same way an RPC mutation's do, so a cached GET action is not served stale
+// after a no-JS-shaped write went through the router.
+import { markStale, parseTagHeader } from './action-cache-client.js';
 // Slot-runtime constants for re-projecting page-authored slotted content of a
 // reused hydrated light-DOM component across a soft nav (#908).
 import {
@@ -341,6 +345,11 @@ export function enableClientRouter() {
   // Seed the "current page" tracker so the first navigation can
   // snapshot the page the user is leaving.
   if (typeof location !== 'undefined') currentPageUrl = location.href;
+  // Last, once the listeners are on: report whether the load that got us here
+  // was a same-origin navigation the router never saw (#1118). Running it after
+  // the listeners means a throw inside a diagnostic can never leave the router
+  // half-installed.
+  reportPreBootNavigation();
 }
 
 /** Disable the client router. */
@@ -373,7 +382,9 @@ export function disableClientRouter() {
 export async function navigate(url, opts) {
   const target = new URL(url, location.href);
   if (target.origin !== location.origin) {
-    location.href = url;
+    // Cross-origin: an intentional full-page nav, not a degradation, but it
+    // ends the session in a test just the same, so it rides the same seam.
+    hardNavigate(url);
     return;
   }
   await performNavigation(target.href, opts?.replace ?? false, null);
@@ -471,6 +482,28 @@ export function revalidate(url) {
  */
 const NON_HTML_EXTENSIONS = /\.(?:pdf|zip|tar|gz|7z|rar|dmg|exe|msi|deb|rpm|apk|ipa|xlsx?|docx?|pptx?|csv|odt|ods|odp|rtf|epub|mobi|xml|json|rss|atom|txt|md|wasm|mp3|mp4|mov|avi|webm|ogg|flac|wav|m4a|m4v|mkv|png|jpe?g|gif|webp|avif|bmp|ico|svg|tiff?|heic)$/i;
 
+/**
+ * The one place the router hands a navigation back to the browser.
+ *
+ * Every hard navigation the router performs goes through here rather than
+ * assigning `location.href` inline, so a browser test can observe it. The
+ * default is exactly the assignment it replaces, so behaviour is unchanged
+ * unless something calls `setHardNavigate`.
+ *
+ * This exists because a hard navigation is UNOBSERVABLE and UNPREVENTABLE from
+ * outside. `preventDefault` cancels a default action, not a script assignment,
+ * and `location.href` is non-configurable on Chromium, Firefox, and WebKit
+ * alike, so a test cannot redefine its setter either (measured; the older
+ * `spyOnReload` helper that tried was silently a no-op on every engine). In a
+ * web-test-runner session a real navigation aborts the WHOLE session, so one
+ * degradation destroys every remaining browser test file and reports `0 failed`
+ * on the way out. A seam is the only thing that makes it catchable.
+ *
+ * @param {string} href
+ */
+let hardNavigate = (href) => { location.href = href; };
+
+
 /** @param {MouseEvent} e */
 function onClick(e) {
   if (!enabled) return;
@@ -763,6 +796,105 @@ function shouldFullLoadDuringParse(isPopState, frameId) {
   );
 }
 
+/**
+ * `sessionStorage` key holding the destination of a full load the ROUTER
+ * itself chose (#1118). Written by `reportFallback` when `willReload` is true,
+ * consumed once by the next document's boot. Per-tab and cleared with the tab,
+ * which is the right lifetime for a marker about one navigation.
+ */
+const FALLBACK_MARKER_KEY = 'webjs:nav-fallback';
+
+/**
+ * Has the pre-boot check already run for THIS document (#1118)? Module scope,
+ * so it resets with the document, which is the lifetime the report is about.
+ */
+let reportedPreBoot = false;
+
+/**
+ * Was THIS document load a same-origin navigation the client router never saw?
+ *
+ * Pure so the branch logic is testable without driving a real navigation
+ * (#1118). Every argument is read from the environment by the one caller.
+ *
+ * @param {string} navType `performance.getEntriesByType('navigation')[0].type`.
+ *   Only `'navigate'` qualifies: a `'reload'` and a `'back_forward'` restore are
+ *   things the browser does, not clicks the router could have intercepted.
+ * @param {string} referrer `document.referrer`. Must parse to the same origin as
+ *   `href`: an empty referrer means a typed URL or an external entry (no router
+ *   was running to miss the click), and a cross-origin one means the previous
+ *   page was not ours.
+ * @param {string} href `location.href` of the document that just loaded.
+ * @param {string | null} marker the consumed `FALLBACK_MARKER_KEY` value. When
+ *   it equals `href` the router already reported this load under its own cause,
+ *   so counting it again would double-count a known degradation as an unknown.
+ * @returns {boolean}
+ */
+function isPreBootNavigation(navType, referrer, href, marker) {
+  if (navType !== 'navigate') return false;
+  if (!referrer) return false;
+  if (marker && marker === href) return false;
+  try {
+    return new URL(referrer).origin === new URL(href).origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Report a document load that reached us by a same-origin navigation the router
+ * did not soft-navigate (#1118).
+ *
+ * A module script is deferred by spec, so it runs only after HTML parsing
+ * completes, while the links it will intercept are clickable from first paint.
+ * That window cannot be closed from inside the router (see #1118 for why an
+ * inline capture shim was rejected), so it is MEASURED instead: this turns the
+ * frequency into a production number a deployed app can read off the existing
+ * `webjs:navigation-fallback` channel, rather than folklore.
+ *
+ * Deliberately imprecise, and the docs say so: a `data-no-router` link, a
+ * cross-document form post, and an app that opted out of the client router all
+ * land here too. The signal is the RATE, not any single event.
+ *
+ * `willReload` is false because the document load has already happened. That is
+ * exactly the distinction the flag was added for.
+ */
+function reportPreBootNavigation() {
+  // Same guard the scroll/current-page seeding above uses: a DOM shim without a
+  // `location` (linkedom under the unit runner) is not a document load to
+  // report on, and reading through would throw inside the boot.
+  if (typeof location === 'undefined') return;
+  // Once per DOCUMENT, not once per enable. `enableClientRouter` is re-callable
+  // after `disableClientRouter()` (the documented per-moment opt-out), and this
+  // reports on the load that produced the document, which does not happen again
+  // when the router is toggled back on. Without this, an app that toggles would
+  // emit a duplicate for a single load and inflate the very rate the report
+  // exists to measure. The marker is already consumed by then, so it cannot
+  // suppress the duplicate on its own.
+  if (reportedPreBoot) return;
+  reportedPreBoot = true;
+  /** @type {string | null} */
+  let marker = null;
+  try {
+    marker = sessionStorage.getItem(FALLBACK_MARKER_KEY);
+    // Consume unconditionally, even when it does not match: a stale marker left
+    // by an earlier navigation must never suppress a later real one.
+    sessionStorage.removeItem(FALLBACK_MARKER_KEY);
+  } catch {
+    // No marker available. Treated as absent, which can only over-report.
+  }
+  let navType = '';
+  try {
+    const nav = performance.getEntriesByType('navigation')[0];
+    navType = nav ? /** @type {PerformanceNavigationTiming} */ (nav).type : '';
+  } catch {
+    // No Navigation Timing Level 2 entry. Without a nav type the check cannot
+    // exclude a reload, so it reports nothing rather than guessing.
+  }
+  if (isPreBootNavigation(navType, document.referrer, location.href, marker)) {
+    reportFallback('pre-boot-navigation', location.href, false);
+  }
+}
+
 /**
  * The client router degraded a soft navigation. Records WHY (the `cause`), so
  * "why did my SPA nav do a full reload?" is answerable instead of guessed at.
@@ -796,6 +928,21 @@ function shouldFullLoadDuringParse(isPopState, frameId) {
  *   dropped", which are very different user-visible events.
  */
 function reportFallback(cause, href, willReload = true) {
+  if (willReload) {
+    // Leave a marker naming the destination this full load is going to
+    // (#1118). The next document's boot reads it to tell "the router itself
+    // chose this full load, and already reported it under its own cause" from
+    // "a same-origin navigation the router never saw", which is the pre-boot
+    // click window. Best-effort: `sessionStorage` throws in some privacy modes
+    // and partitioned contexts, and a diagnostic must never break a navigation.
+    try {
+      sessionStorage.setItem(FALLBACK_MARKER_KEY, href);
+    } catch {
+      // Without the marker the next boot may attribute this load to the
+      // pre-boot window. That is a false positive in a diagnostic, which is
+      // strictly better than a thrown navigation.
+    }
+  }
   if (typeof document !== 'undefined' && typeof CustomEvent !== 'undefined') {
     try {
       document.dispatchEvent(new CustomEvent('webjs:navigation-fallback', {
@@ -1177,7 +1324,7 @@ async function performNavigation(href, isPopState, frameId) {
   // nav carries its own boundary element.
   if (shouldFullLoadDuringParse(isPopState, frameId) && typeof location !== 'undefined') {
     reportFallback('readyState-loading', href);
-    location.href = href;
+    hardNavigate(href);
     return;
   }
 
@@ -1674,7 +1821,16 @@ function prefetch(href) {
   const headers = { 'x-webjs-router': '1', 'x-webjs-prefetch': '1' };
   if (have) headers['x-webjs-have'] = have;
 
-  fetch(href, { method: 'GET', headers, credentials: 'same-origin' })
+  // `no-cache` (revalidate, NOT bypass) is load-bearing (#1131): the deploy
+  // check below reads x-webjs-build / x-webjs-src off this response, and a
+  // page served with a browser max-age would otherwise satisfy the fetch
+  // wholly from the HTTP cache, replaying pre-deploy ids. The check would then
+  // compare two equally stale values and skip the eviction, so a deploy stayed
+  // invisible for the whole freshness window plus one stale-while-revalidate
+  // serving per URL. With stable page ETags a forced revalidation is a
+  // conditional request answered 304, so the cost is a header round-trip, not
+  // a re-download.
+  fetch(href, { method: 'GET', headers, credentials: 'same-origin', cache: 'no-cache' })
     .then(async (resp) => {
       const ctype = resp.headers.get('content-type') || '';
       if (!/^text\/html\b/i.test(ctype)) return;
@@ -2069,7 +2225,7 @@ function handleNavigationError(href, status, error) {
   // carries no `cause` / `willReload`, so it is not a substitute.
   if (typeof location !== 'undefined') {
     reportFallback('navigation-error-unrecoverable', href);
-    location.href = href;
+    hardNavigate(href);
   }
 }
 
@@ -2155,13 +2311,21 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     }
 
     /** @type {RequestInit} */
-    const init = { method, headers, credentials: 'same-origin' };
+    // `no-cache` for the same reason as the prefetch fetch (#1131): applySwap
+    // hard-reloads on a build change it can only see if these headers are
+    // live, not replayed from the HTTP cache.
+    const init = { method, headers, credentials: 'same-origin', cache: 'no-cache' };
     if (signal) init.signal = signal;
     if (body != null && method !== 'GET' && method !== 'HEAD') init.body = body;
 
     const resp = await fetch(href, init);
     respStatus = resp.status;
     respOk = resp.ok;
+    // `fetch` follows a 303 transparently and its headers are then unreadable,
+    // so this lands on a non-redirect response: the 422 failure re-render, or
+    // any form response that answers in place.
+    const invalidated = parseTagHeader(resp.headers.get('x-webjs-invalidate'));
+    if (invalidated.length) markStale(invalidated);
     const ctype = resp.headers.get('content-type') || '';
     const isHTML = /^text\/html\b/i.test(ctype);
     const isStream = ctype.toLowerCase().indexOf(STREAM_MIME) === 0;
@@ -2619,6 +2783,24 @@ function runWithTransition(thunk, afterFinished) {
   return Promise.resolve();
 }
 
+/**
+ * Live nodes a regraft actually moved into the incoming tree, so they
+ * survived the swap BY IDENTITY. Membership is strictly narrower than
+ * "carries `data-webjs-permanent`": the regrafts have a both-exist guard, so
+ * a permanent element arriving for the first time is a freshly imported node
+ * that was never preserved and is not in here. `reactivateScripts` reads this
+ * to decide whether a script inside a permanent element is a script the
+ * author kept alive (skip it) or one that has never run (run it).
+ *
+ * Weak and keyed by node identity, so a destroyed node drops out on its own
+ * and a later element reusing the same `#id` is a different object that
+ * correctly re-runs. Never cleared per navigation: a node preserved across
+ * several navigations must keep its exemption on every one of them.
+ *
+ * @type {WeakSet<Element>}
+ */
+const regraftedPermanents = new WeakSet();
+
 /**
  * Persist `data-webjs-permanent` elements across a swap by NODE IDENTITY.
  *
@@ -2672,6 +2854,7 @@ function regraftPermanentElements(currentRoot, incomingRoot) {
     // incoming placeholder. The swap then adopts the live node.
     if (placeholder === live) continue;
     parent.replaceChild(live, placeholder);
+    regraftedPermanents.add(live);
   }
 }
 
@@ -2714,12 +2897,16 @@ function regraftPermanentInSlice(liveSlice, incomingSlice) {
     const parent = placeholder.parentNode;
     if (parent) {
       parent.replaceChild(live, placeholder);
+      regraftedPermanents.add(live);
     } else {
       // Placeholder is a top-level slice member with no parent (detached):
       // replace it in the incomingSlice array so the reconciler inserts the
       // live node in that position.
       const idx = incomingSlice.indexOf(placeholder);
-      if (idx !== -1) incomingSlice[idx] = live;
+      if (idx !== -1) {
+        incomingSlice[idx] = live;
+        regraftedPermanents.add(live);
+      }
     }
   }
 }
@@ -2889,14 +3076,14 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc)
         } else {
           if (sessionStorage) sessionStorage.setItem(flag, '1');
           reportFallback('deploy-mismatch', href);
-          location.href = href;
+          hardNavigate(href);
           return;
         }
       } catch {
         // sessionStorage unavailable (private mode w/ quota etc.):
         // fall through to a single reload like before.
         reportFallback('deploy-mismatch', href);
-        location.href = href;
+        hardNavigate(href);
         return;
       }
     } else if (!mismatch) {
@@ -3034,7 +3221,7 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc)
     reportFallback(!here ? 'live-boundaries-malformed'
       : !there ? 'incoming-boundaries-malformed'
       : 'no-shared-boundary', href);
-    location.href = href;
+    hardNavigate(href);
     return;
   }
 
@@ -3130,12 +3317,7 @@ function replaceBoundaryRange(target, source) {
   for (const n of incomingSlice) {
     liveParent.insertBefore(n, target.end);
   }
-  for (let n = target.start.nextSibling; n && n !== target.end; n = n.nextSibling) {
-    if (n.nodeType === 1) {
-      reactivateScripts(/** @type {Element} */ (n));
-      upgradeCustomElements(/** @type {Element} */ (n));
-    }
-  }
+  activateSwappedRange(target);
 }
 
 /**
@@ -3188,13 +3370,13 @@ function swapMarkerRange(target, source, _doc) {
   // Run the keyed diff.
   reconcileSiblings(liveParent, target.start, target.end, liveSlice, incomingSlice);
 
-  // Upgrade + activate scripts in the just-swapped range.
-  for (let n = target.start.nextSibling; n && n !== target.end; n = n.nextSibling) {
-    if (n.nodeType === 1) {
-      reactivateScripts(/** @type {Element} */ (n));
-      upgradeCustomElements(/** @type {Element} */ (n));
-    }
-  }
+  // Upgrade + activate scripts in the just-swapped range. A top-level script
+  // here is usually one the keyed reconciler REUSED (`keyOf` reads
+  // `data-key || id`), so it re-executes on every soft nav that morphs this
+  // boundary. That is deliberate: a descendant script inside a reused
+  // container has always re-run through this same pass, and a script's
+  // position in the range is not a reason to treat it differently (#1102).
+  activateSwappedRange(target);
 }
 
 /**
@@ -4348,11 +4530,127 @@ async function streamBoundariesProgressively(reader, dec, initialBuf, isCurrent)
   }
 }
 
-/** @param {Element} container */
+/**
+ * Re-execute every `<script>` in `container`, INCLUDING `container` itself when
+ * it is one (#1102). A script parsed by `DOMParser` carries the spec's
+ * "already started" flag, so the node grafted into the live document is inert
+ * and only a fresh clone runs. `querySelectorAll` never matches the element it
+ * is called on, so a container-is-a-script was silently skipped: the two swap
+ * tiers hand this function each TOP-LEVEL node of the swapped range in turn, so
+ * a script emitted as a sibling of the content (a layout's progressive-
+ * enhancement script, the shape that surfaced this) never ran after a soft nav.
+ *
+ * Replacing the container DETACHES it, which is why both callers snapshot the
+ * range before iterating rather than walking live `nextSibling` links.
+ *
+ * `data-webjs-permanent` splits into two cases here, and the split is the whole
+ * rule (#1252):
+ *
+ *   - The marked element IS a script: NEVER exempt, however the walk reaches
+ *     it. This holds whether it arrives as the `container` or as a descendant
+ *     of one, because the regraft selector has no tag filter and will happily
+ *     preserve a `<script id data-webjs-permanent>` by identity. The exemption
+ *     below is therefore STRICT containment, never reflexive. This must not be
+ *     changed. The regrafts have a both-exist guard, so on the swap that first
+ *     mounts a route there is no live node to preserve, the inert parsed copy
+ *     is what lands, and exempting it would leave a script that runs on a cold
+ *     load and never on a soft navigation. That is precisely the #1102 failure,
+ *     reintroduced under the banner of fixing it. A script's only state is that
+ *     it ran, and re-running is the contract for everything in a swapped range.
+ *   - A script INSIDE a marked element that was ACTUALLY preserved: exempt.
+ *     The attribute means the subtree survives as the same live node, which is
+ *     what `diffElementInPlace` already implements by returning early rather
+ *     than recursing into it. Re-emitting an init script against a widget
+ *     instance the author deliberately kept alive is a double-initialization,
+ *     not a refresh.
+ *
+ * The filter keys on `regraftedPermanents` (actual preservation by identity),
+ * never on the attribute alone. A permanent element arriving for the FIRST time
+ * was never preserved, so its scripts have never run and must run now; an
+ * attribute-only filter would leave them never running on any path.
+ *
+ * @param {Element} container
+ * @returns {Element} `container`, or its replacement when it was a script that
+ *   was re-emitted. The replacement sits wherever `container` was; when
+ *   `container` was already detached, `replaceWith` is a spec no-op and the
+ *   returned clone is detached too, so callers must not assume it is connected.
+ */
 function reactivateScripts(container) {
+  if (container.tagName === 'SCRIPT') {
+    const fresh = cloneScriptWithCorrectNonce(/** @type {HTMLScriptElement} */ (container));
+    // A no-op when the node has no parent. That happens when an EARLIER
+    // script's reactivation ran code that removed this node from the range
+    // (reactivation executes synchronously), so a stale snapshot entry cannot
+    // resurrect itself into the document.
+    container.replaceWith(fresh);
+    return fresh;
+  }
+  // Roots whose subtrees survived this swap by identity. Collected from the
+  // container DOWNWARD so the exemption is bounded to the swapped range by
+  // construction; `closest()` from a script upward could escape into an outer
+  // ancestor that was never part of this swap.
+  /** @type {Element[]} */
+  const preserved = [];
+  if (regraftedPermanents.has(container)) preserved.push(container);
+  for (const el of container.querySelectorAll('[data-webjs-permanent]')) {
+    if (regraftedPermanents.has(el)) preserved.push(el);
+  }
+
   for (const old of container.querySelectorAll('script')) {
+    // STRICT containment: a preserved root exempts its DESCENDANTS, never
+    // itself. The regrafts select `[data-webjs-permanent][id]` with no tag
+    // filter, so a `<script id data-webjs-permanent>` present on both sides is
+    // regrafted like any other element and lands in the WeakSet. Skipping it
+    // here would exempt the marked script itself whenever the walk reaches it
+    // as a descendant (the full-body path), while the container branch above
+    // still re-emits it, so one script would get opposite answers depending on
+    // which entry point reached it. `contains()` is reflexive, hence `p !== old`.
+    if (preserved.length && preserved.some((p) => p !== old && p.contains(old))) continue;
     old.replaceWith(cloneScriptWithCorrectNonce(/** @type {HTMLScriptElement} */ (old)));
   }
+  return container;
+}
+
+/**
+ * Reactivate scripts + upgrade custom elements across a just-swapped boundary
+ * range. The range is SNAPSHOT first: `reactivateScripts` replaces a top-level
+ * script node, which detaches it and cuts a live `nextSibling` walk, silently
+ * skipping every node after it (#1102).
+ *
+ * The snapshot is taken AFTER the tier has finished writing the range (the
+ * replace tier's insert loop, the morph tier's `reconcileSiblings`), so every
+ * entry is attached when it is recorded. It can still go stale DURING the walk,
+ * because reactivating a script executes it synchronously and that code may
+ * mutate the range. Two consequences, both deliberate. A node an earlier script
+ * REMOVED is skipped, since `replaceWith` on a parentless node is a spec no-op.
+ * A node an earlier script INSERTED is not visited, unlike the live walk this
+ * replaced. That costs nothing reachable: such a node is connected by
+ * definition, so the browser upgrades it on insertion, and `ensureUpgradeObserver`
+ * catches it on the microtask regardless. Do NOT "restore" the live walk to
+ * recover it. A correct live walk has to advance off the REPLACEMENT (advancing
+ * off the detached original is bug #1102 itself), and in that form a script
+ * appending a sibling script loops forever, each clone appending the next; it
+ * would also re-run a script that already executed when its own creator
+ * inserted it. The snapshot is additionally safer under a MOVE, since a live
+ * walk would follow a node out of the range and start re-executing unrelated
+ * scripts in the rest of the body.
+ *
+ * @param {{ start: Comment, end: Comment }} range
+ */
+function activateSwappedRange(range) {
+  /** @type {Element[]} */
+  const swapped = [];
+  for (let n = range.start.nextSibling; n && n !== range.end; n = n.nextSibling) {
+    if (n.nodeType === 1) swapped.push(/** @type {Element} */ (n));
+  }
+  for (const el of swapped) {
+    const live = reactivateScripts(el);
+    // Nothing to upgrade in a detached tree. `customElements.upgrade` off
+    // document runs the CONSTRUCTOR (not `connectedCallback`, which waits for
+    // insertion), so this skips constructing elements for a tree that was just
+    // removed and will never be seen.
+    if (live.isConnected !== false) upgradeCustomElements(live);
+  }
 }
 
 /* ====================================================================
@@ -4363,6 +4661,9 @@ export {
   addNewHeadElements as _addNewHeadElements,
   mergeHead as _mergeHead,
   reactivateScripts as _reactivateScripts,
+  isPreBootNavigation as _isPreBootNavigation,
+  FALLBACK_MARKER_KEY as _FALLBACK_MARKER_KEY,
+  activateSwappedRange as _activateSwappedRange,
   findAnchorInPath as _findAnchorInPath,
   activeFrameId as _activeFrameId,
   resolveTargetFrameId as _resolveTargetFrameId,
@@ -4423,6 +4724,20 @@ export function _resetPrefetch() {
   clearPrefetchViewTimers();
 }
 
+/**
+ * Test-only: replace the hard-navigate action so a browser test can observe a
+ * navigation instead of being destroyed by it. Call with no argument to
+ * restore. Underscore-prefixed and kept in this block like every other
+ * test-only export here, so it stays out of `router-client.d.ts` and out of
+ * the app-facing API (the `./client-router` subpath resolves this file under
+ * the `source` condition, so an unprefixed name here would read as public).
+ *
+ * @param {((href: string) => void) | null} [fn]
+ */
+export function _setHardNavigate(fn) {
+  hardNavigate = fn || ((href) => { location.href = href; });
+}
+
 /** Test-only: read the monotonic navigation-token counter. */
 export function _navToken() { return currentNavigationToken; }
 /** Test-only: bump the navigation-token counter (simulates a fresh nav). */

package/src/webjs-config.d.ts

@@ -7,22 +7,18 @@
  *     import type { WebjsConfig } from '@webjsdev/core';
  *     const config: WebjsConfig = { trailingSlash: 'never', csp: true };
  *
- * The server reads this object key by key. Without a type or schema a
- * typo'd key (e.g. `redirect` for `redirects`) was silently dropped and
- * the feature stayed at its default with no diagnostic. This type plus
- * the published JSON Schema close that gap.
+ * This object is read key by key, mostly by the server and for a few keys
+ * by the CLI. Without a type or schema a typo'd key (e.g. `redirect` for
+ * `redirects`) was silently dropped and the feature stayed at its default
+ * with no diagnostic. This type plus the published JSON Schema close that
+ * gap.
  *
  * LOCKSTEP: this file, the JSON Schema at
- * packages/server/webjs-config.schema.json, and the server reader
- * functions MUST stay in sync. The readers are: readElideEnabled
- * (dev.js, elide), readSeedEnabled (dev.js, seed), readClientRouterEnabled
- * (dev.js, clientRouter), compileHeaderRules (headers.js, headers),
- * compileRedirectRules / readTrailingSlashPolicy (redirects.js,
- * redirects / trailingSlash), readBasePath (base-path.js, basePath),
- * readCspConfig (csp.js, csp), and
- * readBodyLimits / computeServerTimeouts (body-limit.js, the byte caps
- * and timeouts). Adding a `webjs.*` key means updating all three places.
- * See packages/server/AGENTS.md for the one documented procedure.
+ * packages/server/webjs-config.schema.json, and the reader functions MUST
+ * stay in sync, so adding a `webjs.*` key means updating all three places
+ * (plus the KNOWN_KEYS drift test). The reader inventory is NOT repeated
+ * here on purpose: packages/server/AGENTS.md holds the one canonical list
+ * along with the procedure, and every copy of it that existed drifted.
  *
  * Every key is optional (the whole block is optional and every key has a
  * default). Zero runtime cost: nothing in this file ships to the browser.
@@ -91,18 +87,19 @@ export interface WebjsRegenerateRule {
   inputs?: string[];
 }
 
-/** Dev task orchestration in `webjs.dev` (#550). `before`/`parallel` read by the CLI, `regenerate` by the server. */
+/** Dev task orchestration in `webjs.dev` (#550). `before`/`parallel` read by the CLI, `regenerate` and `watch` by the server (each sub-key names its own reader below). */
 export interface WebjsDevTasks {
   /**
    * One-shot commands run sequentially to completion BEFORE the dev server
    * boots (the old `predev` hook: `webjs db migrate`, a registry copy). A
-   * non-zero exit aborts the boot.
+   * non-zero exit aborts the boot. Read by the CLI (`readAppTasks`).
    */
   before?: string[];
   /**
    * Long-lived commands run as child processes ALONGSIDE the dev server (the
    * old `concurrently` watchers). Spawned once in the parent and torn down on
-   * exit, so a watcher cannot leak past the server.
+   * exit, so a watcher cannot leak past the server. Read by the CLI
+   * (`readAppTasks`).
    */
   parallel?: string[];
   /**
@@ -136,6 +133,34 @@ export interface WebjsStartTasks {
   before?: string[];
 }
 
+/**
+ * A severity a `webjs.doctor.gate` entry may declare, mirroring ESLint's
+ * three-level scale. `error` fails the `webjs doctor` exit, `warn` reports
+ * without failing, and `off` silences the check: its finding is not printed and
+ * it cannot fail the exit, including under `--strict`. A silenced check still
+ * appears on the checklist as `[off]` and in the summary's silenced count, and
+ * `--json` still carries its whole result.
+ */
+export type WebjsDoctorSeverity = 'off' | 'warn' | 'error';
+
+/** The object form of `webjs.doctor` (#1257). */
+export interface WebjsDoctorConfig {
+  /**
+   * Per-check severity, keyed by the stable doctor code (`NODE_VERSION`,
+   * `UNMARKED_ASSET_LINKS`, `ELISION_CARRIERS`, and so on; `webjs doctor --json`
+   * carries the code on every result). A code with no entry keeps its default:
+   * `error` for a hard toolchain failure, `warn` otherwise. This is how CI gates
+   * on a chosen subset without `--strict` making every warning fatal.
+   *
+   * A malformed gate is a hard error, so a typo cannot silently un-gate CI:
+   * that covers an unknown code, a bad severity, a wrong SHAPE (a non-object
+   * `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`.
+   * A result that could not check (a network or toolchain outage) is capped at
+   * `warn` and can never be escalated to `error`.
+   */
+  gate?: Record<string, WebjsDoctorSeverity>;
+}
+
 /** The object form of `webjs.csp` (the non-boolean shape). */
 export interface WebjsCspConfig {
   /**
@@ -191,6 +216,13 @@ export interface WebjsConfig {
   dev?: WebjsDevTasks;
   start?: WebjsStartTasks;
 
+  /**
+   * `webjs doctor` policy (#1257): which project-health checks the project
+   * treats as fatal. Read by the CLI (`packages/cli/lib/doctor.js`), NOT the
+   * server readers.
+   */
+  doctor?: WebjsDoctorConfig;
+
   /** Per-path response-header rules, shaped like Next's. */
   headers?: WebjsHeaderRule[];