sibujs 4.13.0 → 4.14.0

package/dist/{chunk-24L5RDPS.js → chunk-Y4LUM2XS.js}

@@ -3,22 +3,24 @@ import {
 } from "./chunk-7ZHH77QA.js";
 import {
   effect
-} from "./chunk-BRRRVLHQ.js";
+} from "./chunk-AE32RGWX.js";
 import {
   stripHtml
-} from "./chunk-EXXSN3BW.js";
+} from "./chunk-B3HOT4TK.js";
 import {
   signal
-} from "./chunk-GNSRXK34.js";
+} from "./chunk-4FJSAUKB.js";
 import {
   forEachSubscriber,
   getSubscriberCount,
   getSubscriberDeps
-} from "./chunk-HVVRXRGO.js";
+} from "./chunk-MIRKTVH4.js";
+import {
+  dispose
+} from "./chunk-S37PZD6I.js";
 import {
-  dispose,
   isDev
-} from "./chunk-NYNYSPK7.js";
+} from "./chunk-NT3ZYB5S.js";
 
 // src/devtools/debug.ts
 var debugEnabled = false;

package/dist/data.cjs

@@ -42,7 +42,8 @@ __export(data_exports, {
   syncAdapter: () => syncAdapter,
   throttle: () => throttle,
   withLoader: () => withLoader,
-  withRetry: () => withRetry
+  withRetry: () => withRetry,
+  withholdTransfer: () => withholdTransfer
 });
 module.exports = __toCommonJS(data_exports);
 
