@solidjs/router 2.0.0-next.16 → 2.0.0-next.18

package/dist/index.js

@@ -1,4 +1,4 @@
-import { getOwner, runWithOwner, createMemo, createRenderEffect, onCleanup, untrack, createContext, createSignal, useContext, NotReadyError, isPending, flush, createComponent, createRoot, createEffect, sharedConfig, getObserver, $TRACK, action as action$1 } from 'solid-js';
+import { getOwner, runWithOwner, createMemo, createRenderEffect, onCleanup, untrack, createContext, createSignal, useContext, NotReadyError, isPending, DEV, flush, createComponent, createRoot, Show, createEffect, sharedConfig, getObserver, $TRACK, action as action$1 } from 'solid-js';
 import { registerElementClaim, delegateEvents, isServer, getRequestEvent, hasFlashCookie, clearFlashCookie, createComponent as createComponent$1, memo, isServerFunction, getServerFunctionMetadata, getServerFunctionRPC, isResponseEnvelope, REVALIDATE_HEADER } from '@solidjs/web';
 import { subscribeFlightData, decodeResponsePayload, createServerReference } from '@solidjs/web/server-functions';
 import { decodeFlashCookie } from '@solidjs/web/server-functions/server';
@@ -475,6 +475,15 @@ const int = s => /^-?\d+$/.test(s);
 
 const encodeParam = value => String(value).split("/").map(encodeURIComponent).join("/");
 
+/**
+ * The global Href brand (`@solidjs/web` reads the same registry symbol).
+ * On a paths node it holds the logical path — the routable pathname before
+ * `renderPath` decorates it for display (eg. hash mode's `#` prefix) — so
+ * `navigate()` and `redirect()` can route the node while `toString()` keeps
+ * yielding the display href for the DOM.
+ */
+const HREF = Symbol.for("solid.Href");
+
 /**
  * Creates the runtime path proxy. It is instance-scoped: `renderPath` comes
  * from the router's history adapter (eg. hash routing prefixes `#`), and
@@ -500,7 +509,7 @@ function createPathsProxy(renderPath = p => p, base = "") {
     return new Proxy(build, {
       get(_, prop) {
         if (prop === "toString") return () => toHref(pathname);
-        if (typeof prop === "symbol") return prop === Symbol.toPrimitive ? () => toHref(pathname) : undefined;
+        if (typeof prop === "symbol") return prop === Symbol.toPrimitive ? () => toHref(pathname) : prop === HREF ? pathname || "/" : undefined;
         return node(`${pathname}/${prop}`);
       }
     });
@@ -508,13 +517,6 @@ function createPathsProxy(renderPath = p => p, base = "") {
   return node(normalizePath(base));
 }
 
-// Flash-cookie detection/clearing are cookie utilities on the CORE entry
-// (they live beside the cookie codec) — routing is in every app's eager
-// graph and must never import the server-functions package, whose client
-// half is the fetch transport + the seroval codec. The type below is
-// erased at build; only the server-only action path imports that module's
-// values (behind isServer, tree-shaken from client bundles).
-
 const MAX_REDIRECTS = 100;
 
 /** Consider this API opaque and internal. It is likely to change in the future. */
