@ogygia/core 0.12.2 → 0.13.0

package/dist/runtime/rules.js

@@ -0,0 +1,137 @@
+import { Rules } from "../rules.js";
+import { warn } from "../messages/core.js";
+import { STALE, observe } from "@ogygia/machine";
+// src/runtime/rules.ts
+/**
+* THE RUNTIME'S RULES (#313, ../rules.ts): what is always true of a page, checked in dev a task
+* after machine moves (a navigation is the navigation machine's) and by e2e at the end of a test.
+*
+* - `rule_region_mounted_twice`: one mount per region. A region element holds one island at a time,
+*   and an island whose element left the page is let go with it.
+* - `rule_address_bar_drift`: the address bar and the router's history model (whose current entry
+*   is the page on screen's) agree once no navigation is out.
+* - `rule_old_page_open`: nothing of a page that was left is still open (its visit's scope closed:
+*   its listeners, timers, streams).
+* - `rule_failure_uncoded`: no failure leaves ogygia without a code: an uncaught ogygia error names
+*   its code's page, and a `STALE` never escapes as a rejection.
+* - `rule_parse_upgraded`: a parsed answer is inert (./parse-html.ts, #382): no element of it was
+*   built by a component's constructor before the restore reached it.
+*
+* Each area tells this module what it holds (`note_mount`, `note_visit`, `watch_router`) only when
+* rules are on (`RULES`): every call site folds out of a build without them.
+*/
+/** The runtime's rules. */
+const runtime_rules = /* @__PURE__ */ new Rules();
+/** The region elements that hold an island now, and how many. */
+const mounts = /* @__PURE__ */ new Map();
+/** A region element mounted its island. */
+function note_mount(region) {
+	mounts.set(region, (mounts.get(region) ?? 0) + 1);
+}
+/** A region element let its island go. */
+function note_unmount(region) {
+	const n = (mounts.get(region) ?? 0) - 1;
+	if (n > 0) mounts.set(region, n);
+	else mounts.delete(region);
+}
+const entry_of = (region) => region.getAttribute("entry") ?? region.tagName;
+function one_mount_per_region() {
+	for (const [region, n] of mounts) {
+		if (n > 1) return `${entry_of(region)} holds ${n} islands at once`;
+		if (!region.isConnected) return `${entry_of(region)} left the page with its island still mounted`;
+	}
+	return null;
+}
+/** Each visit made, in the order made: one older than the page on screen's is over. */
+const visits = [];
+let visit_n = 0;
+let current = null;
+/** A page visit was made (`current`: it is the page on screen's now). */
+function note_visit(visit, is_current) {
+	if (!visits.some((v) => v.visit === visit)) visits.push({
+		visit,
+		n: ++visit_n
+	});
+	if (is_current) current = visit;
+}
+function no_old_page_open() {
+	const now = visits.find((v) => v.visit === current);
+	if (now === void 0) return null;
+	for (let i = visits.length - 1; i >= 0; i--) if (visits[i].visit.scope.closed) visits.splice(i, 1);
+	const open = visits.filter((v) => v.n < now.n).length;
+	return open === 0 ? null : `${open} page visit(s) before the one on screen still open`;
+}
+const no_hash = (href) => href.split("#")[0];
+/** The router started: its history model is checked against the address bar. */
+function watch_router(router) {
+	runtime_rules.add("rule_address_bar_drift", () => {
+		if (router.nav.now.kind !== "idle") return null;
+		const id = history.state?.ogygia;
+		if (typeof id !== "string") return null;
+		const page = router.history.current;
+		if (id !== page.id) return `the address bar is on entry ${id}, the history model on ${page.id}`;
+		const bar = no_hash(location.href);
+		const model = no_hash(page.url.href);
+		return bar === model ? null : `the address bar is ${bar}, the history model's page ${model}`;
+	});
+}
+const CODE_LINK_RE = /ogygiajs\.dev\/e\/[a-z_]+/;
+/** The failures that left ogygia without a code, as found (a few). */
+const uncoded = [];
+function failure(reason) {
+	if (uncoded.length >= 10) return;
+	if (reason === STALE) {
+		uncoded.push("a STALE escaped as a rejection");
+		return;
+	}
+	const message = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "";
+	if (message.startsWith("[ogygia]") && !CODE_LINK_RE.test(message)) uncoded.push("an ogygia error with no code: " + message.split("\n")[0].slice(0, 160));
+}
+const no_failure_uncoded = () => uncoded.length === 0 ? null : uncoded.join("; ");
+/** What parses built that they should not have, as found (a few). */
+const parsed_built = [];
+/** The rule's ear on every parse (./parse-html.ts calls it): an element of the parsed fragment that
+*  a component's constructor built (a defined name, an instance of its definition). */
+function note_parse(fragment) {
+	if (parsed_built.length >= 10 || typeof customElements === "undefined") return;
+	const roots = [fragment];
+	for (let q = 0; q < roots.length; q++) {
+		const walk = document.createTreeWalker(roots[q], 1);
+		for (let n = walk.nextNode(); n; n = walk.nextNode()) {
+			if (n.shadowRoot) roots.push(n.shadowRoot);
+			const ctor = customElements.get(n.localName);
+			if (ctor !== void 0 && n instanceof ctor) {
+				parsed_built.push(`<${n.localName}> was built while its answer parsed`);
+				return;
+			}
+		}
+	}
+}
+const no_parse_upgraded = () => parsed_built.length === 0 ? null : parsed_built.join("; ");
+let installed = false;
+let pending = false;
+/** Checks every rule a task from now (once, however many moves ask), and says what broke. */
+function check_soon() {
+	if (pending) return;
+	pending = true;
+	setTimeout(() => {
+		pending = false;
+		runtime_rules.say((code, detail) => warn(code, { detail }));
+	}, 0);
+}
+/** Rules on: `globalThis.__ogygia_rules()` gives what is broken now (for e2e); in dev they are also
+*  checked after machine moves, and what broke is said with its code. */
+function install_rules(dev) {
+	if (installed || typeof window === "undefined") return;
+	installed = true;
+	runtime_rules.add("rule_region_mounted_twice", one_mount_per_region);
+	runtime_rules.add("rule_old_page_open", no_old_page_open);
+	runtime_rules.add("rule_failure_uncoded", no_failure_uncoded);
+	runtime_rules.add("rule_parse_upgraded", no_parse_upgraded);
+	globalThis.__og_parsed = note_parse;
+	globalThis.__ogygia_rules = () => runtime_rules.broken();
+	window.addEventListener("unhandledrejection", (event) => failure(event.reason));
+	window.addEventListener("error", (event) => failure(event.error ?? event.message));
+	if (dev) observe(check_soon);
+}
+export { install_rules, note_mount, note_unmount, note_visit, runtime_rules, watch_router };

