@webjsdev/core 0.7.50 → 0.7.53

package/src/repeat.d.ts

@@ -0,0 +1,15 @@
+// The runtime value also carries a module-private `Symbol.for('webjs.repeat')`
+// key, the marker the renderers check. It is deliberately absent here: it is not
+// exported, so it cannot be named, and no consumer constructs one by hand.
+export interface RepeatDirective<T> {
+  items: T[];
+  keyFn: (item: T, i: number) => string | number;
+  templateFn: (item: T, i: number) => unknown;
+}
+
+export function repeat<T>(
+  items: Iterable<T>,
+  keyFn: (item: T, i: number) => string | number,
+  templateFn: (item: T, i: number) => unknown,
+): RepeatDirective<T>;
+export function isRepeat(x: unknown): x is RepeatDirective<unknown>;

package/src/rich-fetch.d.ts

@@ -0,0 +1,4 @@
+// `body` is widened off `RequestInit` on purpose: richFetch also accepts a plain
+// object, which it serializes with the WebJs wire format. `Omit` first, because
+// an intersection would narrow the property back to `BodyInit | null`.
+export function richFetch<T>(url: string | URL, init?: Omit<RequestInit, 'body'> & { body?: unknown }): Promise<T>;

package/src/router-client/anchors.js

@@ -0,0 +1,44 @@
+/**
+ * Finding the anchor an event happened inside, across shadow boundaries.
+ *
+ * A leaf: both helpers are pure DOM walks over their argument. They lived in
+ * events.js, which made prefetch.js and upgrade.js import the router's event
+ * layer just to resolve an anchor, and that was one of the edges holding the
+ * directory in a cycle.
+ */
+
+/**
+ * Find the nearest <a> in the event's composed path. composedPath() crosses
+ * shadow DOM boundaries: essential because nav links typically live inside
+ * the layout shell's shadow root.
+ *
+ * @param {MouseEvent} e
+ * @returns {HTMLAnchorElement | null}
+ */
+export function findAnchorInPath(e) {
+  for (const el of e.composedPath()) {
+    if (el instanceof HTMLAnchorElement) return el;
+  }
+  return null;
+}
+/**
+ * Nearest enclosing <a>, crossing shadow boundaries, from an event
+ * target. composedPath is click-only, so walk getRootNode().host here.
+ *
+ * @param {EventTarget | null} target
+ * @returns {HTMLAnchorElement | null}
+ */
+export function closestAnchor(target) {
+  let node = /** @type {Node | null} */ (target);
+  while (node) {
+    if (node instanceof HTMLAnchorElement) return node;
+    const el = node.nodeType === 1 ? /** @type {Element} */ (node) : null;
+    if (el) {
+      const a = el.closest && el.closest('a');
+      if (a instanceof HTMLAnchorElement) return a;
+    }
+    const root = node.getRootNode ? node.getRootNode() : null;
+    node = root && /** @type any */ (root).host ? /** @type any */ (root).host : null;
+  }
+  return null;
+}

package/src/router-client/boundaries.js

