@ogygia/core 0.12.3 → 0.13.0

package/dist/runtime/frame-store.js

@@ -1,14 +1,49 @@
 import { notify, watch, watcher_count } from "../ref-watch.js";
+import { STALE, flights, scope } from "@ogygia/machine";
 // src/runtime/frame-store.ts
 /** Frame addresses live in the hub's watcher space under a namespace, so region binders subscribe
 *  through the ONE hub `watch`/`notify` primitive (hub v2 phase W) — the frame store no longer owns
-*  a parallel subscriber set. Fetch orchestration (ticket, inflight, reserve, evict) stays here. */
+*  a parallel subscriber set. */
 const frame_id = (a) => "frame:" + a;
+/** The name of a refused answer's error (./region-endpoint-url.ts): by name, since the store is one
+*  per document across bundle copies, and a copy's class is not another's. */
+const REFUSED = "RegionAnswerRefused";
+/** A refused answer nobody asked for yet (the page's early start: ./early-holes.ts), held at its
+*  address for the first caller that asks there (see `Entry.refused`). Any other failure is not. */
+function hold_refusal(a, err) {
+	if (err?.name === REFUSED) entry(a).refused = err;
+}
 /** Entries with no subscribers linger this long (ms) so quick remounts / SPA swaps reuse content. */
 const EVICT_TTL = 6e4;
 const GLOBAL_KEY = "__ogygia_frames__";
+const FLIGHTS_KEY = "__ogygia_frame_flights__";
 const store_host = typeof globalThis !== "undefined" ? globalThis : {};