package/dist/runtime/schedule.d.ts

@@ -1,3 +1,4 @@
+import { Scope, Stale } from "@ogygia/machine";
 export declare function yield_task(): Promise<void>;
 /**
  * Run `fn` at background priority, off the current task: `scheduler.postTask` at 'background' where
@@ -21,14 +22,16 @@ export declare function background_start(fn: () => void): void;
  * so it waits one task instead. Once resolved it stays resolved: a late region (SPA swap, a hole's
  * answer) passes straight through.
  */
-export declare function after_document_painted(): Promise<void>;
+export declare function after_document_painted(): Promise<void | Stale>;
 /** Test seam: forget the resolved gate (a test that fakes a fresh document). */
 export declare function reset_document_painted(): void;
 /**
  * Register a region with the scheduler at connect: stamp its order, start its viewport snapshot.
- * Cheap on purpose (a stamp and an `observe`) — connect runs for every region in one task.
+ * Cheap on purpose (a stamp and an `observe`) — connect runs for every region in one task. The
+ * snapshot is `owner`'s (the region's lifetime in the page): it stops at the region's turn, or when
+ * the owner ends.
  */
-export declare function register_region(el: Element): void;
+export declare function register_region(el: Element, owner: Scope): void;
 /**
  * Drop a region from the scheduler (disconnect): its snapshot stops and any pending turn is handed
  * out at once — the waiting hydrate step then sees `isConnected === false` and stands down (or, if

package/dist/runtime/schedule.js

@@ -1,4 +1,5 @@
-import { observe } from "./observe.js";
+import { observe as observe$1 } from "./observe.js";
+import { flights, machine } from "@ogygia/machine";
 // src/runtime/schedule.ts
 /**
 * THE HYDRATION SCHEDULER — one island per task, viewport first.
@@ -28,17 +29,100 @@ import { observe } from "./observe.js";
 const SNAPSHOT_WAIT_MS = 48;
 /** How long a ready below-the-fold island holds for a viewport island still loading its module. */
 const HOLD_FOR_VIEWPORT_MS = 1e3;
