@nifrajs/web 5.5.0 → 5.6.0

package/dist/keep-alive.js

@@ -0,0 +1,1069 @@
+/**
+ * @nifrajs/web/keep-alive - pages that stay mounted after the visitor leaves them, so back and forward
+ * show them again as they were left. The generated client entry imports this only when a route
+ * exports `keepAlive`, so no other app's client chunks contain it.
+ *
+ * {@link keepAliveClient} layers over the router. The page on screen is kept when a push or a
+ * back/forward traversal leaves it (at most three, each for at most ten minutes, all dropped when the
+ * visitor signs in or out); a traversal back to a kept page's own history entry publishes that page at
+ * once, then reloads its data in place. Adapters render the active page and every kept one from
+ * {@link slotTree}, and {@link createSlotParking} takes the hidden ones out of the document.
+ */
+import { epochOf, IDENTITY_CHANNEL, onIdentityChange } from "./identity.js";
+import { PAGE_HIDE_EVENT, PAGE_SHOW_EVENT, releasePage } from "./internal/page-events.js";
+import { shareData } from "./internal/share-data.js";
+import { fetchRouteData, isRouteDataEnvelope, } from "./router.js";
+export { EPOCH_COOKIE, IDENTITY_CHANNEL, identityChanged } from "./identity.js";
+export { PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "./internal/page-events.js";
+/** Most pages kept per tab. */
+export const KEEP_ALIVE_MAX = 3;
+/** Longest a page stays hidden unless its route sets `keepAlive: { maxAge }`, in milliseconds. */
+export const KEEP_ALIVE_MAX_AGE_MS = 10 * 60 * 1000;
+const pathnameOf = (path) => {
+    const q = path.indexOf("?");
+    return q === -1 ? path : path.slice(0, q);
+};
+const pagePathOf = (state) => state.intercepted?.pagePath ?? state.path;
+// Unique per document, so an instance an entry carries from an earlier document never names one here.
+const DOCUMENT = Math.random().toString(36).slice(2, 8);
+let sequence = 0;
+const newInstance = () => `${++sequence}:${DOCUMENT}`;
+const ownInstance = (value) => typeof value === "string" && value.endsWith(`:${DOCUMENT}`) ? value : undefined;
+const readEntry = () => {
+    const state = typeof history === "undefined" ? null : history.state;
+    const fields = typeof state === "object" && state !== null ? state : {};
+    const index = Reflect.get(fields, "nifraIndex");
+    return {
+        index: typeof index === "number" ? index : 0,
+        instance: ownInstance(Reflect.get(fields, "nifraInstance")),
+    };
+};
+// The instance rides on the entry beside the history layer's own fields, which every write it makes
+// to an existing entry keeps; a fresh push or replace carries none.
+const stampEntry = (instance) => {
+    if (typeof history === "undefined")
+        return;
+    const state = history.state;
+    if (typeof state === "object" &&
+        state !== null &&
+        Reflect.get(state, "nifraInstance") === instance)
+        return;
+    try {
+        history.replaceState(Object.assign({}, typeof state === "object" ? state : null, { nifraInstance: instance }), "");
+    }
+    catch { }
+};
+const readEpoch = () => (typeof document === "undefined" ? "" : epochOf(document.cookie));
+const now = () => Date.now();
+/**
+ * Keep-alive for a router. See the module docs; the generated client entry wires it:
+ *
+ * ```ts
+ * const keep = keepAliveClient({ table, routeHooks, matchChains })
+ * const router = keep.attach(createClientRouter({ ..., fetchData: keep.fetchData }))
+ * installHistory(router)
+ * ```
+ */
+export function keepAliveClient(options) {
+    const { table, routeHooks, matchChains } = options;
+    const base = options.fetchData ?? fetchRouteData;
+    const max = options.max ?? KEEP_ALIVE_MAX;
+    const keepRoutes = new Set(table.routes);
+    const wrappedLayouts = new Set(table.layouts);
+    // The restore whose reload the router is running, which the transport answers.
+    let reloading;
+    const ownsLoader = (routeId) => routeId !== undefined && routeHooks[routeId]?.clientLoader !== undefined;
+    // What client-loader routes loaded since the page on screen settled. A restore that loads nothing
+    // runs the client loader over the kept page's own, as a navigation over prefetched data does.
+    const fresh = new Map();
+    const noteSource = (path, payload) => {
+        if (!isRouteDataEnvelope(payload))
+            fresh.set(path, payload);
+        else if (payload.status === undefined)
+            fresh.set(path, payload.data);
+    };
+    const sourcesOf = (state) => {
+        const sources = new Map();
+        for (const path of [pagePathOf(state), state.path])
+            if (fresh.has(path))
+                sources.set(path, fresh.get(path));
+        return sources.size === 0 ? undefined : sources;
+    };
+    // A restored page's reload: its kept data, unrequested, when it needs no reload; otherwise the
+    // response shared onto the kept data, so what did not change keeps the identity it has on screen.
+    // A reload that fails shows the kept data instead of loading the page as a document.
+    const fetchData = async (path, match, signal, navigation, purpose, hosts, read) => {
+        const restore = reloading;
+        const held = restore?.kept.intercepted;
+        // A page kept with a boundary open reloads twice: its own data, then the target the boundary holds.
+        const target = held !== undefined && path === restore?.kept.path && path !== restore.pagePath
+            ? restore.kept.boundaries?.[held.boundary]
+            : undefined;
+        if (restore === undefined || (path !== restore.pagePath && target === undefined)) {
+            if (purpose === "prefetch" || !ownsLoader(match.routeId))
+                return base(path, match, signal, navigation, purpose, hosts, read);
+            const payload = await base(path, match, signal, navigation, purpose, hosts, read);
+            noteSource(path, payload);
+            return payload;
+        }
+        const sourced = restore.sources?.has(path) === true;
+        const kept = () => {
+            const data = sourced ? restore.sources?.get(path) : target?.data;
+            if (target !== undefined)
+                return { v: 1, data, live: target.live };
+            const envelope = envelopeOf(restore.kept);
+            if (sourced)
+                envelope.data = data;
+            return envelope;
+        };
+        // The page's hole hosts reload as fills, applied in place on the roots kept with it, even when
+        // the route keeps its own data.
+        const holes = target === undefined ? hostsOf(restore.kept) : [];
+        if (!restore.reload && holes.length === 0)
+            return kept();
+        let payload;
+        try {
+            payload = await base(path, match, signal, navigation, purpose, holes.length === 0 ? hosts : holes, read);
+        }
+        catch (error) {
+            if (signal?.aborted === true || hasRedirect(error))
+                throw error;
+            return kept();
+        }
+        if (!restore.reload)
+            return fillsOnto(kept(), restore.kept, payload, holes);
+        if (ownsLoader(match.routeId))
+            noteSource(path, payload);
+        const hooks = routeHooks[target === undefined ? restore.kept.routeId : match.routeId];
+        // `read` itself answers a reload whose response text is what the path shows, which the router
+        // keeps unparsed.
+        if (payload === read || hooks?.shareData === false)
+            return payload;
+        // The router's transport records the text of a plain JSON response, a tree with no symbol keys.
+        const plainJson = read?.text !== undefined && hooks?.clientLoader === undefined;
+        return target === undefined
+            ? sharedOnto(restore.kept, payload, plainJson)
+            : targetOnto(target.data, payload, plainJson);
+    };
+    const attach = (inner) => {
+        const records = new Map();
+        const listeners = new Set();
+        const before = new Set();
+        const wrappedFetchers = new Map();
+        let keptPages;
+        let lastEpoch = readEpoch();
+        const first = readEntry();
+        const initial = inner.snapshot();
+        // A client loader runs over the document's own data as the router hydrates.
+        if (ownsLoader(initial.routeId))
+            fresh.set(initial.path, initial.data);
+        // Where the page's data came from: `epoch` is the one it was loaded under (a page left after a
+        // sign-in or sign-out shows the previous visitor's data, so it is not kept), and `sources` what
+        // a client loader built it from.
+        let active = {
+            instance: first.instance ?? newInstance(),
+            index: first.index,
+            settled: initial,
+            epoch: lastEpoch,
+            sources: sourcesOf(initial),
+        };
+        stampEntry(active.instance);
+        if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
+            Reflect.set(globalThis, KEPT_PAGES_GLOBAL, {
+                pages: () => describeKept(records.values()),
+            });
+        // What is on screen: the router's state, or a restored page's kept state until its reload lands.
+        let shown = active.settled;
+        let flags;
+        // The page being left stays mounted, hidden, while a `_loading` page takes its place.
+        let leaving = false;
+        // The page being left is gone (dropped, or unmountable) before its navigation settled.
+        let leftGone = false;
+        const keepAliveOf = (routeId) => keepRoutes.has(routeId) ? routeHooks[routeId]?.keepAlive : undefined;
+        // A boundary open over the page is kept with it (its target is the page's to show again).
+        const keepable = (state) => !state.pending && keepAliveOf(state.routeId) !== undefined;
+        // One page instance per route, and per pathname on a route that keeps alive, whose pages would
+        // otherwise have nothing to keep.
+        const sameInstance = (a, b) => a.routeId === b.routeId &&
+            (!keepRoutes.has(b.routeId) || pathnameOf(pagePathOf(a)) === pathnameOf(pagePathOf(b)));
+        const compose = () => {
+            keptPages ??= [...records.values()].map((record) => record.page);
+            const kept = leaving
+                ? [...keptPages, { instance: active.instance, state: active.settled }]
+                : keptPages;
+            return {
+                ...shown,
+                instance: leaving ? undefined : active.instance,
+                kept: kept.length === 0 ? undefined : kept,
+                ...flags,
+            };
+        };
+        let published = compose();
+        const drop = (instances, reason) => {
+            const gone = instances.filter((instance) => records.delete(instance));
+            if (gone.length === 0)
+                return;
+            keptPages = undefined;
+            options.onDrop?.(reason, gone);
+        };
+        const refresh = () => {
+            let next = compose();
+            // A kept page whose chain leaves the page on screen at an unwrapped layout cannot be hidden.
+            const stuck = unplaceable(next, matchChains, keepRoutes, wrappedLayouts);
+            if (stuck.length > 0) {
+                if (leaving && stuck.includes(active.instance)) {
+                    leaving = false;
+                    leftGone = true;
+                }
+                drop(stuck, "layout");
+                next = compose();
+            }
+            for (const listener of [...before])
+                listener(next);
+            published = next;
+            for (const listener of [...listeners])
+                listener();
+        };
+        const dropKept = (reason = "manual") => {
+            const left = leaving || inner.snapshot().pending;
+            if (records.size === 0 && !leaving) {
+                if (left)
+                    leftGone = true;
+                return;
+            }
+            if (left) {
+                leaving = false;
+                leftGone = true;
+            }
+            drop([...records.keys()], reason);
+            refresh();
+        };
+        const sweep = () => {
+            const at = now();
+            const expired = [];
+            for (const [instance, record] of records)
+                if (at - record.hiddenAt > record.maxAge)
+                    expired.push(instance);
+            drop(expired, "expired");
+        };
+        // A response or another tab may carry a new epoch: what was kept belonged to the previous visitor.
+        const checkEpoch = () => {
+            const epoch = readEpoch();
+            if (epoch === lastEpoch)
+                return;
+            lastEpoch = epoch;
+            channel?.postMessage("changed");
+            dropKept("identity");
+        };
+        const keep = ({ instance, index, settled: state, epoch, sources }) => {
+            if (!keepable(state) || epoch !== readEpoch())
+                return;
+            const setting = keepAliveOf(state.routeId);
+            const settings = typeof setting === "object" ? setting : {};
+            records.delete(instance);
+            records.set(instance, {
+                page: { instance, state },
+                index,
+                epoch,
+                sources,
+                hiddenAt: now(),
+                maxAge: settings.maxAge ?? KEEP_ALIVE_MAX_AGE_MS,
+                revalidate: settings.revalidate !== false,
+                stale: false,
+            });
+            keptPages = undefined;
+            if (records.size > max)
+                drop([...records.keys()].slice(0, records.size - max), "lru");
+        };
+        const settle = (next) => {
+            const entry = readEntry();
+            if (sameInstance(active.settled, next)) {
+                // Data the router did not load again is still the data it was loaded with.
+                const same = next.data === active.settled.data;
+                active = {
+                    instance: active.instance,
+                    index: entry.index,
+                    settled: next,
+                    epoch: same ? active.epoch : readEpoch(),
+                    sources: same ? active.sources : sourcesOf(next),
+                };
+            }
+            else {
+                // The page on screen was left: by a push (a fresh entry above it), a traversal (an entry that
+                // already carries an instance), or a replace (its own entry rewritten), which discards it.
+                if (entry.index > active.index && entry.instance === undefined) {
+                    drop([...records].filter(([, record]) => record.index >= entry.index).map(([id]) => id), "forward");
+                }
+                if (entry.index !== active.index && !leftGone)
+                    keep(active);
+                const reuse = entry.index !== active.index &&
+                    entry.instance !== undefined &&
+                    entry.instance !== active.instance &&
+                    !records.has(entry.instance)
+                    ? entry.instance
+                    : undefined;
+                active = {
+                    instance: reuse ?? newInstance(),
+                    index: entry.index,
+                    settled: next,
+                    epoch: readEpoch(),
+                    sources: sourcesOf(next),
+                };
+            }
+            fresh.clear();
+            stampEntry(active.instance);
+            sweep();
+            shown = next;
+            flags = undefined;
+            leaving = false;
+            leftGone = false;
+            refresh();
+            checkEpoch();
+        };
+        let restoring;
+        const endRestore = () => {
+            const restore = restoring;
+            restoring = undefined;
+            reloading = undefined;
+            restore?.done();
+        };
+        inner.subscribe(() => {
+            const next = inner.snapshot();
+            const restore = restoring;
+            if (restore !== undefined) {
+                // The restored page stays on screen while its reload runs: the router's own pending tick for
+                // it is not a navigation the visitor made. A redirect it follows is.
+                if (next.pending &&
+                    (next.pendingPath === undefined ||
+                        next.pendingPath === restore.path ||
+                        next.pendingPath === restore.pagePath))
+                    return;
+                const onPage = !next.pending &&
+                    pagePathOf(next) === restore.pagePath &&
+                    next.routeId === restore.kept.routeId;
+                // The page alone, on the way to opening its boundary on the target again.
+                if (onPage && restore.kept.intercepted !== undefined && next.intercepted === undefined)
+                    return;
+                endRestore();
+                if (onPage) {
+                    active = {
+                        instance: active.instance,
+                        index: active.index,
+                        settled: next,
+                        epoch: restore.reload ? readEpoch() : active.epoch,
+                        // A reload that failed shows the kept data, from the kept sources.
+                        sources: sourcesOf(next) ?? active.sources,
+                    };
+                    fresh.clear();
+                    shown = { ...next, params: shareData(restore.kept.params, next.params) };
+                    flags = undefined;
+                    refresh();
+                    checkEpoch();
+                    return;
+                }
+            }
+            if (!next.pending) {
+                settle(next);
+                return;
+            }
+            shown = next;
+            flags = undefined;
+            leaving = next.routeId !== active.settled.routeId && !leftGone && keepable(active.settled);
+            refresh();
+        });
+        const restore = (path, instance, record) => {
+            const entry = readEntry();
+            records.delete(instance);
+            keptPages = undefined;
+            if (!leftGone)
+                keep(active);
+            const kept = record.page.state;
+            const { sources } = record;
+            active = { instance, index: entry.index, settled: kept, epoch: record.epoch, sources };
+            fresh.clear();
+            // Data a client loader built is shown again only from what it was built from.
+            const unsourced = (ownsLoader(kept.routeId) && sources?.has(pagePathOf(kept)) !== true) ||
+                (kept.intercepted !== undefined &&
+                    ownsLoader(inner.match(kept.path)?.routeId) &&
+                    sources?.has(kept.path) !== true);
+            const reload = record.revalidate || record.stale || kept.path !== path || unsourced;
+            const modal = kept.intercepted;
+            const pagePath = modal === undefined ? path : modal.pagePath;
+            let done = () => { };
+            const ended = new Promise((resolve) => {
+                done = resolve;
+            });
+            endRestore();
+            const mine = { path, pagePath, kept, reload, sources, done, ended };
+            restoring = mine;
+            reloading = { path, pagePath, kept, reload, sources };
+            stampEntry(instance);
+            shown = kept;
+            flags = { restored: true, revalidating: reload };
+            leaving = false;
+            leftGone = false;
+            refresh();
+            // The router shows a boundary's target only over the page it opened on: it loads the page, then
+            // opens the boundary on the target again, as the link that first opened it did.
+            const reloaded = modal === undefined
+                ? inner.navigate(path)
+                : inner.navigate(pagePath).then(() => {
+                    const now = inner.snapshot();
+                    const onPage = restoring === mine &&
+                        !now.pending &&
+                        now.routeId === kept.routeId &&
+                        pagePathOf(now) === pagePath;
+                    return onPage ? inner.navigate(path) : undefined;
+                });
+            return reloaded.finally(() => {
+                if (restoring === mine)
+                    endRestore();
+            });
+        };
+        const navigate = (path, navOptions) => {
+            sweep();
+            const instance = navOptions?.traverse ?? readEntry().instance;
+            const record = instance === undefined || instance === active.instance ? undefined : records.get(instance);
+            if (instance !== undefined && record !== undefined) {
+                if (record.epoch !== readEpoch())
+                    dropKept("identity");
+                else if (pathnameOf(record.page.state.path) === pathnameOf(path))
+                    return restore(path, instance, record);
+            }
+            endRestore();
+            return inner.navigate(path);
+        };
+        // A submit or an invalidation may change what a hidden page shows; the response that says which
+        // paths (`X-Nifra-Revalidate`) is read inside the router, so every kept page reloads when shown.
+        const markStale = (paths) => {
+            for (const record of records.values()) {
+                const { state } = record.page;
+                if (paths === undefined || paths.includes(pagePathOf(state)) || paths.includes(state.path))
+                    record.stale = true;
+            }
+        };
+        // A submit or an invalidation acts on the page on screen, which a restore hands to the router only
+        // once its reload settles.
+        const afterRestore = async () => {
+            while (restoring !== undefined)
+                await restoring.ended;
+        };
+        const channel = typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(IDENTITY_CHANNEL);
+        const identityDrop = () => {
+            lastEpoch = readEpoch();
+            dropKept("identity");
+        };
+        channel?.addEventListener("message", identityDrop);
+        onIdentityChange(identityDrop);
+        if (typeof addEventListener === "function") {
+            addEventListener("pagehide", (event) => {
+                if ("persisted" in event && event.persisted === true)
+                    dropKept("pagehide");
+            });
+            addEventListener("visibilitychange", () => {
+                if (document.visibilityState === "visible")
+                    checkEpoch();
+            });
+        }
+        return {
+            snapshot: () => published,
+            subscribe: (listener) => {
+                listeners.add(listener);
+                return () => {
+                    listeners.delete(listener);
+                };
+            },
+            navigate,
+            submit: async (action, body, submitOptions) => {
+                await afterRestore();
+                try {
+                    await inner.submit(action, body, submitOptions);
+                }
+                finally {
+                    markStale();
+                    checkEpoch();
+                }
+            },
+            hydrate: () => inner.hydrate(),
+            invalidate: (paths) => {
+                markStale(paths);
+                // At once when nothing is restoring: the live client names its load around this call.
+                return restoring === undefined
+                    ? inner.invalidate(paths)
+                    : afterRestore().then(() => inner.invalidate(paths));
+            },
+            prefetch: (path) => inner.prefetch(path),
+            fetcher: (key) => {
+                let fetcher = wrappedFetchers.get(key);
+                if (fetcher === undefined) {
+                    const own = inner.fetcher(key);
+                    fetcher = {
+                        snapshot: own.snapshot,
+                        subscribe: own.subscribe,
+                        load: own.load,
+                        submit: async (action, body) => {
+                            try {
+                                await own.submit(action, body);
+                            }
+                            finally {
+                                markStale();
+                                checkEpoch();
+                            }
+                        },
+                    };
+                    wrappedFetchers.set(key, fetcher);
+                }
+                return fetcher;
+            },
+            fetchers: () => inner.fetchers(),
+            subscribeFetchers: (listener) => inner.subscribeFetchers(listener),
+            match: (path) => inner.match(path),
+            dropKept,
+            beforePublish: (listener) => {
+                before.add(listener);
+                return () => {
+                    before.delete(listener);
+                };
+            },
+        };
+    };
+    return { fetchData, attach };
+}
+const hasRedirect = (error) => typeof error === "object" &&
+    error !== null &&
+    typeof Reflect.get(error, "redirectTo") === "string";
+/** A held target's reload, its data shared onto what the boundary shows. */
+const targetOnto = (shown, payload, plainJson) => {
+    if (!isRouteDataEnvelope(payload))
+        return shareData(shown, payload, plainJson);
+    if (payload.status !== undefined)
+        return payload;
+    return { ...payload, data: shareData(shown, payload.data, plainJson) };
+};
+/** The holes of `state`'s page that are hosts a partially prerendered document left open. */
+const hostsOf = (state) => Object.values(state.boundaries ?? {})
+    .filter((held) => held.ppr === true)
+    .map((held) => held.name);
+/** `envelope`, what `kept` shows, with the fills `payload` carries for its hole hosts `holes` and
+ * nothing else of it. */
+const fillsOnto = (envelope, kept, payload, holes) => {
+    if (!isRouteDataEnvelope(payload) || payload.status !== undefined)
+        return envelope;
+    const boundaries = { ...kept.boundaries };
+    for (const name of holes) {
+        const fill = payload.boundaries?.[name];
+        if (fill?.ppr === true)
+            boundaries[name] = fill;
+    }
+    return { ...envelope, boundaries };
+};
+/** A route data envelope that publishes exactly `state`'s data. */
+const envelopeOf = (state) => {
+    const envelope = {
+        v: 1,
+        data: state.data,
+        layoutData: state.layoutData,
+        serverComponents: state.serverComponents,
+        live: state.live,
+    };
+    if (state.boundaries !== undefined)
+        envelope.boundaries = state.boundaries;
+    return envelope;
+};
+/** `payload` with every part equal to what `kept` shows replaced by that part. A layout the server
+ * skipped (`retained`) takes the value on screen, as on any navigation. */
+const sharedOnto = (kept, payload, plainJson) => {
+    if (!isRouteDataEnvelope(payload))
+        return shareData(kept.data, payload, plainJson);
+    if (payload.status !== undefined)
+        return payload;
+    const retained = new Set(payload.retained ?? []);
+    return {
+        ...payload,
+        data: shareData(kept.data, payload.data, plainJson),
+        layoutData: payload.layoutData?.map((value, index) => retained.has(index) ? value : shareData(kept.layoutData?.[index], value, plainJson)),
+        ...(payload.boundaries === undefined
+            ? {}
+            : { boundaries: shareData(kept.boundaries, payload.boundaries, plainJson) }),
+        serverComponents: shareData(kept.serverComponents, payload.serverComponents, plainJson),
+    };
+};
+const NO_LAYOUTS = [];
+// The `_loading` page shown while a navigation runs has no instance of its own.
+const LOADING = "\0loading";
+const memberOf = (instance, state, hidden, recency, chains) => {
+    const ids = chains[state.routeId]?.ids;
+    const order = instance === undefined ? Number.MAX_SAFE_INTEGER : Number.parseInt(instance, 10);
+    return {
+        key: instance === undefined ? LOADING : `\0${instance}`,
+        order: Number.isNaN(order) ? Number.MAX_SAFE_INTEGER : order,
+        recency,
+        state,
+        hidden,
+        layouts: ids === undefined ? NO_LAYOUTS : ids.slice(0, -1),
+        leaf: ids?.at(-1) ?? state.routeId,
+    };
+};
+const membersOf = (state, chains) => {
+    const kept = state.kept ?? [];
+    const members = kept.map((page, i) => memberOf(page.instance, page.state, true, i, chains));
+    members.push(memberOf(state.instance, state, false, kept.length, chains));
+    return members.sort((a, b) => a.order - b.order || (a.key < b.key ? -1 : 1));
+};
+const levelOf = (members, depth, pages, layouts, previous) => {
+    const groups = new Map();
+    for (const member of members) {
+        const key = member.layouts[depth] ?? member.key;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, [member]);
+        else
+            group.push(member);
+    }
+    const nodes = [];
+    for (const [key, group] of groups) {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a group is created with its first member
+        const head = group[0];
+        if (key === head.key) {
+            nodes.push(reuse(previous, {
+                key,
+                depth,
+                state: head.state,
+                hidden: head.hidden,
+                wrapped: pages.has(head.leaf),
+            }));
+            continue;
+        }
+        let shown = head;
+        for (const member of group) {
+            if (!member.hidden) {
+                shown = member;
+                break;
+            }
+            if (member.recency > shown.recency)
+                shown = member;
+        }
+        nodes.push(reuse(previous, {
+            key,
+            depth,
+            state: shown.state,
+            hidden: shown.hidden,
+            wrapped: layouts.has(key),
+            children: levelOf(group, depth + 1, pages, layouts, previous),
+        }));
+    }
+    return nodes;
+};
+// The previous tree's node when nothing about it changed, so a renderer that memoizes on the node
+// skips it: a hidden page never re-renders while it is hidden.
+const reuse = (previous, node) => {
+    const old = previous.get(node.key);
+    if (old === undefined ||
+        old.depth !== node.depth ||
+        old.state !== node.state ||
+        old.hidden !== node.hidden ||
+        old.wrapped !== node.wrapped)
+        return node;
+    const a = old.children;
+    const b = node.children;
+    if (a === b)
+        return old;
+    if (a === undefined || b === undefined || a.length !== b.length)
+        return node;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return node;
+    return old;
+};
+const indexTree = (nodes, into) => {
+    for (const node of nodes) {
+        into.set(node.key, node);
+        if (node.children !== undefined)
+            indexTree(node.children, into);
+    }
+};
+/**
+ * The view of `state`: the page on screen and every kept page, grouped by the layouts they share. A
+ * layout every page under it shares renders once; where two chains part, each part is a slot. Pass
+ * the previous tree to keep the identity of every node that did not change.
+ */
+export function slotTree(state, chains, table, previous) {
+    const before = new Map();
+    if (previous !== undefined)
+        indexTree(previous, before);
+    return levelOf(membersOf(state, chains), 0, new Set(table.routes), new Set(table.layouts), before);
+}
+// The kept pages a render of `state` could not hide: their chain leaves the page on screen at a
+// layout rendered without slot wrappers.
+const unplaceable = (state, chains, pages, layouts) => {
+    if (state.kept === undefined)
+        return [];
+    const stuck = [];
+    const visit = (nodes, parentHidden) => {
+        for (const node of nodes) {
+            if (node.hidden && !parentHidden && !node.wrapped)
+                collect(node, stuck);
+            else if (node.children !== undefined)
+                visit(node.children, node.hidden);
+        }
+    };
+    visit(levelOf(membersOf(state, chains), 0, pages, layouts, new Map()), false);
+    return stuck;
+};
+const collect = (node, into) => {
+    if (node.children === undefined) {
+        if (node.key !== LOADING)
+            into.push(node.key.slice(1));
+        return;
+    }
+    for (const child of node.children)
+        collect(child, into);
+};
+const scrollOffsets = (page) => {
+    const offsets = [];
+    if (page.scrollTop !== 0 || page.scrollLeft !== 0)
+        offsets.push([page, page.scrollTop, page.scrollLeft]);
+    for (const element of page.querySelectorAll("*")) {
+        if (element.scrollTop !== 0 || element.scrollLeft !== 0)
+            offsets.push([element, element.scrollTop, element.scrollLeft]);
+    }
+    return offsets;
+};
+/**
+ * Note the inner scroll offsets of a page's top-level `elements` and the element inside them that has
+ * focus, while they are still laid out. For an adapter whose framework takes a hidden page out of the
+ * document itself (Vue's `KeepAlive`), in place of {@link createSlotParking}.
+ */
+export function rememberView(elements) {
+    const offsets = elements.flatMap(scrollOffsets);
+    const focused = typeof document === "undefined" ? null : document.activeElement;
+    const focus = focused !== null && elements.some((element) => element.contains(focused)) ? focused : undefined;
+    return {
+        restore() {
+            for (const [element, top, left] of offsets) {
+                if (!element.isConnected)
+                    continue;
+                element.scrollTop = top;
+                element.scrollLeft = left;
+            }
+            if (focus?.isConnected)
+                // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: it held focus, so it is focusable; the call stays optional
+                focus.focus?.({ preventScroll: true });
+        },
+    };
+}
+const wrappedNodes = (nodes, into = []) => {
+    for (const node of nodes) {
+        if (node.wrapped)
+            into.push(node);
+        if (node.children !== undefined)
+            wrappedNodes(node.children, into);
+    }
+    return into;
+};
+// Development only: what each slot renders, by slot key, for the devtools panel's node counts.
+const keptViews = new Map();
+/**
+ * For an adapter, in development: the elements slot `key` renders, read when the devtools panel
+ * counts a kept page's nodes. `undefined` once the slot has left the view.
+ */
+export function noteKeptView(key, elements) {
+    if (elements === undefined)
+        keptViews.delete(key);
+    else
+        keptViews.set(key, elements);
+}
+/** Where a development build lists its kept pages, for `@nifrajs/devtools`. */
+export const KEPT_PAGES_GLOBAL = "__nifraKeepAlive";
+const describeKept = (records) => {
+    const at = now();
+    return [...records].map(({ page, hiddenAt }) => {
+        const elements = keptViews.get(`\0${page.instance}`)?.();
+        return {
+            instance: page.instance,
+            path: page.state.path,
+            routeId: page.state.routeId,
+            hiddenFor: at - hiddenAt,
+            nodes: elements?.reduce((count, element) => count + 1 + element.querySelectorAll("*").length, 0),
+        };
+    });
+};
+/** One per mounted view. */
+export function createSlotParking() {
+    const slots = new Map();
+    const entryRefs = new Map();
+    const pageRefs = new Map();
+    const slotOf = (key) => {
+        let slot = slots.get(key);
+        if (slot === undefined) {
+            slot = {
+                parked: false,
+                shown: false,
+                showing: false,
+                hid: false,
+                next: null,
+                offsets: undefined,
+                focus: undefined,
+                checked: false,
+            };
+            slots.set(key, slot);
+        }
+        return slot;
+    };
+    const remember = (slot) => {
+        if (slot.page === undefined || slot.offsets !== undefined)
+            return;
+        slot.offsets = scrollOffsets(slot.page);
+        const focused = typeof document === "undefined" ? null : document.activeElement;
+        slot.focus =
+            focused !== null && focused !== slot.page && slot.page.contains(focused) ? focused : undefined;
+    };
+    // Sent while the page is still in the document, before the router's subscribers see the state that
+    // hides it, so what holds the page's content (server components) sets it aside first.
+    const fire = (slot, hide) => {
+        slot.hid = hide;
+        slot.page?.dispatchEvent(new CustomEvent(hide ? PAGE_HIDE_EVENT : PAGE_SHOW_EVENT, { bubbles: true }));
+    };
+    const unpark = (slot) => {
+        if (!slot.parked || slot.page === undefined || slot.entry === undefined)
+            return;
+        slot.entry.insertBefore(slot.page, slot.next?.parentNode === slot.entry ? slot.next : null);
+        slot.parked = false;
+        slot.showing = true;
+    };
+    return {
+        entry(key) {
+            let ref = entryRefs.get(key);
+            if (ref === undefined) {
+                ref = (element) => {
+                    slotOf(key).entry = element ?? undefined;
+                };
+                entryRefs.set(key, ref);
+            }
+            return ref;
+        },
+        page(key) {
+            let ref = pageRefs.get(key);
+            if (ref === undefined) {
+                // A null never clears the page: React detaches refs inside a hidden `Activity`, and a parked
+                // page is still the framework's element. The slot leaving the tree (`after`) drops it.
+                ref = (element) => {
+                    if (element === null)
+                        return;
+                    slotOf(key).page = element;
+                    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
+                        noteKeptView(key, () => [element]);
+                };
+                pageRefs.set(key, ref);
+            }
+            return ref;
+        },
+        before(next) {
+            for (const node of wrappedNodes(next)) {
+                const slot = slots.get(node.key);
+                if (slot === undefined)
+                    continue;
+                if (node.hidden) {
+                    if (!slot.shown)
+                        continue;
+                    remember(slot);
+                    if (!slot.hid && slot.page !== undefined)
+                        fire(slot, true);
+                }
+                else {
+                    // Shown again before it was parked: it never left the document.
+                    if (slot.hid && !slot.parked)
+                        fire(slot, false);
+                    unpark(slot);
+                }
+            }
+        },
+        after(tree) {
+            const live = new Set();
+            for (const node of wrappedNodes(tree)) {
+                live.add(node.key);
+                const slot = slots.get(node.key);
+                const page = slot?.page;
+                if (slot === undefined || page === undefined || slot.entry === undefined)
+                    continue;
+                if (node.hidden) {
+                    if (!slot.parked) {
+                        if (slot.shown)
+                            remember(slot);
+                        if (!slot.hid)
+                            fire(slot, true);
+                        slot.next = page.nextSibling;
+                        page.remove();
+                        slot.parked = true;
+                    }
+                    slot.shown = false;
+                    continue;
+                }
+                unpark(slot);
+                if (slot.showing) {
+                    slot.showing = false;
+                    for (const [element, top, left] of slot.offsets ?? []) {
+                        if (!page.contains(element))
+                            continue;
+                        element.scrollTop = top;
+                        element.scrollLeft = left;
+                    }
+                    const focus = slot.focus;
+                    if (focus?.isConnected && page.contains(focus))
+                        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: it held focus, so it is focusable; the call stays optional
+                        focus.focus?.({ preventScroll: true });
+                    fire(slot, false);
+                }
+                slot.offsets = undefined;
+                slot.focus = undefined;
+                if (!slot.shown && !slot.checked) {
+                    slot.checked = true;
+                    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
+                        checkSlotCss(slot.entry, page);
+                }
+                slot.shown = true;
+            }
+            for (const key of [...slots.keys()]) {
+                if (live.has(key))
+                    continue;
+                const page = slots.get(key)?.page;
+                if (page !== undefined)
+                    releasePage(page);
+                slots.delete(key);
+                entryRefs.delete(key);
+                pageRefs.delete(key);
+                if (typeof process !== "undefined" && process.env.NODE_ENV !== "production")
+                    noteKeptView(key, undefined);
+            }
+        },
+    };
+}
+// The selectors already reported, once per document.
+const reportedCss = new Set();
+// Pseudo-classes that read an element's position among its siblings, which the wrappers change.
+const POSITIONAL = /:(?:first-child|last-child|only-child|nth-child\([^)]*\)|nth-last-child\([^)]*\))/g;
+const DIRECT_HAS = /:has\(\s*>\s*([^)]*)\)/;
+/** `selector`'s compounds and the combinators between them, split outside parentheses and brackets. */
+const compoundsOf = (selector) => {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    let combinator = "";
+    const flush = (end) => {
+        const compound = selector.slice(start, end).trim();
+        if (compound !== "") {
+            parts.push({ compound, before: combinator });
+            combinator = "";
+        }
+    };
+    for (let i = 0; i < selector.length; i++) {
+        const char = selector[i];
+        if (char === "(" || char === "[")
+            depth++;
+        else if (char === ")" || char === "]")
+            depth--;
+        if (depth > 0 || (char !== " " && char !== ">" && char !== "+" && char !== "~"))
+            continue;
+        flush(i);
+        if (char !== " ")
+            combinator = char;
+        else if (combinator === "")
+            combinator = " ";
+        start = i + 1;
+    }
+    if (depth <= 0)
+        flush(selector.length);
+    return parts;
+};
+const matches = (element, selector) => {
+    try {
+        return element.matches(selector);
+    }
+    catch {
+        return false;
+    }
+};
+// Whether `selector` targets a top-level node of the page as a child of the element the slot sits in,
+// which the two wrappers between them now break.
+const breaksAround = (selector, parent, tops) => {
+    const parts = compoundsOf(selector);
+    for (const [i, { compound, before }] of parts.entries()) {
+        const prefix = parts
+            .slice(0, i)
+            .map((part, j) => (j === 0 ? part.compound : `${part.before} ${part.compound}`))
+            .join(" ");
+        if (before === ">" && matches(parent, prefix) && tops.some((top) => matches(top, compound)))
+            return true;
+        if (POSITIONAL.test(compound)) {
+            POSITIONAL.lastIndex = 0;
+            const rest = compound.replace(POSITIONAL, "") || "*";
+            if (tops.some((top) => matches(top, rest)) &&
+                (prefix === "" || matches(parent, prefix) || parent.closest(prefix) !== null))
+                return true;
+        }
+        POSITIONAL.lastIndex = 0;
+        const has = DIRECT_HAS.exec(compound);
+        if (has !== null) {
+            const owner = compound.replace(DIRECT_HAS, "") || "*";
+            if (matches(parent, owner) && tops.some((top) => matches(top, has[1] ?? "")))
+                return true;
+        }
+    }
+    return false;
+};
+const scanRules = (rules, parent, tops, source) => {
+    for (const rule of rules) {
+        if (rule instanceof CSSStyleRule) {
+            for (const selector of splitSelectors(rule.selectorText)) {
+                if (reportedCss.has(selector) || !breaksAround(selector, parent, tops))
+                    continue;
+                reportedCss.add(selector);
+                console.warn(`[nifra/web] NIFRA_KEEPALIVE_DIRECT_CHILD_CSS: the selector "${selector}"${source} reaches a kept page's top-level element as a direct child of <${parent.tagName.toLowerCase()}>, but a keepAlive page renders inside two display:contents wrappers, so it no longer matches. Use a descendant combinator, target the wrapper ([data-nifra-page] > ...), or put a class on the page's root element.`);
+            }
+        }
+        else if ("cssRules" in rule) {
+            // @media, @supports, @layer and @container rules hold style rules of their own.
+            // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a rule with cssRules is a grouping rule
+            scanRules(rule.cssRules, parent, tops, source);
+        }
+    }
+};
+const splitSelectors = (list) => {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < list.length; i++) {
+        const char = list[i];
+        if (char === "(" || char === "[")
+            depth++;
+        else if (char === ")" || char === "]")
+            depth--;
+        else if (char === "," && depth === 0) {
+            out.push(list.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    out.push(list.slice(start).trim());
+    return out.filter((selector) => selector !== "");
+};
+/**
+ * Dev only: report each same-origin style rule whose selector the slot wrappers around `page` stop
+ * matching (`NIFRA_KEEPALIVE_DIRECT_CHILD_CSS`). A stylesheet the page cannot read is skipped.
+ */
+export function checkSlotCss(entry, page) {
+    const parent = entry.parentElement;
+    const tops = [...page.children];
+    if (parent === null || tops.length === 0 || typeof document === "undefined")
+        return;
+    for (const sheet of document.styleSheets) {
+        let rules;
+        try {
+            rules = sheet.cssRules;
+        }
+        catch {
+            continue;
+        }
+        scanRules(rules, parent, tops, sheet.href === null ? "" : ` (${sheet.href})`);
+    }
+}
+//# sourceMappingURL=keep-alive.js.map