@@ -112,12 +113,12 @@ function claimedByBoundary(error, context) {
 }
 function resolveEventTarget(node) {
   const ELEMENT_NODE = 1;
-  let current = node;
-  while (current) {
-    if (current.nodeType === ELEMENT_NODE && typeof current.dispatchEvent === "function") {
-      return current;
+  let current2 = node;
+  while (current2) {
+    if (current2.nodeType === ELEMENT_NODE && typeof current2.dispatchEvent === "function") {
+      return current2;
     }
-    current = current.parentNode;
+    current2 = current2.parentNode;
   }
   const self = node;
   return typeof self.dispatchEvent === "function" ? self : null;
@@ -126,10 +127,21 @@ function defaultReport(error, context) {
   if (typeof console === "undefined") return;
   console.error(`[SibuJS] Uncaught error during ${describe(context)}: ${error.message}`, error);
 }
+function requestErrorSink() {
+  const shared = globalThis[/* @__PURE__ */ Symbol.for("sibujs.ssr.v1")];
+  if (!shared) return void 0;
+  const store = shared.als ? shared.als.getStore() : shared.fallbackDepth > 0 ? shared.fallbackStore : void 0;
+  return store?.errors;
+}
 function reportError(error, context) {
   const err = normalizeError(error);
   untrackedRun(() => {
     if (claimedByBoundary(err, context)) return;
+    const sink = requestErrorSink();
+    if (sink) {
+      sink.push({ error: err, context });
+      return;
+    }
     const s = state();
     const handler = s.handler;
     if (handler && s.handlerDepth === 0) {
@@ -150,6 +162,32 @@ function reportError(error, context) {
   });
 }
 
+// src/core/rendering/adoptScope.ts
+var current = null;
+function currentSink() {
+  return current?.s.on ? current.s : null;
+}
+
+// src/core/rendering/hydrationHooks.ts
+var _a;
+var slot = globalThis[_a = /* @__PURE__ */ Symbol.for("sibujs.hydration.v2")] ?? (globalThis[_a] = { a: /* @__PURE__ */ new Set(), c: null });
+function ownSession() {
+  return currentSink()?.h ?? slot.c;
+}
+function hydrationOwners() {
+  const own = ownSession();
+  return own ? own.open ? [own] : [] : Array.from(slot.a);
+}
+function notify(session) {
+  for (const wake of Array.from(session.wake)) wake();
+}
+function holdHydration(sessions, entry) {
+  for (const s of sessions) s.pending.add(entry);
+  return () => {
+    for (const s of sessions) if (s.pending.delete(entry)) notify(s);
+  };
+}
+
 // src/core/rendering/dispose.ts
 function resolveCapture(capture) {
   let frame = capture;
@@ -737,7 +775,7 @@ function forEachSubscriber(signal2, visit) {
 }
 
 // src/reactivity/track.ts
-var _runtimeVersion = true ? "4.13.0" : "dev";
+var _runtimeVersion = true ? "4.14.0" : "dev";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("sibujs.reactive.v1");
 function resolveReactiveApi() {
   const g = globalThis;
@@ -919,6 +957,13 @@ function derived(getter, options) {
   return computedGetter;
 }
 
+// src/core/rendering/streamBoundary.ts
+var _a2;
+var slot2 = globalThis[_a2 = /* @__PURE__ */ Symbol.for("sibujs.streamBoundary.v1")] ?? (globalThis[_a2] = { hook: null, current: null });
+function currentBoundary() {
+  return slot2.current;
+}
+
 // src/core/ssr-context.ts
 var SSR_KEY = /* @__PURE__ */ Symbol.for("sibujs.ssr.v1");
 function detectSSRShared() {
@@ -934,6 +979,8 @@ function detectSSRShared() {
       }
       if (mod) detected = new mod.AsyncLocalStorage();
     }
+    const globalAls = globalThis.AsyncLocalStorage;
+    if (!detected && typeof globalAls === "function") detected = new globalAls();
   } catch {
     detected = null;
   }
@@ -954,6 +1001,10 @@ function getSSRStore() {
   }
   return fallbackStore;
 }
+function getRequestStore() {
+  if (als) return als.getStore() ?? null;
+  return _shared.fallbackDepth > 0 ? fallbackStore : null;
+}
 function isSSR() {
   return getSSRStore().ssr;
 }
@@ -968,6 +1019,33 @@ function getRequestScopedCache(name) {
   }
   return c;
 }
+function requestSlot(name, create) {
+  const store = getRequestStore();
+  if (!store) return void 0;
+  const slots = store.slots ?? (store.slots = /* @__PURE__ */ new Map());
+  if (!slots.has(name) && create) slots.set(name, create());
+  return slots.get(name);
+}
+function trackPending(promise, label, hydration = true) {
+  const store = getRequestStore();
+  const pending = store?.pending;
+  const sessions = pending || !hydration ? [] : hydrationOwners();
+  if (!pending && sessions.length === 0) return promise;
+  const entry = { label, since: Date.now(), boundary: currentBoundary() ?? void 0 };
+  pending?.add(entry);
+  const release = holdHydration(sessions, entry);
+  const done = () => {
+    pending?.delete(entry);
+    store?.wake?.();
+    release();
+  };
+  try {
+    Promise.resolve(promise).then(done, done);
+  } catch {
+    done();
+  }
+  return promise;
+}
 
 // src/core/signals/effect.ts
 var _g = globalThis;
@@ -1033,7 +1111,7 @@ function disposeEffect(ctx) {
 }
 function effect(effectFn, options) {
   devAssert(typeof effectFn === "function", "effect: argument must be a function.");
-  if (isSSR()) return () => {
+  if (isSSR() && !options?.server) return () => {
   };
   const ctx = {
     fn: effectFn,
@@ -1230,6 +1308,73 @@ function globalSingleton(key, create) {
   return g[key] ?? (g[key] = create());
 }
 
+// src/utils/guards.ts
+var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isUnsafeKey(key) {
+  return UNSAFE_KEYS.has(key);
+}
+function readOwnGlobal(key) {
+  if (typeof window === "undefined") return void 0;
+  if (!Object.hasOwn(window, key)) return void 0;
+  const value = window[key];
+  if (typeof Node !== "undefined" && value instanceof Node) return void 0;
+  return value;
+}
+
+// src/utils/transfer.ts
+var TRANSFER_GLOBAL = "__SIBU_TRANSFER__";
+var TRANSFER_VERSION = 1;
+var REGISTRY_KEY2 = /* @__PURE__ */ Symbol.for("sibujs.transfer.v1");
+function registry() {
+  const g = globalThis;
+  let r = g[REGISTRY_KEY2];
+  if (!r) {
+    r = { collectors: /* @__PURE__ */ new Map(), payload: void 0 };
+    g[REGISTRY_KEY2] = r;
+  }
+  return r;
+}
+function registerTransferCollector(section, collect) {
+  registry().collectors.set(section, collect);
+}
+function isPlainRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function readPayload() {
+  const r = registry();
+  if (r.payload !== void 0) return r.payload;
+  r.payload = null;
+  if (typeof window === "undefined" || getRequestStore()) return null;
+  const raw = readOwnGlobal(TRANSFER_GLOBAL);
+  if (!isPlainRecord(raw) || raw.v !== TRANSFER_VERSION) return null;
+  const sections = /* @__PURE__ */ Object.create(null);
+  for (const key of Object.keys(raw)) {
+    const section = raw[key];
+    if (key === "v" || isUnsafeKey(key) || !isPlainRecord(section)) continue;
+    const entries = /* @__PURE__ */ Object.create(null);
+    for (const k of Object.keys(section)) if (!isUnsafeKey(k)) entries[k] = section[k];
+    sections[key] = entries;
+  }
+  r.payload = sections;
+  return sections;
+}
+function takeTransferred(section, key) {
+  const entries = readPayload()?.[section];
+  if (!entries || !Object.hasOwn(entries, key)) return void 0;
+  const value = entries[key];
+  delete entries[key];
+  return value;
+}
+function takeTransferredSection(section) {
+  const payload = readPayload();
+  const entries = payload?.[section];
+  if (!payload || !entries) return {};
+  delete payload[section];
+  return entries;
+}
+
 // src/data/abort.ts
 function isAbortError(error) {
   return typeof error === "object" && error !== null && error.name === "AbortError";
@@ -1424,8 +1569,34 @@ function sharedView(entry) {
 }
 var globalQueryCache = globalSingleton(/* @__PURE__ */ Symbol.for("sibujs.query.cache.v1"), () => /* @__PURE__ */ new Map());
 function getActiveQueryCache() {
-  return getRequestScopedCache("query") ?? globalQueryCache;
-}
+  const requestCache = getRequestScopedCache("query");
+  if (requestCache) return requestCache;
+  primeFromTransfer();
+  return globalQueryCache;
+}
+var SERVER_EFFECT = { server: true };
+function primeFromTransfer() {
+  const entries = takeTransferredSection("q");
+  const now = Date.now();
+  for (const key of Object.keys(entries)) {
+    const record = entries[key];
+    if (!record || typeof record !== "object" || record.d === void 0) continue;
+    if (globalQueryCache.has(key)) continue;
+    const entry = getOrCreateEntry(globalQueryCache, key, record.d);
+    const t = typeof record.t === "number" && Number.isFinite(record.t) ? record.t : now;
+    entry.dataUpdatedAt = Math.min(t, now);
+  }
+}
+registerTransferCollector("q", () => {
+  const cache = getRequestScopedCache("query");
+  if (!cache) return void 0;
+  const out = {};
+  for (const [key, entry] of cache) {
+    if (entry.noTransfer || entry.data === void 0 || entry.error) continue;
+    out[key] = { d: entry.data, t: entry.dataUpdatedAt };
+  }
+  return out;
+});
 function abandonEntry(entry) {
   if (entry.gcTimer) clearTimeout(entry.gcTimer);
   entry.gcTimer = null;
@@ -1471,11 +1642,13 @@ function query(key, fetcher, options = {}) {
     onError,
     onSettled,
     select,
-    structuralSharing = true
+    structuralSharing = true,
+    ssr = true
   } = options;
+  const onServer = isSSR();
   const resolveKey = typeof key === "function" ? key : () => key;
   const enabledGate = typeof enabled === "function" ? derived(() => Boolean(enabled())) : null;
-  const isEnabled = enabledGate ?? (() => Boolean(enabled));
+  const isEnabled = onServer && !ssr ? () => false : enabledGate ?? (() => Boolean(enabled));
   const cache = getActiveQueryCache();
   const [data, setData] = signal(initialData);
   const [isFetching, setIsFetching] = signal(false);
@@ -1549,7 +1722,7 @@ function query(key, fetcher, options = {}) {
     selectedEntry = entry;
     selectedValue = value;
     setData(value);
-  }) : null;
+  }, SERVER_EFFECT) : null;
   function detachFromEntry() {
     const entry = attachedEntry;
     const key2 = attachedKey;
@@ -1563,9 +1736,9 @@ function query(key, fetcher, options = {}) {
     if (cache.get(key2) !== entry) return;
     if (entry.gcTimer !== null) clearTimeout(entry.gcTimer);
     entry.gcTimer = setTimeout(() => {
-      const current = cache.get(key2);
-      if (current === entry && current.subscribers <= 0) {
-        abandonEntry(current);
+      const current2 = cache.get(key2);
+      if (current2 === entry && current2.subscribers <= 0) {
+        abandonEntry(current2);
         cache.delete(key2);
       }
     }, cacheTime);
@@ -1632,7 +1805,7 @@ function query(key, fetcher, options = {}) {
       runCallback("query onSettled", () => onSettled?.());
       return;
     }
-    entry.promise = promise;
+    entry.promise = trackPending(promise, `query:${key2}`, false);
     try {
       const result = await promise;
       if (entry.generation !== generation) return;
@@ -1704,6 +1877,7 @@ function query(key, fetcher, options = {}) {
       return;
     }
     const entry = getOrCreateEntry(cache, key2, initialData);
+    if (!ssr) entry.noTransfer = true;
     const reattached = attachedEntry !== entry;
     attachToEntry(entry, key2);
     if (keyChanged) setIsFetching(entry.promise !== null);
@@ -1725,15 +1899,15 @@ function query(key, fetcher, options = {}) {
     if (on && (entry.data === void 0 || isDataStale)) {
       doFetch();
     }
-  });
-  if (refetchInterval && refetchInterval > 0) {
+  }, SERVER_EFFECT);
+  if (!onServer && refetchInterval && refetchInterval > 0) {
     intervalTimer = setInterval(() => {
       if (!disposed && currentKey) doFetch();
     }, refetchInterval);
   }
   let focusHandler = null;
   let onlineHandler = null;
-  if (typeof globalThis !== "undefined" && typeof globalThis.addEventListener === "function") {
+  if (!onServer && typeof globalThis !== "undefined" && typeof globalThis.addEventListener === "function") {
     if (refetchOnWindowFocus) {
       focusHandler = () => {
         if (!disposed && currentKey) doFetch();
@@ -2077,12 +2251,12 @@ function infiniteQuery(key, fetcher, options) {
 // src/data/previous.ts
 function previous(getter) {
   const [previous2, setPrevious] = signal(void 0);
-  let current = getter();
+  let current2 = getter();
   const stop = effect(() => {
     const next = getter();
-    if (!Object.is(next, current)) {
-      setPrevious(current);
-      current = next;
+    if (!Object.is(next, current2)) {
+      setPrevious(current2);
+      current2 = next;
     }
   });
   Object.defineProperty(previous2, "dispose", {
@@ -2162,6 +2336,28 @@ function throttle(getter, interval) {
 }
 
 // src/data/resource.ts
+function transferSlot() {
+  return requestSlot("resource:transfer", () => /* @__PURE__ */ new Map());
+}
+function withheldSlot() {
+  return requestSlot("resource:transfer:withheld", () => /* @__PURE__ */ new Set());
+}
+registerTransferCollector("r", () => {
+  const slot3 = transferSlot();
+  if (!slot3 || slot3.size === 0) return void 0;
+  const withheld = withheldSlot();
+  const out = {};
+  let any = false;
+  for (const [key, value] of slot3) {
+    if (withheld?.has(key)) continue;
+    out[key] = value;
+    any = true;
+  }
+  return any ? out : void 0;
+});
+function withholdTransfer(key) {
+  withheldSlot()?.add(key);
+}
 function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
   let source = null;
   let fetcher;
@@ -2175,10 +2371,14 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
     fetcher = (_source, info) => rawFetcher(info);
     options = fetcherOrOptions ?? {};
   }
-  const [data, setData] = signal(options.initialValue);
+  const transferred = options.key !== void 0 ? takeTransferred("r", options.key) : void 0;
+  const hydrated = transferred !== void 0;
+  const initialValue = hydrated ? transferred : options.initialValue;
+  const onServer = isSSR();
+  const [data, setData] = signal(initialValue);
   const [loading, setLoading] = signal(false);
   const [error, setError] = signal(void 0);
-  let currentData = options.initialValue;
+  let currentData = initialValue;
   function commitData(next, explicit) {
     const sharing = options.structuralSharing ?? true;
     const shared = untracked2(
@@ -2186,6 +2386,7 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
     );
     currentData = shared.ok ? shared.value : next;
     setData(currentData);
+    if (onServer && options.key !== void 0) transferSlot()?.set(options.key, currentData);
     return currentData;
   }
   let abortController = null;
@@ -2231,19 +2432,28 @@ function resource(sourceOrFetcher, fetcherOrOptions, maybeOptions) {
       }
     }
   }
+  const run = (sourceValue) => trackPending(doFetch(sourceValue), "resource", false);
   if (source) {
-    effectCleanup = effect(() => {
-      const sourceValue = source();
-      doFetch(sourceValue);
-    });
-  } else if (options.immediate !== false) {
-    doFetch(void 0);
+    let skipFirst = hydrated;
+    effectCleanup = effect(
+      () => {
+        const sourceValue = source();
+        if (skipFirst) {
+          skipFirst = false;
+          return;
+        }
+        run(sourceValue);
+      },
+      { server: true }
+    );
+  } else if (options.immediate !== false && !hydrated) {
+    run(void 0);
   }
   return {
     data,
     loading,
     error,
-    refetch: () => doFetch(source ? source() : void 0),
+    refetch: () => run(source ? source() : void 0),
     mutate: (value) => {
       const newValue = typeof value === "function" ? value(currentData) : value;
       commitData(newValue, true);
@@ -2544,8 +2754,27 @@ function currentScope() {
   }
   return scope;
 }
+function automaticKey(loader, context) {
+  const key = `loader:${context.path}${loader.name ? `:${loader.name}` : ""}`;
+  const cache = getRequestScopedCache("routeLoader");
+  if (!cache) return key;
+  let owners = cache.get("owners");
+  if (!owners) {
+    owners = /* @__PURE__ */ new Map();
+    cache.set("owners", owners);
+  }
+  const owner = owners.get(key);
+  if (owner === void 0) {
+    owners.set(key, loader);
+    return key;
+  }
+  if (owner === loader) return key;
+  withholdTransfer(key);
+  return void 0;
+}
 function executeLoader(loader, context, options) {
-  const res = resource(({ signal: signal2 }) => loader(context, { signal: signal2 }), options);
+  const key = options?.key ?? automaticKey(loader, context);
+  const res = resource(({ signal: signal2 }) => loader(context, { signal: signal2 }), { ...options, key });
   const disposeResource = res.dispose;
   res.dispose = () => {
     _disposed.add(res);
@@ -2912,5 +3141,6 @@ function stream(url, options) {
   syncAdapter,
   throttle,
   withLoader,
-  withRetry
+  withRetry,
+  withholdTransfer
 });

package/dist/data.d.cts

@@ -222,6 +222,14 @@ interface QueryOptions<T> {
      * Also applied to this observer's `select` output.
      */
     structuralSharing?: StructuralSharingOption<T>;
+    /**
+     * Fetch during a server render (default `true`). The server render waits for
+     * the fetch and transfers the result to the browser, which then does not
+     * fetch it again while it is fresh (`staleTime`). `false` leaves the query
+     * idle on the server — it renders its loading state — and keeps its data out
+     * of the transferred state; the browser fetches it after takeover.
+     */
+    ssr?: boolean;
 }
 interface QueryResult<T> {
     /** Reactive getter for the cached data */
@@ -452,6 +460,14 @@ declare function debounce<T>(getter: () => T, delay: number): DisposableAccessor
  */
 declare function throttle<T>(getter: () => T, interval: number): DisposableAccessor<T>;
 
+/**
+ * Keep `key` out of this request's transferred state, whatever is or will be
+ * stored under it: the browser then fetches it itself. For a key whose owner
+ * is ambiguous (two loaders resolved to it). Server only; a no-op outside a
+ * request.
+ * @internal
+ */
+declare function withholdTransfer(key: string): void;
 /**
  * Lifecycle callbacks follow the shared data-layer contract: an exception
  * thrown by `onStart`, `onSuccess`, `onError`, or `onSettled` never changes the
@@ -497,6 +513,13 @@ interface ResourceOptions<T> {
      *   unshared.
      */
     structuralSharing?: StructuralSharingOption<T>;
+    /**
+     * Transfer key. With a key, the value a server render fetched is embedded in
+     * the document, and the browser starts from it instead of fetching again
+     * (its initial fetch is skipped; `refetch()` and source changes still
+     * fetch). Must be unique per page; the data must be JSON-serializable.
+     */
+    key?: string;
 }
 interface Resource<T> {
     /** Reactive getter for the fetched data */
@@ -676,6 +699,13 @@ interface LoaderRoute {
 /**
  * Execute a route loader and wrap its result in a reactive Resource.
  *
+ * The result is transferred from a server render to the browser under the key
+ * `loader:<path>:<loader name>` (or `options.key`), so the browser does not run
+ * the loader again on takeover. Two different loader functions with the same
+ * name for the same path (two `loader: async () => …` properties, two
+ * anonymous loaders) cannot be told apart: neither transfers, and both fetch in
+ * the browser, unless they have explicit keys.
+ *
  * Executing a loader does not make its data visible to `loaderData()`; render
  * the route's component inside {@link renderWithLoader} (or use
  * {@link withLoader}) so the component reads its own route's data.
@@ -777,4 +807,4 @@ declare function stream(url: string, options?: {
     dispose: () => void;
 };
 
-export { type ConflictStrategy, type InfiniteQueryOptions, type InfiniteQueryResult, type LoaderRoute, type MutationOptions, type MutationResult, type OfflineStore, type OfflineStoreOptions, type QueryOptions, type QueryResult, type Resource, type ResourceOptions, type RetryOptions, type RouteLoaderFn, type SyncAdapter, type SyncChange, type SyncConflict, type SyncResult, __resetQueryCache, calculateDelay, clearQueryCache, debounce, executeLoader, getQueryData, infiniteQuery, invalidateQueries, loaderData, mutation, offlineStore, preloadRoute, previous, query, renderWithLoader, resource, setQueryData, socket, stream, syncAdapter, throttle, withLoader, withRetry };
+export { type ConflictStrategy, type InfiniteQueryOptions, type InfiniteQueryResult, type LoaderRoute, type MutationOptions, type MutationResult, type OfflineStore, type OfflineStoreOptions, type QueryOptions, type QueryResult, type Resource, type ResourceOptions, type RetryOptions, type RouteLoaderFn, type SyncAdapter, type SyncChange, type SyncConflict, type SyncResult, __resetQueryCache, calculateDelay, clearQueryCache, debounce, executeLoader, getQueryData, infiniteQuery, invalidateQueries, loaderData, mutation, offlineStore, preloadRoute, previous, query, renderWithLoader, resource, setQueryData, socket, stream, syncAdapter, throttle, withLoader, withRetry, withholdTransfer };

package/dist/data.d.ts

@@ -222,6 +222,14 @@ interface QueryOptions<T> {
      * Also applied to this observer's `select` output.
      */
     structuralSharing?: StructuralSharingOption<T>;
+    /**
+     * Fetch during a server render (default `true`). The server render waits for
+     * the fetch and transfers the result to the browser, which then does not
+     * fetch it again while it is fresh (`staleTime`). `false` leaves the query
+     * idle on the server — it renders its loading state — and keeps its data out
+     * of the transferred state; the browser fetches it after takeover.
+     */
+    ssr?: boolean;
 }
 interface QueryResult<T> {
     /** Reactive getter for the cached data */
@@ -452,6 +460,14 @@ declare function debounce<T>(getter: () => T, delay: number): DisposableAccessor
  */
 declare function throttle<T>(getter: () => T, interval: number): DisposableAccessor<T>;
 
+/**
+ * Keep `key` out of this request's transferred state, whatever is or will be
+ * stored under it: the browser then fetches it itself. For a key whose owner
+ * is ambiguous (two loaders resolved to it). Server only; a no-op outside a
+ * request.
+ * @internal
+ */
+declare function withholdTransfer(key: string): void;
 /**
  * Lifecycle callbacks follow the shared data-layer contract: an exception
  * thrown by `onStart`, `onSuccess`, `onError`, or `onSettled` never changes the
@@ -497,6 +513,13 @@ interface ResourceOptions<T> {
      *   unshared.
      */
     structuralSharing?: StructuralSharingOption<T>;
+    /**
+     * Transfer key. With a key, the value a server render fetched is embedded in
+     * the document, and the browser starts from it instead of fetching again
+     * (its initial fetch is skipped; `refetch()` and source changes still
+     * fetch). Must be unique per page; the data must be JSON-serializable.
+     */
+    key?: string;
 }
 interface Resource<T> {
     /** Reactive getter for the fetched data */
@@ -676,6 +699,13 @@ interface LoaderRoute {
 /**
  * Execute a route loader and wrap its result in a reactive Resource.
  *
+ * The result is transferred from a server render to the browser under the key
+ * `loader:<path>:<loader name>` (or `options.key`), so the browser does not run
+ * the loader again on takeover. Two different loader functions with the same
+ * name for the same path (two `loader: async () => …` properties, two
+ * anonymous loaders) cannot be told apart: neither transfers, and both fetch in
+ * the browser, unless they have explicit keys.
+ *
  * Executing a loader does not make its data visible to `loaderData()`; render
  * the route's component inside {@link renderWithLoader} (or use
  * {@link withLoader}) so the component reads its own route's data.
@@ -777,4 +807,4 @@ declare function stream(url: string, options?: {
     dispose: () => void;
 };
 
-export { type ConflictStrategy, type InfiniteQueryOptions, type InfiniteQueryResult, type LoaderRoute, type MutationOptions, type MutationResult, type OfflineStore, type OfflineStoreOptions, type QueryOptions, type QueryResult, type Resource, type ResourceOptions, type RetryOptions, type RouteLoaderFn, type SyncAdapter, type SyncChange, type SyncConflict, type SyncResult, __resetQueryCache, calculateDelay, clearQueryCache, debounce, executeLoader, getQueryData, infiniteQuery, invalidateQueries, loaderData, mutation, offlineStore, preloadRoute, previous, query, renderWithLoader, resource, setQueryData, socket, stream, syncAdapter, throttle, withLoader, withRetry };
+export { type ConflictStrategy, type InfiniteQueryOptions, type InfiniteQueryResult, type LoaderRoute, type MutationOptions, type MutationResult, type OfflineStore, type OfflineStoreOptions, type QueryOptions, type QueryResult, type Resource, type ResourceOptions, type RetryOptions, type RouteLoaderFn, type SyncAdapter, type SyncChange, type SyncConflict, type SyncResult, __resetQueryCache, calculateDelay, clearQueryCache, debounce, executeLoader, getQueryData, infiniteQuery, invalidateQueries, loaderData, mutation, offlineStore, preloadRoute, previous, query, renderWithLoader, resource, setQueryData, socket, stream, syncAdapter, throttle, withLoader, withRetry, withholdTransfer };

package/dist/data.js

@@ -21,16 +21,21 @@ import {
   syncAdapter,
   throttle,
   withLoader,
-  withRetry
-} from "./chunk-QV5WEOFD.js";
-import "./chunk-YJ57VR6Y.js";
+  withRetry,
+  withholdTransfer
+} from "./chunk-SVULV7O4.js";
+import "./chunk-3HZOSMPX.js";
+import "./chunk-62BDYGAG.js";
+import "./chunk-N7A6FKWW.js";
 import "./chunk-7ZHH77QA.js";
-import "./chunk-BRRRVLHQ.js";
-import "./chunk-EXXSN3BW.js";
-import "./chunk-7XHATCIH.js";
-import "./chunk-GNSRXK34.js";
-import "./chunk-HVVRXRGO.js";
-import "./chunk-NYNYSPK7.js";
+import "./chunk-AE32RGWX.js";
+import "./chunk-B3HOT4TK.js";
+import "./chunk-UYTYNCMZ.js";
+import "./chunk-4FJSAUKB.js";
+import "./chunk-MIRKTVH4.js";
+import "./chunk-S37PZD6I.js";
+import "./chunk-NT3ZYB5S.js";
+import "./chunk-R5U7XKVJ.js";
 export {
   __resetQueryCache,
   calculateDelay,
@@ -54,5 +59,6 @@ export {
   syncAdapter,
   throttle,
   withLoader,
-  withRetry
+  withRetry,
+  withholdTransfer
 };