@@ -0,0 +1,221 @@
+/**
+ * Client router: boundaries.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+
+/**
+ * Walk a node tree collecting KEYED children-boundary pairs into a Map
+ * keyed by segment path.
+ *
+ * Boundaries are HTML comments emitted by SSR around each layout's
+ * children interpolation AND around the page itself:
+ *   <!--wj:children:/docs:/docs-->            (open: segment + route-key)
+ *     <page content>
+ *   <!--/wj:children:/docs-->                 (close: segment)
+ *
+ * The close carries the SEGMENT, so pairing is deterministic id-matching:
+ * a close must match the segment of the INNERMOST open boundary (proper
+ * nesting), never a positional LIFO guess. The open additionally carries
+ * the resolved ROUTE-KEY (param values percent-encoded at emit), which
+ * `planBoundarySwap` compares between the live and incoming DOM to pick
+ * the swap tier.
+ *
+ * STRICT INTEGRITY, by design (#1015): this scanner never guesses. ANY
+ * violation poisons the whole scan and returns null:
+ *   - an open with no route-key (the legacy anonymous format, or truncation)
+ *   - a close whose segment does not match the innermost open boundary
+ *   - a close with no open boundary at all
+ *   - a duplicate segment (two boundaries claiming one id)
+ *   - an open boundary never closed (truncated response)
+ * The caller degrades a poisoned side to a FULL PAGE LOAD: bounded, correct,
+ * and honest, where the deleted heuristic recovery (#994's orphan recovery +
+ * trailing-count bounding) could guess wrong and corrupt silently. The main
+ * PRODUCER of mispairing (our own comment-stripping parse, #1007, and
+ * mid-parse soft navs, #1008) is already fixed upstream, so poisoning is a
+ * rare backstop, not a common path.
+ *
+ * @param {ParentNode} root
+ * @returns {Map<string, { routeKey: string, start: Comment, end: Comment }> | null}
+ *   The boundary map, or null when the tree's boundaries are malformed.
+ */
+export function collectBoundaries(root) {
+  /** @type {Map<string, { routeKey: string, start: Comment, end: Comment }>} */
+  const out = new Map();
+  /** @type {{ segment: string, routeKey: string, start: Comment }[]} */
+  const stack = [];
+  let poisoned = false;
+
+  // Plain recursive comment walk: TreeWalker/NodeFilter aren't available
+  // in every DOM polyfill (notably linkedom in tests). Iterative depth-
+  // first traversal keeps us portable across linkedom + native + jsdom.
+  /** @param {Node} node */
+  function visit(node) {
+    if (poisoned) return;
+    if (node.nodeType === 8 /* COMMENT_NODE */) {
+      const data = /** @type {Comment} */ (node).data.trim();
+      if (data.startsWith('wj:children:')) {
+        const rest = data.slice('wj:children:'.length);
+        // The route-key is everything after the LAST ':'. Substituted param
+        // values are percent-encoded at emit and static pieces have their
+        // delimiter characters encoded too, so the last colon is unambiguous
+        // for framework-emitted boundaries. A hand-authored folder name that
+        // still smuggles a delimiter through can only MIS-SPLIT here, which
+        // mismatches the close and poisons the scan: degrade-only, never a
+        // wrong pairing.
+        const cut = rest.lastIndexOf(':');
+        if (cut <= 0 || cut === rest.length - 1) { poisoned = true; return; }
+        const segment = rest.slice(0, cut);
+        const routeKey = rest.slice(cut + 1);
+        if (out.has(segment) || stack.some((f) => f.segment === segment)) {
+          poisoned = true;
+          return;
+        }
+        stack.push({ segment, routeKey, start: /** @type {Comment} */ (node) });
+        return;
+      }
+      if (data.startsWith('/wj:children')) {
+        const seg = data.slice('/wj:children'.length).replace(/^:/, '');
+        const frame = stack.pop();
+        if (!frame || frame.segment !== seg) { poisoned = true; return; }
+        // Same-parent integrity: HTML parser reparenting (a <p> auto-closed
+        // by block content) can split a pair across parents. The range
+        // operations walk nextSibling from start and insert before end, so a
+        // cross-parent pair would empty the region and then throw mid-swap.
+        // Poison instead: degrade up front.
+        if (frame.start.parentNode !== /** @type {Comment} */ (node).parentNode) {
+          poisoned = true;
+          return;
+        }
+        // Table-context integrity: foster-parenting moves CONTENT out of the
+        // table while comment tokens stay put, so a boundary emitted in table
+        // context shares a parent (passing the check above) while its actual
+        // children were fostered OUTSIDE the range. Swapping that empty range
+        // would silently leave stale visible content. A `${children}` slot
+        // directly in table context cannot work as a swap boundary at all,
+        // so poison it.
+        {
+          const pt = /** @type {Element} */ (frame.start.parentNode).tagName;
+          if (pt === 'TABLE' || pt === 'TBODY' || pt === 'THEAD' || pt === 'TFOOT' || pt === 'TR') {
+            poisoned = true;
+            return;
+          }
+        }
+        out.set(frame.segment, {
+          routeKey: frame.routeKey,
+          start: frame.start,
+          end: /** @type {Comment} */ (node),
+        });
+        return;
+      }
+      return;
+    }
+    if (node.hasChildNodes && node.hasChildNodes()) {
+      for (let child = node.firstChild; child && !poisoned; child = child.nextSibling) {
+        visit(child);
+      }
+    }
+  }
+  visit(/** @type {Node} */ (root));
+
+  if (poisoned || stack.length > 0) return null;
+  return out;
+}
+
+/**
+ * Plan the two-tier boundary swap from the live + incoming boundary maps
+ * (#1015). Boundary segments are nested path prefixes, so the shared segments
+ * form a chain from `/` down to the deepest shared boundary D.
+ *
+ * Rules (Next.js remount-vs-preserve parity):
+ *  - A changed route-key REPLACES at the PARENT of the shallowest changed
+ *    boundary. The parent, not the changed boundary itself: a LAYOUT's
+ *    boundary wraps its CHILDREN slot, so the layout's OWN markup (an
+ *    `[org]`-name header it renders around `${children}`) lives inside the
+ *    PARENT's range. Anchoring at the parent remounts the changed layout's
+ *    chrome AND its subtree, exactly like Next re-rendering the layout with
+ *    new params. The page boundary composes the same way: its parent is the
+ *    nearest layout's children slot, so `/blog/a` -> `/blog/b` under a
+ *    `/blog` layout remounts just the page while the `/blog` layout chrome
+ *    is preserved; with no intermediate layout the anchor is `/` and the
+ *    root layout's chrome (outside its own children boundary) is still
+ *    preserved. A changed boundary with NO shared parent degrades (null).
+ *  - No route-key changed but the subtree below D diverges (D is a LAYOUT,
+ *    not the deepest boundary, on either side, e.g. `/about` -> `/contact`
+ *    under a shared static root layout): REPLACE D's contents wholesale.
+ *  - No route-key changed and D is the deepest boundary on BOTH sides: MORPH
+ *    D. The searchParams-only / refresh / revalidate nav, which must preserve
+ *    hydrated component state while updating searchParam-driven DOM.
+ *  - No shared segment at all: null (the caller degrades to a full load). In
+ *    practice the page boundary exists on both sides of any same-app nav, so
+ *    this is reached only for a divergent or malformed shell.
+ *
+ * @param {Map<string, { routeKey: string, start: Comment, end: Comment }>} here
+ * @param {Map<string, { routeKey: string, start: Comment, end: Comment }>} there
+ * @returns {{ mode: 'replace' | 'morph', segment: string,
+ *   live: { routeKey: string, start: Comment, end: Comment },
+ *   incoming: { routeKey: string, start: Comment, end: Comment } } | null}
+ */
+export function planBoundarySwap(here, there) {
+  // Shared segments, shallowest first (a nested path prefix is shorter).
+  const shared = [...here.keys()].filter((s) => there.has(s)).sort((a, b) => a.length - b.length);
+  if (shared.length === 0) return null;
+  // A changed route-key remounts at the PARENT of the shallowest change.
+  for (const seg of shared) {
+    if (here.get(seg).routeKey !== there.get(seg).routeKey) {
+      let parent = null;
+      for (const p of shared) {
+        if (p === seg) break;
+        if (seg.startsWith(p === '/' ? p : p + '/')) parent = p;
+      }
+      if (!parent) return null; // no anchored parent: degrade
+      return { mode: 'replace', segment: parent, live: here.get(parent), incoming: there.get(parent) };
+    }
+  }
+  // No route-key changed. D = deepest shared boundary.
+  const D = shared[shared.length - 1];
+  /** @param {Map<string, unknown>} m */
+  const deepestOf = (m) => {
+    let best = null;
+    for (const s of m.keys()) if (best === null || s.length > best.length) best = s;
+    return best;
+  };
+  const leafOnBoth = deepestOf(here) === D && deepestOf(there) === D;
+  return {
+    mode: leafOnBoth ? 'morph' : 'replace',
+    segment: D,
+    live: here.get(D),
+    incoming: there.get(D),
+  };
+}
+
+/* ====================================================================
+ * Snapshot cache (Turbo SnapshotCache pattern)
+ * ==================================================================== */
+
+/**
+ * Build the X-Webjs-Have header value from the live DOM's boundaries.
+ * Comma-separated `<segment>:<route-key>` entries in document order. The
+ * ROUTE-KEY rides along so the server's short-circuit can distinguish "the
+ * client has this layout" from "the client has this layout rendered for
+ * DIFFERENT params": a dynamic `[org]` layout the client holds for org-a
+ * must be re-rendered (and re-shipped) on an org-b navigation, or the
+ * parent-anchored REPLACE would have no fresh layout markup to swap in.
+ * The server ignores the page-boundary entry (never a layout segment).
+ *
+ * A poisoned live DOM (malformed boundaries) reports an EMPTY have, so the
+ * server returns the full page. The subsequent applySwap re-scans, sees the
+ * same poisoned live tree, and degrades to a full load: consistent with the
+ * integrity-gate model, never a reduced fragment spliced against a tree we
+ * cannot trust (#1015).
+ *
+ * @returns {string}
+ */
+export function buildHaveHeader() {
+  const boundaries = collectBoundaries(document.body);
+  if (!boundaries) return '';
+  return [...boundaries.entries()].map(([seg, b]) => `${seg}:${b.routeKey}`).join(',');
+}

