@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/render-document.ts

@@ -24,6 +24,7 @@ import type {
   PageLocales,
   RenderAdapter,
   RenderProps,
+  RenderStreamOptions,
 } from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
@@ -33,15 +34,19 @@ import {
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LIVE_GLOBAL,
   LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
+  SWAP_HEADER,
 } from "../render-seam.ts"
 import { PRERENDERED_GLOBAL } from "../router.ts"
 import { trustedHeadAttributes } from "./head-attributes.ts"
 import { isStaticMeta, mergeHeads } from "./head-merge.ts"
+import { reportDeferredRejection } from "./request-abort.ts"
 import { PRE_HYDRATION_GUARD } from "./runtime-contract.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./script-types.ts"
+import type { HeadersLike } from "./status-page.ts"
 
 const TEXT_ENCODER = new TextEncoder()
 
@@ -105,6 +110,11 @@ export interface RenderPageOptions {
   /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
    * for the client so post-POST hydration matches. Omit on GETs. */
   readonly actionData?: unknown
+  /**
+   * A live runtime's seed for this page (`createWebApp({ live })` sets it): handed to the client
+   * entry, which exchanges it for a grant instead of loading the page again.
+   */
+  readonly live?: unknown
   /**
    * URL of the built client entry (loaded as a module script).
    *
@@ -171,6 +181,14 @@ export interface RenderPageOptions {
   readonly matchChain?: MatchChain
   /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
   readonly status?: number
+  /**
+   * The slot an `x-nifra-swap` request names. When the adapter renders slots and nothing is
+   * deferred, the response is that slot's HTML alone; otherwise the whole document.
+   */
+  readonly swapSlot?: string
+  /** Chain indices the adapter renders inside the slot wrappers of a kept page (`keepAlive`), so the
+   * browser can keep the page this document shows without remounting it. */
+  readonly slots?: readonly number[]
   /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
    * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
    * so neither can be overridden from here. */
@@ -205,6 +223,11 @@ export interface RenderPageOptions {
   /** CSP nonce applied to every framework-owned executable script in this document. Nonce-bearing
    * documents are marked `private, no-store` so a request-specific nonce is never replayed. */
   readonly nonce?: string
+  /** The request's abort signal. A deferred value that rejects because it aborted is the client
+   * leaving, not a failure, so the server log skips it. Omit ⇒ every rejection is logged. */
+  readonly signal?: AbortSignal
+  /** Where a rejected deferred value is logged: the app's error log. Omit ⇒ the console. */
+  readonly logError?: ((error: unknown) => void) | undefined
   /**
    * A hash-based Content-Security-Policy from `createCspPolicy`. The document then carries `nonce`
    * only when it needs one (it defers a value, or a head tag names the nonce); otherwise it renders
@@ -262,6 +285,18 @@ export function renderPage(options: RenderPageInput): MaybePromise<Response> {
   return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse()
 }
 
+// Every option of an adapter call, for a render with slot wrappers (only a keep-alive app's).
+const streamOptions = (
+  nonce: string | undefined,
+  parts: DocumentParts | undefined,
+  slots: readonly number[],
+): RenderStreamOptions => {
+  const options: { -readonly [K in keyof RenderStreamOptions]: RenderStreamOptions[K] } = { slots }
+  if (nonce !== undefined) options.nonce = nonce
+  if (parts !== undefined) options.parts = parts
+  return options
+}
+
 export function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage> {
   const { csp } = options
   if (csp !== undefined) {
@@ -388,6 +423,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     options.serverComponents === undefined
       ? ""
       : `,"__NIFRA_COMPONENTS__":${serializeData(options.serverComponents)}`
+  const liveTail =
+    options.live === undefined ? "" : `,"${LIVE_GLOBAL}":${serializeData(options.live)}`
   const deferredRuntime =
     allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
   // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
@@ -500,7 +537,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // Tail - the page-state handover + the client module. Module scripts defer (run after parse), so
   // the handover + every streamed deferred resolution are in the document before the entry hydrates.
   const tailHtml = hydrate
-    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${slot.tailPost}`
+    ? `${slot.tailPre}${serializeData(forClient)}${action}${layoutTail}${boundaryTail}${componentTail}${liveTail}${slot.tailPost}`
     : (slot.tailPost as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
   if (locale !== undefined) headers["content-language"] = lang
@@ -512,6 +549,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       if (name !== "content-type") headers[name] = value
     }
   }
+  if (adapter.renderSlot !== undefined)
+    headers.vary = headers.vary === undefined ? SWAP_HEADER : `${headers.vary}, ${SWAP_HEADER}`
   // ISR: advertise the route's freshness so a `withISR` wrapper can set this page's cache TTL. A
   // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
   // the client's path-list channel.
@@ -551,6 +590,17 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     ...(locale === undefined ? {} : { locale }),
   }
 
+  const { swapSlot, ...documentOptions } = options
+  const slots = options.slots
+  if (swapSlot !== undefined && allDeferred.length === 0 && adapter.renderSlot !== undefined) {
+    const slotPage = (slotHtml: string | undefined): MaybePromise<RenderedPage> =>
+      slotHtml === undefined
+        ? renderPageResult(documentOptions)
+        : new BufferedRenderedPage(slotHtml, status, swapHeaders(headers, swapSlot))
+    const out = adapter.renderSlot(chain, renderProps, swapSlot)
+    return out instanceof Promise ? out.then(slotPage) : slotPage(out)
+  }
+
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
   // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
   // (those take the streaming path below); for a plain page the streaming pipeline + the framework's
@@ -571,6 +621,9 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       headers,
       streamNonce,
       streamNonce === nonce ? nonceAttr : ` nonce="${escapeAttr(streamNonce ?? "")}"`,
+      options.signal,
+      options.slots,
+      options.logError,
     ).then((response) => new ResponseRenderedPage(response))
   const last = chain[chain.length - 1]
   const leaf = isWeakKey(last) ? last : undefined
@@ -596,15 +649,17 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       return streamed(renderNonce)
     }
     const out =
-      parts !== undefined
-        ? adapter.renderToString(
-            chain,
-            renderProps,
-            renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
-          )
-        : renderNonce === undefined
-          ? adapter.renderToString(chain, renderProps)
-          : adapter.renderToString(chain, renderProps, { nonce: renderNonce })
+      slots !== undefined
+        ? adapter.renderToString(chain, renderProps, streamOptions(renderNonce, parts, slots))
+        : parts !== undefined
+          ? adapter.renderToString(
+              chain,
+              renderProps,
+              renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
+            )
+          : renderNonce === undefined
+            ? adapter.renderToString(chain, renderProps)
+            : adapter.renderToString(chain, renderProps, { nonce: renderNonce })
     const page = (bodyHtml: string | undefined): MaybePromise<RenderedPage> => {
       if (bodyHtml === undefined) {
         // The render suspended on something only the streaming renderer waits for (React's `use`
@@ -643,6 +698,9 @@ async function renderStreamedPage(
   headers: Record<string, string>,
   nonce: string | undefined,
   nonceAttr: string,
+  signal: AbortSignal | undefined,
+  slots: readonly number[] | undefined,
+  logError: ((error: unknown) => void) | undefined,
 ): Promise<Response> {
   // Streaming path - required for `defer()` (progressive `<Await>` resolution) and used by any adapter
   // that doesn't implement `renderToString`. Awaiting `renderToStream` resolves on shell-readiness
@@ -652,21 +710,54 @@ async function renderStreamedPage(
   const closeRoot = enc.encode(closeRootHtml)
   const tail = enc.encode(tailHtml)
   const appStream =
-    parts !== undefined
-      ? await adapter.renderToStream(
-          chain,
-          renderProps,
-          nonce === undefined ? { parts } : { nonce, parts },
-        )
-      : nonce === undefined
-        ? await adapter.renderToStream(chain, renderProps)
-        : await adapter.renderToStream(chain, renderProps, { nonce })
+    slots !== undefined
+      ? await adapter.renderToStream(chain, renderProps, streamOptions(nonce, parts, slots))
+      : parts !== undefined
+        ? await adapter.renderToStream(
+            chain,
+            renderProps,
+            nonce === undefined ? { parts } : { nonce, parts },
+          )
+        : nonce === undefined
+          ? await adapter.renderToStream(chain, renderProps)
+          : await adapter.renderToStream(chain, renderProps, { nonce })
   // After the render: an adapter fills its document parts before handing back the stream.
   const shell = enc.encode(shellOf())
-  const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
+  const body = streamDocument(
+    shell,
+    appStream,
+    closeRoot,
+    allDeferred,
+    tail,
+    enc,
+    nonceAttr,
+    signal,
+    logError,
+  )
   return new Response(body, { status, headers })
 }
 
+// A swap response shares its URL with the document, so like a data response it is never stored: a
+// cache keyed on the URL alone would serve one slot in place of the page. A slot joins a page that
+// already runs under its own policy, so the CSP header belongs to the document alone.
+const DOCUMENT_ONLY_HEADERS = new Set([
+  ISR_REVALIDATE_HEADER,
+  ISR_REVALIDATE_TAGS_HEADER,
+  "content-security-policy",
+])
+
+function swapHeaders(
+  document: Readonly<Record<string, string>>,
+  slot: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {}
+  for (const [name, value] of Object.entries(document))
+    if (!DOCUMENT_ONLY_HEADERS.has(name)) headers[name] = value
+  headers["cache-control"] = "private, no-store"
+  headers[SWAP_HEADER] = slot
+  return headers
+}
+
 class BufferedRenderedPage implements RenderedPage {
   readonly [RESPONSE_RESULT] = true
   private readonly body: string
@@ -732,6 +823,8 @@ function streamDocument(
   tail: Uint8Array,
   enc: TextEncoder,
   nonceAttr: string,
+  signal: AbortSignal | undefined,
+  logError: ((error: unknown) => void) | undefined,
 ): ReadableStream<Uint8Array> {
   const reader = stream.getReader()
   // A client that goes away cancels the body: the renderer stops, and nothing more is written.
@@ -756,7 +849,7 @@ function streamDocument(
         // A rejected (or unserializable) deferred streams __nifraReject (the client `<Await>`
         // surfaces it) - it must not break the whole body. Redact: stream a stable opaque code,
         // never the raw error text; log the real reason server-side.
-        console.error("[nifra/web] deferred value rejected:", err)
+        reportDeferredRejection(signal, err, logError)
         return `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
       }),
   )
@@ -857,24 +950,6 @@ export function redirect(location: string, options: RedirectOptions = {}): Respo
   })
 }
 
-/**
- * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
- *
- * A loader that throws a bare `Response` has always been passed straight through - that is how
- * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
- * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
- * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
- * checking it *before* the pass-through is what keeps every existing throw working unchanged.
- *
- * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
- * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
- * be a maddening bug to trace.
- */
-/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
- * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
- * type here would break their build. Same workaround as `SSEInit.headers` in core. */
-export type HeadersLike = ConstructorParameters<typeof Headers>[0]
-
 /**
  * The signatures a **duplicate module instance** produces during SSR, across engines.
  *
@@ -977,8 +1052,6 @@ export const layoutErrorId = (err: unknown): string | undefined =>
     ? ((err as Record<symbol, unknown>)[LAYOUT_ERROR_ID] as string | undefined)
     : undefined
 
-export const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
-
 /** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
  * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
  * useful than shipping a table of every RFC status for a body almost nobody will see. */
@@ -993,84 +1066,49 @@ export const STATUS_TEXT: Readonly<Record<number, string>> = {
   500: "Internal Server Error",
 }
 
-export interface StatusSignal extends Response {
-  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
-}
-
-export function isStatusSignal(value: unknown): value is StatusSignal {
-  return value instanceof Response && STATUS_SIGNAL in value
-}
-
-function statusSignal(status: number, options: StatusPageOptions): never {
-  if (!Number.isInteger(status) || status < 400 || status > 599) {
-    throw new Error(
-      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
-    )
+/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
+ * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
+ * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
+ * the paths via the `X-Nifra-Revalidate` header. */
+export interface RevalidateResult<T> {
+  readonly __nifraRevalidate: readonly string[]
+  readonly data: T
+  /** What else the write made stale: cache tags and live keys. */
+  readonly __nifraInvalidate?: {
+    readonly tags: readonly string[]
+    readonly keys: readonly string[]
   }
-  const response = new Response(null, { status })
-  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
-  Object.defineProperty(response, STATUS_SIGNAL, {
-    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
-    enumerable: false,
-  })
-  throw response
 }
 
-/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
-export interface StatusPageOptions {
-  /**
-   * Extra headers for the rendered response - `cache-control` above all.
-   *
-   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
-   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
-   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
-   * for weeks.
-   */
-  readonly headers?: HeadersLike
+/** `value` is what {@link revalidate} returned. */
+export function isRevalidateResult(value: unknown): value is RevalidateResult<unknown> {
+  return typeof value === "object" && value !== null && "__nifraRevalidate" in value
 }
 
-/**
- * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
- * exist.
- *
- * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
- * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
- * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
- * shipped - while search engines penalise it and keep the dead URL indexed.
- *
- * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
- * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
- */
-export function notFound(options: StatusPageOptions = {}): never {
-  return statusSignal(404, options)
+/** Cache tags and live keys an action's write made stale, beside its paths. */
+export interface RevalidateOptions {
+  /** Cache tags: data caches, the page store and the CDN drop entries carrying them; live pages watching a tag as a key reload. */
+  readonly tags?: readonly string[]
+  /** Live keys (`ctx.live`): every open page watching one reloads it. */
+  readonly keys?: readonly string[]
 }
 
-/**
- * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
- * was deliberately removed - a withdrawn listing, a deleted post.
- *
- * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
- * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
- */
-export function gone(options: StatusPageOptions = {}): never {
-  return statusSignal(410, options)
-}
-
-/**
- * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
- * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
- */
-export function statusPage(status: number, options: StatusPageOptions = {}): never {
-  return statusSignal(status, options)
-}
+const INVALIDATION_NAME = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/
+const MAX_INVALIDATION_NAMES = 64
 
-/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
- * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
- * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
- * the paths via the `X-Nifra-Revalidate` header. */
-export interface RevalidateResult<T> {
-  readonly __nifraRevalidate: readonly string[]
-  readonly data: T
+function invalidationNames(names: readonly string[] | undefined, kind: string): readonly string[] {
+  if (names === undefined) return []
+  if (!Array.isArray(names) || names.length > MAX_INVALIDATION_NAMES) {
+    throw new TypeError(`[nifra/web] revalidate() takes at most ${MAX_INVALIDATION_NAMES} ${kind}`)
+  }
+  for (const name of names) {
+    if (typeof name !== "string" || !INVALIDATION_NAME.test(name)) {
+      throw new TypeError(
+        `[nifra/web] revalidate() ${kind} are a letter followed by up to 127 of A-Z a-z 0-9 . _ : / -`,
+      )
+    }
+  }
+  return [...new Set(names)]
 }
 
 /**
@@ -1080,8 +1118,15 @@ export interface RevalidateResult<T> {
  * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
  * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
  */
-export function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T> {
-  return { __nifraRevalidate: paths, data }
+export function revalidate<T>(
+  paths: readonly string[],
+  data: T,
+  options?: RevalidateOptions,
+): RevalidateResult<T> {
+  if (options === undefined) return { __nifraRevalidate: paths, data }
+  const tags = invalidationNames(options.tags, "tags")
+  const keys = invalidationNames(options.keys, "keys")
+  return { __nifraRevalidate: paths, data, __nifraInvalidate: { tags, keys } }
 }
 
 /**

package/src/internal/request-abort.ts

@@ -0,0 +1,26 @@
+/** Whether `error` is a load giving up because its request was aborted - the client went away - rather
+ * than a failure: nobody reads the outcome, so there is nothing to report. */
+export function isRequestAbort(signal: AbortSignal | undefined, error: unknown): boolean {
+  return (
+    signal?.aborted === true &&
+    (error === signal.reason || (error instanceof Error && error.name === "AbortError"))
+  )
+}
+
+/** Report a deferred value's rejection to `log`, the app's error log, or to the console without
+ * one or when it throws: both callers stream an opaque error code after this, which a failing
+ * logger must not cut off. A rejection the client's leaving caused is not reported. */
+export function reportDeferredRejection(
+  signal: AbortSignal | undefined,
+  error: unknown,
+  log: ((error: unknown) => void) | undefined,
+): void {
+  if (isRequestAbort(signal, error)) return
+  if (log !== undefined) {
+    try {
+      log(error)
+      return
+    } catch {}
+  }
+  console.error("[nifra/web] deferred value rejected:", error)
+}

package/src/internal/server-boundary.ts

@@ -12,6 +12,8 @@
 
 /** Modules whose exports become client stubs: `todos.fn.ts`, `x.fn.mjs`, or the extensionless `foo.fn`. */
 export const SERVER_FN_MODULE = /\.fn(\.[cm]?[jt]sx?)?$/
+/** A server-function namespace: lowercase, dot/dash separated, so a mount cannot invent a path. */
+export const SERVER_FN_NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/
 
 import { jsStringLiteral } from "./js-string.ts"
 import { DATE_TAG, REVIVE_DATES_SOURCE } from "./revive-dates.ts"
@@ -105,7 +107,14 @@ function stringEnd(source: string, start: number): number {
  */
 export function serverFnNamespace(filePath: string): string {
   const base = filePath.replaceAll("\\", "/").split("/").pop() ?? ""
-  return base.replace(SERVER_FN_MODULE, "")
+  const namespace = base.replace(SERVER_FN_MODULE, "")
+  // `serverFunctions()` refuses this namespace, so a stub calling it could never reach a function.
+  if (!SERVER_FN_NAMESPACE.test(namespace)) {
+    throw new Error(
+      `[nifra/fn] ${base} names the server-function namespace ${JSON.stringify(namespace)}, which serverFunctions() refuses - name the file in lowercase dot/dash segments (todo-items.fn.ts).`,
+    )
+  }
+  return namespace
 }
 
 /** The server functions a module declares, in source order. */

package/src/internal/share-data.ts

@@ -0,0 +1,136 @@
+const isPlain = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype
+
+const TOO_DEEP = Symbol("data too deep")
+
+// Client loaders may return graphs, unlike JSON. Check the whole graph before comparing: a cycle
+// inside a new subtree or beyond the array sample must not acquire copied parents. Shared references
+// and accessors also keep the fresh result intact, rather than changing aliases or invoking getters.
+function isTree(value: unknown, seen: Set<object>, depth: number): boolean {
+  if (!Array.isArray(value) && !isPlain(value)) return true
+  if (depth >= 128 || seen.has(value)) return false
+  seen.add(value)
+  for (const key of Reflect.ownKeys(value)) {
+    const field = Object.getOwnPropertyDescriptor(value, key)
+    if (
+      field === undefined ||
+      !("value" in field) ||
+      (!field.enumerable && !(Array.isArray(value) && key === "length")) ||
+      !isTree(field.value, seen, depth + 1)
+    )
+      return false
+  }
+  return true
+}
+
+/**
+ * Structural sharing for reloaded route data. Plain objects and arrays compare by content and Dates
+ * by time; other values and symbol-bearing objects come from `next`. Non-tree client data stays
+ * intact. `plainJson` is only for freshly parsed JSON, before any client-loader transformation.
+ *
+ * Array elements with an `id` pair by it before position, preserving unchanged rows on a prepend or
+ * reorder. An array whose first 32 elements keep nothing is taken whole, without a full old-row index.
+ */
+export function shareData<T>(prev: unknown, next: T, plainJson?: boolean): T
+export function shareData(prev: unknown, next: unknown, plainJson = false): unknown {
+  if (Object.is(prev, next)) return prev
+  if (!plainJson && !isTree(next, new Set(), 0)) return next
+  try {
+    return share(prev, next, 0, plainJson)
+  } catch (error) {
+    if (error === TOO_DEEP) return next
+    throw error
+  }
+}
+
+// Client loaders can attach metadata that an enumerable-string-key copy would lose. Parsed JSON has
+// no symbol keys, and the check would cost a third of a reload that changed one row.
+const hasSymbols = (a: object, b: object): boolean =>
+  Object.getOwnPropertySymbols(a).length > 0 || Object.getOwnPropertySymbols(b).length > 0
+
+function share(prev: unknown, next: unknown, depth: number, json: boolean): unknown {
+  if (Object.is(prev, next)) return prev
+  if (prev instanceof Date)
+    return next instanceof Date && prev.getTime() === next.getTime() ? prev : next
+  if (Array.isArray(next)) {
+    if (!Array.isArray(prev) || (!json && hasSymbols(prev, next))) return next
+    if (depth >= 128) throw TOO_DEEP
+    const out: unknown[] = []
+    let same = prev.length === next.length
+    let byId: Map<unknown, number> | undefined
+    let completeIndex = false
+    // Which old elements a new one took, from the first id lookup on: each pairs at most once, so
+    // duplicate ids never put one old object at two places. Every element before that lookup took
+    // its own position.
+    let taken: Uint8Array | undefined
+    let kept = 0
+    let i = 0
+    for (const item of next) {
+      let old: unknown = taken?.[i] === 1 ? undefined : prev[i]
+      const id = isPlain(item) ? item.id : undefined
+      if (id !== undefined && !(isPlain(old) && old.id === id)) {
+        if (taken === undefined) {
+          taken = new Uint8Array(prev.length)
+          taken.fill(1, 0, i)
+        }
+        if (byId === undefined || (i >= 32 && !completeIndex)) {
+          // Index only IDs needed by the sample until a kept row makes a full index worthwhile.
+          const wanted =
+            i < 32
+              ? new Set(next.slice(0, 32).map((value) => (isPlain(value) ? value.id : undefined)))
+              : undefined
+          completeIndex = wanted === undefined
+          let min = Number.POSITIVE_INFINITY
+          let max = Number.NEGATIVE_INFINITY
+          for (const key of wanted ?? []) {
+            if (typeof key !== "number" || Number.isNaN(key)) {
+              min = Number.NEGATIVE_INFINITY
+              max = Number.POSITIVE_INFINITY
+              break
+            }
+            min = Math.min(min, key)
+            max = Math.max(max, key)
+          }
+          byId = new Map()
+          for (let at = 0; at < prev.length; at++) {
+            const entry = prev[at]
+            if (!isPlain(entry)) continue
+            const entryId = entry.id
+            if (
+              wanted === undefined ||
+              ((typeof entryId !== "number" || !(entryId < min || entryId > max)) &&
+                wanted.has(entryId))
+            )
+              byId.set(entryId, at)
+          }
+        }
+        const at = byId.get(id)
+        old = at === undefined || taken[at] === 1 ? undefined : prev[at]
+        if (at !== undefined) taken[at] = 1
+      } else if (taken !== undefined && i < taken.length && old !== undefined) {
+        taken[i] = 1
+      }
+      const value = share(old, item, depth + 1, json)
+      out.push(value)
+      if (value === old) kept++
+      else if (i === 31 && kept === 0) return next
+      if (value !== prev[i]) same = false
+      i++
+    }
+    return same ? prev : out
+  }
+  if (!isPlain(prev) || !isPlain(next) || (!json && hasSymbols(prev, next))) return next
+  if (depth >= 128) throw TOO_DEEP
+  const keys = Object.keys(next)
+  let same = keys.length === Object.keys(prev).length
+  const out: Record<string, unknown> = {}
+  for (const key of keys) {
+    // A parsed payload can own a `__proto__` key, which a copy would turn into its prototype.
+    if (key === "__proto__") return next
+    const old = prev[key]
+    const value = share(old, next[key], depth + 1, json)
+    if (value !== old || (old === undefined && !Object.hasOwn(prev, key))) same = false
+    out[key] = value
+  }
+  return same ? prev : out
+}