@webjsdev/core 0.7.22 → 0.7.23

package/index-browser.js

@@ -38,6 +38,15 @@ export {
   stringify, parse,
   serialize, deserialize,
 } from './src/serialize.js';
+// The client router auto-enables on bundle load: `router-client.js` calls
+// `enableClientRouter()` at module end (idempotent). This is INTENTIONAL, so
+// any page that loads `@webjsdev/core` (i.e. ships any component) gets client
+// navigation with no per-app opt-in. A layout no longer needs to
+// `import '@webjsdev/core/client-router'`. The bare side-effect import below
+// pins that contract even if the named re-export is later refactored away;
+// the re-export still also evaluates the module, so the two are belt-and-
+// suspenders, not a double-enable (ESM evaluates once, enable is idempotent).
+import './src/router-client.js';
 export { enableClientRouter, disableClientRouter, navigate, revalidate } from './src/router-client.js';
 export { WebjsFrame } from './src/webjs-frame.js';
 export { WebjsStream, renderStream } from './src/webjs-stream.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.22",
+  "version": "0.7.23",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.d.ts

@@ -146,10 +146,14 @@ export type InferProps<S> = {
   [K in keyof S]: S[K] extends PropertyDeclaration<infer T> ? T : Infer<S[K]>
 };
 
-export interface WebComponentConstructor {
-  new (): WebComponentBase;
-  prototype: WebComponentBase;
-
+/**
+ * The static surface every `WebComponent` constructor carries (the bare base,
+ * a factory-produced base, and a registered subclass alike). Declared ONCE
+ * here and referenced from both `WebComponentConstructor` and the factory-call
+ * return type below, so adding or changing a static can never let the two
+ * positions drift. Mirrors the `static` members on `WebComponentBase`.
+ */
+interface WebComponentStatics {
   shadow: boolean;
   hydrate: 'visible' | undefined;
   properties: Record<string, PropertyDeclaration>;
@@ -157,18 +161,15 @@ export interface WebComponentConstructor {
   lazy?: boolean;
   register(tag: string): void;
   readonly observedAttributes: string[];
+}
 
-  <S extends Record<string, any>>(shape: S): {
+export interface WebComponentConstructor extends WebComponentStatics {
+  new (): WebComponentBase;
+  prototype: WebComponentBase;
+
+  <S extends Record<string, any>>(shape: S): WebComponentStatics & {
     new (): WebComponentBase & InferProps<S>;
     prototype: WebComponentBase & InferProps<S>;
-
-    shadow: boolean;
-    hydrate: 'visible' | undefined;
-    properties: Record<string, PropertyDeclaration>;
-    styles: CSSResult | CSSResult[] | null;
-    lazy?: boolean;
-    register(tag: string): void;
-    readonly observedAttributes: string[];
   };
 }
 

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-->`
@@ -606,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)
  * ==================================================================== */
@@ -772,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);
 
@@ -801,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
@@ -819,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);
@@ -828,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;
@@ -895,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);
 
@@ -935,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;
     }
   }
@@ -1719,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' });
     }
   }
 
@@ -3199,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
@@ -3211,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/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
@@ -144,6 +145,15 @@ 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