@webjsdev/core 0.7.21 → 0.7.23

package/src/router-client.js

@@ -27,11 +27,11 @@ const STREAM_MIME = 'text/vnd.webjs-stream.html';
  * children of that boundary. Outer layout DOM (header, sidenav, footer)
  * stays mounted: no re-render, no flicker, scroll positions preserved.
  *
- * To enable, import this module from a layout or boot script:
- *
- *   import '@webjsdev/core/client-router';
- *
- * Or call `enableClientRouter()` for programmatic control.
+ * Enablement is automatic: this module calls `enableClientRouter()` at its
+ * end (idempotent), and the `@webjsdev/core` browser entry loads it, so any
+ * page that ships a component gets the router with no import to add. Call
+ * `disableClientRouter()` to opt out, or `enableClientRouter()` for
+ * programmatic control.
  *
  * Mechanism: auto-derived from folder structure:
  *   1. SSR injects `<!--wj:children:<segment-path>-->...<!--/wj:children-->`
@@ -220,6 +220,7 @@ export function disableClientRouter() {
   document.removeEventListener('pointerout', onPrefetchOut, true);
   document.removeEventListener('webjs:navigate', refreshPrefetchObservers);
   clearPrefetchHover();
+  clearPrefetchViewTimers();
   if (prefetchViewObserver) { prefetchViewObserver.disconnect(); prefetchViewObserver = null; }
   if (typeof history !== 'undefined' && prevScrollRestoration !== null) {
     history.scrollRestoration = prevScrollRestoration;
@@ -605,6 +606,64 @@ function warnOnce(key, message) {
   if (typeof console !== 'undefined' && console.warn) console.warn(message);
 }
 
+/**
+ * Dev-only, fire-once hint: the router forces an INSTANT scroll-to-top on a
+ * forward navigation (matching a native page load), so an app-level
+ * `scroll-behavior: smooth` on <html> does not affect route transitions (it
+ * still applies to in-page #anchor links via `scrollIntoView`). A developer
+ * who set smooth expecting smooth nav scrolling would otherwise be puzzled.
+ * Also flags the iOS sticky-`backdrop-filter` flash this combination can
+ * cause (#610). Never warns in production, never throws.
+ *
+ * The `smoothScrollChecked` flag gates the `getComputedStyle` read (a forced
+ * style flush) to AT MOST ONCE per page, so a dev session does not pay a
+ * per-navigation reflow after the first forward nav.
+ */
+let smoothScrollChecked = false;
+function warnIfSmoothScrollOnHtml() {
+  if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production') return;
+  if (smoothScrollChecked) return;
+  if (typeof document === 'undefined' || typeof getComputedStyle !== 'function') return;
+  const root = document.documentElement;
+  if (!root) return;
+  smoothScrollChecked = true;
+  let behavior;
+  try { behavior = getComputedStyle(root).scrollBehavior; } catch { return; }
+  if (behavior !== 'smooth') return;
+  warnOnce(
+    'scroll-behavior-smooth-html',
+    '[webjs] Detected `scroll-behavior: smooth` on <html>. The client router scrolls ' +
+    'to the top instantly on navigation (like a native page load), so route transitions ' +
+    'are not affected by it. It still applies to in-page #anchor links. Pairing it with a ' +
+    'sticky `backdrop-filter` header can also flash on iOS during navigation.'
+  );
+}
+
+/**
+ * Nav-in-flight signalling. The router can expose `data-navigating` on <html>
+ * so an app may style a loading indicator with `html[data-navigating] { … }`.
+ *
+ * This is OPT-IN, set only when the app marks `<html data-webjs-nav-progress>`.
+ * The reason it is not unconditional: toggling ANY attribute on the root
+ * re-runs global style resolution, and on WebKit (so every iOS browser, since
+ * they all use it) that re-resolves `oklch()` / `color-mix(in oklch, …)` token
+ * values to an equivalent oklab representation and repaints them for one frame.
+ * On a token-driven theme that is a visible background flash on navigation
+ * (#610). The flash only shows on a nav slow enough to reach the deferred set
+ * below, which a desktop nav rarely is but a mobile forward fetch routinely is,
+ * so the symptom is iOS-and-forward-only. With no opt-in the attribute is never
+ * written, so the re-resolution never happens and the flash cannot occur.
+ */
+function setNavigating(on) {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  if (!root || !root.hasAttribute('data-webjs-nav-progress')) return;
+  try {
+    if (on) root.setAttribute('data-navigating', '');
+    else root.removeAttribute('data-navigating');
+  } catch { /* non-DOM environment */ }
+}
+
 /* ====================================================================
  * Marker discovery (the heart of the partial-swap mechanism)
  * ==================================================================== */
@@ -771,17 +830,11 @@ async function performNavigation(href, isPopState, frameId) {
   // about to read in the popstate-restore branch below.
   if (currentPageUrl) snapshotCurrent(currentPageUrl);
 
-  // Show a subtle loading indicator, but only if the nav takes long
-  // enough to be worth showing one. Setting an attribute on <html>
-  // invalidates global style computation: which forces CSS like
-  // `color-mix(in oklch, …)` to re-resolve. For values that use
-  // wide-gamut color spaces the re-resolution can switch between
-  // equivalent representations (oklch ↔ oklab) and fire any
-  // `transition` rules listening on that property, producing a
-  // visible flash on every nav. Defer the attribute set so quick
-  // navs (sub-150ms) never set it at all.
+  // Expose the opt-in `data-navigating` loading-indicator hook (see
+  // setNavigating), but only if the nav takes long enough to be worth showing
+  // one. Deferred so quick navs (sub-150ms) never set it at all.
   let navigatingFlagTimer = setTimeout(() => {
-    document.documentElement.setAttribute('data-navigating', '');
+    setNavigating(true);
     navigatingFlagTimer = null;
   }, 150);
 
@@ -800,9 +853,11 @@ async function performNavigation(href, isPopState, frameId) {
         const cachedDoc = parseHTML(cached.html);
         if (cachedDoc) {
           applySwap(cachedDoc, frameId, /* revalidating */ true, /* href */ null);
-          // Restore window scroll to where the user left it.
+          // Restore window scroll to where the user left it. Use
+          // behavior:'instant' so an app-level `scroll-behavior: smooth`
+          // stylesheet does not animate the restore (native nav jumps).
           if (typeof window !== 'undefined') {
-            window.scrollTo(cached.scrollX, cached.scrollY);
+            window.scrollTo({ left: cached.scrollX, top: cached.scrollY, behavior: 'instant' });
           }
           // Fire-and-forget revalidation. Uses a fresh AbortController
           // since this background fetch is allowed to overlap with the
@@ -818,7 +873,7 @@ async function performNavigation(href, isPopState, frameId) {
       // on the page they popped FROM. Scroll to top as the reasonable
       // default; fetchAndApply skips its own scroll handling when
       // recordHistory=false (which is the case here).
-      if (typeof window !== 'undefined') window.scrollTo(0, 0);
+      if (typeof window !== 'undefined') window.scrollTo({ left: 0, top: 0, behavior: 'instant' });
     }
 
     await fetchAndApply(href, frameId, !isPopState, optimisticState, 'GET', null, signal, myToken);
@@ -827,7 +882,7 @@ async function performNavigation(href, isPopState, frameId) {
     // Only clear the navigating flag if WE are still the active nav.
     // A newer nav has its own flag lifecycle.
     if (myToken === currentNavigationToken) {
-      document.documentElement.removeAttribute('data-navigating');
+      setNavigating(false);
       // Record where the user is NOW so the next navigation can
       // snapshot under the right URL key.
       if (typeof location !== 'undefined') currentPageUrl = location.href;
@@ -894,7 +949,7 @@ async function performSubmission(href, method, body, frameId, form) {
   if (currentPageUrl) snapshotCurrent(currentPageUrl);
 
   let navigatingFlagTimer = setTimeout(() => {
-    document.documentElement.setAttribute('data-navigating', '');
+    setNavigating(true);
     navigatingFlagTimer = null;
   }, 150);
 
@@ -934,7 +989,7 @@ async function performSubmission(href, method, body, frameId, form) {
     if (busyForm) clearFormBusy(busyForm, myToken, url.href, outcomeOk);
     if (navigatingFlagTimer) clearTimeout(navigatingFlagTimer);
     if (myToken === currentNavigationToken) {
-      document.documentElement.removeAttribute('data-navigating');
+      setNavigating(false);
       if (typeof location !== 'undefined') currentPageUrl = location.href;
     }
   }
@@ -960,12 +1015,16 @@ function buildHaveHeader() {
  * warms a dedicated cache speculatively so the click reads it instantly.
  *
  * Strategy per anchor via a `data-prefetch` attribute (valid-HTML data-*,
- * like SvelteKit / Astro), defaulting to `intent` so the common case is
- * fast without per-link opt-in, the way Next / Nuxt / SvelteKit ship
- * auto-prefetch. Value vocabulary borrows Next's true/false/auto aliases:
- *   - intent    (default)    : hover / focus / touch, after a short dwell
+ * like SvelteKit / Astro). The default is DEVICE-ADAPTIVE so the common case
+ * is fast on every device without per-link opt-in: `intent` on a hover-capable
+ * pointer (a real head-start before the click), `viewport` on touch (no hover
+ * exists, and `touchstart` fires too close to the tap to front-run it). Value
+ * vocabulary borrows Next's true/false/auto aliases:
+ *   - absent (default)       : intent on pointer, viewport on touch (adaptive)
+ *   - intent                 : hover / focus / touch, after a short dwell
  *   - true / render          : eager, as soon as a document scan sees it
- *   - auto / viewport        : on viewport entry (IntersectionObserver, 0.5)
+ *   - auto / viewport        : on viewport entry (IntersectionObserver, 0.5),
+ *                              after a dwell so a fast scroll-through skips it
  *   - false / none           : never (also data-no-prefetch / rel="external")
  *
  * Why a separate cache, not snapshotCache: snapshotCache is keyed to the
@@ -976,7 +1035,10 @@ function buildHaveHeader() {
  * prefetchTake() before falling back to the network.
  *
  * Only same-origin in-app links are prefetched (the same eligibility as
- * a click), and never under Save-Data / prefers-reduced-data. There is no
+ * a click), and never under Save-Data / prefers-reduced-data / a 2g link,
+ * never past a small concurrency cap, and never twice (deduped + cached). The
+ * viewport path additionally waits a dwell and cancels on scroll-out, so a
+ * fast scroll through a long list does not flood the network tab. There is no
  * logout-style heuristic: prefetch issues a real GET, so as everywhere in
  * the ecosystem (Next / Nuxt / Remix), a non-idempotent action must be a
  * POST or a `<form>`, and `data-no-prefetch` / `rel="external"` opt out.
@@ -996,6 +1058,13 @@ const PREFETCH_CONCURRENCY = 3;
 const PREFETCH_QUEUE_CAP = 24;
 /** Hover dwell before a prefetch fires (ms): filter drive-by pointer moves. Matches Remix's intent timeout. */
 const PREFETCH_HOVER_DELAY = 100;
+/**
+ * Viewport dwell before a prefetch fires (ms): a link must SETTLE on-screen,
+ * not merely flash past during a scroll. A fast scroll-through clears the
+ * timer on exit, so flicked-past links never fetch. Astro uses 300ms for the
+ * same purpose; we sit a touch lower so a deliberate stop still feels instant.
+ */
+const PREFETCH_VIEWPORT_DELAY = 250;
 
 /** @typedef {{ html: string, build: string | null, finalUrl: string, at: number }} PrefetchEntry */
 /** @type {Map<string, PrefetchEntry>} */
@@ -1011,18 +1080,28 @@ let prefetchHoverTimer = null;
 let prefetchHoverAnchor = null;
 /** IntersectionObserver for data-prefetch="viewport" anchors, or null. */
 let prefetchViewObserver = null;
+/** Per-anchor viewport-dwell timers, so a scroll-out can cancel before firing. */
+let prefetchViewTimers = new WeakMap();
+/** Live viewport-dwell timer ids, for bulk teardown on disable. */
+const prefetchViewPending = new Set();
 
 /**
- * True when the user or platform has asked us to conserve data. Both the
- * Save-Data client hint and the prefers-reduced-data media query disable
- * speculative fetching. Guarded for non-browser / partial DOM.
+ * True when the user or platform has asked us to conserve data, OR the
+ * connection is too slow to spend bytes speculatively. The Save-Data client
+ * hint, the prefers-reduced-data media query, and a 2g `effectiveType` all
+ * disable speculative fetching, the same gate Astro / Nuxt apply. Guarded for
+ * non-browser / partial DOM.
  *
  * @returns {boolean}
  */
 function prefetchSaysSaveData() {
   try {
     const c = typeof navigator !== 'undefined' ? /** @type any */ (navigator).connection : null;
-    if (c && c.saveData === true) return true;
+    if (c) {
+      if (c.saveData === true) return true;
+      // effectiveType is 'slow-2g' | '2g' | '3g' | '4g'; skip the 2g tiers.
+      if (typeof c.effectiveType === 'string' && /2g$/.test(c.effectiveType)) return true;
+    }
     if (typeof matchMedia === 'function' && matchMedia('(prefers-reduced-data: reduce)').matches) {
       return true;
     }
@@ -1030,6 +1109,27 @@ function prefetchSaysSaveData() {
   return false;
 }
 
+/**
+ * Whether the device drives a hover-capable fine pointer (a mouse or
+ * trackpad), as opposed to touch. This picks the ADAPTIVE prefetch default:
+ * `intent` (hover / focus) on a pointer device, `viewport` on touch, since a
+ * touch device has no hover and `touchstart` fires too close to the tap to
+ * front-run it. Detected with `matchMedia('(hover: hover) and (pointer: fine)')`
+ * rather than a user-agent sniff. When `matchMedia` is unavailable we assume a
+ * pointer (the historical default), so a non-browser / partial-DOM environment
+ * keeps the `intent` behaviour and never silently switches to viewport.
+ *
+ * @returns {boolean}
+ */
+function prefetchHasHoverPointer() {
+  try {
+    if (typeof matchMedia === 'function') {
+      return matchMedia('(hover: hover) and (pointer: fine)').matches;
+    }
+  } catch { /* ignore */ }
+  return true;
+}
+
 /**
  * Lowercased whitespace-separated rel tokens of an anchor.
  * @param {Element} anchor
@@ -1091,12 +1191,21 @@ function prefetchSuppressed(anchor) {
  * absent or unrecognised.
  *
  * Value mapping (case-insensitive):
- *   - absent / unknown   : `intent`  (the default)
+ *   - absent / unknown   : the DEVICE-ADAPTIVE default (intent on a pointer,
+ *                          viewport on touch); an explicit value always wins
  *   - `intent`           : hover / focus / touch, after a short dwell
  *   - `true` / `render`  : eager, as soon as a document scan sees the link
- *   - `auto` / `viewport`: on viewport entry (IntersectionObserver)
+ *   - `auto` / `viewport`: on viewport entry (IntersectionObserver), after a dwell
  *   - `false` / `none`   : never (also via data-no-prefetch / rel="external")
  *
+ * The default is adaptive (not a single `intent`) because `intent` does not
+ * help on mobile: a touch device has no hover, and `touchstart` fires at tap
+ * time, so the prefetch races the navigation. On touch we default to
+ * `viewport` (warm links as they settle on-screen) and keep `touchstart` as an
+ * extra warm for the tapped link; on a pointer device `intent` stays the
+ * default (precise, cheap, a real head-start before the click). A per-link
+ * `data-prefetch` always overrides the adaptive default.
+ *
  * Returns `none` for suppressed anchors so callers have a single check.
  *
  * @param {Element} anchor
@@ -1118,8 +1227,8 @@ function prefetchMode(anchor) {
     case 'intent':
       return 'intent';
     default:
-      // Unset or unrecognised value: the fast default.
-      return 'intent';
+      // Unset or unrecognised value: the device-adaptive default.
+      return prefetchHasHoverPointer() ? 'intent' : 'viewport';
   }
 }
 
@@ -1134,6 +1243,9 @@ function prefetchMode(anchor) {
  * @param {string} href
  */
 function prefetch(href) {
+  // Never speculate once the router is torn down: a leftover hover / queue /
+  // dwell timer that fires after disableClientRouter must not issue a fetch.
+  if (!enabled) return;
   if (typeof fetch !== 'function') return;
   if (prefetchSaysSaveData()) return;
   const key = cacheKey(href);
@@ -1245,12 +1357,19 @@ function onPrefetchIntent(e) {
   if (!enabled) return;
   const anchor = closestAnchor(/** @type any */ (e.target));
   if (!anchor) return;
-  // Only `intent` links prefetch on hover/focus/touch. `render` and
-  // `viewport` links are handled by the document scan / observer, and
-  // `none` is suppressed.
-  if (prefetchMode(anchor) !== 'intent') return;
+  const mode = prefetchMode(anchor);
+  // `none` is suppressed; `render` already prefetched on the document scan.
+  if (mode === 'none' || mode === 'render') return;
   const href = eligibleAnchorHref(anchor);
   if (!href) return;
+  // touchstart IS the tap: warm the tapped link immediately, for both intent
+  // and viewport modes (a single request for a link about to be navigated, the
+  // small mobile win the viewport default cannot give for the link just tapped).
+  // No dwell, since the tap is the intent.
+  if (e.type === 'touchstart') { prefetch(href); return; }
+  // hover / focus only warm `intent` links; `viewport` links are the
+  // observer's job (warmed on a dwell, not on a stray hover).
+  if (mode !== 'intent') return;
   // pointerover/focusin bubble, so re-entering a child of the same anchor
   // would re-arm; collapse to one timer per anchor.
   if (prefetchHoverAnchor === anchor && prefetchHoverTimer) return;
@@ -1274,6 +1393,13 @@ function clearPrefetchHover() {
   prefetchHoverAnchor = null;
 }
 
+/** Cancel every pending viewport-dwell timer and reset the per-anchor map. */
+function clearPrefetchViewTimers() {
+  for (const timer of prefetchViewPending) clearTimeout(timer);
+  prefetchViewPending.clear();
+  prefetchViewTimers = new WeakMap();
+}
+
 /**
  * Nearest enclosing <a>, crossing shadow boundaries, from an event
  * target. composedPath is click-only, so walk getRootNode().host here.
@@ -1314,15 +1440,40 @@ function refreshPrefetchObservers() {
     if (!prefetchViewObserver) {
       prefetchViewObserver = new IntersectionObserver((entries) => {
         for (const entry of entries) {
-          if (!entry.isIntersecting) continue;
           const anchor = /** @type {Element} */ (entry.target);
-          prefetchViewObserver.unobserve(anchor);
-          const href = eligibleAnchorHref(anchor);
-          if (href && prefetchMode(anchor) === 'viewport') prefetch(href);
+          if (entry.isIntersecting) {
+            // Arm a dwell timer; the link must STAY on-screen to warm. One
+            // timer per anchor, so re-entry while pending does not stack.
+            if (prefetchViewTimers.has(anchor)) continue;
+            const timer = setTimeout(() => {
+              prefetchViewPending.delete(timer);
+              prefetchViewTimers.delete(anchor);
+              prefetchViewObserver.unobserve(anchor);
+              const href = eligibleAnchorHref(anchor);
+              if (href && prefetchMode(anchor) === 'viewport') prefetch(href);
+            }, PREFETCH_VIEWPORT_DELAY);
+            prefetchViewTimers.set(anchor, timer);
+            prefetchViewPending.add(timer);
+          } else {
+            // Scrolled out before the dwell elapsed: cancel, so a fast
+            // scroll-through never spends a request.
+            const timer = prefetchViewTimers.get(anchor);
+            if (timer) {
+              clearTimeout(timer);
+              prefetchViewPending.delete(timer);
+              prefetchViewTimers.delete(anchor);
+            }
+          }
         }
       }, { threshold: 0.5 });
     } else {
+      // Re-scan: drop the old observation set AND cancel any pending dwell
+      // timers, so a timer armed for an anchor the soft-nav swap removed cannot
+      // fire a prefetch for a stale URL (its exit callback never comes once it
+      // is gone). Anchors still on-screen re-arm when observe() below redelivers
+      // their current intersection state.
       prefetchViewObserver.disconnect();
+      clearPrefetchViewTimers();
     }
   }
   for (const anchor of document.querySelectorAll('a[href]')) {
@@ -1622,10 +1773,16 @@ async function fetchAndApply(href, frameId, recordHistory, optimisticState, meth
     const url = new URL(finalUrl);
     if (url.hash) {
       const t = document.getElementById(url.hash.slice(1));
+      // A hash anchor is the one nav scroll we DON'T force instant: a
+      // `#section` link is exactly where an app's `scroll-behavior: smooth`
+      // is wanted, and native browsers animate it too.
       if (t) t.scrollIntoView();
-      else window.scrollTo(0, 0);
+      else { warnIfSmoothScrollOnHtml(); window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); }
     } else {
-      window.scrollTo(0, 0);
+      // Scroll-to-top on a forward nav. behavior:'instant' so an app-level
+      // `scroll-behavior: smooth` does not animate it (match native nav).
+      warnIfSmoothScrollOnHtml();
+      window.scrollTo({ left: 0, top: 0, behavior: 'instant' });
     }
   }
 
@@ -3070,6 +3227,7 @@ export {
   regraftPermanentInSlice as _regraftPermanentInSlice,
   prefetchSuppressed as _prefetchSuppressed,
   prefetchMode as _prefetchMode,
+  prefetchHasHoverPointer as _prefetchHasHoverPointer,
   prefetch as _prefetch,
   prefetchTake as _prefetchTake,
   prefetchSaysSaveData as _prefetchSaysSaveData,
@@ -3090,6 +3248,7 @@ export function _resetPrefetch() {
   prefetchQueue.length = 0;
   prefetchQueued.clear();
   clearPrefetchHover();
+  clearPrefetchViewTimers();
 }
 
 /** Test-only: read the monotonic navigation-token counter. */
@@ -3100,6 +3259,8 @@ export function _bumpNavToken() { return ++currentNavigationToken; }
 export function _currentPageUrl() { return currentPageUrl; }
 /** Test-only: set the tracker (simulates being on a specific page). */
 export function _setCurrentPageUrl(u) { currentPageUrl = u; }
+/** Test-only: clear the fire-once warning guards so a case can be re-exercised. */
+export function _resetWarnOnce() { warnedKeys.clear(); smoothScrollChecked = false; }
 
 /**
  * Predicate used by the onClick handler to decide whether a same-origin
@@ -3112,7 +3273,13 @@ export function _isNonHtmlPath(pathname) {
   return NON_HTML_EXTENSIONS.test(pathname);
 }
 
-// Auto-enable on import (standard Turbo-Drive convention). Placed last so
-// every top-level binding the router touches (notably the prefetch state)
-// is initialised before enableClientRouter() runs.
-enableClientRouter();
+// Auto-enable on import (standard Turbo-Drive convention) UNLESS the app opted
+// out with `webjs.clientRouter: false` (#629), which the server signals by
+// setting `window.__WEBJS_CLIENT_ROUTER__ = false` in an inline script emitted
+// BEFORE this (deferred) bundle runs. On the server `window` is undefined, so
+// the call still runs and no-ops behind its own `typeof document` guard, as
+// before. Placed last so every top-level binding the router touches (notably
+// the prefetch state) is initialised before enableClientRouter() runs.
+if (typeof window === 'undefined' || window.__WEBJS_CLIENT_ROUTER__ !== false) {
+  enableClientRouter();
+}

package/src/task.js

@@ -29,9 +29,7 @@
  * import { WebComponent, html } from '@webjsdev/core';
  * import { Task } from '@webjsdev/core/task';
  *
- * class UserSearch extends WebComponent {
- *   static properties = { query: { type: String } };
- *
+ * class UserSearch extends WebComponent({ query: String }) {
  *   _search = new Task(this, {
  *     task: async (query, { signal }) => {
  *       const res = await fetch(`/api/users?q=${query}`, { signal });

package/src/webjs-config.d.ts

@@ -15,7 +15,8 @@
  * 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), compileHeaderRules (headers.js, headers),
+ * (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
@@ -80,6 +81,32 @@ export interface WebjsRedirectRule {
 /** The trailing-slash canonicalization policy in `webjs.trailingSlash`. */
 export type WebjsTrailingSlash = 'never' | 'always' | 'ignore';
 
+/** Dev task orchestration in `webjs.dev` (#550). Read by the CLI, not the server. */
+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.
+   */
+  before?: string[];
+  /**
+   * Long-lived commands run as child processes ALONGSIDE the dev server (the
+   * old `concurrently` watchers: the Tailwind CLI `--watch`). Spawned once in
+   * the parent and torn down on exit, so a watcher cannot leak past the server.
+   */
+  parallel?: string[];
+}
+
+/** Start task orchestration in `webjs.start` (#550). Read by the CLI, not the server. */
+export interface WebjsStartTasks {
+  /**
+   * One-shot commands run sequentially to completion BEFORE the prod server
+   * boots (the old `prestart` hook: `webjs db migrate`). A non-zero exit
+   * aborts the boot.
+   */
+  before?: string[];
+}
+
 /** The object form of `webjs.csp` (the non-boolean shape). */
 export interface WebjsCspConfig {
   /**
@@ -118,6 +145,23 @@ export interface WebjsConfig {
    */
   seed?: boolean;
 
+  /**
+   * Client-router switch (#629). Default `true`: the client router auto-enables
+   * in the browser whenever `@webjsdev/core` loads, so any page that ships a
+   * component gets SPA-style navigation with no import. Set to `false` to opt
+   * the whole app out (pure MPA, full-page navigation; `disableClientRouter()`
+   * stays the programmatic escape hatch).
+   */
+  clientRouter?: boolean;
+
+  /**
+   * Dev/start task orchestration (#550). `webjs dev` / `webjs start` run these
+   * so a bare CLI invocation matches `npm run dev` / `start`. Read by the CLI
+   * (`packages/cli/lib/app-tasks.js`), NOT the server readers.
+   */
+  dev?: WebjsDevTasks;
+  start?: WebjsStartTasks;
+
   /** Per-path response-header rules, shaped like Next's. */
   headers?: WebjsHeaderRule[];