@lesto/ui 0.1.1 → 0.1.2

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@lesto/ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "Lesto's AI-native UI rendering engine core — validate a JSON UI tree and render it to React against a vetted component registry.",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -19,8 +20,8 @@
     }
   },
   "dependencies": {
-    "@lesto/errors": "0.1.1",
-    "@lesto/router": "0.1.1",
+    "@lesto/errors": "0.1.2",
+    "@lesto/router": "0.1.2",
     "react": "^19",
     "react-dom": "^19"
   },

package/src/client.ts

@@ -51,4 +51,11 @@ export type {
   SoftNavKind,
   SoftNavOptions,
   SoftNavWindow,
+  SwapResult,
 } from "./softnav";
+
+// The `lesto dev` page-refresh hook (DX-parity R2): a saved `app/routes/*` file does a
+// server re-render + DOM swap instead of a full reload. The synthesized dev entry calls
+// `enableDevPageRefresh` so the CLI's live-reload client can refresh the page in place.
+export { DEV_PAGE_REFRESH_GLOBAL, enableDevPageRefresh } from "./softnav";
+export type { DevPageRefreshOptions } from "./softnav";

package/src/data-client.ts

@@ -1,27 +1,38 @@
 /**
  * Client data hooks — `useQuery` / `useMutation` over a tiny shared cache.
  *
- * The smallest credible step of the reactive data layer (ADR 0027), and no more:
- * islands today hand-roll `useState`+`useEffect` to fetch (a re-implemented loading/error
+ * The client-local layer of the reactive data layer (ADR 0027 Phase 1): islands
+ * otherwise hand-roll `useState`+`useEffect` to fetch (a re-implemented loading/error
  * machine per island, no sharing) and re-build a mutation client per submit. These
  * hooks replace that with one cache that gives:
  *
  *   - **in-flight dedupe** — N components asking for the same key while a request
  *     is in flight share ONE request, not N;
- *   - **an explicit-invalidation cache** — a resolved key stays cached until a
- *     mutation (or a manual `refetch`) invalidates it, so a re-mount or a sibling
- *     reading the same key paints instantly;
+ *   - **an explicit-invalidation cache** — by KEY (`invalidate(key)`) or by **topic**:
+ *     a mutation declares the topics it dirties (`invalidates: ["posts"]`) and a query
+ *     subscribes to topics (`useQuery(key, fetcher, { topics: ["posts"] })`). The client
+ *     keeps a **topic → keys** registry; invalidating a topic refetches every mounted
+ *     reader registered under it. Still EXPLICIT — the writer names the topic; nothing is
+ *     schema-inferred. The keyspaces are NOT unified (a `useQuery` key, a `@lesto/client`
+ *     `"METHOD /path"` key, and a `defineDataSource` name stay independent); the **topic**
+ *     is the addressable unit, decoupled from any key format — which is exactly what the
+ *     later server-push phase targets.
+ *   - **opt-in background revalidation** — `staleTime`, refetch-on-focus,
+ *     refetch-on-reconnect, and a polling `refetchInterval`, with the focus/online/timer
+ *     events behind an injected {@link RevalidationEnvironment} seam (so it is testable and
+ *     SSR-safe, and absent when not opted into — the default behaviour is unchanged);
  *   - **`useMutation`** — `{ mutate, isPending, error, data }` with optimistic
- *     update + rollback and an `onSuccess` hook that typically invalidates keys.
+ *     update + rollback, a declarative `invalidates` (the topics to drop on success), and
+ *     an `onSuccess` hook.
  *
  * What this is NOT (so the doc never over-promises): it is NOT the full reactive
- * layer. There is no schema-INFERRED invalidation (a mutation does not know which
- * queries it dirties — you invalidate by key, explicitly), no normalized `(table, pk)`
- * store, no automatic background revalidation, and no cache EVICTION — a key's snapshot +
- * last-fetcher live for the page's lifetime (bounded by the distinct keys an app
- * queries; fine for a per-session SPA, revisit if a long-lived app accumulates many).
- * Those are the later ADR 0027 phases (server-pushed invalidation over LISTEN/NOTIFY,
- * durable storage); this is the thin hook layer an app adopts now and they build on.
+ * layer. Topic invalidation is EXPLICIT, never schema-INFERRED (a mutation declares its
+ * topics; the client does not derive them from the rows a write touched). There is no
+ * normalized `(table, pk)` store and no cache EVICTION — a key's snapshot + last-fetcher
+ * live for the page's lifetime (bounded by the distinct keys an app queries; fine for a
+ * per-session SPA). The push that makes a topic invalidation cross processes / tabs /
+ * clients (LISTEN/NOTIFY + browser fan-out) and durable storage are the later ADR 0027
+ * phases; the topic registry defined here is the seam they build on.
  *
  * Decoupled by design: the hooks never import `@lesto/client`. The caller passes a
  * `fetcher` / `mutationFn` thunk (typically closing over a `createApi` /
@@ -64,9 +75,13 @@ export function serializeQueryKey(key: QueryKey): string {
  * One instance backs every hook by default ({@link defaultQueryClient}); a test
  * (or an app wanting an isolated cache) constructs its own and passes it via the
  * hook's `client` option. Holds the published snapshots, the in-flight promises
- * (for dedupe), the last fetcher per key (so `invalidate` can refetch), and the
+ * (for dedupe), the last fetcher per key (so `invalidate` can refetch), the
  * per-key subscriber sets — kept OUT of the snapshot so a re-render is driven only
- * by a value change.
+ * by a value change — the per-key "last fetched at" stamp (for `staleTime`), and the
+ * **topic → keys** registry (for topic invalidation).
+ *
+ * `now` is injected for testability: a fake clock drives `staleTime` math without real
+ * time. It defaults to `Date.now`.
  */
 export class QueryClient {
   readonly #snapshots = new Map<string, QuerySnapshot<unknown>>();
@@ -77,6 +92,20 @@ export class QueryClient {
 
   readonly #listeners = new Map<string, Set<() => void>>();
 
+  /** When `key` last became `success` — used by {@link isStale} for `staleTime`. */
+  readonly #fetchedAt = new Map<string, number>();
+
+  /** topic -> (key -> mount count): the readers registered to each topic. N mounted
+   *  readers of one key under one topic register once; the key leaves the topic only
+   *  when the last reader unmounts. The single source of truth for topic membership. */
+  readonly #topicKeyCounts = new Map<string, Map<string, number>>();
+
+  readonly #now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+
   /** The current published snapshot for `key` — the shared idle one until it has one. */
   getSnapshot(key: string): QuerySnapshot<unknown> {
     return this.#snapshots.get(key) ?? IDLE_SNAPSHOT;
@@ -129,36 +158,36 @@ export class QueryClient {
 
     this.#publish(key, { status: "loading", data: previous?.data });
 
-    const promise = fetcher().then(
-      (data) => {
-        this.#inflight.delete(key);
-        this.#publish(key, { status: "success", data });
-
-        return data;
-      },
-      (error: unknown) => {
-        this.#inflight.delete(key);
-        this.#publish(key, { status: "error", error });
-
-        throw error;
-      },
-    );
+    return this.#track(key, fetcher());
+  }
 
-    this.#inflight.set(key, promise);
+  /**
+   * Seed `key` from an ALREADY-in-flight request — the parse-time data primer
+   * (`window.__lestoData[source]`; see {@link hydrateQueryClient}). Registers the
+   * promise as `key`'s in-flight request so a `useQuery(key)` that mounts during
+   * hydration DEDUPES its own fetch onto it (no second network request) and paints
+   * the value the instant the parse-time fetch lands — no `JS → fetch → data`
+   * waterfall.
+   *
+   * Unlike {@link fetch} it does NOT remember the promise as the refetch fetcher: a
+   * one-shot primer must never be replayed by {@link invalidate} (that would re-serve
+   * the pre-write value); the real fetcher is recorded when the reader mounts. A
+   * no-op if `key` is already loading (a request is in flight) or already holds a
+   * value — priming never clobbers live state.
+   */
+  prime(key: string, promise: Promise<unknown>): void {
+    if (this.#inflight.has(key) || this.getSnapshot(key).status === "success") return;
 
-    // A deduped caller may never attach a handler; swallow the rejection on the
-    // STORED branch so it raises no `unhandledrejection`. The error is already on
-    // the snapshot, and a direct awaiter still sees the re-thrown rejection above.
-    promise.catch(() => {});
+    this.#publish(key, { status: "loading", data: this.#snapshots.get(key)?.data });
 
-    return promise;
+    this.#track(key, promise);
   }
 
   /**
    * Invalidate `key`: drop its cached value and refetch with its last fetcher, so
    * every mounted `useQuery(key)` re-renders fresh. Explicit-only — a mutation
-   * names the keys it dirties; there is no inferred invalidation (a later ADR 0027 phase). A
-   * key never fetched (no remembered fetcher) is simply reset to idle.
+   * names the keys (or topics) it dirties; there is no inferred invalidation (a later
+   * ADR 0027 phase). A key never fetched (no remembered fetcher) is simply reset to idle.
    */
   invalidate(key: string): Promise<unknown> | undefined {
     const fetcher = this.#fetchers.get(key);
@@ -172,10 +201,121 @@ export class QueryClient {
     return this.fetch(key, fetcher);
   }
 
-  /** Publish a new snapshot for `key` and notify its subscribers. */
+  /**
+   * Register `key` as a reader of every `topic`, so a later {@link invalidateTopic}
+   * refetches it. Returns an unregister thunk (call on unmount). Reference-counted: M
+   * mounted readers of the same key+topic register once; the key leaves the topic only
+   * when the last unregisters. The registry holds only currently-mounted readers.
+   */
+  registerTopics(key: string, topics: readonly string[]): () => void {
+    for (const topic of topics) {
+      let counts = this.#topicKeyCounts.get(topic);
+
+      if (counts === undefined) {
+        counts = new Map();
+        this.#topicKeyCounts.set(topic, counts);
+      }
+
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+
+    return () => {
+      for (const topic of topics) {
+        const counts = this.#topicKeyCounts.get(topic);
+
+        if (counts === undefined) continue;
+
+        const remaining = (counts.get(key) ?? 0) - 1;
+
+        if (remaining > 0) {
+          counts.set(key, remaining);
+
+          continue;
+        }
+
+        counts.delete(key);
+
+        if (counts.size === 0) this.#topicKeyCounts.delete(topic);
+      }
+    };
+  }
+
+  /** Invalidate every key registered to `topic`. The seam the server-push phase targets. */
+  invalidateTopic(topic: string): Promise<void> {
+    return this.invalidateTopics([topic]);
+  }
+
+  /**
+   * Invalidate every key registered to ANY of `topics` (a mutation's `invalidates`).
+   * A key dirtied by two topics is invalidated once. Resolves when every refetch settles.
+   */
+  invalidateTopics(topics: readonly string[]): Promise<void> {
+    const keys = new Set<string>();
+
+    for (const topic of topics) {
+      const counts = this.#topicKeyCounts.get(topic);
+
+      if (counts !== undefined) for (const key of counts.keys()) keys.add(key);
+    }
+
+    const pending: Array<Promise<unknown>> = [];
+
+    for (const key of keys) {
+      const promise = this.invalidate(key);
+
+      if (promise !== undefined) pending.push(promise);
+    }
+
+    return Promise.all(pending).then(() => undefined);
+  }
+
+  /**
+   * Whether `key`'s cached value is older than `staleTimeMs` (by the injected clock).
+   * A key that never succeeded is considered stale. The hook guards its calls with a
+   * `success` check, so the caller controls when this matters.
+   */
+  isStale(key: string, staleTimeMs: number): boolean {
+    const at = this.#fetchedAt.get(key);
+
+    return at === undefined ? true : this.#now() - at >= staleTimeMs;
+  }
+
+  /**
+   * Wire a request `promise` into `key`'s lifecycle: settle it to `success`/`error`,
+   * clear the in-flight slot, and store it for dedupe. Shared by {@link fetch} (which
+   * also remembers the fetcher) and {@link prime} (which does not). The STORED branch
+   * swallows its rejection so a deduped caller that never attaches a handler raises no
+   * `unhandledrejection`; a direct awaiter still sees the re-thrown rejection.
+   */
+  #track(key: string, promise: Promise<unknown>): Promise<unknown> {
+    const tracked = promise.then(
+      (data) => {
+        this.#inflight.delete(key);
+        this.#publish(key, { status: "success", data });
+
+        return data;
+      },
+      (error: unknown) => {
+        this.#inflight.delete(key);
+        this.#publish(key, { status: "error", error });
+
+        throw error;
+      },
+    );
+
+    this.#inflight.set(key, tracked);
+
+    tracked.catch(() => {});
+
+    return tracked;
+  }
+
+  /** Publish a new snapshot for `key`, stamp its fetch time on success, and notify subscribers. */
   #publish(key: string, snapshot: QuerySnapshot<unknown>): void {
     this.#snapshots.set(key, snapshot);
 
+    if (snapshot.status === "success") this.#fetchedAt.set(key, this.#now());
+
     const set = this.#listeners.get(key);
 
     if (set !== undefined) for (const listener of set) listener();
@@ -185,6 +325,116 @@ export class QueryClient {
 /** The cache every hook shares unless given its own `client` — the common case. */
 export const defaultQueryClient = new QueryClient();
 
+/**
+ * Seed a {@link QueryClient} from the parse-time data primer, so a `useQuery(key)`
+ * that mounts during hydration paints the server-fetched value with no second request
+ * and no `JS → fetch → data` waterfall.
+ *
+ * The primer (`dataPrimerScript`, ADR 0010) kicks each `defineDataSource` fetch at
+ * HTML-parse time and stores the in-flight PROMISE on `window.__lestoData[source]`.
+ * This hands each such promise to {@link QueryClient.prime}, so the matching
+ * `useQuery` dedupes its mount-time fetch onto the already-running request.
+ *
+ * `sourceToKey` names the correspondence from a primer source name to the `useQuery`
+ * key its reader passes: the keyspaces are decoupled by design (a source name, a
+ * `@lesto/client` `"METHOD /path"`, and a `useQuery` key are independent), so the
+ * caller — which knows both — declares the mapping. Sources that were not primed are
+ * skipped. A no-op on the server (no `window`) and when nothing was primed; safe to
+ * call once during client setup, before mounting islands.
+ */
+export function hydrateQueryClient(
+  client: QueryClient,
+  sourceToKey: Readonly<Record<string, QueryKey>>,
+): void {
+  if (typeof window === "undefined") return;
+
+  // The parse-time primer stores its in-flight promises here (declared globally by the
+  // hydration runtime). Read it through a local shape so this isomorphic core stays
+  // self-contained — it never depends on that ambient augmentation being in scope.
+  const primed = (window as { __lestoData?: Record<string, Promise<unknown>> }).__lestoData;
+
+  if (primed === undefined) return;
+
+  for (const [source, key] of Object.entries(sourceToKey)) {
+    const promise = primed[source];
+
+    if (promise !== undefined) client.prime(serializeQueryKey(key), promise);
+  }
+}
+
+/**
+ * The focus / online / timer events that drive background revalidation, injected so
+ * the hook stays testable (a fake env, no real time or DOM events) and SSR-safe (the
+ * methods are only ever called from a client-only effect, never during render).
+ */
+export interface RevalidationEnvironment {
+  /** Call `cb` when the tab regains focus / becomes visible. Returns an unsubscribe. */
+  onFocus(cb: () => void): () => void;
+
+  /** Call `cb` when the browser comes back online. Returns an unsubscribe. */
+  onReconnect(cb: () => void): () => void;
+
+  /** Call `cb` every `ms` until the returned cancel thunk runs (the poll loop). */
+  setInterval(cb: () => void, ms: number): () => void;
+}
+
+/** The default {@link RevalidationEnvironment} over real `window`/`document` events + timers. */
+export const browserRevalidationEnvironment: RevalidationEnvironment = {
+  onFocus(cb) {
+    const onVisible = (): void => {
+      if (document.visibilityState === "visible") cb();
+    };
+
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", cb);
+
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible);
+      window.removeEventListener("focus", cb);
+    };
+  },
+
+  onReconnect(cb) {
+    window.addEventListener("online", cb);
+
+    return () => window.removeEventListener("online", cb);
+  },
+
+  setInterval(cb, ms) {
+    const id = setInterval(cb, ms);
+
+    return () => clearInterval(id);
+  },
+};
+
+/** Options for {@link useQuery} — cache selection, topic subscription, and revalidation. */
+export interface QueryOptions {
+  /** The cache to read/write — defaults to the shared {@link defaultQueryClient}. */
+  client?: QueryClient;
+
+  /** Topics this query reads; invalidating any of them refetches this key while mounted. */
+  topics?: readonly string[];
+
+  /**
+   * Treat a cached value younger than this (ms) as fresh. When set, a mount or a
+   * focus/reconnect event refetches only if the value is older. Absent ⇒ no
+   * staleness-driven refetch (the default; a cached success is never auto-refetched).
+   */
+  staleTime?: number;
+
+  /** Refetch when the tab regains focus (gated by {@link QueryOptions.staleTime}). */
+  refetchOnWindowFocus?: boolean;
+
+  /** Refetch when the browser comes back online (gated by {@link QueryOptions.staleTime}). */
+  refetchOnReconnect?: boolean;
+
+  /** Poll: refetch every this-many ms while mounted (ignores `staleTime` — it is a poll). */
+  refetchInterval?: number;
+
+  /** The focus/online/timer seam — defaults to {@link browserRevalidationEnvironment}. */
+  environment?: RevalidationEnvironment;
+}
+
 /** What `useQuery` returns. `data` is undefined until the first success. */
 export interface QueryResult<T> {
   data: T | undefined;
@@ -207,24 +457,43 @@ export interface QueryResult<T> {
  * `isLoading` is true while uncached or in flight. A FRESH mount of an uncached
  * OR previously-errored key kicks a fetch — so navigating away and back to a
  * listing that failed transiently retries (matching a plain mount-effect fetch),
- * while a SUCCESS stays cached (the dedupe/cache win). The fetch fires once per
- * mount / key-change (the effect deps are only `[client, keyStr]`), never per
- * render, so there is no retry storm; an in-mount retry is a manual
- * {@link QueryResult.refetch}.
+ * while a SUCCESS stays cached (the dedupe/cache win) UNLESS a `staleTime` is set and
+ * the value has aged past it. The fetch fires once per mount / key-change (the effect
+ * deps are only `[client, keyStr, staleTime]`), never per render, so there is no retry
+ * storm; an in-mount retry is a manual {@link QueryResult.refetch}.
+ *
+ * Opt-in background revalidation ({@link QueryOptions}): `staleTime`,
+ * `refetchOnWindowFocus`, `refetchOnReconnect`, and a polling `refetchInterval`, all
+ * wired through the injected {@link RevalidationEnvironment}. None of it runs unless
+ * opted into — the default is the explicit-invalidation behaviour above. A query may
+ * also declare the `topics` it reads, so a mutation's topic invalidation refetches it.
  */
 export function useQuery<T>(
   key: QueryKey,
   fetcher: () => Promise<T>,
-  options?: { client?: QueryClient },
+  options?: QueryOptions,
 ): QueryResult<T> {
   const client = options?.client ?? defaultQueryClient;
   const keyStr = serializeQueryKey(key);
 
+  const topics = options?.topics;
+  const staleTime = options?.staleTime;
+  const refetchOnWindowFocus = options?.refetchOnWindowFocus ?? false;
+  const refetchOnReconnect = options?.refetchOnReconnect ?? false;
+  const refetchInterval = options?.refetchInterval;
+  const environment = options?.environment ?? browserRevalidationEnvironment;
+
   // The latest fetcher closure, read through a ref so `refetch`/the effect always
   // run the current one without re-subscribing when the closure identity changes.
   const fetcherRef = useRef(fetcher);
   fetcherRef.current = fetcher;
 
+  // Topics through a ref so the registration effect re-runs only when the topic SET
+  // changes (keyed by `topicsKey`), not on every render's fresh array identity.
+  const topicsRef = useRef(topics);
+  topicsRef.current = topics;
+  const topicsKey = topics === undefined ? "" : topics.join("");
+
   // One getSnapshot for both client and server reads (same idle/cached value), so
   // there is a single function to cover and no SSR/CSR snapshot divergence.
   const getSnapshot = useCallback(
@@ -241,14 +510,66 @@ export function useQuery<T>(
   useEffect(() => {
     // Fetch on a fresh mount when the key is uncached (`idle`) OR previously
     // errored — so a remount retries a transient failure rather than showing a
-    // terminal stale error. A `loading`/`success` key is left alone: a sibling
-    // already has it in flight or cached (the dedupe at mount time).
+    // terminal stale error. A cached `success` is left alone UNLESS a `staleTime`
+    // is set and the value has aged past it (then revalidate on mount).
     const status = client.getSnapshot(keyStr).status;
 
-    if (status === "idle" || status === "error") {
+    if (
+      status === "idle" ||
+      status === "error" ||
+      (status === "success" && staleTime !== undefined && client.isStale(keyStr, staleTime))
+    ) {
       void client.fetch(keyStr, () => fetcherRef.current());
     }
-  }, [client, keyStr]);
+  }, [client, keyStr, staleTime]);
+
+  useEffect(() => {
+    // Register while mounted so a topic invalidation refetches this key; re-runs only
+    // when the topic SET changes (keyed by `topicsKey`, not the array's render identity).
+    const current = topicsRef.current;
+
+    if (current === undefined || current.length === 0) return undefined;
+
+    return client.registerTopics(keyStr, current);
+  }, [client, keyStr, topicsKey]);
+
+  useEffect(() => {
+    const offs: Array<() => void> = [];
+
+    // Revalidate on an event only when the cached value is success and stale (an
+    // absent `staleTime` means "always stale on the event" — i.e. refetch every time).
+    const revalidate = (): void => {
+      if (
+        client.getSnapshot(keyStr).status === "success" &&
+        client.isStale(keyStr, staleTime ?? 0)
+      ) {
+        void client.fetch(keyStr, () => fetcherRef.current());
+      }
+    };
+
+    if (refetchOnWindowFocus) offs.push(environment.onFocus(revalidate));
+    if (refetchOnReconnect) offs.push(environment.onReconnect(revalidate));
+
+    if (refetchInterval !== undefined) {
+      offs.push(
+        environment.setInterval(() => {
+          void client.fetch(keyStr, () => fetcherRef.current());
+        }, refetchInterval),
+      );
+    }
+
+    return () => {
+      for (const off of offs) off();
+    };
+  }, [
+    client,
+    keyStr,
+    staleTime,
+    refetchOnWindowFocus,
+    refetchOnReconnect,
+    refetchInterval,
+    environment,
+  ]);
 
   const refetch = useCallback(() => {
     void client.fetch(keyStr, () => fetcherRef.current());
@@ -274,7 +595,16 @@ export interface MutationOptions<Input, Data> {
    */
   onMutate?: (input: Input) => (() => void) | void;
 
-  /** Run after success — typically `client.invalidate(key)` to revalidate reads. */
+  /**
+   * The topics this mutation dirties. On success the client invalidates every key
+   * registered to them — the declarative alternative to hand-calling `invalidate`.
+   */
+  invalidates?: readonly string[];
+
+  /** The cache `invalidates` targets — defaults to the shared {@link defaultQueryClient}. */
+  client?: QueryClient;
+
+  /** Run after success (after `invalidates`) — for side effects beyond revalidation. */
   onSuccess?: (data: Data, input: Input) => void;
 
   /** Run after a failed request (after any rollback). */
@@ -302,8 +632,8 @@ export interface MutationResultApi<Input, Data> {
 /**
  * Manage one write: `mutate(input)` flips `isPending`, runs `mutationFn`, and lands
  * the result on `data` or the throw on `error` (never re-thrown — the result-union
- * style). Supports an optimistic `onMutate` (with rollback on failure) and an
- * `onSuccess`/`onError` pair (the former usually invalidates queries).
+ * style). Supports an optimistic `onMutate` (with rollback on failure), a declarative
+ * `invalidates` (the topics dropped on success), and an `onSuccess`/`onError` pair.
  *
  * `mutationFn` may itself return a discriminated result (e.g. a `@lesto/client`
  * mutation's `{ ok, … }` union) — that union simply becomes `data`; throw inside
@@ -328,13 +658,21 @@ export function useMutation<Input, Data>(
   const mutate = useCallback(async (input: Input): Promise<Data | undefined> => {
     setState({ status: "pending" });
 
-    const rollback = optionsRef.current?.onMutate?.(input);
+    const opts = optionsRef.current;
+    const rollback = opts?.onMutate?.(input);
 
     try {
       const data = await fnRef.current(input);
 
       setState({ status: "success", data });
-      optionsRef.current?.onSuccess?.(data, input);
+
+      // Declarative revalidation first (drop the dirtied topics' keys), then the
+      // success side-effect hook.
+      if (opts?.invalidates !== undefined && opts.invalidates.length > 0) {
+        void (opts.client ?? defaultQueryClient).invalidateTopics(opts.invalidates);
+      }
+
+      opts?.onSuccess?.(data, input);
 
       return data;
     } catch (error) {
@@ -342,7 +680,7 @@ export function useMutation<Input, Data>(
       if (typeof rollback === "function") rollback();
 
       setState({ status: "error", error });
-      optionsRef.current?.onError?.(error, input);
+      opts?.onError?.(error, input);
 
       return undefined;
     }

package/src/data.ts

@@ -10,9 +10,11 @@
  * write — the whole point.
  *
  * The token carries only a NAME, a SCOPE (per-user vs shared — it picks the auto
- * route's cache header, ADR 0010 §3a), and a phantom TYPE. It deliberately holds
- * no implementation, so importing the shared token module from the client bundle
- * (as the island registry does) drags no server code across the wire.
+ * route's cache header, ADR 0010 §3a), an ACCESS posture (whether a per-user
+ * source may be served without a guard chain — see {@link DataSourceAccess}), and
+ * a phantom TYPE. It deliberately holds no implementation, so importing the shared
+ * token module from the client bundle (as the island registry does) drags no
+ * server code across the wire.
  *
  * Delivery is chosen by topology, never by the author:
  *   - dynamically rendered → the render-time resolver in `data-resolve.tsx`
@@ -42,10 +44,36 @@ import type { IslandMount } from "./island";
  */
 export type DataSourceScope = "private" | "shared";
 
+/**
+ * Whether a per-user (`scope: "private"`) source's auto-exposed route may be
+ * served WITHOUT a guard chain — the secure-by-default decision a private source
+ * must make (ADR 0010 §5a).
+ *
+ *   - `"guarded"` (the default for a private source): the route serves per-user
+ *     data, so it MUST be registered behind guards. `lesto().data(source, loader)`
+ *     with neither a guard chain nor this posture relaxed throws
+ *     `WEB_PRIVATE_DATA_UNGUARDED` at registration — before any request — so a
+ *     private source cannot be shipped on the unguarded `/__lesto/data/<name>`
+ *     route by omission. A file-route `middleware.ts` guards only the page
+ *     document GET, never the separate data route, so the framework refuses to
+ *     guess that "no guards" was intentional.
+ *   - `"request-scoped"`: the explicit opt-out — the loader derives its result
+ *     SOLELY from the caller's own request (its cookie / session / params), so an
+ *     unguarded route leaks nothing across users (each caller sees only their own
+ *     data). A `"who am I"` session source is the canonical case. Declaring it is
+ *     a visible statement of that invariant, not a silent default.
+ *
+ * It is moot for a `scope: "shared"` source — shared data is the same for every
+ * visitor and publicly cacheable by construction, so its route is never guarded
+ * on these grounds and `access` is ignored.
+ */
+export type DataSourceAccess = "guarded" | "request-scoped";
+
 /**
  * A typed handle to a named data source — no implementation, just a name, a
- * scope, and a phantom value type. `defineDataSource<User | null>("session")`
- * names the source and pins what its loader returns / its bound prop receives.
+ * scope, an access posture, and a phantom value type.
+ * `defineDataSource<User | null>("session")` names the source and pins what its
+ * loader returns / its bound prop receives.
  */
 export interface DataSource<T = unknown> {
   readonly name: string;
@@ -53,6 +81,13 @@ export interface DataSource<T = unknown> {
   /** Per-user or shared — drives the route's cache header. Defaults to `"private"`. */
   readonly scope: DataSourceScope;
 
+  /**
+   * Whether a private source may serve unguarded — {@link DataSourceAccess}.
+   * Defaults to `"guarded"` (a private source must be guarded or explicitly
+   * declared `"request-scoped"`). Moot for a shared source.
+   */
+  readonly access: DataSourceAccess;
+
   /** Phantom: carries the resolved value's type to the binding. Never present at runtime. */
   readonly __value?: T;
 }
@@ -85,10 +120,18 @@ export function dataSourceHref(name: string): string {
  * route's cache header (ADR 0010 §3a). Private-by-default keeps the dangerous
  * configuration (a per-user value heuristically cached by a CDN) unrepresentable
  * without a visible declaration.
+ *
+ * `access` declares whether a private source's route may serve UNGUARDED
+ * (`"guarded"`, the default, vs `"request-scoped"` — {@link DataSourceAccess}).
+ * It pairs with the scope default: a private source is both not-shared-cacheable
+ * AND not-servable-unguarded unless the author says otherwise, so the bypass
+ * (a per-user route the page's `middleware.ts` never reaches) is closed by
+ * default rather than by remembering to pass guards. It is recorded on the token
+ * here and enforced where the route is registered (`lesto().data(...)`).
  */
 export function defineDataSource<T>(
   name: string,
-  options?: { scope?: DataSourceScope },
+  options?: { scope?: DataSourceScope; access?: DataSourceAccess },
 ): DataSource<T> {
   if (!VALID_SOURCE_NAME.test(name)) {
     throw new UiError(
@@ -98,7 +141,7 @@ export function defineDataSource<T>(
     );
   }
 
-  return { name, scope: options?.scope ?? "private" };
+  return { name, scope: options?.scope ?? "private", access: options?.access ?? "guarded" };
 }
 
 /** One bound prop on an island: which source feeds it, and where the client fetches it. */

package/src/index.ts

@@ -57,7 +57,7 @@ export { islandMount } from "./mount";
 // + `dataPrimerScript` are the STATIC-tier server delivery seams (the client half
 // lives in `@lesto/ui/client`'s hydration runtime).
 export { DATA_ROUTE_PREFIX, dataPrimerScript, dataSourceHref, defineDataSource } from "./data";
-export type { DataSource, DataSourceScope, IslandBind } from "./data";
+export type { DataSource, DataSourceAccess, DataSourceScope, IslandBind } from "./data";
 
 // The render-time source resolver (ADR 0012): the DYNAMIC-tier delivery that runs
 // loaders during the render and inlines the values — feeding the canonical
@@ -67,13 +67,17 @@ export { createSourceResolver, IslandDataContext, IslandDataProvider } from "./d
 export type { SourceResolver } from "./data-resolve";
 
 // Client data hooks (the first step of the reactive data layer, ADR 0027):
-// `useQuery`/`useMutation` over one shared cache giving in-flight dedupe +
-// explicit-by-key invalidation — NOT yet the schema-inferred invalidation a
-// later phase may add. Decoupled from
-// `@lesto/client` (the caller passes the fetcher/mutationFn thunk), so they stay
-// in this isomorphic core; the fetch is kicked from an effect, so SSR never fetches.
+// `useQuery`/`useMutation` over one shared cache giving in-flight dedupe,
+// explicit invalidation by key OR by topic (a mutation declares the topics it
+// dirties; a query subscribes to them — still EXPLICIT, never schema-inferred), and
+// opt-in background revalidation (staleTime / focus / reconnect / interval behind an
+// injected RevalidationEnvironment). Decoupled from `@lesto/client` (the caller passes
+// the fetcher/mutationFn thunk), so they stay in this isomorphic core; the fetch is
+// kicked from an effect, so SSR never fetches.
 export {
+  browserRevalidationEnvironment,
   defaultQueryClient,
+  hydrateQueryClient,
   QueryClient,
   serializeQueryKey,
   useMutation,
@@ -84,11 +88,29 @@ export type {
   MutationResultApi,
   MutationStatus,
   QueryKey,
+  QueryOptions,
   QueryResult,
   QuerySnapshot,
   QueryStatus,
+  RevalidationEnvironment,
 } from "./data-client";
 
+// The realtime consumer (ADR 0027 Phase 2 over the ADR 0040 transport): `connectLive`
+// opens the app's `GET /__lesto/live` SSE stream and drives `QueryClient.invalidateTopic`
+// so a mounted `useQuery` goes LIVE — a peer's write refetches it. `useLive` is the
+// island hook that holds the subscription for the component's lifetime. The wire carries
+// a topic, never row data (the ADR 0027 invariant), so this stays in the isomorphic core
+// (SSR-safe: `EventSource` is touched only from a client effect); it drives the
+// `QueryClient` seam and reads an `EventSource`, taking NO `@lesto/realtime` dependency.
+export { browserLiveEnvironment, connectLive, useLive } from "./live";
+export type {
+  ConnectLiveOptions,
+  LiveEnvironment,
+  LiveEventSource,
+  LiveMessageEvent,
+  UseLiveOptions,
+} from "./live";
+
 // The audited seam for inlining island JSON into a `<script>`: escapes the
 // breakout characters `JSON.stringify` leaves raw. ALL island-manifest emission
 // MUST go through this — never a bare stringify or a `String.replace` splice.
@@ -99,26 +121,13 @@ export type {
 // `#lesto-islands` manifest.
 export { serializeManifest, serializeScriptJson } from "./serialize";
 
-// Resource hints + LCP/modulepreload conventions over React 19's native APIs.
-// Server-safe: the `react-dom` resource functions are isomorphic and only emit
-// markup during an SSR render.
-export {
-  lcpImage,
-  modulePreload,
-  preconnect,
-  prefetchDNS,
-  preinit,
-  preinitModule,
-  preload,
-} from "./resources";
-export type {
-  LcpImageProps,
-  PreconnectOptions,
-  PreinitModuleOptions,
-  PreinitOptions,
-  PreloadOptions,
-  ResourceRegistrar,
-} from "./resources";
+// Resource hints + LCP/modulepreload conventions over React 19's native APIs
+// (`lcpImage`/`modulePreload`/`preconnect`/…) are an SSR document-head concern and
+// import the resource functions from bare `react-dom`, so they are NOT re-exported
+// here — they live behind the `@lesto/ui/server` subpath. Keeping them off this
+// isomorphic barrel means the client/island bundle never even references
+// `react-dom`, so a stray future re-export can't drag it in (defense-in-depth over
+// the `sideEffects:false` tree-shake that already drops the unused symbols).
 
 // Document metadata helpers + the dedup convention React's hoist-without-dedupe
 // leaves to the framework. Pure: React elements / data in, data out.

package/src/live.ts

@@ -0,0 +1,191 @@
+/**
+ * `connectLive` / `useLive` — the browser consumer of the realtime SSE fan-out
+ * (ADR 0040 Phase B) that turns a plain {@link useQuery} into a **live** one.
+ *
+ * It opens the app's `GET /__lesto/live` Server-Sent-Events stream and maps each
+ * frame onto the {@link QueryClient}: an `invalidate` frame drops one topic (so a
+ * mounted `useQuery` refetches it through its own authorized read), and a `resync`
+ * frame refetches every subscribed topic (the always-correct floor when the server
+ * cannot prove continuity). The wire carries a **topic, never row data** (the ADR
+ * 0027 invariant); this file never sees a row.
+ *
+ * Decoupled from `@lesto/realtime` on purpose: this consumer only drives the
+ * `QueryClient` seam and reads an `EventSource`, so `@lesto/ui` keeps no realtime
+ * dependency. Opt-in and side-effect-free until called, so it tree-shakes away on a
+ * page that never goes live.
+ */
+
+import { useEffect, useRef } from "react";
+
+import { defaultQueryClient } from "./data-client";
+import type { QueryClient } from "./data-client";
+
+/** The reserved path the runtime recognizes as a long-lived stream (ADR 0040). */
+const DEFAULT_LIVE_PATH = "/__lesto/live";
+
+/**
+ * The slice of an SSE message event {@link connectLive} reads — just its `data`. A
+ * named `invalidate` event carries the topic here; a `resync` carries the empty
+ * string. Narrow on purpose, so a fake satisfies it without a real `EventSource`.
+ */
+export interface LiveMessageEvent {
+  readonly data: string;
+}
+
+/**
+ * The slice of an `EventSource` {@link connectLive} drives — a listener for the
+ * named events, and a close. The browser `EventSource` satisfies this through
+ * {@link browserLiveEnvironment}; a test injects a fake.
+ */
+export interface LiveEventSource {
+  addEventListener(
+    type: "invalidate" | "resync" | "error",
+    listener: (event: LiveMessageEvent) => void,
+  ): void;
+
+  close(): void;
+}
+
+/**
+ * Opens a {@link LiveEventSource} for a URL — the seam through which
+ * {@link connectLive} reaches `EventSource`. Injected so a test fakes the whole
+ * stream and importing this module stays SSR-safe: the global `EventSource` is
+ * touched only inside the default's `open`, never at import or during a render.
+ */
+export interface LiveEnvironment {
+  open(url: string): LiveEventSource;
+}
+
+/** The default {@link LiveEnvironment} over the browser's native `EventSource`. */
+export const browserLiveEnvironment: LiveEnvironment = {
+  open(url) {
+    const source = new EventSource(url);
+
+    return {
+      addEventListener: (type, listener) =>
+        source.addEventListener(type, (event) => listener(event as MessageEvent)),
+
+      close: () => source.close(),
+    };
+  },
+};
+
+/** Options for {@link connectLive}. */
+export interface ConnectLiveOptions {
+  /** The topics to subscribe to; each is invalidated live as the server pushes it. */
+  readonly topics: readonly string[];
+
+  /** The cache to invalidate — defaults to the shared {@link defaultQueryClient}. */
+  readonly client?: QueryClient;
+
+  /** The live-stream path the app mounted. Defaults to `/__lesto/live`. */
+  readonly path?: string;
+
+  /** The `EventSource` seam — defaults to {@link browserLiveEnvironment}. */
+  readonly environment?: LiveEnvironment;
+
+  /**
+   * Notified of a stream `error` (a transient disconnect). Informational only:
+   * `EventSource` reconnects on its own — resuming from its last `id:` via the
+   * `Last-Event-ID` header — so a handler here need not reconnect, only observe.
+   */
+  readonly onError?: (event: LiveMessageEvent) => void;
+}
+
+/**
+ * Open a live subscription: stream `(topic, cursor)` invalidations from the app's
+ * `GET /__lesto/live` SSE endpoint and drive {@link QueryClient.invalidateTopic}, so
+ * a mounted `useQuery` refetches the instant a peer's write dirties one of its topics
+ * — "live `useQuery`" (ADR 0027 Phase 2 over the ADR 0040 transport).
+ *
+ * `EventSource` handles reconnect and the resume cursor (`Last-Event-ID`) natively
+ * and ignores the heartbeat comments, so this consumer only maps the two named
+ * events onto the cache: an `invalidate` frame's `data` is the single topic to drop;
+ * a `resync` frame refetches every subscribed topic.
+ *
+ * Unauthorized topics are **not** an error here: the server drops them silently — no
+ * delivery, no timing signal (ADR 0040's `selectAuthorizedTopics`) — so a client that
+ * asks for a topic it may not see simply never receives it, and this consumer never
+ * learns the difference.
+ *
+ * Returns a disconnect thunk — call it on unmount (or use {@link useLive}, which
+ * does). Framework-agnostic; the React lifetime lives in {@link useLive}.
+ */
+export function connectLive(options: ConnectLiveOptions): () => void {
+  const client = options.client ?? defaultQueryClient;
+  const path = options.path ?? DEFAULT_LIVE_PATH;
+  const environment = options.environment ?? browserLiveEnvironment;
+  const { topics, onError } = options;
+
+  const query = new URLSearchParams({ topics: topics.join(",") });
+
+  const source = environment.open(`${path}?${query.toString()}`);
+
+  // An `invalidate` frame's `data` is the single topic to drop and refetch.
+  source.addEventListener("invalidate", (event) => {
+    void client.invalidateTopic(event.data);
+  });
+
+  // A `resync` frame carries no topic: refetch everything this connection subscribes to.
+  source.addEventListener("resync", () => {
+    void client.invalidateTopics(topics);
+  });
+
+  // A stream error is informational (EventSource reconnects itself); forward it only
+  // when the caller asked to observe.
+  if (onError !== undefined) {
+    source.addEventListener("error", onError);
+  }
+
+  return () => source.close();
+}
+
+/** Options for {@link useLive} — everything {@link connectLive} takes but the topics. */
+export type UseLiveOptions = Omit<ConnectLiveOptions, "topics">;
+
+/**
+ * The island hook: hold a live subscription for `topics` open while the component is
+ * mounted, re-subscribing when the topic SET changes and disconnecting on unmount. A
+ * thin {@link connectLive} wrapper — the effect owns the connection's lifetime.
+ *
+ * SSR-safe: the connection is opened from an effect (never during render), so a
+ * server render neither touches `EventSource` nor holds a stream. Pair it with a
+ * `useQuery` reading the same topics and the query goes live.
+ *
+ * **One connection per call — call it ONCE, high in a view.** Unlike `useQuery` (which
+ * dedupes by key), each `useLive` opens its OWN `EventSource`. Calling it in many
+ * components — e.g. once per list row — opens many streams and can exhaust the browser's
+ * per-origin connection budget and the server's per-IP stream cap. Subscribe to every
+ * topic a view needs in a single `useLive` at the top of that view.
+ *
+ * **Options are read when the subscription opens and must be STABLE across renders.**
+ * Only a change to the topic SET reopens the stream; a new `client`/`path`/`environment`/
+ * `onError` identity on a later render is ignored. Pass a stable `client` (not
+ * `new QueryClient()` per render) — the same expectation `useQuery` has of its `client`.
+ */
+export function useLive(topics: readonly string[], options?: UseLiveOptions): void {
+  // Topics through a ref so the effect re-runs only when the SET changes (keyed by
+  // `topicsKey`), not on every render's fresh array identity. Joined on "," — the wire
+  // delimiter a topic can never contain — so the key is unambiguous (a space-joined key
+  // would collide `["a b"]` with `["a", "b"]`).
+  const topicsRef = useRef(topics);
+  topicsRef.current = topics;
+  const topicsKey = topics.join(",");
+
+  // The latest options through a ref, so a new `client`/`onError` closure identity
+  // does not tear down and reopen the stream — only a topic-set change does.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    const o: UseLiveOptions = optionsRef.current ?? {};
+
+    return connectLive({
+      topics: topicsRef.current,
+      ...(o.client !== undefined ? { client: o.client } : {}),
+      ...(o.path !== undefined ? { path: o.path } : {}),
+      ...(o.environment !== undefined ? { environment: o.environment } : {}),
+      ...(o.onError !== undefined ? { onError: o.onError } : {}),
+    });
+  }, [topicsKey]);
+}

package/src/server.ts

@@ -1,9 +1,10 @@
 /**
  * `@lesto/ui/server` — the server-render half of the engine.
  *
- * Everything here imports `react-dom/server` (or its Preact twin,
- * `preact-render-to-string`) directly or transitively: the buffered and streamed
- * page renderers and the two server-render dialects. It is split out of the core
+ * Everything here pulls in the `react-dom` family directly or transitively:
+ * `react-dom/server` (or its Preact twin, `preact-render-to-string`) for the
+ * buffered and streamed page renderers and the two server-render dialects, plus
+ * bare `react-dom` for the React 19 resource-hint helpers. It is split out of the core
  * `@lesto/ui` barrel for one load-bearing reason — a CLIENT bundle that imports
  * `@lesto/ui` (for `Registry`, `defineIsland`, the island/data tokens) must NEVER
  * drag `react-dom/server` into the browser graph. React's `react-dom/server` is
@@ -42,3 +43,26 @@ export type {
 // (`preact-render-to-string`), present only when an adopter chooses Preact, so a
 // default React server never drags Preact's renderer into its build.
 export { preactServerRenderer } from "./server-preact";
+
+// Resource hints + LCP/modulepreload conventions over React 19's native APIs.
+// These import the resource functions from bare `react-dom` and only emit markup
+// during an SSR render (an SSR document-head concern, never called client-side),
+// so they live behind this server subpath — off the isomorphic barrel — to keep
+// `react-dom` out of the client/island bundle's import graph entirely.
+export {
+  lcpImage,
+  modulePreload,
+  preconnect,
+  prefetchDNS,
+  preinit,
+  preinitModule,
+  preload,
+} from "./resources";
+export type {
+  LcpImageProps,
+  PreconnectOptions,
+  PreinitModuleOptions,
+  PreinitOptions,
+  PreloadOptions,
+  ResourceRegistrar,
+} from "./resources";

package/src/softnav-contract.ts

@@ -47,10 +47,12 @@ export type PrefetchStrategy = "viewport" | "hover";
  * below the deepest common layout.
  *
  * The runtime treats this as ENTIRELY OPTIONAL: a document with no such markers
- * falls back to the full-body swap (today's behavior), so this never becomes
- * load-bearing. EMITTING the marker is the server renderer's job (`@lesto/web`'s
- * `render-page.tsx` / the file-route layout composer) — until it does, the partial
- * swap is dormant and the full swap runs, with no regression.
+ * falls back to the full-body swap, so this never becomes load-bearing. EMITTING the
+ * marker is the server renderer's job — `@lesto/web`'s `wrap` (`render-page.tsx`,
+ * shared by the app-level and file-route layout chains) stamps one `display:contents`
+ * marker around each layout's children, so a page with layouts gets a marker per
+ * layout depth and the partial swap activates; a page with none emits no marker and
+ * the full-body swap runs, with no regression.
  */
 export const LAYOUT_ATTR = "data-lesto-layout";
 

package/src/softnav.ts

@@ -46,7 +46,7 @@
 
 import { UiError } from "./errors";
 import { hydrateDocumentIslands } from "./hydrate";
-import type { HydrateOptions, HydrationResult } from "./hydrate";
+import type { HydrateOptions, HydrationResult, IslandRoot } from "./hydrate";
 import type { Registry } from "./registry";
 import { eligibleAnchor, LAYOUT_ATTR, PREFETCH_ATTR, RELOAD_ATTR } from "./softnav-contract";
 import type { PrefetchStrategy, SoftNavAnchor, SoftNavClick } from "./softnav-contract";
@@ -117,15 +117,47 @@ export interface FetchedPage {
 export type PageFetcher = (url: string, signal: AbortSignal) => Promise<FetchedPage>;
 
 /**
- * Swap the fetched document's body into the live one and return the new title.
+ * What a swap REPLACED: the new `<title>` to adopt (or `undefined` to leave the tab
+ * alone) and the live SUBTREE whose contents now hold the swapped-in page — the
+ * element the caller re-hydrates, and ONLY that element. Scoping re-hydration to the
+ * swapped subtree is what makes the layout-preserving partial swap safe: re-scanning
+ * the whole document would re-mount the PRESERVED outer layout's islands (there is no
+ * idempotency guard in `hydrateDocumentIslands`) and reset the very state the partial
+ * swap kept.
+ */
+export interface SwapResult {
+  /** The fetched `<title>`, or `undefined` when the page is title-less (don't blank the tab). */
+  title: string | undefined;
+
+  /** The live element whose CONTENTS were replaced — the re-hydration scope. */
+  root: IslandRoot;
+}
+
+/**
+ * Swap the fetched document's body into the live one. Returns a {@link SwapResult}
+ * (the new title + the swapped subtree to re-hydrate), or — the back-compatible
+ * shorthand — a bare title `string`/`undefined`, which the runtime reads as "re-hydrate
+ * the WHOLE document" (the pre-partial-swap behavior).
  *
- * The default {@link defaultSwap} parses the HTML, swaps the body — LAYOUT-PRESERVING
- * when the document carries {@link LAYOUT_ATTR} markers, else replacing the whole
- * body's contents — and returns the fetched `<title>`. A caller can inject a finer
- * swap (a single content region, a view-transition wrapper for Bet I) without this
- * module knowing how the page is structured.
+ * The default {@link defaultSwap} parses the HTML and swaps the body — LAYOUT-PRESERVING
+ * when the document carries {@link LAYOUT_ATTR} markers (it returns just the deepest
+ * shared layout's inner element as `root`), else replacing the whole body's contents
+ * (root = `<body>`). A caller can inject a finer swap (a single content region, a
+ * view-transition wrapper for Bet I) without this module knowing how the page is
+ * structured; a finer swap that wants scoped re-hydration returns its own `root`.
+ */
+export type PageSwapper = (html: string, doc: Document) => SwapResult | string | undefined;
+
+/**
+ * Normalize a {@link PageSwapper}'s result to a {@link SwapResult}: a bare title
+ * (the back-compatible shorthand) becomes `{ title, root: <whole document> }`, so an
+ * old-style swap keeps the pre-partial-swap whole-document re-hydrate while a
+ * `SwapResult`-returning swap drives the scoped re-hydrate. The one place the union is
+ * collapsed, shared by both the soft-nav and dev-page-swap appliers.
  */
-export type PageSwapper = (html: string, doc: Document) => string | undefined;
+function readSwapResult(result: SwapResult | string | undefined, doc: Document): SwapResult {
+  return typeof result === "object" ? result : { title: result, root: doc };
+}
 
 /**
  * The re-hydrate call after a swap — defaults to {@link hydrateDocumentIslands}.
@@ -409,26 +441,30 @@ function deepestSharedLayout(
  * the live nodes — and the click listener delegated to `<body>`'s document — attached
  * across the swap. The head is left alone (the client module + styles already ran);
  * only the per-page `<title>` is carried over.
+ *
+ * Returns the swapped element as `root` — the body for a full swap, the deepest shared
+ * layout's inner element for a partial one — so the caller re-hydrates ONLY that
+ * subtree and a preserved outer layout's islands are never re-mounted.
  */
 const defaultSwap: PageSwapper = (html, doc) => {
   const parsed = new DOMParser().parseFromString(html, "text/html");
 
   const shared = deepestSharedLayout(doc.body, parsed.body);
 
-  if (shared === undefined) {
-    // No shared layout boundary → swap the whole body (the original behavior).
-    replaceContents(doc.body, parsed.body, doc);
-  } else {
-    // A shared outer layout → swap only its inner contents, preserving the outer
-    // layout DOM (and any island state mounted in it) across the navigation.
-    replaceContents(shared.live, shared.fetched, doc);
-  }
+  // The live element whose CONTENTS we replace, and therefore the subtree to
+  // re-hydrate. A shared outer layout → swap only its inner contents (the page + any
+  // deeper layouts), preserving every outer layout's DOM and island state; no shared
+  // boundary → the whole `<body>`, the original full-swap behavior.
+  const root = shared?.live ?? doc.body;
+  const fetched = shared?.fetched ?? parsed.body;
+
+  replaceContents(root, fetched, doc);
 
   // `textContent` is "" when the fetched page has no <title>; treat that as "no
   // title to set" so we never blank the tab on a title-less page.
   const title = parsed.title;
 
-  return title === "" ? undefined : title;
+  return { title: title === "" ? undefined : title, root };
 };
 
 /** The id of the framework-owned `aria-live` region soft nav announces routes through. */
@@ -643,7 +679,7 @@ export function enableSoftNav(registry: Registry, options: SoftNavOptions = {}):
         return;
       }
 
-      const title = swap(html, doc);
+      const { title, root } = readSwapResult(swap(html, doc), doc);
 
       if (title !== undefined) doc.title = title;
 
@@ -653,22 +689,15 @@ export function enableSoftNav(registry: Registry, options: SoftNavOptions = {}):
         hist.pushState({ lestoSoftNav: true, scroll: { x: 0, y: 0 } }, "", landed);
       }
 
-      // Re-hydrate against the JUST-SWAPPED document — `root` is the seam islands
-      // are looked up under, so the new body's mount scripts are the ones found,
-      // not the ambient global `document`'s.
-      //
-      // ACTIVATION CAVEAT for the layout-preserving partial swap: this re-hydrates
-      // the WHOLE document, which is correct ONLY for the full-body swap (today's
-      // path — no server emits `data-lesto-layout`, so `deepestSharedLayout` always
-      // returns undefined). The moment a server DOES emit those markers and a partial
-      // swap keeps an outer layout's DOM, re-scanning the whole doc here would re-mount
-      // that preserved layout's islands (no idempotency guard in `hydrateDocumentIslands`)
-      // and DESTROY the very state the partial swap preserves. So before wiring the
-      // marker, this must scope to the swapped subtree (the `defaultSwap` would have to
-      // surface which element it replaced) OR `hydrateDocumentIslands` must skip an
-      // already-mounted shell. Until then the partial-swap branch stays a dormant, pure
-      // fallback (see docs/plans/dx-parity.md W8) — never activate one without the other.
-      const hydration = rehydrate(registry, { root: doc });
+      // Re-hydrate ONLY the swapped subtree — `root` is the element whose contents
+      // the swap just replaced (the `<body>` for a full swap, or just the deepest
+      // shared layout's inner region for a layout-preserving partial swap). Scoping
+      // here is what makes the partial swap safe: re-scanning the WHOLE document would
+      // re-mount the preserved outer layout's islands (no idempotency guard in
+      // `hydrateDocumentIslands`) and DESTROY the very state the partial swap keeps.
+      // A full-body swap's `root` is the body, so this stays equivalent to the old
+      // whole-document re-hydrate (mount scripts live in the body, never the head).
+      const hydration = rehydrate(registry, { root });
 
       // The swapped-in page brings its own `viewport`-prefetch links; register them
       // so they warm as the user scrolls the new page. (Hover links are caught by
@@ -932,3 +961,98 @@ export function enableSoftNav(registry: Registry, options: SoftNavOptions = {}):
 
   return disable;
 }
+
+/**
+ * The window-global the `lesto dev` live-reload client calls to refresh the current
+ * page in place — the wire contract between the CLI's injected reload script
+ * (`@lesto/cli`'s `dev-overlay.ts`, a raw string that cannot import this module) and
+ * the hook {@link enableDevPageRefresh} installs. A literal both sides pin, like the
+ * live-reload WebSocket's message types: `dev-overlay.ts` hardcodes the SAME literal
+ * (it cannot import this constant across the package boundary), so a rename here must
+ * update it there too — `packages/e2e/page-swap.spec.ts` guards the pair end to end (a
+ * mismatch makes the client miss the hook → full reload → the spec's marker assertion fails).
+ */
+export const DEV_PAGE_REFRESH_GLOBAL = "__lestoDevRefreshPage";
+
+/** The injectable seams {@link enableDevPageRefresh} runs on; all default to the real browser. */
+export interface DevPageRefreshOptions {
+  /** The document to refresh + re-hydrate. Defaults to `document`. */
+  document?: Document;
+
+  /** How to fetch the current page's fresh HTML. Defaults to the same same-origin GET soft nav uses. */
+  fetchPage?: PageFetcher;
+
+  /** How to swap the fetched body in. Defaults to {@link defaultSwap} (layout-aware, full-body fallback). */
+  swap?: PageSwapper;
+
+  /** How to re-hydrate after the swap. Defaults to {@link hydrateDocumentIslands}. */
+  rehydrate?: Rehydrate;
+
+  /** Where the refresh hook is installed for the dev client to call. Defaults to the document's window. */
+  target?: Record<string, unknown>;
+}
+
+/**
+ * Install the `lesto dev` PAGE refresh hook: a function that re-fetches the CURRENT
+ * url, swaps its body in, and re-hydrates — the same fetch-and-swap soft nav does, but
+ * for a server-driven dev signal (a saved `app/routes/*` file) rather than a click.
+ *
+ * The CLI's live-reload client (`dev-overlay.ts`) calls the installed
+ * {@link DEV_PAGE_REFRESH_GLOBAL} on a `{type:"page-swap"}` frame instead of
+ * `location.reload()`, so a page edit re-renders WITHOUT the jarring full reload
+ * (scroll kept, no white flash, no asset re-download). A page is server-rendered, so
+ * there is no client component state to preserve — re-hydrating the whole document is
+ * exactly right here; the win is purely avoiding the reload. If the hook is absent or
+ * its refresh throws, the client falls back to a real reload — the floor always holds.
+ *
+ * The synthesized client entry (`@lesto/assets`'s `synthesizeEntry`) calls this only
+ * when built with `beacon.dev` — TODAY the island-dev (Vite) dev entry, the scaffold
+ * default. The Bun client build (`buildClient`, which serves `lesto dev`'s non-island-dev
+ * path AND prod) does not set it, so there the dev client falls back to a full reload and
+ * prod ships neither symbol nor call (extending it to the Bun dev path is tracked separately).
+ *
+ * Reuses {@link defaultSwap}, so when the server emits {@link LAYOUT_ATTR} markers the
+ * DOM swap is layout-preserving AND the re-hydrate is scoped to the swapped subtree
+ * (via the swap's returned `root`) — so editing an `app/routes/*` page re-renders just
+ * the page region and the unchanged layout's islands keep their state across the swap,
+ * no full reload and no re-mount. A page with no layouts swaps the whole body and
+ * re-hydrates it, exactly as before.
+ *
+ * Returns the refresh function (also installed on the target) so a test can drive it
+ * directly without reaching through the global.
+ */
+export function enableDevPageRefresh(
+  registry: Registry,
+  options: DevPageRefreshOptions = {},
+): () => Promise<void> {
+  const doc: Document = options.document ?? document;
+  const fetchPage: PageFetcher = options.fetchPage ?? defaultFetchPage;
+  const swap: PageSwapper = options.swap ?? defaultSwap;
+  const rehydrate: Rehydrate = options.rehydrate ?? hydrateDocumentIslands;
+
+  const refresh = async (): Promise<void> => {
+    // A dev refresh has no supersession/cancel story (unlike soft nav's click navigations),
+    // so a fresh, never-aborted controller just satisfies `PageFetcher`'s required signal.
+    const { html } = await fetchPage(doc.URL, new AbortController().signal);
+
+    const { title, root } = readSwapResult(swap(html, doc), doc);
+
+    if (title !== undefined) doc.title = title;
+
+    // Re-hydrate ONLY the swapped subtree — `root` is the element the swap replaced.
+    // For a full-body swap that is the body (re-mount every island, correct since the
+    // whole page changed); for a layout-preserving partial swap it is just the inner
+    // page region, so the unchanged outer layout's islands are NOT re-mounted and keep
+    // their state — the deferred half of the dev page-swap, now wired.
+    rehydrate(registry, { root });
+  };
+
+  // Install the hook for the dev client to call. The document's window is the default
+  // target; a detached document (a test fake) with no `defaultView` gets none — the
+  // returned `refresh` is still usable directly.
+  const target = options.target ?? (doc.defaultView as unknown as Record<string, unknown> | null);
+
+  if (target !== null && target !== undefined) target[DEV_PAGE_REFRESH_GLOBAL] = refresh;
+
+  return refresh;
+}