@webjsdev/core 0.7.51 → 0.7.54

package/src/router-client/scroll.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { ANCHOR_RELEASE_EVENTS, ANCHOR_SUPPRESS_CEILING_MS, ANCHOR_SUPPRESS_FLOOR_MS } from './constants.js';
+import { ANCHOR_RELEASE_EVENTS, ANCHOR_SUPPRESS_CEILING_MS, WRITE_BACK_ARMED_MS } from './constants.js';
 
 /**
  * Closes the currently open restore window, or null when none is open.
@@ -58,29 +58,89 @@ export let releaseScrollAnchor = null;
  * for the life of the page after their first Back. That is a far worse trade
  * than one repaint, so the root it is.
  *
+ * @param {number} [targetX] the restore's recorded horizontal offset. Together
+ *   with `targetY` this arms the write-back below; omit BOTH to open a
+ *   suppression-only window with no scroll enforcement.
+ * @param {number} [targetY] the restore's recorded vertical offset. The
+ *   write-back is armed only when this is a number, so a caller that passes
+ *   nothing gets the pre-#1428 behaviour.
  * @returns {() => void} Idempotent release. Safe to call after the window has
  *   already closed on user input or the ceiling.
  */
-export function suppressScrollAnchoring() {
+export function suppressScrollAnchoring(targetX, targetY) {
   if (typeof document === 'undefined' || !document.documentElement) return () => {};
   // A second restore inside an open window supersedes the first.
   if (releaseScrollAnchor) releaseScrollAnchor();
   const root = document.documentElement;
   // Save and restore the author's own inline value rather than blanking it,
-  // the same contract `prevScrollRestoration` keeps above.
+  // the same save-and-put-back contract the router keeps elsewhere.
   const prev = root.style.getPropertyValue('overflow-anchor');
   root.style.setProperty('overflow-anchor', 'none');
   /** @type {ReturnType<typeof setTimeout> | null} */
   let timer = null;
+  // With a target, the window also WRITES BACK a programmatic displacement
+  // (#1428). The browser owns the restore now, and its replay is the offset IT
+  // recorded for the entry, which can DISAGREE with the snapshot: an entry the
+  // router snapshotted without the reader having scrolled there under the UA's
+  // observation carries a stale 0. This write-back is what reconciles the two,
+  // and it is the only thing that does, so it is not redundant with the UA
+  // being correct in the common case. A user can never trigger
+  // this listener first: every release event is a CAPTURE-phase input
+  // listener (wheel / touchmove / keydown / pointerdown), and each of those
+  // fires BEFORE the scroll event that follows it, so by the time a
+  // user-driven scroll lands here the window is already closed. What remains
+  // is exactly a programmatic non-user write inside the restore's own span,
+  // which is the one thing the restore may overrule. Re-entry is benign: the
+  // write-back's own scroll event arrives on-target and returns.
+  //
+  // It is armed only BRIEFLY, not for the window's full life. The thing it
+  // exists to reconcile is one event, the UA's replay of its own recorded
+  // offset, which lands about a frame after the popstate handler. Left armed
+  // for the window's life (the revalidation settle, or up to the 2s ceiling)
+  // it would spend seconds reverting any programmatic scroll, and the longer it
+  // stands the more it claims. 250ms bounds that.
+  //
+  // It does NOT make the write-back harmless, and the honest statement is that
+  // a programmatic scroll inside the arming span still loses to the restore. A
+  // component calling `scrollIntoView()` from `connectedCallback` as the
+  // restored page upgrades, or an autofocus on a below-fold control, runs a
+  // microtask or a frame after the swap, which is INSIDE 250ms, so it is
+  // reverted. That is the deliberate precedence on a Back: the reader asked for
+  // the page they left, not for wherever a component jumped while rehydrating.
+  // What the bound buys is that a scroll a second later, which has nothing to
+  // do with the restore, is left alone; find-in-page from the browser chrome is
+  // the case that matters there, since it fires no page `keydown` and so does
+  // not close the window the way a real key press would.
+  //
+  // Bounded by TIME rather than by a correction count. A count is the obvious
+  // bound and it is wrong: a single-shot can be spent on an unrelated scroll
+  // event that happens to arrive before the UA's replay, after which the stale
+  // replay stands uncorrected. That reproduced on Firefox as an intermittent,
+  // roughly one run in three. A short arming span covers the replay whenever it
+  // lands, however many events precede it.
+  let armed = typeof targetY === 'number';
+  const disarm = () => { armed = false; };
+  const armTimer = armed && typeof setTimeout === 'function'
+    ? setTimeout(disarm, WRITE_BACK_ARMED_MS) : null;
+  const onScroll = (typeof targetY === 'number' && typeof window !== 'undefined')
+    ? () => {
+      if (!armed) return;
+      if (Math.abs(window.scrollY - targetY) <= 1 && Math.abs(window.scrollX - (targetX || 0)) <= 1) return;
+      window.scrollTo({ left: targetX || 0, top: targetY, behavior: 'instant' });
+    }
+    : null;
   const release = () => {
     // Only the window that installed this release may close it.
     if (releaseScrollAnchor !== release) return;
     releaseScrollAnchor = null;
     if (timer) { clearTimeout(timer); timer = null; }
+    if (armTimer) clearTimeout(armTimer);
+    armed = false;
     if (typeof window !== 'undefined') {
       for (const ev of ANCHOR_RELEASE_EVENTS) {
         window.removeEventListener(ev, release, /** @type {any} */ ({ capture: true }));
       }
+      if (onScroll) window.removeEventListener('scroll', onScroll);
     }
     if (prev) root.style.setProperty('overflow-anchor', prev);
     else root.style.removeProperty('overflow-anchor');
@@ -91,22 +151,76 @@ export function suppressScrollAnchoring() {
     for (const ev of ANCHOR_RELEASE_EVENTS) {
       window.addEventListener(ev, release, { capture: true, passive: true });
     }
+    if (onScroll) window.addEventListener('scroll', onScroll, { passive: true });
   }
   return release;
 }
 
 /**
- * Cancels an in-flight catch-up, or null when none is running.
+ * Closes the currently held height reservation, or null when none is open.
  * @type {(() => void) | null}
  */
-export let cancelScrollCatchUp = null;
+export let releaseHeightReservation = null;
+
+/**
+ * Reserve the restored page's SETTLED height across a Back/Forward restore
+ * (#1428 architecture).
+ *
+ * A restore re-inserts an outerHTML snapshot, and that markup is SHORTER than
+ * the page it was serialized from until its components upgrade and re-render a
+ * beat later. Every scroll defect in this file's history lived in that window:
+ * the browser clamped the recorded offset against the short document (#1310's
+ * clamped band, formerly healed by a chase), and the UA's own restoration
+ * landed short the same way. Holding the settled height on the ROOT element
+ * makes the recorded offset reachable from the first frame, so a restore lands
+ * exactly, once, and the clamp class cannot occur at all.
+ *
+ * The root and not `<body>`, because the restore REPLACES the whole body, so
+ * an inline style there would leave with the old node. Same
+ * save-and-put-back contract as `overflow-anchor` above.
+ *
+ * Released on the restore's settle, on the ceiling, and on supersede (a new
+ * page navigation, a submission, disabling the router). NEVER on user input:
+ * the window releases early for a reader taking over, but yanking the page's
+ * height out from under a reader mid-scroll is the one harm an early release
+ * here could cause, so this deliberately does not share that trigger.
+ *
+ * @param {number} px the snapshot's recorded `scrollHeight`
+ * @returns {() => void} Idempotent release.
+ */
+export function reserveRestoredHeight(px) {
+  if (typeof document === 'undefined' || !document.documentElement) return () => {};
+  // A second reservation supersedes the first, and does so BEFORE the height
+  // guard below. Ordering it after would let a restore with no recorded height
+  // (a legacy string snapshot, `scrollHeight: 0`) return early while the
+  // PREVIOUS page's min-height stayed pinned to the root until the ceiling.
+  // Superseding first means every restore clears its predecessor, whether or
+  // not it has a height of its own to hold.
+  if (releaseHeightReservation) releaseHeightReservation();
+  if (!(px > 0)) return () => {};
+  const root = document.documentElement;
+  const prev = root.style.getPropertyValue('min-height');
+  root.style.setProperty('min-height', px + 'px');
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  const release = () => {
+    if (releaseHeightReservation !== release) return;
+    releaseHeightReservation = null;
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (prev) root.style.setProperty('min-height', prev);
+    else root.style.removeProperty('min-height');
+  };
+  releaseHeightReservation = release;
+  timer = setTimeout(release, ANCHOR_SUPPRESS_CEILING_MS);
+  return release;
+}
 
 /**
  * Bumped wherever a restore is superseded (#1310), and read by the one restore
  * path that outlives the call scheduling it. That means a PAGE navigation, a
  * PAGE-level submission, and disabling the router. A frame-targeted nav or
  * submission swaps one region and leaves the page, so it is excluded, exactly
- * like the `loadFrame` case below.
+ * like the `loadFrame` case.
  *
  * Deliberately NOT `currentNavigationToken`, which is the obvious choice and the
  * wrong one: `loadFrame` bumps that too, and its own contract says a frame
@@ -119,120 +233,6 @@ export let cancelScrollCatchUp = null;
  */
 export let restoreGeneration = 0;
 
-/**
- * Chase a restored scroll offset the document was too SHORT to reach (#1310).
- *
- * The sibling of `suppressScrollAnchoring`, for the case that one deliberately
- * declines. When the recorded offset is past the un-grown document's maximum,
- * the browser clamps, and anchoring then adds the growth back as the page
- * settles. That lands a reader who left at the very bottom back at the bottom,
- * because there the shortfall and the growth are the same number. It is wrong
- * for everyone else: anchoring adds the FULL growth whatever the shortfall was,
- * so a reader who left 100px above the bottom is carried 100px too far.
- *
- * This re-asserts the recorded offset once the document can actually hold it,
- * which is the only moment the number becomes reachable, and then stops.
- *
- * It is deliberately narrow, because #1310 rejected re-asserting the scroll in
- * the general case and that reasoning still holds. The difference is that this
- * knows exactly where it is going and can tell when it has arrived: it runs
- * ONLY on the clamped path, only while the offset is still out of reach, writes
- * once, and stops on the first real input.
- *
- * It does NOT escape the settling-versus-streaming question, and it is worth
- * being exact about that rather than claiming otherwise. It cannot tell the
- * restore settling apart from any other growth, so the guard is its WINDOW: it
- * lives for `ANCHOR_SUPPRESS_FLOOR_MS` from the RESTORE and no longer. That is
- * tighter than the window a landed restore gets, which runs to the later of the
- * floor and the revalidation and is capped by the ceiling, and deliberately so,
- * because this path WRITES scroll. The suppression this path installs once the
- * chase lands is part of the same window, not a second one: it shares this
- * deadline, so the whole clamped path is bounded by one floor measured from the
- * restore however late the landing happens.
- *
- * Be precise about what the bound does and does not buy, since it is easy to
- * overclaim in both directions. WHILE the window is open the reader is
- * protected: until the offset is reachable there is nothing to protect, and
- * from the moment the chase lands on it, suppression holds it against the rest
- * of the growth. AFTER the window closes, both halves stop: the router writes
- * no more scroll, and anchoring is back on, so any growth still arriving is
- * added to `scrollY` and carries the reader down toward the bottom, which is
- * main's behaviour. So the cost of a component that settles later than the
- * window is that the reader drifts below the offset, not that they sit at the
- * clamp.
- *
- * @param {number} targetY  The recorded offset to reach.
- * @param {number} targetX
- */
-export function catchUpToRestoredScroll(targetY, targetX) {
-  if (typeof window === 'undefined' || typeof requestAnimationFrame !== 'function') return;
-  if (cancelScrollCatchUp) cancelScrollCatchUp();
-  let rafId = 0;
-  /** @type {ReturnType<typeof setTimeout> | null} */
-  let timer = null;
-  /** Release for the suppression installed once the offset is reached. */
-  let releaseLanded = null;
-  const stop = () => {
-    if (cancelScrollCatchUp !== stop) return;
-    cancelScrollCatchUp = null;
-    if (rafId) cancelAnimationFrame(rafId);
-    if (timer) { clearTimeout(timer); timer = null; }
-    if (releaseLanded) { releaseLanded(); releaseLanded = null; }
-    for (const ev of ANCHOR_RELEASE_EVENTS) {
-      window.removeEventListener(ev, stop, /** @type {any} */ ({ capture: true }));
-    }
-  };
-  const tick = () => {
-    if (cancelScrollCatchUp !== stop) return;
-    const maxY = document.documentElement.scrollHeight - window.innerHeight;
-    if (maxY >= targetY) {
-      // Reachable at last. Land the reader on the recorded offset.
-      window.scrollTo({ left: targetX, top: targetY, behavior: 'instant' });
-      // And then protect it, because landing is not the end of the story. The
-      // growth that made the offset reachable is rarely all of it: the real
-      // cause is components upgrading one at a time, so more arrives after
-      // this. Anchoring is still on here, deliberately, so every later stage
-      // would be added on top of the offset just written and carry the reader
-      // below it again. Measured on a two-stage fixture, an offset of 4000
-      // ended at 5000.
-      //
-      // Once the reader IS on the recorded offset the situation is identical to
-      // a restore that landed on its first try, so it gets that case's
-      // protection for what remains.
-      //
-      // It shares THIS chase's deadline rather than starting one of its own,
-      // which matters: a fresh floor-length timer here would start at landing
-      // rather than at the restore, so the clamped path could hold anchoring
-      // off for nearly twice the floor and stop being the tighter of the two
-      // windows, which is the whole reason for the bound. `stop` owns the
-      // release, so the existing timer and the input listeners close it.
-      releaseLanded = suppressScrollAnchoring();
-      // Deliberately NOT `stop()`: the window has to outlive the landing, up to
-      // the deadline already running.
-      if (rafId) { cancelAnimationFrame(rafId); rafId = 0; }
-      return;
-    }
-    rafId = requestAnimationFrame(tick);
-  };
-  cancelScrollCatchUp = stop;
-  // Same inputs that close a suppression window: the reader has taken over.
-  for (const ev of ANCHOR_RELEASE_EVENTS) {
-    window.addEventListener(ev, stop, { capture: true, passive: true });
-  }
-  // Bounded by the FLOOR, not the ceiling. The ceiling is a backstop for a hung
-  // fetch; this is a scroll WRITE, so its window is the one thing that decides
-  // whether a reader can be moved without asking. Any growth past the target
-  // fires it, and growth is not exclusively the restore settling: a
-  // <webjs-suspense> boundary resolving, a lazy component entering, or a late
-  // image would all qualify. Holding it open for the full ceiling would mean a
-  // reader who landed and started READING, and so generates no input to cancel
-  // it, could be scrolled up to two seconds after pressing Back. The floor
-  // covers the restore's own settling, which is what it is for, and is measured
-  // in a few hundred milliseconds rather than seconds.
-  timer = setTimeout(stop, ANCHOR_SUPPRESS_FLOOR_MS);
-  rafId = requestAnimationFrame(tick);
-}
-
 /**
  * Run `fn` after two animation frames, so a just-applied DOM has laid out
  * before it reads or acts. Falls back to a macrotask where
@@ -257,3 +257,52 @@ export function afterTwoFrames(fn) {
 export function bumpRestoreGeneration() {
   restoreGeneration += 1;
 }
+
+/**
+ * Whether this navigation should keep the reader's current scroll offset rather
+ * than scrolling to top (#1436).
+ *
+ * Resolved from `data-preserve-scroll` on the trigger OR the nearest ancestor
+ * carrying it, so one filter bar / tab strip / breadcrumb marks every link in it
+ * at once. That is `resolveTargetFrameId`'s precedent (`frames.js`), not
+ * `data-no-router`'s element-only read: `data-no-router` turns the router OFF
+ * for a link, a big enough hammer that an ancestor doing it silently would
+ * surprise, while this is a soft preference whose natural authoring unit is a
+ * region.
+ *
+ * VALUE-aware, and the only value that means anything is the literal `false`.
+ * That is Remix 3's `rmx-reset-scroll` test (`!== 'false'`) and the value
+ * vocabulary `prefetchMode` already accepts here. Because `closest()` returns
+ * the NEAREST carrier, `data-preserve-scroll="false"` on one link inside a
+ * marked wrapper opts that link back into the default with no extra logic.
+ *
+ * `fallback` is consulted only when `trigger` resolves NO carrier, which is what
+ * a form submission needs. A submitter is form-associated by `form="id"` rather
+ * than by containment, so `<button form="f">` may sit anywhere in the document
+ * and `closest()` from it would never pass through the form it submits. Falling
+ * back to the form covers that, and ordering it AFTER the trigger is what keeps
+ * `data-preserve-scroll="false"` on the submitter winning over a marked form:
+ * a resolved carrier is never overridden, only a missing one is filled in.
+ *
+ * @param {Element | null} trigger  the clicked anchor, or a submitted form's
+ *   submitter (falling back to the form when there is no submitter).
+ * @param {Element | null} [fallback]  the submitted form, consulted only when
+ *   the trigger carries no mark and is not inside one.
+ * @returns {boolean}
+ */
+export function resolvePreserveScroll(trigger, fallback) {
+  const carrier = findScrollCarrier(trigger) || findScrollCarrier(fallback);
+  if (!carrier) return false;
+  return (carrier.getAttribute('data-preserve-scroll') || '').toLowerCase().trim() !== 'false';
+}
+
+/**
+ * The nearest element at or above `el` carrying `data-preserve-scroll`.
+ *
+ * @param {Element | null | undefined} el
+ * @returns {Element | null}
+ */
+function findScrollCarrier(el) {
+  if (!el || typeof el.closest !== 'function') return null;
+  return el.closest('[data-preserve-scroll]');
+}

package/src/router-client/snapshot-cache.js

@@ -8,7 +8,7 @@
  */
 import { SNAPSHOT_CAP } from './constants.js';
 
-/** @typedef {{ html: string, scrollX: number, scrollY: number }} Snapshot */
+/** @typedef {{ html: string, scrollX: number, scrollY: number, scrollHeight: number }} Snapshot */
 /** @type {Map<string, Snapshot | string>} */
 export const snapshotCache = new Map();
 
@@ -41,6 +41,15 @@ export function snapshotCurrent(url) {
     html: document.documentElement.outerHTML,
     scrollX: typeof window !== 'undefined' ? window.scrollX || 0 : 0,
     scrollY: typeof window !== 'undefined' ? window.scrollY || 0 : 0,
+    // The page's SETTLED height, captured at the same moment as the offset.
+    // A restore re-inserts this snapshot as raw markup, and the document is
+    // SHORTER than this until its components upgrade and re-render, which is
+    // the window every scroll defect in #1310 lived in. The restore reserves
+    // this height across that window (#1428 architecture), so the recorded
+    // offset is reachable from the first frame and the browser's own
+    // restoration lands exactly, with no clamp and nothing to chase.
+    scrollHeight: typeof document !== 'undefined' && document.documentElement
+      ? document.documentElement.scrollHeight || 0 : 0,
   };
   snapshotCache.set(key, snap);
   while (snapshotCache.size > SNAPSHOT_CAP) {
@@ -64,7 +73,14 @@ export function snapshotGet(url) {
   // Move-to-front.
   snapshotCache.delete(key);
   snapshotCache.set(key, v);
-  if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0 };
+  // A legacy string entry carries no offsets and no height. `scrollHeight: 0`
+  // is stated rather than left undefined so the returned object satisfies the
+  // `Snapshot` typedef, and because `reserveRestoredHeight` treats a
+  // non-positive height as "nothing to reserve" and no-ops: there is no
+  // recorded height to hold, so reserving is not merely skippable, it is
+  // meaningless. Such an entry restores with no reservation, which is the
+  // pre-#1428 behaviour and correct for a snapshot that never recorded one.
+  if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0, scrollHeight: 0 };
   return v;
 }
 

package/src/router-client/state.js

@@ -90,3 +90,66 @@ export let enabled = false;
 export function _setEnabled(v) {
   enabled = v;
 }
+
+/**
+ * The href a bowed-out same-document fragment CLICK is navigating to, pending
+ * the popstate that click is about to produce.
+ *
+ * This exists because URLs alone cannot separate the two ways a popstate can
+ * arrive carrying the url the reader is already on, and the two need opposite
+ * treatment (#1437).
+ *
+ *   - A REPEAT click of one in-page anchor REPLACES its history entry rather
+ *     than pushing, so it fires popstate with `location.href` unchanged. The
+ *     browser has already done the jump and there is nothing to fetch.
+ *   - A Back between two DISTINCT entries that happen to share a url is a real
+ *     traversal that must re-render. The no-JS write path produces that pair: a
+ *     bound `<form action=${fn}>` emits no `action` attribute (invariant 12), so
+ *     `form.action` reflects the node document's URL and the 422 re-render
+ *     pushes a duplicate entry at it.
+ *
+ * An earlier attempt tried to tell them apart by whether the url carried a
+ * fragment, on the reasoning that a repeat anchor click always has one and a
+ * 422 entry never does. The second half is false: `form.action` returns the
+ * document URL WITH its fragment (measured in Chromium, for a missing `action`
+ * attribute and an empty one alike), so a reader who used an in-page anchor
+ * before submitting produces a 422 entry carrying `#sec`, and the Back out of
+ * the validation error was swallowed.
+ *
+ * So the signal is not the url, it is provenance: the router SAW the click it
+ * bowed out of, and it never sees a traversal. `onClick` records the href here
+ * on its way out, the very next popstate consumes it, and anything that starts
+ * a real navigation or submission drops it so it cannot leak across.
+ *
+ * Underscore-prefixed because no source module reads the binding (they go
+ * through the three functions below); its only reader is the test suite, and
+ * this file's own convention is that an unprefixed export here reads as public
+ * API.
+ *
+ * @type {string | null}
+ */
+export let _pendingFragmentNav = null;
+
+/**
+ * Record that a bowed-out fragment click is about to fire a popstate.
+ *
+ * @param {string} href The absolute href the click is navigating to.
+ */
+export function markFragmentNav(href) { _pendingFragmentNav = href; }
+
+/**
+ * Consume the pending mark if it matches, and clear it either way. Clearing on
+ * a MISS matters as much as on a hit: a mark that outlived its popstate must
+ * not sit around waiting to swallow an unrelated one.
+ *
+ * @param {string} href `location.href` at popstate time.
+ * @returns {boolean} True when this popstate is the one that click produced.
+ */
+export function consumeFragmentNav(href) {
+  const hit = _pendingFragmentNav !== null && _pendingFragmentNav === href;
+  _pendingFragmentNav = null;
+  return hit;
+}
+
+/** Drop the pending mark. Any real navigation or submission invalidates it. */
+export function clearFragmentNav() { _pendingFragmentNav = null; }

package/src/router-client/swap.js

@@ -51,10 +51,13 @@ export let _swapCommit = Promise.resolve();
  *   DOM mutation, for the same reason `ingestSeeds` is: this function can still
  *   decide to throw the response away after parsing it, and a `pushState`
  *   issued for a swap that never happened is worse than a late one. It runs
- *   BEFORE the incoming document replaces what is on screen, because WebKit
- *   binds a same-document entry's back-forward gesture snapshot to the page
- *   state at the moment the entry is recorded, and a snapshot taken against
- *   the incoming (often shorter) document previews blank.
+ *   BEFORE the incoming document replaces what is on screen, so the entry for
+ *   the page being left is finalized while that page is still the live
+ *   document (#1406, and Turbo Drive's ordering).
+ *
+ *   NOTE: #1406 believed this ordering fixed the blank iOS back-swipe
+ *   preview. It does not, shown on-device in #1428; the cause was
+ *   `history.scrollRestoration = 'manual'`.
  *
  *   "Before the content swap" is the precise claim, NOT "before anything on
  *   the page has changed". The page may already have been mutated by the time

package/src/router-client.d.ts

@@ -2,7 +2,7 @@ import type { Route } from './routes.js';
 
 export function enableClientRouter(): void;
 export function disableClientRouter(): void;
-export function navigate(url: Route, opts?: { replace?: boolean }): Promise<void>;
+export function navigate(url: Route, opts?: { replace?: boolean; scroll?: boolean }): Promise<void>;
 export function loadFrame(
   frameEl: Element,
   url: string,

package/src/router-client.js

@@ -95,6 +95,9 @@ export {
   prefetchSuppressed as _prefetchSuppressed,
   prefetchTake as _prefetchTake,
 } from './router-client/prefetch.js';
+export {
+  resolvePreserveScroll as _resolvePreserveScroll,
+} from './router-client/scroll.js';
 export {
   snapshotCache as _snapshotCache,
 } from './router-client/snapshot-cache.js';

package/src/suspense.d.ts

@@ -0,0 +1,9 @@
+export interface SuspenseBoundary {
+  _$webjsSuspense: true;
+  fallback: unknown;
+  children: unknown;
+}
+
+export function Suspense(props: { fallback: unknown; children: unknown | Promise<unknown> }): SuspenseBoundary;
+export function isSuspense(x: unknown): x is SuspenseBoundary;
+export const SUSPENSE: unique symbol;

package/src/webjs-config.d.ts

@@ -144,6 +144,46 @@ export interface WebjsStartTasks {
   before?: string[];
 }
 
+/** One command step of `webjs ci` (#1471). */
+export interface WebjsCiCommand {
+  /** Shown in the step heading and its result line. */
+  title: string;
+  /** The shell command, run with `node_modules/.bin` on PATH and `CI=true` in the environment. */
+  run: string;
+  /** Extra environment for this step only, e.g. `{ WEBJS_E2E: '1' }`. */
+  env?: Record<string, string>;
+}
+
+/** A step inside a group: a nested group takes ONE slot of its parent and runs sequentially, so it cannot declare `parallel`. */
+export interface WebjsCiNestedGroup {
+  /** The group name. */
+  title: string;
+  /** The group's steps, run in order. */
+  steps: WebjsCiNestedStep[];
+}
+
+/** A top-level group of `webjs ci` steps. */
+export interface WebjsCiGroup extends WebjsCiNestedGroup {
+  /** How many steps run at once (default 1, sequential). Captured output is replayed whole per step, never interleaved. */
+  parallel?: number;
+}
+
+/** A top-level `webjs ci` step: a string is shorthand for a command whose title is the command. */
+export type WebjsCiStep = string | WebjsCiCommand | WebjsCiGroup;
+
+/** A step inside a group: the same shapes, minus `parallel` on a nested group. */
+export type WebjsCiNestedStep = string | WebjsCiCommand | WebjsCiNestedGroup;
+
+/**
+ * Local CI in `webjs.ci` (#1471): the step list `webjs ci` runs, and the same
+ * list a cloud pipeline runs through `npm run ci`. Read by the CLI
+ * (`packages/cli/lib/ci-config.js`), not the server.
+ */
+export interface WebjsCiConfig {
+  /** The steps, run in order. A failing step fails the run. Required: a block with no steps is refused, since a run of zero steps would read as green. */
+  steps: WebjsCiStep[];
+}
+
 /**
  * A severity a `webjs.doctor.gate` entry may declare, mirroring ESLint's
  * three-level scale. `error` fails the `webjs doctor` exit, `warn` reports
@@ -227,6 +267,24 @@ export interface WebjsConfig {
   dev?: WebjsDevTasks;
   start?: WebjsStartTasks;
 
+  /**
+   * The `webjs db` verb map (#1468), bring-your-own-ORM. Each key is a verb
+   * and its value the shell command `webjs db <verb>` runs instead of the
+   * drizzle-kit default (node_modules/.bin on PATH, extra args appended), so
+   * `webjs db migrate` keeps one spelling across ORMs:
+   * `{ migrate: 'prisma migrate deploy' }`. Any key is a verb; an unmapped one
+   * keeps its default, so an app with no block is unchanged. Read by the CLI
+   * (`packages/cli/lib/app-tasks.js`), NOT the server.
+   */
+  db?: Record<string, string>;
+
+  /**
+   * Local CI (#1471): the step list `webjs ci` runs locally and a cloud
+   * pipeline runs through `npm run ci`, so the two cannot drift. Read by the
+   * CLI (`packages/cli/lib/ci-config.js`), NOT the server.
+   */
+  ci?: WebjsCiConfig;
+
   /**
    * `webjs doctor` policy (#1257): which project-health checks the project
    * treats as fatal. Read by the CLI (`packages/cli/lib/doctor.js`), NOT the

package/src/websocket-client.d.ts

@@ -0,0 +1,22 @@
+export interface ConnectOptions {
+  onOpen?: (ev: Event) => void;
+  // `any`, matching the JSDoc, and load-bearing rather than lazy: the socket
+  // delivers an arbitrary JSON payload, and the contract is that the CALLER
+  // names the shape it expects (`(msg: ChatMessage) => ...`). Narrowing this to
+  // `unknown` type-checks here and breaks every such handler, which is not a
+  // change a PR filling in missing declarations gets to make.
+  onMessage?: (data: any, ev: MessageEvent) => void;
+  onClose?: (ev: CloseEvent) => void;
+  onError?: (ev: Event) => void;
+  protocols?: string | string[];
+  reconnect?: boolean;
+}
+
+export interface WSConnection {
+  send(data: string | ArrayBuffer | ArrayBufferView | object): void;
+  close(code?: number, reason?: string): void;
+  readonly socket: WebSocket | null;
+  readonly readyState: 0 | 1 | 2 | 3;
+}
+
+export function connectWS(url: string, opts?: ConnectOptions): WSConnection;