-const pending = [];
-let draining = false;
+let pending_count = 0;
+let next_seq = 0;
+const heap_vis = [];
+const heap_rest = [];
+const turns_of = /* @__PURE__ */ new Map();
+const unsnapped = [];
+let unsnapped_head = 0;
+/**
+* The drain, as a machine:
+*
+*   idle ─ queued ─ idle            a drain waits for its task (`yield_task`), then runs
+*       ╲ waiting{at} ╱             a drain waits for a time: the snapshot, or a viewport island
+*
+* `waiting` owns its timer (its visit's scope), so leaving it drops the timer: a drain queued
+* meanwhile runs sooner and works out the waits again, and a sooner wait replaces a later one
+* (#236). One state in place of the `draining` flag beside a `wait_timer` and its `wait_at`.
+*/
+const drainer = machine()({
+	name: "hydrate-drain",
+	initial: "idle",
+	steps: {
+		idle: ["queued", "waiting"],
+		queued: ["idle"],
+		waiting: ["queued", "waiting"]
+	}
+}).create();
 /** Connect-order stamp per region — document order at upgrade, insertion order after a morph. */
 const order_of = /* @__PURE__ */ new WeakMap();
 let next_order = 0;
 /** The snapshot: intersecting now? Absent = the observer has not reported yet. */
 const in_viewport = /* @__PURE__ */ new WeakMap();
-const unobserve_of = /* @__PURE__ */ new WeakMap();
+/** Each region's viewport snapshot while it runs (closing it stops the snapshot). */
+const snapshot_of = /* @__PURE__ */ new WeakMap();
 /** Regions whose hydrate has STARTED (module in flight) and not yet taken its turn. */
 const loading = /* @__PURE__ */ new Set();