@@ -817,12 +819,17 @@ const encodeSegment = s => encodeURIComponent(s).replace(/%(2B|40|3A|24|26|2C|3B
 const lazyBoundaries = new WeakMap();
 // Module scope: boundary resolution is global, deterministic state (same
 // thunk -> same routes), shared by every factory instance and the server's
-// flight collector.
+// flight collector. The counter is the source of truth; the client mirrors
+// it into a signal for subscription. Server render is pure (signal writes
+// are inert as of solid 2.0.0-rc.3): there the plain counter serves reads,
+// and re-runs come from the parked computation's promise retry, not from
+// reactivity.
+let lazyTreeCounter = 0;
 const [lazyTreeVersion, setLazyTreeVersion] = createSignal(0);
 
 /** Reactive read of the lazy-subtree version — recompile compiled branches when it changes. */
 function trackLazySubtrees() {
-  return lazyTreeVersion();
+  return isServer ? lazyTreeCounter : lazyTreeVersion();
 }
 function getLazyBoundary(thunk) {
   let record = lazyBoundaries.get(thunk);
@@ -834,17 +841,42 @@ function getLazyBoundary(thunk) {
 
 /**
  * Kicks (or joins) a boundary's resolution. Returns the resolved routes
- * synchronously once available, the in-flight promise otherwise. Commit is
- * always async — even for thunks returning arrays — so the version bump
- * never writes a signal from inside a render computation.
+ * synchronously once available, the in-flight promise otherwise.
+ *
+ * Failure contract (same as solid's lazy(), 2.0.0-rc.1: the platform
+ * re-fetches a failed dynamic import): a client rejection is held through its
+ * settlement flush. The recomputes the settled promise triggers — the parked
+ * transition's and the mainline commit's — both consume it here as a
+ * synchronous throw, becoming cached error status that reaches the nearest
+ * error boundary like a failed lazy() component. The hold clears a microtask
+ * after the first delivery, so any later recompute — boundary reset(), a new
+ * navigation — finds a clean record and retries the import. Holding through
+ * the flush is what keeps the erroring computation from refiring the import
+ * in a tight loop while it fails. Server records are shared across requests
+ * and hold nothing — each request retries. Commit is always async — even for
+ * thunks returning arrays — so the version bump never writes a signal from
+ * inside a render computation.
  */
 function resolveLazySubtree(record) {
   if (record.resolved) return record.resolved;
+  if (record.error !== undefined) {
+    if (!record.sweep) {
+      record.sweep = true;
+      queueMicrotask(() => record.error = record.sweep = undefined);
+    }
+    throw record.error;
+  }
   return record.promise ||= Promise.resolve(record.thunk()).then(m => {
     const routes = Array.isArray(m) ? m : m.default || m.routes || [];
     record.resolved = routes;
-    setLazyTreeVersion(v => v + 1);
+    lazyTreeCounter++;
+    isServer || setLazyTreeVersion(lazyTreeCounter);
     return record.resolved;
+  }, e => {
+    // ?? Error(): a held undefined would read as "no failure" and refire
+    if (!isServer) record.error = e ?? new Error();
+    record.promise = undefined;
+    throw e;
   });
 }
 
@@ -992,7 +1024,7 @@ function createLocation(path, state, queryWrapper) {
       // doubled leading slashes would otherwise parse as protocol-relative
       return new URL(path_[0] === "/" ? mockBase + path_ : path_, origin);
     } catch (err) {
-      console.error(`Invalid path ${path_}`);
+      DEV && console.error(`Invalid path ${path_}`);
       return prev;
     }
   }, {
@@ -1143,7 +1175,14 @@ function createRouterContext(integration, branches, getContext, options = {}) {
     // from the carried promise's retry on the server; a boundary nested
     // inside a boundary just parks the recomputed chain again.
     const pending = unresolvedLazyMatches(m);
-    if (pending.length) throw new NotReadyError(Promise.all(pending.map(resolveLazySubtree)));
+    if (pending.length) {
+      const all = Promise.all(pending.map(resolveLazySubtree));
+      // pre-handle rejections: the failure reaches the app through this
+      // computation's error status, so the raw chain must not also surface
+      // as an unhandled rejection
+      all.catch(() => {});
+      throw new NotReadyError(all);
+    }
     return m;
   });
 
@@ -1153,7 +1192,18 @@ function createRouterContext(integration, branches, getContext, options = {}) {
   // window, and isPending over the location/matches read reports any
   // in-flight fork — including popstate traversals and the lazy-subtree
   // resolution matches() parks on.
-  const isRouting = createMemo(() => isNavigating() || isPending(() => (matches(), location.search, location.hash)));
+  const isRouting = createMemo(() => isNavigating() || isPending(() => {
+    // A real error means the navigation settled (failed) — it surfaces
+    // to the app through render reads, not through this derivation.
+    // Not-ready must keep propagating so isPending sees the parking.
+    try {
+      matches();
+    } catch (e) {
+      if (e instanceof NotReadyError) throw e;
+    }
+    location.search;
+    location.hash;
+  }));
   const buildParams = () => mergeParams(matches());
   const wrapParams = utils.paramsWrapper ? getParams => utils.paramsWrapper(getParams, branches) : getParams => createMemoObject(getParams);
   const params = wrapParams(buildParams);
@@ -1195,12 +1245,22 @@ function createRouterContext(integration, branches, getContext, options = {}) {
         if (!to) ; else if (utils.go) {
           utils.go(to);
         } else {
-          console.warn("Router integration does not support relative routing");
+          DEV && console.warn("Router integration does not support relative routing");
         }
         return;
       }
-      // typed path proxy nodes coerce to their href
-      if (typeof to !== "string") to = to.toString();
+      // A paths node carries its logical path under the Href brand — read
+      // that rather than coercing: toString() renders the *display* href
+      // (eg. hash mode's `#` prefix), which is for the DOM, not for routing.
+      // Foreign Href-branded values without the slot still coerce.
+      if (typeof to !== "string") to = to[HREF] || to.toString();
+      // Display hrefs can still arrive as plain strings: terminating paths
+      // calls type as `string`, and redirect Location headers round-trip
+      // through here. Under hash mode those start with `#` — a spelling no
+      // logical path uses — so map them back through the integration's
+      // parser, exactly like the anchor click handler does. Elsewhere
+      // parsePath is identity and `#...` keeps its URL meaning below.
+      if (to[0] === "#") to = parsePath(to);
       const {
         replace,
         resolve,
@@ -1301,9 +1361,15 @@ function createRouterContext(integration, branches, getContext, options = {}) {
     const matches = getRouteMatches(branches(), url.pathname);
     // An unresolved lazy subtree in the chain: the placeholder's
     // component.preload (below) kicks the table load; once it lands,
-    // preload again so the real inner routes warm too.
+    // preload again so the real inner routes warm too. Preloads are
+    // speculative: a failed load (held sync throw or rejection) is ignored
+    // here — the real navigation surfaces and retries it.
     const boundary = matches.find(m => m.route.lazy && !m.route.lazy.resolved);
-    boundary && resolveLazySubtree(boundary.route.lazy).then(() => preloadRoute(url, preloadData));
+    if (boundary) {
+      try {
+        resolveLazySubtree(boundary.route.lazy).then(() => preloadRoute(url, preloadData), () => {});
+      } catch {}
+    }
     const prevIntent = intent;
     intent = "preload";
     for (let match in matches) {
@@ -1508,18 +1574,26 @@ function Routes(props) {
   return memo(outlet);
 }
 const createOutlet = child => {
-  return () => {
-    const c = child();
-    if (c) {
-      return createComponent$1(RouteContextObj, {
-        value: c,
-        get children() {
-          return c.outlet();
-        }
-      });
-    }
-    return undefined;
-  };
+  // Keyed on the context's identity (#588). `when` compiles to a lazy prop
+  // getter, so child() is tracked inside Show's memo — the outlet function
+  // reads nothing reactive and Show owns the subtree. Levels whose context is
+  // reference-reused (parent layouts) keep their subtree across navigations;
+  // a changed context must re-create the provider, not just re-render under
+  // it: a context value is registered once at provider creation
+  // (setContext(provider, props.value)), so non-keyed reuse would leave new
+  // route content reading the previous level's context.
+  return () => createComponent$1(Show, {
+    get when() {
+      return child();
+    },
+    keyed: true,
+    children: c => createComponent$1(RouteContextObj, {
+      value: c,
+      get children() {
+        return c.outlet();
+      }
+    })
+  });
 };
 
 // for data only mode with single flight mutations
@@ -1982,7 +2056,7 @@ function createRouter(config) {
     // fight it — stale content on click navigations, conflicting link
     // attributes. Compose route trees instead; lazy subtrees are the planned
     // answer for definitions unknown at build time.
-    if (useOptionalContext(RouterContextObj)) {
+    if (DEV && useOptionalContext(RouterContextObj)) {
       console.warn("Mounting a router inside another router is not supported. " + "Compose route trees in one createRouter config instead.");
     }
     const root = untrack(() => props.children);
@@ -2139,7 +2213,7 @@ const useBeforeLeave = listener => {
 };
 
 const LocationHeader = "Location";
-const PRELOAD_TIMEOUT = 5000;
+const PRELOAD_TIMEOUT$1 = 5000;
 const CACHE_TIMEOUT = 180000;
 // When this client booted. Flight-registry entries (sharedConfig.has/load)
 // hold values the server computed while rendering THIS page, so their age is
@@ -2165,6 +2239,23 @@ function getCache() {
   return (req.router || (req.router = {})).cache || (req.router.cache = new Map());
 }
 
+// Other keyed stores participating in the data protocols (live query
+// channels) register here — revalidate() stays the one invalidation verb,
+// and single-flight payloads reach every keyed store, not just the cache.
+const revalidateHooks = [];
+function registerRevalidateHook(hook) {
+  revalidateHooks.push(hook);
+}
+const flightHooks = [];
+function registerFlightDataHook(hook) {
+  flightHooks.push(hook);
+}
+/** Fans a single-flight payload out to registered keyed stores (the query
+ * cache itself is seeded by the caller via query.set). */
+function deliverFlightData(data) {
+  for (const hook of flightHooks) hook(data);
+}
+
 /**
  * Revalidates the given cache entry/entries.
  */
@@ -2174,6 +2265,8 @@ function revalidate(key, force = true) {
     force && (entry[0] = 0); //force cache miss
     entry[4][1](now); // retrigger live signals
   });
+  const keys = key === undefined ? undefined : Array.isArray(key) ? key : [key];
+  for (const hook of revalidateHooks) hook(keys, force);
 }
 function cacheKeyOp(key, fn) {
   key && !Array.isArray(key) && (key = [key]);
@@ -2227,7 +2320,7 @@ function query(fn, name) {
       tracking = true;
       onCleanup(() => cached[4].count--);
     }
-    if (cached && cached[0] && (isServer || intent === "native" || cached[4].count || Date.now() - cached[0] < PRELOAD_TIMEOUT)) {
+    if (cached && cached[0] && (isServer || intent === "native" || cached[4].count || Date.now() - cached[0] < PRELOAD_TIMEOUT$1)) {
       if (tracking) {
         cached[4].count++;
         cached[4][0](); // track
@@ -2259,7 +2352,7 @@ function query(fn, name) {
     // refetches instead of serving a minutes-old value on a fresh navigation.
     if (!isServer && sharedConfig.has && sharedConfig.has(key)) {
       const payloadAge = now - bootTime;
-      if (!intent || payloadAge < (intent === "native" ? CACHE_TIMEOUT : PRELOAD_TIMEOUT)) {
+      if (!intent || payloadAge < (intent === "native" ? CACHE_TIMEOUT : PRELOAD_TIMEOUT$1)) {
         adopted = true;
         res = sharedConfig.load(key); // hydrating
         // @ts-ignore at least until we add a delete method to sharedConfig
@@ -2741,8 +2834,10 @@ function applyResponseMetadata(metadata, navigate, flightData) {
   }
   // invalidate
   cacheKeyOp(keys, entry => entry[0] = 0);
-  // set cache
+  // set cache — and fan the payload out to other keyed stores (live query
+  // channels adopt delivered values instead of reconnecting)
   flightData && Object.keys(flightData).forEach(k => query.set(k, flightData[k]));
+  flightData && deliverFlightData(flightData);
   // trigger revalidation inside the same transition as the navigation, so
   // the redirect commits atomically with fresh data: surviving consumers
   // (shared layouts) the flight payload didn't seed refetch and hold the
@@ -2782,6 +2877,366 @@ async function handleResponse(response, error, navigate, metadataHandled) {
   } : undefined;
 }
 
+// Matches query's preload lifetime: a channel warmed by preload intent
+// stays held this long waiting for its navigation.
+const PRELOAD_TIMEOUT = 5000;
+
+// The live-source brand (registered symbol — no transport import needed):
+// computations meeting a branded iterable apply live SSR policy (document
+// face takes the first value; hydration re-runs the compute after adoption
+// to reconnect). liveQuery writes it on both faces itself — the server-side
+// resolved iterable and the client-side multicast iterable — so a producer
+// needs no separate live() declaration to be live here.
+const LIVE_SOURCE = Symbol.for("solid.LiveSource");
+const channelMap = new Map();
+// Status outlives the channel (an "idle"/"closed" read after teardown is
+// meaningful), so signals live in their own keyed map.
+const statusMap = new Map();
+function statusSignal(key) {
+  let s = statusMap.get(key);
+  // ownedWrite: the first write happens synchronously inside whatever
+  // computation pulled the channel open — this is channel-owned state, not
+  // the computation's own.
+  if (!s) statusMap.set(key, s = createSignal("idle", {
+    ownedWrite: true
+  }));
+  return s;
+}
+function wake(ch) {
+  const waiters = [...ch.waiters];
+  ch.waiters.clear();
+  for (const w of waiters) w();
+}
+const noStatus = () => {};
+async function connect(ch) {
+  const gen = ch.gen;
+  const setStatus = ch.report ? statusSignal(ch.key)[1] : noStatus;
+  let attempts = 0;
+  setStatus(ch.version ? "reconnecting" : "connecting");
+  while (true) {
+    try {
+      const result = await ch.call();
+      if (gen !== ch.gen || ch.done) {
+        // superseded (reconnect) or torn down while connecting: the arrived
+        // stream must still be ended or its request leaks
+        result?.[Symbol.asyncIterator] && result[Symbol.asyncIterator]().return?.();
+        return;
+      }
+      // A live()-declared producer's own retry loop erases deaths from the
+      // value stream and reports them through onstatus — forward those into
+      // the channel's status so both producer kinds read the same. Its
+      // "closed" is redundant with our own done handling below.
+      if (result !== null && typeof result === "object") {
+        try {
+          result.onstatus = state => {
+            if (gen === ch.gen && state !== "closed") setStatus(state);
+          };
+        } catch {}
+      }
+      const it = result !== null && typeof result === "object" && result[Symbol.asyncIterator] ? result[Symbol.asyncIterator]() : async function* () {
+        yield result;
+      }();
+      ch.close = () => {
+        try {
+          const r = it.return && it.return();
+          if (r && typeof r.then === "function") r.then(undefined, () => {});
+        } catch {}
+      };
+      while (true) {
+        const r = await it.next();
+        if (gen !== ch.gen || ch.done) return;
+        if (r.done) break;
+        ch.latest = r.value;
+        ch.version++;
+        attempts = 0; // healthy value: backoff resets
+        setStatus("connected");
+        wake(ch);
+      }
+      ch.done = true;
+      setStatus("closed");
+      wake(ch);
+      return;
+    } catch (error) {
+      if (gen !== ch.gen || ch.done) return;
+      const status = error?.status;
+      if (!ch.version || typeof status === "number" && status >= 400 && status < 500) {
+        // Terminal: never connected (fail like a normal call), or a
+        // definite rejection — the transport stamps HTTP statuses onto
+        // failures, and a 4xx means the server understood and refused;
+        // retrying cannot change the answer. Consumers rethrow (after
+        // draining the latest value), surfacing to error boundaries.
+        ch.error = error;
+        ch.done = true;
+        setStatus("closed");
+        wake(ch);
+        return;
+      }
+      // A stream that had delivered died transiently (network, 5xx,
+      // severed stream): the channel IS the live layer — reconnect with
+      // backoff, latest value keeps serving meanwhile. (A live()-declared
+      // producer never reaches here; its transport retries.)
+      setStatus("reconnecting");
+      let timer, wakeUp;
+      await new Promise(resolve => {
+        wakeUp = () => resolve();
+        timer = setTimeout(wakeUp, Math.min(500 * 2 ** attempts++, 10000));
+        // connectivity returning wakes the sleep early
+        if (typeof addEventListener === "function") addEventListener("online", wakeUp, {
+          once: true
+        });
+      });
+      clearTimeout(timer);
+      // a timer-woken sleep leaves its once-listener behind otherwise —
+      // one leaked closure per backoff cycle until an online event fires
+      if (typeof removeEventListener === "function") removeEventListener("online", wakeUp);
+      if (gen !== ch.gen || ch.done) return;
+    }
+  }
+}
+function teardown(ch) {
+  // Deferred so a same-key resubscribe in the same tick (a memo re-running
+  // its compute) reuses the connection instead of thrashing it.
+  queueMicrotask(() => {
+    if (ch.count > 0 || ch.map.get(ch.key) !== ch) return;
+    const ended = ch.done; // completed/failed on its own — "closed" persists
+    ch.done = true;
+    ch.close();
+    wake(ch);
+    if (ch.retain) return; // request-scoped: latest stays replayable
+    ch.map.delete(ch.key);
+    if (ch.report && !ended) statusSignal(ch.key)[1]("idle");
+  });
+}
+function openChannel(map, key, call, report, retain) {
+  let ch = map.get(key);
+  if (!ch) {
+    ch = {
+      key,
+      map,
+      count: 0,
+      version: 0,
+      latest: undefined,
+      error: undefined,
+      done: false,
+      waiters: new Set(),
+      gen: 0,
+      close: () => {},
+      call,
+      report,
+      retain
+    };
+    map.set(key, ch);
+    connect(ch);
+  }
+  return ch;
+}
+
+// The consumer half: a branded iterable whose iterators subscribe to the
+// channel lazily (first pull connects — a hydration trace or speculative
+// call opens nothing), replay the latest value immediately, then follow
+// with latest-wins delivery.
+function subscriberIterable(open) {
+  return {
+    [LIVE_SOURCE]: true,
+    [Symbol.asyncIterator]() {
+      const ch = open();
+      ch.count++;
+      let seen = 0;
+      let released = false;
+      const release = () => {
+        if (released) return;
+        released = true;
+        if (--ch.count === 0) teardown(ch);
+      };
+      const pull = async () => {
+        while (true) {
+          if (ch.error && seen >= ch.version) {
+            release();
+            throw ch.error;
+          }
+          if (ch.version > seen) {
+            seen = ch.version;
+            return {
+              done: false,
+              value: ch.latest
+            };
+          }
+          if (ch.done) {
+            release();
+            return {
+              done: true,
+              value: undefined
+            };
+          }
+          await new Promise(resolve => ch.waiters.add(resolve));
+        }
+      };
+      return {
+        next: () => released ? Promise.resolve({
+          done: true,
+          value: undefined
+        }) : pull(),
+        return(value) {
+          release();
+          return Promise.resolve({
+            done: true,
+            value
+          });
+        }
+      };
+    }
+  };
+}
+function reconnectChannel(ch) {
+  ch.gen++;
+  ch.close();
+  ch.error = undefined;
+  ch.done = false;
+  connect(ch);
+}
+function push(ch, value) {
+  ch.latest = value;
+  ch.version++;
+  wake(ch);
+}
+
+// Live channels participate in both data protocols. Registered on first
+// liveQuery() call, not at module scope: a side-effectful top level would
+// anchor this module into graphs that never use it.
+//
+// - Explicit revalidate(key) (force) reconnects — the producer re-yields
+//   current state on invocation by contract.
+// - The post-mutation sweep (force=false) does NOT reconnect: the
+//   connection is alive and is itself the freshness mechanism — a
+//   push-driven producer yields the mutated state on its own, and tearing
+//   down healthy connections on every mutation defeats the model.
+// - Single-flight payloads deliver INTO open channels, exactly as they seed
+//   the query cache: the mutation response is the round trip, the channel
+//   adopts the value immediately, and the live stream stays authoritative
+//   for everything after.
+let hooked = false;
+function hookRevalidate() {
+  if (hooked) return;
+  hooked = true;
+  registerRevalidateHook((keys, force) => {
+    if (!force) return;
+    for (const [k, ch] of channelMap) {
+      if (keys === undefined || matchKey(k, keys)) reconnectChannel(ch);
+    }
+  });
+  registerFlightDataHook(data => {
+    for (const k in data) {
+      const ch = channelMap.get(k);
+      if (!ch || ch.done) continue;
+      const v = data[k];
+      if (v !== null && typeof v === "object" && v[Symbol.asyncIterator]) {
+        // a live key collected server-side arrives stream-shaped: adopt
+        // its yields for as long as it runs (it ends with the response
+        // body); the channel's own connection remains authoritative
+        (async () => {
+          try {
+            for await (const value of v) {
+              if (ch.done) return;
+              push(ch, value);
+            }
+          } catch {}
+        })();
+      } else push(ch, v);
+    }
+  });
+}
+/**
+ * Declares a keyed live query over a value-shaped stream: an async-iterable
+ * producer whose yields are successive VALUES of one logical query, with the
+ * contract that the producer re-yields current state on every invocation.
+ * liveQuery IS the live layer — no separate declaration needed:
+ *
+ * - One connection per (name + args) key, shared by every consumer. Late
+ *   subscribers receive the latest value immediately, delivery is
+ *   latest-wins, and the connection closes when the last consumer leaves.
+ * - A connected stream that dies transiently (network, 5xx) reconnects with
+ *   exponential backoff — the latest value keeps serving meanwhile. A
+ *   definite rejection (4xx: the transport stamps HTTP statuses onto
+ *   failures) ends the channel and surfaces the error to consumers, as does
+ *   a first-connect failure.
+ * - Server functions are declared GET at creation (like `query`). Live
+ *   queries participate in single-flight on the delivery side: a mutation's
+ *   flight payload pushes straight into open channels (the mutation
+ *   response is the round trip), while the post-mutation sweep leaves the
+ *   healthy connection in place — the live stream stays authoritative.
+ * - Calling under preload intent warms the channel (a temporary hold keeps
+ *   it open through the preload window), so navigation renders against an
+ *   already-connected stream instead of holding the transition on connect
+ *   plus first yield. Outside preload, calling remains free — only a real
+ *   pull connects.
+ * - SSR: the document face renders the first value; hydration adopts it and
+ *   reconnects. Channels are request-scoped on the server, so every
+ *   consumer of a key in one render observes the same value. Explicit
+ *   `revalidate(key)` reconnects (the producer re-yields current state on
+ *   invocation), and `status(...args)` is a reactive read of the channel's
+ *   wire state.
+ *
+ * ```ts
+ * const roomMessages = liveQuery(getMessages, "messages");
+ * // in a component — one connection, however many consumers:
+ * const messages = createMemo(() => roomMessages(props.room));
+ * ```
+ */
+function liveQuery(fn, name) {
+  hookRevalidate();
+  // liveQuery implies GET, exactly as query does: reads belong on the GET
+  // transport (cacheable URLs, no single-flight enveloping). An explicit
+  // GET(fn) or live(GET(fn)) declaration passes through untouched.
+  if (isServerFunction(fn) && !getServerFunctionMetadata(fn)?.method) {
+    const rpc = getServerFunctionRPC();
+    if (rpc) fn = rpc.GET(fn);
+  }
+  const liveFn = (...args) => {
+    const key = name + hashKey(args);
+    if (isServer) {
+      const e = getRequestEvent();
+      if (!e) {
+        // No request scope (static render, tests): hand the source through
+        // whole, branded, so the signals layer applies live SSR policy
+        // (first value, then client takeover).
+        const result = fn(...args);
+        const brand = r => {
+          if (r !== null && typeof r === "object" && r[Symbol.asyncIterator]) r[LIVE_SOURCE] = true;
+          return r;
+        };
+        return result !== null && typeof result === "object" && typeof result.then === "function" ? result.then(brand) : brand(result);
+      }
+      // Request-scoped channels: two consumers of one key during one render
+      // must observe the SAME first value (query's request cache gives its
+      // reads the same guarantee). Channels live in the event, retained
+      // past teardown so a later consumer replays the settled value instead
+      // of reinvoking; the producer still closes with its last consumer.
+      const router = e.router || (e.router = {});
+      const channels = router.liveChannels || (router.liveChannels = new Map());
+      return subscriberIterable(() => openChannel(channels, key, () => fn(...args), false, true));
+    }
+    const open = () => openChannel(channelMap, key, () => fn(...args), true, false);
+    // Preload warms the channel, exactly as calling a query in a preload
+    // function warms its cache: connect now, hold a temporary consumer slot
+    // so refcounting doesn't close it before navigation renders. When the
+    // real consumer arrives it inherits the live connection (first pull
+    // replays the already-arrived value — the transition doesn't hold);
+    // when navigation never comes, the hold lapses and teardown closes it.
+    if (getIntent() === "preload") {
+      const ch = open();
+      ch.count++;
+      setTimeout(() => {
+        if (--ch.count === 0) teardown(ch);
+      }, PRELOAD_TIMEOUT);
+    }
+    return subscriberIterable(open);
+  };
+  liveFn.keyFor = (...args) => name + hashKey(args);
+  liveFn.key = name;
+  liveFn.status = (...args) => statusSignal(name + hashKey(args))[0]();
+  return liveFn;
+}
+
 // The delegation fallback's lazy entry (see data/events.ts). Nothing imports
 // this module statically — it exists so the dynamic import has a target that
 // bundlers can keep as a split point: router-only apps never load the action
@@ -2792,4 +3247,4 @@ var serverForms = /*#__PURE__*/Object.freeze({
   submitServerForm: submitServerForm
 });
 
-export { RouterContextObj as RouterContext, mergeSearchString as _mergeSearchString, action, browserHistory, createBeforeLeave, createRouter, defineRoute, defineRoutes, hashHistory, int, memoryHistory, query, revalidate, useAction, useBeforeLeave, useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, useParams, usePreloadRoute, useResolvedPath, useRouteMatches, useSearchParams, useSubmissions };
+export { RouterContextObj as RouterContext, mergeSearchString as _mergeSearchString, action, browserHistory, createBeforeLeave, createRouter, defineRoute, defineRoutes, hashHistory, int, liveQuery, memoryHistory, query, revalidate, useAction, useBeforeLeave, useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, useParams, usePreloadRoute, useResolvedPath, useRouteMatches, useSearchParams, useSubmissions };