package/src/router-client/constants.js

@@ -0,0 +1,206 @@
+/**
+ * Client router: constants.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+
+/** The content type a content-negotiated stream-action response carries (#248). */
+export const STREAM_MIME = 'text/vnd.webjs-stream.html';
+
+/**
+ * Client router for webjs: nested-layout-aware partial swap.
+ *
+ * Intercepts same-origin link clicks and form submissions, fetches the
+ * target page's HTML via `fetch()`, finds the deepest layout boundary
+ * shared by both the current and incoming pages, and replaces ONLY the
+ * children of that boundary. Outer layout DOM (header, sidenav, footer)
+ * stays mounted: no re-render, no flicker, scroll positions preserved.
+ *
+ * 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 (#1015):
+ *   1. SSR injects KEYED boundary comment pairs around each layout's
+ *      `${children}` interpolation and around the page itself:
+ *      `<!--wj:children:<segment>:<route-key>-->` ... `<!--/wj:children:<segment>-->`.
+ *      The close carries the segment (deterministic id-matched pairing, no
+ *      LIFO), the open carries the resolved route-key (param values
+ *      percent-encoded).
+ *   2. On link click, STRICTLY scan both the live DOM and the incoming HTML
+ *      into segment → {routeKey, range} maps. Any pairing violation poisons
+ *      the scan.
+ *   3. Two-tier DECISION (Next.js remount parity), nothing applied yet: a
+ *      CHANGED route-key REPLACES (fresh remount) at the PARENT of the
+ *      shallowest changed boundary (whose range contains the changed layout's
+ *      own markup), else MORPH (keyed reconcile preserving input values,
+ *      scroll, popover state, and node identity) at the deepest shared
+ *      boundary.
+ *   4. A poisoned scan or no shared boundary degrades to a FULL PAGE LOAD:
+ *      bounded and correct, never a guessed recovery.
+ *   5. Commit, in this order: `history.pushState`, then merge head, then apply
+ *      the replace/morph from step 3, then re-run scripts and upgrade custom
+ *      elements. Only the push moved (#1406); the rest of the sequence is
+ *      unchanged. The push leads so the entry for the page being left is
+ *      finalized while that page is still the live document, rather than
+ *      against the content that replaced it. This is Turbo Drive's ordering
+ *      too.
+ *
+ *      #1406 justified the move as the fix for the blank iOS back-swipe
+ *      preview, on the theory that WebKit binds the gesture snapshot to page
+ *      state at the moment the entry is recorded. That theory is FALSE, shown
+ *      on-device in #1428: Turbo Drive has this exact ordering and previews
+ *      blank the same way, and the real cause was
+ *      `history.scrollRestoration = 'manual'` suppressing the browser's
+ *      per-entry scroll recording. The ordering stands on its own merits;
+ *      it just never fixed that bug.
+ *
+ * Optimizations bundled into the same response cycle:
+ *   - `X-Webjs-Have` request header lists `segment:route-key` entries for
+ *     the boundaries the client already has. The server walks the target's
+ *     layout chain and short-circuits at the deepest FULL match (segment AND
+ *     key, so a dynamic layout held for other params is re-rendered), then
+ *     returns only the divergent fragment (wrapped in the matched boundary).
+ *     Real wire-byte savings: the layout chain is never re-serialized for
+ *     same-shell navigations.
+ *   - URL-keyed snapshot cache (Turbo SnapshotCache pattern). Back/
+ *     forward via popstate restores from cache instantly, then
+ *     revalidates in the background.
+ *   - Per-segment loading templates: SSR emits each segment's
+ *     loading.ts content as `<template id="wj-loading:<path>">`. On
+ *     nav-start the client clones the deepest matching template into
+ *     the swap slot so users see an instant skeleton instead of stale
+ *     content.
+ *
+ * Escape hatch:
+ *   `<webjs-frame id="...">`: declarative partial-swap region NOT
+ *   tied to a folder layout. If a link's enclosing `closest('webjs-frame')`
+ *   matches a frame in the incoming HTML, the frame swap takes
+ *   precedence over the layout-marker mechanism. Use for ad-hoc
+ *   widgets (tabs, lazy-loaded cards) where the swap region isn't a
+ *   folder route segment.
+ */
+
+/**
+ * Hard ceiling on the restore window (#1310). The revalidation is a
+ * same-origin GET of a page the browser rendered moments ago, so this is
+ * generously past its p99. It exists only so a hung or never-settling fetch
+ * can never leave scroll anchoring suppressed for the life of the page.
+ */
+export const ANCHOR_SUPPRESS_CEILING_MS = 2000;
+
+/**
+ * Floor on the restore window (#1310). The window's other closer is the
+ * revalidation settling, which is only long enough while the revalidation is
+ * SLOWER than the restored page's own upgrade-and-render. That holds on a
+ * deployed site (measured: growth ~65ms after the swap, the revalidation's swap
+ * ~300ms after that) but it is a property of one deployment, not a guarantee: a
+ * local server, a 304, or a warm cache answers in single-digit milliseconds and
+ * would otherwise close the window before the growth it exists to absorb.
+ *
+ * So the window lasts at least this long whatever the network does. The value
+ * clears the measured revalidation swap with margin and stays well under the
+ * ceiling. It is a floor, not a delay: a real user input still closes the
+ * window immediately, which is the case that actually matters for not holding
+ * anchoring off longer than a reader would want.
+ */
+export const ANCHOR_SUPPRESS_FLOOR_MS = 500;
+
+/**
+ * Inputs that mean the reader has taken over the viewport, so the restore is
+ * over and the browser's own anchoring should resume.
+ *
+ * NOT `scroll`. The router's own `scrollTo` and anchoring itself both fire
+ * `scroll`, so it cannot tell a reader apart from the restore it is guarding,
+ * and no threshold makes it able to. These are input events, so there is
+ * nothing to threshold out and the FIRST one closes the window. `keydown` is
+ * deliberately not narrowed to scrolling keys: any keypress means interaction,
+ * and closing early only restores the browser default, which is the safe
+ * direction to err in.
+ *
+ * @type {string[]}
+ */
+export const ANCHOR_RELEASE_EVENTS = ['wheel', 'touchmove', 'keydown', 'pointerdown'];
+
+/**
+ * Pathnames with these extensions are never HTML pages.
+ */
+export 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 reserved `data-webjs-frame` token that forces a full-page navigation,
+ * breaking OUT of any enclosing frame (Turbo's `data-turbo-frame="_top"`).
+ * `resolveTargetFrameId` returns this sentinel; callers treat it exactly
+ * like "no frame" (a normal layout-marker / full-body swap), so a trigger
+ * physically nested in a frame escapes the frame swap. Distinct from `null`
+ * only inside `resolveTargetFrameId` (where `null` would otherwise fall back
+ * to the enclosing frame); both reach `performNavigation` as a frameless
+ * nav, so they behave identically downstream.
+ */
+export const FRAME_TOP = '_top';
+
+/**
+ * `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.
+ */
+export const FALLBACK_MARKER_KEY = 'webjs:nav-fallback';
+
+export const SNAPSHOT_CAP = 16;
+
+/**
+ * Attribute names whose live DOM state must NEVER be overwritten by
+ * incoming server HTML during a partial swap. The server emits these
+ * with their initial-render value; the user may have typed/clicked
+ * between renders. Preserving them keeps focus, typing, open state,
+ * and popover state intact across navigation.
+ */
+export const LIVE_ATTRS = new Set([
+  // Form controls
+  'value', 'checked', 'selected', 'indeterminate', 'disabled',
+  // Disclosure / popover
+  'open', 'popover',
+]);
+
+/* ====================================================================
+ * Optimistic loading (per-segment loading.ts templates)
+ * ==================================================================== */
+
+/**
+ * The one framework-owned keyed meta that must NEVER be reconciled: the CSP
+ * nonce. A soft-nav response carries a FRESH per-request nonce, but the browser
+ * enforces CSP against the nonce the ORIGINAL page load declared (see
+ * `getCspNonce`), so overwriting the live `csp-nonce` meta with the incoming
+ * one would make every later nonce-stamped script/preload violate the active
+ * policy. Excluded from add/update/remove so the original meta survives verbatim.
+ */
+export const META_KEY_CSP_NONCE = 'name=csp-nonce';
+
+/**
+ * Predicate used by the onClick handler to decide whether a same-origin
+ * href should bypass the router. Exposed for unit testing.
+ *
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function _isNonHtmlPath(pathname) {
+  return NON_HTML_EXTENSIONS.test(pathname);
+}
+
+/**
+ * How long the restore window's write-back stays armed (#1428).
+ *
+ * It exists to reconcile ONE event, the browser's replay of its own recorded
+ * scroll offset, which lands about a frame after the popstate handler. This is
+ * generous for that (roughly fifteen frames at 60Hz) and far short of the
+ * window's own life, so a legitimate programmatic scroll arriving later, a
+ * component's `scrollIntoView()` during upgrade or a find-in-page jump, is left
+ * alone rather than reverted.
+ */
+export const WRITE_BACK_ARMED_MS = 250;