-let wait_timer = null;
+/** The loading regions the snapshot says intersect the viewport (what a hold waits for). */
+const loading_vis = /* @__PURE__ */ new Set();
+/** Keep `loading_vis` in step after `el`'s loading state or snapshot changed. */
+function sync_loading(el) {
+	if (loading.has(el) && in_viewport.get(el) === true) loading_vis.add(el);
+	else loading_vis.delete(el);
+}
+function stop_loading(el) {
+	loading_vis.delete(el);
+	return loading.delete(el);
+}
+/** Connect order, then request order: the pick order within one heap. */
+const before = (a, b) => a.order < b.order || a.order === b.order && a.seq < b.seq;
+function heap_push(h, t) {
+	let i = h.push(t) - 1;
+	while (i > 0) {
+		const p = i - 1 >> 1;
+		if (!before(h[i], h[p])) break;
+		[h[i], h[p]] = [h[p], h[i]];
+		i = p;
+	}
+}
+function heap_pop(h) {
+	const last = h.pop();
+	if (!h.length) return;
+	h[0] = last;
+	for (let i = 0;;) {
+		const l = 2 * i + 1;
+		const r = l + 1;
+		let m = i;
+		if (l < h.length && before(h[l], h[m])) m = l;
+		if (r < h.length && before(h[r], h[m])) m = r;
+		if (m === i) return;
+		[h[i], h[m]] = [h[m], h[i]];
+		i = m;
+	}
+}
+/** The heap's first live turn (stale entries on top are dropped on the way). */
+function heap_top(h, vis) {
+	while (h.length && (h[0].done || h[0].vis !== vis)) heap_pop(h);
+	return h[0];
+}
+/** File each pending turn of `el` in the heap its snapshot now says. */
+function refile(el) {
+	const vis = in_viewport.get(el) === true;
+	for (const t of turns_of.get(el) ?? []) {
+		if (t.vis === vis) continue;
+		t.vis = vis;
+		heap_push(vis ? heap_vis : heap_rest, t);
+	}
+}
+/** The turn leaves the queue (taken, or its region went away). */
+function retire(t) {
+	t.done = true;
+	pending_count--;
+	const list = turns_of.get(t.el);
+	list.splice(list.indexOf(t), 1);
+	if (!list.length) turns_of.delete(t.el);
+}
 /**
 * Yield to the event loop: resolves in a NEW task, so whatever ran before is a finished task and
 * the browser may render and handle input in between. `scheduler.yield()` where it exists (it
@@ -99,7 +183,11 @@ function post_background(fn) {
 	} catch {}
 	setTimeout(fn, 0);
 }
-let document_painted = null;
+/** The gate below, once for the document (a test's reset drops it). */
+const document_painted = flights({
+	name: "document painted",
+	run: () => until_painted()
+});
 /**
 * Resolves once the document is parsed AND painted: after `DOMContentLoaded`, then one rendered
 * frame. This is the moment SvelteKit starts hydrating (its start runs from a deferred module
@@ -115,7 +203,10 @@ let document_painted = null;
 * answer) passes straight through.
 */
 function after_document_painted() {
-	return document_painted ??= new Promise((resolve) => {
+	return document_painted.get();
+}
+function until_painted() {
+	return new Promise((resolve) => {
 		if (typeof document === "undefined") return resolve();
 		const painted = () => {
 			if (document.visibilityState === "hidden" || typeof requestAnimationFrame !== "function") setTimeout(resolve, 0);
@@ -142,19 +233,27 @@ function dom_content_loaded() {
 }
 /** Test seam: forget the resolved gate (a test that fakes a fresh document). */
 function reset_document_painted() {
-	document_painted = null;
+	document_painted.drop(() => true);
 }
 /**
 * Register a region with the scheduler at connect: stamp its order, start its viewport snapshot.
-* Cheap on purpose (a stamp and an `observe`) — connect runs for every region in one task.
+* Cheap on purpose (a stamp and an `observe`) — connect runs for every region in one task. The
+* snapshot is `owner`'s (the region's lifetime in the page): it stops at the region's turn, or when
+* the owner ends.
 */
-function register_region(el) {
+function register_region(el, owner) {
 	if (!order_of.has(el)) order_of.set(el, next_order++);
-	if (unobserve_of.has(el)) return;
-	unobserve_of.set(el, observe(el, "0px", (intersecting) => {
+	if (snapshot_of.has(el) || owner.closed) return;
+	const stop = observe$1(el, "0px", (intersecting) => {
 		in_viewport.set(el, intersecting);
-		if (pending.length) schedule_drain();
-	}));
+		sync_loading(el);
+		refile(el);
+		if (pending_count) schedule_drain();
+	});
+	snapshot_of.set(el, stop);
+	owner.defer(() => {
+		if (snapshot_of.get(el) === stop) stop_snapshot(el);
+	});
 }
 /**
 * Drop a region from the scheduler (disconnect): its snapshot stops and any pending turn is handed
@@ -164,26 +263,29 @@ function register_region(el) {
 function unregister_region(el) {
 	stop_snapshot(el);
 	in_viewport.delete(el);
-	loading.delete(el);
-	for (let i = pending.length - 1; i >= 0; i--) {
-		if (pending[i].el !== el) continue;
-		const [turn] = pending.splice(i, 1);
+	stop_loading(el);
+	const list = turns_of.get(el);
+	if (list) for (const turn of list.slice().reverse()) {
+		retire(turn);
 		turn.resolve();
 	}
-	if (pending.length) schedule_drain();
+	if (pending_count) schedule_drain();
 }
 function stop_snapshot(el) {
-	unobserve_of.get(el)?.();
-	unobserve_of.delete(el);
+	const stop = snapshot_of.get(el);
+	if (stop === void 0) return;
+	snapshot_of.delete(el);
+	stop();
 }
 /** The island's module is in flight: a viewport island here holds ready islands below the fold. */
 function hydrate_started(el) {
 	loading.add(el);
+	sync_loading(el);
 }
 /** The hydrate attempt is over (turn taken, or it never got there — no entry, a failed import). */
 function hydrate_settled(el) {
-	if (!loading.delete(el)) return;
-	if (pending.length) schedule_drain();
+	if (!stop_loading(el)) return;
+	if (pending_count) schedule_drain();
 }
 /**
 * Wait for this region's turn. Resolves in a task of its own, after every region ahead of it in
@@ -192,12 +294,21 @@ function hydrate_settled(el) {
 */
 function hydrate_turn(el) {
 	return new Promise((resolve) => {
-		pending.push({
+		const turn = {
 			el,
 			order: order_of.get(el) ?? (order_of.set(el, next_order), next_order++),
+			seq: next_seq++,
 			queued_at: now(),
-			resolve
-		});
+			resolve,
+			vis: in_viewport.get(el) === true,
+			done: false
+		};
+		pending_count++;
+		heap_push(turn.vis ? heap_vis : heap_rest, turn);
+		const list = turns_of.get(el);
+		if (list) list.push(turn);
+		else turns_of.set(el, [turn]);
+		if (!in_viewport.has(el)) unsnapped.push(turn);
 		schedule_drain();
 	});
 }
@@ -205,52 +316,56 @@ function now() {
 	return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
 }
 function schedule_drain() {
-	if (draining) return;
-	draining = true;
+	if (drainer.now.kind === "queued") return;
+	drainer.go("queued");
 	yield_task().then(drain);
 }
-/** Re-drain after `ms` (one timer at a time — the earliest wait wins, later ones ride it). */
+/** Re-drain after `ms`. One wait at a time, and it is the EARLIEST: a sooner wait replaces a later
+*  one (a short snapshot wait set during a long hold), a later one rides the sooner. */
 function drain_after(ms) {
-	if (wait_timer) return;
-	wait_timer = setTimeout(() => {
-		wait_timer = null;
-		schedule_drain();
-	}, Math.max(1, ms));
+	const at = now() + Math.max(1, ms);
+	const s = drainer.now;
+	if (s.kind === "waiting" && s.at <= at) return;
+	drainer.go("waiting", { at });
+	drainer.scope.timeout(schedule_drain, Math.max(1, ms));
+}
+/**
+* The earliest-requested pending turn still waiting for its snapshot within its wait, or none.
+* Turns are requested in time order, so the ones ahead of it that reported, went, or ran out of
+* wait are behind for good (the clock only moves on) and leave the queue.
+*/
+function first_unsnapped(t) {
+	while (unsnapped_head < unsnapped.length) {
+		const p = unsnapped[unsnapped_head];
+		if (!p.done && !in_viewport.has(p.el) && SNAPSHOT_WAIT_MS - (t - p.queued_at) > 0) return p;
+		unsnapped_head++;
+	}
+	unsnapped.length = unsnapped_head = 0;
 }
 /** One turn per call: pick the best pending region, hand it its task; the next pick after a yield. */
 function drain() {
-	draining = false;
-	if (!pending.length) return;
+	drainer.go("idle");
+	if (!pending_count) return;
 	const t = now();
 	const hidden = typeof document !== "undefined" && document.visibilityState === "hidden";
-	if (!hidden) for (const p of pending) {
-		if (in_viewport.has(p.el)) continue;
-		const left = SNAPSHOT_WAIT_MS - (t - p.queued_at);
-		if (left > 0) return drain_after(left);
+	if (!hidden) {
+		const p = first_unsnapped(t);
+		if (p) return drain_after(SNAPSHOT_WAIT_MS - (t - p.queued_at));
 	}
-	let best = 0;
-	for (let i = 1; i < pending.length; i++) {
-		const a = pending[best];
-		const b = pending[i];
-		const va = in_viewport.get(a.el) === true;
-		const vb = in_viewport.get(b.el) === true;
-		if (vb !== va ? vb : b.order < a.order) best = i;
-	}
-	const turn = pending[best];
-	if (!hidden && in_viewport.get(turn.el) !== true) {
+	const turn = heap_top(heap_vis, true) ?? heap_top(heap_rest, false);
+	if (!hidden && !turn.vis && loading_vis.size) {
 		const left = HOLD_FOR_VIEWPORT_MS - (t - turn.queued_at);
-		if (left > 0) {
-			for (const el of loading) if (in_viewport.get(el) === true) return drain_after(left);
-		}
+		if (left > 0) return drain_after(left);
 	}
-	pending.splice(best, 1);
-	loading.delete(turn.el);
+	heap_pop(turn.vis ? heap_vis : heap_rest);
+	retire(turn);
+	stop_loading(turn.el);
 	stop_snapshot(turn.el);
 	turn.resolve();
-	if (pending.length) schedule_drain();
+	if (pending_count) schedule_drain();
 }
 /** Test seam: is a hydration turn queued or being drained right now? */
 function schedule_idle() {
-	return pending.length === 0 && !draining;
+	return pending_count === 0 && drainer.now.kind !== "queued";
 }
 export { after_document_painted, background_start, hydrate_settled, hydrate_started, hydrate_turn, register_region, reset_document_painted, schedule_idle, unregister_region, yield_task };

package/dist/runtime/seeds.d.ts

@@ -1,3 +1,4 @@
+import { PageVisit } from "./session.js";
 import { parse_sidecar_text } from "./wire-format.js";
 import { PageSnapshot } from "../shims/page-store.svelte.js";
 export declare const PAGE_SEED_SELECTOR = "script[type=\"application/ogygia-page\"]";
@@ -44,8 +45,11 @@ export declare function apply_soft_invalidate_doc(doc: Document): void;
  * Do **not** clear `query_map` / `live_query_map` here — old islands are still mounted, and Kit's
  * LiveQueryProxy throws if its cache entry vanishes mid-render. Instance sweep happens in
  * {@link finish_spa_document} after the swap.
+ *
+ * `next`: the visit of the page going in, made by its navigation (runtime/session.ts `PageVisit`):
+ * from here on it is the page's, and the visit of the page going out ends.
  */
-export declare function prepare_spa_document(): void;
+export declare function prepare_spa_document(next?: PageVisit): void;
 /**
  * After the body swap: old islands have disconnected; new ones have only queued their hydrate.
  * Sweep Kit query/live instance maps so the next page cannot reuse a LiveQuery whose `#start` is

package/dist/runtime/seeds.js

@@ -5,6 +5,7 @@ import { install_page_defer, page_defer_revivers } from "./page-defer.js";
 import { transport_decoders } from "./app-transport.js";
 import { kit_page_thread } from "./kit-page-thread.svelte.js";
 import { boot_link, slots } from "./slots.js";
+import { warn } from "../messages/lazy.js";
 // src/runtime/seeds.ts
 /**
 * THE PAGE SEED on the client — parsed ONCE per document, kept in ONE place.
@@ -125,7 +126,7 @@ function seed_page_once() {
 		const el = document.querySelector(PAGE_SEED_SELECTOR);
 		if (el) apply_page_seed(parse_page_seed(el));
 	}
-	if (session().page_facts.length) absorb_page_facts();
+	if (session().visit.facts.length) absorb_page_facts();
 }
 /**
 * ONE PAGE, NOT TWO (server/render-page.ts): an answer rendered outside its page — a hole, a region a
@@ -134,9 +135,11 @@ function seed_page_once() {
 * values their HTML was rendered from, and every island reading the same keys sees them too (the
 * page's data changed: a locale saved, a sign-in). On a Kit-hydrated page Kit owns `page.data`: the
 * page's data is older than the answer's, and dev says to refresh it (`invalidateAll()`) first.
+* Only the page's own: the facts queued on its visit (runtime/session.ts `PageVisit`), never the
+* ones a page left before them brought (#269).
 */
 function absorb_page_facts() {
-	const queued = session().page_facts.splice(0);
+	const queued = session().visit.facts.splice(0);
 	let merged = null;
 	for (const text of queued) {
 		let facts;
@@ -154,7 +157,7 @@ function absorb_page_facts() {
 		if (import.meta.env.DEV) {
 			const data = kit.page.data ?? {};
 			const older = Object.keys(merged).filter((k) => data[k] !== merged[k] && JSON.stringify(data[k]) !== JSON.stringify(merged[k]));
-			if (older.length) console.warn(`[ogygia] a region came back rendered with newer page.data (${older.join(", ")}) than this Kit page holds. Refresh the page's data (invalidateAll()) before refreshing the region, or the islands inside it hydrate against the older values.`);
+			if (older.length) warn("region_newer_page_data", { keys: older.join(", ") });
 		}
 		return;
 	}
@@ -195,9 +198,12 @@ function apply_soft_invalidate_doc(doc) {
 * Do **not** clear `query_map` / `live_query_map` here — old islands are still mounted, and Kit's
 * LiveQueryProxy throws if its cache entry vanishes mid-render. Instance sweep happens in
 * {@link finish_spa_document} after the swap.
+*
+* `next`: the visit of the page going in, made by its navigation (runtime/session.ts `PageVisit`):
+* from here on it is the page's, and the visit of the page going out ends.
 */
-function prepare_spa_document() {
-	session().reset();
+function prepare_spa_document(next) {
+	session().reset(next);
 	slots.remoteSeeds?.clear_remote_seeds();
 	reset_page();
 }

package/dist/runtime/session.d.ts

@@ -1,4 +1,5 @@
 import { ConcurrencyGate } from "./concurrency.js";
+import { Scope } from "@ogygia/machine";
 /** Cached SSR DOM (+ optional SWR endpoint) for `{#if}` remount of hydrate:none regions.
  * Keyed by lake entry id — size is O(unique lakes on the page), not O(toggles).
  * Cleared on SPA body swap via `reset()`. SWR refresh replaces the entry (does not grow). */
@@ -11,6 +12,33 @@ export type LakeCacheEntry = {
   /** Client TTL in ms; `0` = no expiry. */
   maxAgeMs: number;
 };
+/**
+ * THE PAGE VISIT: one per page the visitor is on, the document load, then each page a navigation
+ * swaps in. It ends when the next page's swap takes over (`RuntimeSession.reset`). What the page
+ * holds is its own and goes with it: on `scope`, its listeners, timers, observers and streams (the
+ * router's link scan, the batch of its holes, the waits for the sheets its answers bring); in
+ * `facts`, what its answers brought for its next hydrate.
+ *
+ * A navigation makes the visit of the page it brings before its swap (`RuntimeSession.next_visit`):
+ * what it starts for that page early, the batch of its holes, is that visit's. A navigation that
+ * ends without its swap (called off, taken over, given to the browser) ends that visit, never the
+ * page's (./router-nav.ts `navigate`).
+ */
+export type PageVisit = {
+  /** Closed when the visit ends. */
+  readonly scope: Scope;
+  /** The page facts answers rendered with (server/render-page.ts), queued at the answer seam
+   *  (`region_fragment`) for the next hydrate to merge into the page store (seeds.ts). This page's
+   *  only: the next page's visit starts with none (#269). */
+  readonly facts: string[];
+};
+/** What one island's hydrate step put in `<head>` ({@link RuntimeSession.mark_head}). */
+export interface HeadMark {
+  /** The head's elements now that were not its children when the mark was made, in head order. */
+  added(): Element[];
+  /** Stop noting (a step that ended without a record). */
+  stop(): void;
+}
 export declare class RuntimeSession {
   #private;
   /** Page-owned head nodes (see above). Survives `reset()`: it is the document's, not a page's. */
@@ -21,9 +49,16 @@ export declare class RuntimeSession {
   claim_page_head(node: Node): void;
   /** At boot: everything already in <head> came from the server — the page owns it. */
   adopt_document_head(): void;
-  /** After an island's hydrate: the head elements it added (not in `before`, not page-owned) are
-   *  that island's; then retire the page's copies of them. */
-  record_island_head(before: ReadonlySet<Node>): void;
+  /**
+   * Before an island's hydrate step: start noting what lands in `<head>`. A MutationObserver on the
+   * head's own children, read synchronously when the step ends, so the record costs what the island
+   * added, not the whole head (a copy of the head per island grew as islands × head). Without
+   * MutationObserver: the head's elements, copied.
+   */
+  mark_head(): HeadMark;
+  /** After an island's hydrate: the head elements it added (not there before the step, not
+   *  page-owned) are that island's; then retire the page's copies of them. */
+  record_island_head(mark: HeadMark): void;
   /**
    * Remove every PAGE-owned head element that duplicates a live island-owned one (same markup), and
    * the page's `<title>` once an island renders its own (the browser honours the first title, and
@@ -34,9 +69,11 @@ export declare class RuntimeSession {
   readonly settled_lakes: WeakSet<Element>;
   readonly initialized_lakes: Set<string>;
   readonly server_gate: ConcurrencyGate;
-  /** The page facts answers rendered with (server/render-page.ts), queued at the answer seam
-   *  (`region_fragment`) for the next hydrate to merge into the page store (seeds.ts). */
-  readonly page_facts: string[];
+  /** The visit of the page on screen (see {@link PageVisit}). */
+  get visit(): PageVisit;
+  /** The visit of the page a navigation brings, made before its swap: the navigation's (it ends
+   *  it when there is no swap) until `reset(next)` makes it the page. */
+  next_visit(): PageVisit;
   get remote_seeded(): boolean;
   mark_remote_seeded(): void;
   get page_seeded(): boolean;
@@ -46,7 +83,9 @@ export declare class RuntimeSession {
   /** Insert/replace a lake cache entry; evict oldest if over LAKE_CACHE_MAX. */
   set_lake_cache(id: string, entry: LakeCacheEntry): void;
   settle_lakes_in(root: ParentNode): void;
-  reset(): void;
+  /** The next page takes over (its visit, made by its navigation; a new one when none is given),
+   *  and the visit of the page it replaces ends. */
+  reset(next?: PageVisit): void;
 }
 /** Process-wide session for the islands runtime (one client module graph). */
 export declare const runtime_session: RuntimeSession;