-const entries = store_host[GLOBAL_KEY] ?? (store_host[GLOBAL_KEY] = /* @__PURE__ */ new Map());
+const entries = store_host[GLOBAL_KEY] ??= /* @__PURE__ */ new Map();
+/** The fetches in flight, one per address, shared by every caller of it. Nothing is kept: the
+*  versioned store holds what landed. A flight's work aborts once its last caller left. */
+function frame_flights() {
+	return store_host[FLIGHTS_KEY] ??= flights.keyed()({
+		name: "frames",
+		key: ["a"],
+		ignore: { work: "one flight per address: a fetch or a batch part out there is joined" },
+		keep: 0,
+		run: ({ a, work }, signal) => typeof work === "function" ? fetch_frame(a, work, signal) : work
+	});
+}
+/** A fetch at an address takes its ticket at its start, and writes what it got (a newer write may
+*  have raced past it: the answer is whatever the store then holds). */
+async function fetch_frame(a, fetcher, signal) {
+	const t = ticket(a);
+	const html = await fetcher(signal);
+	if (!signal.aborted) write({
+		a,
+		v: t,
+		html
+	});
+	return entries.get(a)?.html ?? html;
+}
+/** A fetch or a batch's part is out at this address. */
+const flying = (a) => store_host[FLIGHTS_KEY]?.peek({ a }) !== void 0;
 function entry(a) {
 	let e = entries.get(a);
 	if (!e) {
@@ -16,28 +51,29 @@ function entry(a) {
 			v: 0,
 			html: null,
 			seq: 0,
-			inflight: null,
-			evict: null
+			batch: null,
+			evict: null,
+			renewed: null,
+			refused: null
 		};
 		entries.set(a, e);
 	}
 	return e;
 }
 /**
-* Let an idle entry (no subscribers, no in-flight fetch) linger EVICT_TTL, then drop it. A late binder
+* Let an idle entry (no subscribers, nothing in flight) linger EVICT_TTL, then drop it. A late binder
 * that mounts inside the window still catches its content (prefetch / batch-stream ahead of the DOM);
-* nothing bound means nothing to keep. Idempotent — resets the timer. Both channels that leave an
-* entry idle call this: a subscriber unbinding, AND a `write()` that lands where nothing is listening
-* (a single-flight mutation for an unmounted region, or a live tick whose address keeps changing).
-* Without the write path, those orphan entries would accumulate forever — they never had a subscriber
-* to trigger eviction.
+* nothing bound means nothing to keep. Idempotent — resets the timer. Every channel that leaves an
+* entry idle calls this: a subscriber unbinding, a flight that settled, AND a `write()` that lands
+* where nothing is listening (a single-flight mutation for an unmounted region, or a live tick whose
+* address keeps changing). Without the write path, those orphan entries would accumulate forever —
+* they never had a subscriber to trigger eviction.
 */
 function schedule_evict(a, e) {
-	if (watcher_count(frame_id(a)) > 0 || e.inflight) return;
-	if (e.evict) clearTimeout(e.evict);
-	e.evict = setTimeout(() => {
-		const cur = entries.get(a);
-		if (cur === e && watcher_count(frame_id(a)) === 0 && !cur.inflight) entries.delete(a);
+	if (watcher_count(frame_id(a)) > 0 || flying(a)) return;
+	e.evict?.close();
+	(e.evict = scope()).timeout(() => {
+		if (entries.get(a) === e && watcher_count(frame_id(a)) === 0 && !flying(a)) entries.delete(a);
 	}, EVICT_TTL);
 }
 /** Applied content for an address, if any. */
@@ -48,10 +84,18 @@ function peek(a) {
 		html: e.html
 	} : null;
 }
+/** A renewal at this address answered `fresh`, the capability its elements fetch with from now on. */
+function renew(a, fresh) {
+	entry(a).renewed = fresh;
+}
+/** The fresh capability a renewal at this address answered, if any. */
+function renewal(a) {
+	return entries.get(a)?.renewed ?? null;
+}
 /** Nothing applied and nothing in flight at this address (a batch may take it on). */
 function is_idle(a) {
 	const e = entries.get(a);
-	return !e || e.html == null && !e.inflight;
+	return !e || e.html == null && !flying(a);
 }
 /** Next request ticket for an address. External channels (streaming, mutations) use this too. */
 function ticket(a) {
@@ -67,9 +111,10 @@ function write(f) {
 	if (f.v > e.seq) e.seq = f.v;
 	e.v = f.v;
 	e.html = f.html;
-	const held = e.inflight;
-	if (held?.settle) {
-		e.inflight = null;
+	e.refused = null;
+	const held = e.batch;
+	if (held) {
+		e.batch = null;
 		held.settle(f.html);
 	}
 	notify(frame_id(f.a), f);
@@ -78,48 +123,43 @@ function write(f) {
 }
 /**
 * Reserve an address whose content is arriving via an EXTERNAL batch stream (single-flight navigation). A region
-* binder that mounts before its frame lands calls `ensure()`, sees this reservation, and JOINS it
+* binder that mounts before its frame lands calls `ensure()`, finds the batch's flight there, and JOINS it
 * instead of starting its own fetch — so a navigation that pulls N regions makes ONE batch request,
-* not N. `write()` fulfils the reservation when the frame arrives; `release()` fails it if the batch
-* ends without one (the binder then falls back to its own fetch). No-op if content or a fetch is
-* already present.
+* not N. `write()` fulfils it when the frame arrives; `release()` fails it if the batch ends without
+* one (the binder then falls back to its own fetch). The flight is the batch's: a binder leaving never
+* ends it. No-op if content or a fetch is already present.
 */
 function reserve(a) {
 	const e = entry(a);
-	if (e.html != null || e.inflight) return;
-	if (e.evict) {
-		clearTimeout(e.evict);
-		e.evict = null;
-	}
-	let settle;
-	let fail;
-	const promise = new Promise((res, rej) => {
-		settle = res;
-		fail = rej;
+	if (e.html != null || flying(a)) return;
+	e.evict?.close();
+	e.evict = null;
+	const batch = new Promise((settle, fail) => {
+		e.batch = {
+			settle,
+			fail
+		};
 	});
-	promise.catch(() => {});
-	e.inflight = {
-		ticket: ticket(a),
-		promise,
-		controller: new AbortController(),
-		waiters: 0,
-		settle,
-		fail
-	};
+	batch.catch(() => {});
+	const settled = () => schedule_evict(a, e);
+	frame_flights().get({
+		a,
+		work: batch
+	}).then(settled, settled);
 }
 /**
-* Fail an unfulfilled reservation (the batch ended and no frame carried this address). Joined binders
-* reject out of `ensure()` and retry with their own fetch. No-op once content has arrived.
+* Fail an unfulfilled batch part (the batch ended and no frame was written at this address, by it or
+* by anyone). Joined binders reject out of `ensure()` and retry with their own fetch. No-op once a
+* frame has landed (it settled the part).
 */
 function release(a) {
 	const e = entries.get(a);
-	const held = e?.inflight;
-	if (!e || !held?.fail || e.html != null) return;
-	e.inflight = null;
+	const held = e?.batch;
+	if (!e || !held) return;
+	e.batch = null;
 	const miss = /* @__PURE__ */ new Error("ogygia batch: no frame for " + a);
 	miss.name = BATCH_MISS;
 	held.fail(miss);
-	schedule_evict(a, e);
 }
 /** The error a joined reservation rejects with when its batch ended without its frame: the binder's
 *  own fetch runs at once (nothing failed — the batch just did not carry it). */
@@ -132,10 +172,8 @@ const BATCH_MISS = "OgygiaBatchMiss";
 */
 function subscribe(a, cb) {
 	const e = entry(a);
-	if (e.evict) {
-		clearTimeout(e.evict);
-		e.evict = null;
-	}
+	e.evict?.close();
+	e.evict = null;
 	const off = watch(frame_id(a), cb);
 	if (e.html != null) cb({
 		a,
@@ -151,64 +189,52 @@ function subscribe(a, cb) {
 * Ensure an address has content, deduping concurrent callers onto one fetch.
 *
 * - Content already applied (and not `force`): resolves immediately with it.
-* - A fetch is in flight (and not `force`): joins it — N regions, ONE request.
+* - A fetch (or a batch's part) is in flight (and not `force`): joins it — N regions, ONE request.
 * - Otherwise starts `fetcher` with a fresh ticket; on success the response is WRITTEN (subject to
 *   the staleness check) and the resolved value is whatever the store now holds.
-* - `force` (SWR revalidate) always starts a new fetch; the ticket ordering still guarantees an
-*   older in-flight response can't overwrite it.
+* - `force` (SWR revalidate) always starts a new fetch, and ends the one out before it: whoever
+*   waited on that one joins the new one. The ticket ordering still guarantees an older response
+*   can't overwrite a newer one.
 *
-* Rejections propagate to every joined caller; retry policy stays with the caller (the element).
+* `signal` is the caller's: when it aborts, this caller alone gets `STALE` at once, and the shared
+* fetch is aborted only once its LAST caller left — one unmounting element must not kill a fetch
+* its twin still awaits. Rejections propagate to every joined caller; retry policy stays with the
+* caller (the element).
 */
-function ensure(a, fetcher, opts = {}) {
+async function ensure(a, fetcher, opts = {}) {
+	const { signal } = opts;
+	const f = frame_flights();
 	const e = entry(a);
-	if (!opts.force) {
-		if (e.html != null) return Promise.resolve(e.html);
-		if (e.inflight) {
-			e.inflight.waiters++;
-			return e.inflight.promise;
-		}
-	}
-	const controller = new AbortController();
-	const t = ticket(a);
-	const inflight = {
-		ticket: t,
-		controller,
-		waiters: 1,
-		promise: fetcher(controller.signal).then((html) => {
-			if (e.inflight === inflight) e.inflight = null;
-			write({
+	let fresh = opts.force === true;
+	try {
+		for (;;) {
+			if (!fresh && e.html != null) return e.html;
+			const refused = e.refused;
+			e.refused = null;
+			if (!fresh && refused !== null) throw refused;
+			const html = await f.get({
 				a,
-				v: t,
-				html
+				work: fetcher
+			}, {
+				signal,
+				fresh
 			});
-			return e.html ?? html;
-		}, (err) => {
-			if (e.inflight === inflight) e.inflight = null;
-			throw err;
-		})
-	};
-	e.inflight = inflight;
-	return inflight.promise;
-}
-/**
-* A waiter is leaving (its element disconnected). Aborts the shared fetch only when the LAST
-* waiter leaves — one unmounting element must not kill a fetch its twin still awaits.
-*/
-function abandon(a) {
-	const e = entries.get(a);
-	if (!e?.inflight) return;
-	if (--e.inflight.waiters <= 0) {
-		e.inflight.controller.abort();
-		e.inflight = null;
+			if (html !== STALE || signal?.aborted || frame_flights() !== f) return html;
+			fresh = false;
+		}
+	} finally {
+		schedule_evict(a, e);
 	}
 }
 /** Test/HMR hook — drop everything. */
 function _reset() {
 	for (const e of entries.values()) {
-		if (e.evict) clearTimeout(e.evict);
-		e.inflight?.fail?.(/* @__PURE__ */ new Error("reset"));
-		e.inflight?.controller.abort();
+		e.evict?.close();
+		e.batch?.fail(/* @__PURE__ */ new Error("reset"));
 	}
+	const old = store_host[FLIGHTS_KEY];
+	store_host[FLIGHTS_KEY] = void 0;
+	old?.drop(() => true);
 	entries.clear();
 }
-export { BATCH_MISS, _reset, abandon, ensure, is_idle, peek, release, reserve, subscribe, ticket, write };
+export { BATCH_MISS, _reset, ensure, hold_refusal, is_idle, peek, release, renew, renewal, reserve, subscribe, ticket, write };

package/dist/runtime/frames.js

@@ -1,23 +1,27 @@
 import { slots } from "./slots.js";
-import { abandon, ensure, subscribe } from "./frame-store.js";
+import { ensure, renew, renewal, subscribe } from "./frame-store.js";
 import { batch_times, join_batch, streamFrames } from "./frame-nav.js";
+import { adopt_early_holes } from "./early-holes.js";
+import { runtime_session } from "./session.js";
 // src/runtime/frames.ts
 /**
 * frames feature: hand the client frame store to core through the {@link ./slots.js slots} seam.
 *
 * Core drives deferred / live / SWR-lake regions off this store (subscribe → apply, ensure →
-* single-flight fetch, abandon → cleanup), and the router single-flights a route's deferred holes through
+* single-flight fetch, a caller's signal → its leaving), and the router single-flights a route's deferred holes through
 * `stream` — but NEITHER may statically import the store, or the ~10 kB store + nav-stream graph
 * lands in every build, including a plain router app with no such region. The generated runtime entry
 * installs this feature only when the app actually ships a deferred / live / lake region, so a
 * static-islands app (and a router app without deferred regions) tree-shakes the whole graph away.
 */
 function install() {
+	adopt_early_holes(runtime_session.visit.scope);
 	slots.frames = {
 		subscribe,
 		ensure,
-		abandon,
-		stream: streamFrames,
+		renew,
+		renewal,
+		stream: (endpoints, visit) => streamFrames(endpoints, "nav", visit),
 		join: join_batch,
 		batch_times
 	};

package/dist/runtime/hole-facts.js

@@ -1,4 +1,5 @@
 import { HOLES_SCRIPT_TYPE } from "../holes-record.js";
+import { parse_region_html } from "./parse-html.js";
 // src/runtime/hole-facts.ts
 /**
 * THE HOLES RECORD — what the server minted for each deferred hole on a KIT-HYDRATED document,
@@ -32,17 +33,15 @@ function parse_record(doc) {
 		if (!entry || typeof entry.endpoint !== "string" || !entry.endpoint) continue;
 		map.set(identity, {
 			endpoint: entry.endpoint,
-			sidecar: typeof entry.sidecar === "string" && entry.sidecar ? sidecar_element(doc, entry.sidecar) : null
+			sidecar: typeof entry.sidecar === "string" && entry.sidecar ? sidecar_element(entry.sidecar) : null
 		});
 	}
 	return map;
 }
-/** The recorded sidecar HTML back into a script element (off the DOM; a `<template>` parses it
-*  without running anything — the sidecar is a data script, never executable). */
-function sidecar_element(doc, html) {
-	const holder = doc.createElement("template");
-	holder.innerHTML = html;
-	const el = holder.content.firstElementChild;
+/** The recorded sidecar HTML back into a script element, through the one parser (./parse-html.ts:
+*  inert, nothing runs — the sidecar is a data script, never executable). */
+function sidecar_element(html) {
+	const el = parse_region_html(html).firstElementChild;
 	return el && el.tagName === "SCRIPT" ? el : null;
 }
 /** The server-minted facts of the hole with this identity on `doc`, or `null`. */

package/dist/runtime/hole-fetch.d.ts

@@ -0,0 +1,17 @@
+export type HoleFetch = {
+  /** Past the browser cache: the endpoint may answer `private, max-age`, and stale is the whole
+   *  point of revalidating. */
+  revalidate?: boolean;
+  priority?: "high" | "auto" | "low";
+  signal?: AbortSignal;
+  /** A renewal answered this fresh capability for the hole. */
+  renewed?: (fresh: string) => void;
+};
+/** A hole's fetch: its request started ({@link start_hole}), its answer read ({@link read_hole}). */
+export declare function fetch_hole(endpoint: string, opts?: HoleFetch): Promise<string>;
+/** The request for a hole's HTML (the page's head starts a `load` hole's the same way:
+ *  ../early-holes.ts). */
+export declare function start_hole(endpoint: string, { revalidate, priority, signal }?: HoleFetch): Promise<Response>;
+/** A hole's answer, read: whatever lands at an address is read this one way, whoever started its
+ *  request. */
+export declare function read_hole(endpoint: string, response: Promise<Response>, opts?: Pick<HoleFetch, "signal" | "renewed">): Promise<string>;

package/dist/runtime/hole-fetch.js

@@ -0,0 +1,47 @@
+import { KEEP_FALLBACK_HTML } from "../keep-fallback-marker.js";
+import { RegionAnswerRefused, capability_expired, deny_of, is_allowed_region_endpoint, is_document_answer, is_redirected_answer, is_same_origin_response, renewal_url } from "./region-endpoint-url.js";
+// src/runtime/hole-fetch.ts
+/**
+* THE ONE NETWORK FETCH OF A HOLE'S HTML. The element's own wake, its `prefetch` warm and `preload()`
+* all fetch a hole through here, so whatever lands in the frame store at its address was read one
+* way: the endpoint's text, the keep-fallback marker on a 204 (`keepFallback()` on the server), or a
+* refusal when the answer is not the region's. An expired capability renews once, and the fresh one
+* is handed to `renewed` (the frame store keeps it for the address). No DOM, no store, no scheduler:
+* the caller decides when it may go out.
+*/
+/** A hole's fetch: its request started ({@link start_hole}), its answer read ({@link read_hole}). */
+async function fetch_hole(endpoint, opts = {}) {
+	return read_hole(endpoint, start_hole(endpoint, opts), opts);
+}
+/** The request for a hole's HTML (the page's head starts a `load` hole's the same way:
+*  ../early-holes.ts). */
+function start_hole(endpoint, { revalidate = false, priority = "auto", signal } = {}) {
+	return fetch(endpoint, {
+		credentials: "same-origin",
+		cache: revalidate ? "no-store" : "default",
+		priority,
+		signal
+	});
+}
+/** A hole's answer, read: whatever lands at an address is read this one way, whoever started its
+*  request. */
+async function read_hole(endpoint, response, opts = {}) {
+	let res = await response;
+	if (res.status === 403 && capability_expired(endpoint)) {
+		res = await start_hole(renewal_url(endpoint), {
+			revalidate: true,
+			signal: opts.signal
+		});
+		const fresh = res.ok ? res.headers.get("x-ogygia-capability") : null;
+		if (fresh && is_allowed_region_endpoint(fresh)) opts.renewed?.(fresh);
+	}
+	if (!is_same_origin_response(res)) throw new Error("cross-origin redirect");
+	if (is_redirected_answer(res)) throw new RegionAnswerRefused("redirected", res.url);
+	if (res.status === 403) throw new RegionAnswerRefused("forbidden", res.url || endpoint, deny_of(res, endpoint));
+	if (!res.ok) throw new Error("status " + res.status);
+	if (res.status === 204) return KEEP_FALLBACK_HTML;
+	const text = await res.text();
+	if (is_document_answer(text)) throw new RegionAnswerRefused("document", res.url);
+	return text;
+}
+export { fetch_hole, read_hole, start_hole };

package/dist/runtime/hydrate-core.d.ts

@@ -1,7 +1,7 @@
 import { Component } from "svelte";
 export declare const seed_page_once: () => void;
 export declare const seed_remote_once: () => void;
-export declare const kit_page_thread: () => Promise<void> | null;
+export declare const kit_page_thread: (signal: AbortSignal) => Promise<unknown> | null;
 /** A hydrated island as the element holds it: how to tear it down, and (keep / live hosts) how to
  *  push the next page's props into it. */
 export type IslandHandle = {
@@ -94,8 +94,8 @@ export declare function read_region_props(region: Element, foreign?: boolean): R
  */
 export declare function hydrate_island(region: HTMLElement, entry: string, mod: IslandModule, ssr_html?: string | null, touched?: boolean): IslandHandle | null;
 /**
- * Hydrate a live region's swapped-in HTML through {@link LiveHost} (props-pushable). A live region's
- * HTML comes from svelte `render()` (both envelope layers) — same as the deferred swap path, so it
- * is NOT wrapped in extra `[..]` hydration comments. `null` when the live feature is absent.
+ * Hydrate a live region's swapped-in HTML with pushable props, so a later tick reaches the mounted
+ * island in place. Its HTML is svelte `render()`'s (the root anchor pair already there) — the
+ * deferred swap's shape, so it is never wrapped again. `null` when the live feature is absent.
  */
 export declare function hydrate_live(region: HTMLElement, entry: string, mod: IslandModule, props: Record<string, unknown>): IslandHandle | null;