@ogygia/core 0.0.0 → 0.11.0

package/dist/runtime/nav-handle.d.ts

@@ -0,0 +1,25 @@
+import { AfterNavigateCallback, BeforeNavigateCallback } from "./router.js";
+export declare const NAV_HANDLE_KEY: unique symbol;
+export type NavHandle = {
+  goto(url: string | URL, opts?: {
+    replaceState?: boolean;
+    external?: boolean;
+  }): Promise<void>;
+  invalidate(): Promise<void>;
+  invalidateAll(): Promise<void>;
+  preloadData(url: string | URL): Promise<unknown>;
+  preloadCode(url?: string | URL): Promise<void>;
+  disableScrollHandling(): void;
+  pushState(): void;
+  replaceState(): void;
+  beforeNavigate(fn: BeforeNavigateCallback): () => void;
+  afterNavigate(fn: AfterNavigateCallback): () => void;
+  bust_page_cache(): void;
+};
+/** Publish the document's navigation handle (the router's replaces the MPA one). */
+export declare function publish_nav(handle: NavHandle): void;
+/**
+ * The handle when the router feature is not in this runtime (`router: false`): the browser owns
+ * navigation. Same contract the router's own functions had for that case.
+ */
+export declare function mpa_nav(): NavHandle;

package/dist/runtime/nav-handle.js

@@ -0,0 +1,71 @@
+import { speculate_url } from "./speculate-hint.js";
+// src/runtime/nav-handle.ts
+/**
+* THE NAVIGATION HANDLE — how ISLAND-SIDE code (the `$app/navigation` shim, `ogygia/app`, the
+* remote-functions client stub, the lifecycle hooks) reaches the running runtime's navigation
+* WITHOUT importing a runtime module.
+*
+* Why not just import the router: island code is bundled apart from the runtime (an island chunk
+* can load on a csr=true page where the runtime never boots). A runtime module island code imports
+* is SHARED between the two graphs, so the bundler must keep it out of the runtime chunk — and with
+* it everything that module's own lazy chunks need. One `import … from '../runtime/router.ts'` in the
+* navigation shim split the runtime's boot into a dozen files. So island code reads this handle
+* from the global realm (the same pattern as the Kit page bridge, `Symbol.for('ogygia.kit-page')`),
+* and `test/runtime-boot-svelte-free.test.ts` pins that no island-side module imports a boot module.
+*
+* Who publishes it, always, on a document ogygia boots:
+* - the ROUTER feature (./router.ts `install`) — the SPA router's API;
+* - otherwise core (`boot`) publishes {@link mpa_nav}: the browser navigates, preloads become
+*   Speculation Rules hints, and `invalidateAll` is still the soft seed refresh (./router-nav.ts,
+*   loaded on first use) — exactly what `router: false` apps got before.
+*
+* Island code reads it as `globalThis[Symbol.for('ogygia.nav')]` (the key is repeated there on
+* purpose: importing {@link NAV_HANDLE_KEY} would be the very edge this module exists to avoid).
+*/
+const NAV_HANDLE_KEY = Symbol.for("ogygia.nav");
+/** Publish the document's navigation handle (the router's replaces the MPA one). */
+function publish_nav(handle) {
+	globalThis[NAV_HANDLE_KEY] = handle;
+}
+const NO_UNSUBSCRIBE = () => {};
+/**
+* The handle when the router feature is not in this runtime (`router: false`): the browser owns
+* navigation. Same contract the router's own functions had for that case.
+*/
+function mpa_nav() {
+	return {
+		goto(url, opts = {}) {
+			const target = new URL(url, location.href);
+			if (target.protocol !== "http:" && target.protocol !== "https:") throw new Error("[ogygia] goto() only supports http(s) URLs");
+			if (target.origin !== location.origin && !opts.external) throw new Error("[ogygia] goto() only supports same-origin URLs (pass { external: true } to leave)");
+			if (opts.replaceState) location.replace(target.href);
+			else location.assign(target.href);
+			return Promise.resolve();
+		},
+		invalidate: () => import("./router-nav.js").then((n) => n.invalidate_all()),
+		invalidateAll: () => import("./router-nav.js").then((n) => n.invalidate_all()),
+		preloadData(url) {
+			speculate_url(url, "prerender");
+			return Promise.resolve({
+				type: "loaded",
+				status: 200,
+				data: {}
+			});
+		},
+		preloadCode(url) {
+			if (url != null) speculate_url(url, "prefetch");
+			return Promise.resolve();
+		},
+		disableScrollHandling() {},
+		pushState() {
+			console.warn("[ogygia] pushState() shallow routing is not supported; use goto().");
+		},
+		replaceState() {
+			console.warn("[ogygia] replaceState() shallow routing is not supported; use goto().");
+		},
+		beforeNavigate: () => NO_UNSUBSCRIBE,
+		afterNavigate: () => NO_UNSUBSCRIBE,
+		bust_page_cache() {}
+	};
+}
+export { NAV_HANDLE_KEY, mpa_nav, publish_nav };

package/dist/runtime/nav-hooks.d.ts

@@ -0,0 +1,2 @@
+/** Tie a registration's unsubscribe to the calling component's lifetime; returns it too. */
+export declare function bind_to_component(off: () => void): () => void;

package/dist/runtime/nav-hooks.js

@@ -0,0 +1,23 @@
+import { onDestroy } from "svelte";
+// src/runtime/nav-hooks.ts
+/**
+* `beforeNavigate` / `afterNavigate` as a COMPONENT sees them (`$app/navigation`, `ogygia/app`):
+* lifecycle-bound like Kit's — the hook is unsubscribed when the calling component is destroyed.
+* The raw registrations (the runtime's navigation handle, ./nav-handle.ts) return an unsubscribe and
+* nothing else; a component that called them on every mount (an island re-mounting on each
+* navigation) left one more callback behind per visit. This module imports `onDestroy` from Svelte,
+* so it lives beside the shims (in an island's chunk, where Svelte already is) — never in the
+* runtime's boot chunk — and it imports nothing from the runtime (island code reaches it only
+* through the navigation handle).
+*
+* Outside a component (a plain module, a test) Svelte throws on `onDestroy`; the registration
+* still stands and the returned unsubscribe is the caller's to call, exactly as before.
+*/
+/** Tie a registration's unsubscribe to the calling component's lifetime; returns it too. */
+function bind_to_component(off) {
+	try {
+		onDestroy(off);
+	} catch {}
+	return off;
+}
+export { bind_to_component };

package/dist/runtime/nearest-attr.d.ts

@@ -0,0 +1,4 @@
+/** The value of `attr` on `el` or its NEAREST ancestor that has it, crossing shadow-root boundaries (an
+ *  island inside a web component's shadow tree still finds the block around the component; a link a
+ *  component renders in its shadow tree, the router's `data-sveltekit-reload` around the component). */
+export declare function nearest_attr(el: Element, attr: string): string | null;

package/dist/runtime/nearest-attr.js

@@ -0,0 +1,16 @@
+// src/runtime/nearest-attr.ts
+/** The value of `attr` on `el` or its NEAREST ancestor that has it, crossing shadow-root boundaries (an
+*  island inside a web component's shadow tree still finds the block around the component; a link a
+*  component renders in its shadow tree, the router's `data-sveltekit-reload` around the component). */
+function nearest_attr(el, attr) {
+	const sel = `[${typeof CSS !== "undefined" && CSS.escape ? CSS.escape(attr) : attr}]`;
+	let at = el;
+	while (at) {
+		const hit = at.closest(sel);
+		if (hit) return hit.getAttribute(attr);
+		const root = at.getRootNode();
+		at = root instanceof ShadowRoot ? root.host : null;
+	}
+	return null;
+}
+export { nearest_attr };

package/dist/runtime/observe.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ONE IntersectionObserver per distinct `rootMargin`, shared by every element that wants to know
+ * when it enters the viewport — `wake:'visible'` islands, `when="visible"` holes, the hydration
+ * scheduler's viewport snapshot. An observer per island (150 of them on a measured page) is 150
+ * observers the browser walks on every scroll; one per margin is a handful, each walking the same
+ * targets in one pass. Callbacks live on a per-observer `WeakMap` keyed by the target, so a
+ * disconnected element drops out with its callbacks.
+ *
+ * SEVERAL callbacks per element per margin. It was one, a second `observe` replacing the first —
+ * and the hydration scheduler's viewport snapshot and a `wake:'visible'` island both watch the
+ * island at the default margin: the wake replaced the snapshot, so the scheduler never learned
+ * where a visible island was and held every one of them for its whole 48 ms snapshot wait (200
+ * islands scrolled into view: each woke 62–84 ms late, with nothing ahead of it).
+ */
+type Callback = (intersecting: boolean) => void;
+/**
+ * Observe `el` under the shared observer for `rootMargin`; `cb` sees every intersection change
+ * (the initial one included) until the returned unobserve is called. Any number of callbacks per
+ * element: a later one gets the element's last known state at once (the browser reports an
+ * element it already watches only on a change), or the first report with the others.
+ */
+export declare function observe(el: Element, rootMargin: string, cb: Callback): () => void;
+/** Test seam: how many observers exist (one per distinct rootMargin, ever). */
+export declare function observer_count(): number;
+/** Observe until the FIRST time `el` intersects, then fire once and stop. */
+export declare function once_visible(el: Element, rootMargin: string, fire: () => void): () => void;
+export {};

package/dist/runtime/observe.js

@@ -0,0 +1,63 @@
+// src/runtime/observe.ts
+const observers = /* @__PURE__ */ new Map();
+function shared(rootMargin) {
+	let s = observers.get(rootMargin);
+	if (!s) {
+		const callbacks = /* @__PURE__ */ new WeakMap();
+		const last = /* @__PURE__ */ new WeakMap();
+		s = {
+			io: new IntersectionObserver((entries) => {
+				for (const e of entries) {
+					last.set(e.target, e.isIntersecting);
+					const set = callbacks.get(e.target);
+					if (set) for (const cb of Array.from(set)) cb(e.isIntersecting);
+				}
+			}, { rootMargin }),
+			callbacks,
+			last
+		};
+		observers.set(rootMargin, s);
+	}
+	return s;
+}
+/**
+* Observe `el` under the shared observer for `rootMargin`; `cb` sees every intersection change
+* (the initial one included) until the returned unobserve is called. Any number of callbacks per
+* element: a later one gets the element's last known state at once (the browser reports an
+* element it already watches only on a change), or the first report with the others.
+*/
+function observe(el, rootMargin, cb) {
+	const s = shared(rootMargin);
+	let set = s.callbacks.get(el);
+	if (!set) s.callbacks.set(el, set = /* @__PURE__ */ new Set());
+	const first = set.size === 0;
+	set.add(cb);
+	if (first) s.io.observe(el);
+	else if (s.last.has(el)) {
+		const state = s.last.get(el);
+		queueMicrotask(() => {
+			if (s.callbacks.get(el)?.has(cb)) cb(state);
+		});
+	}
+	return () => {
+		const now = s.callbacks.get(el);
+		if (!now?.delete(cb) || now.size) return;
+		s.callbacks.delete(el);
+		s.last.delete(el);
+		s.io.unobserve(el);
+	};
+}
+/** Test seam: how many observers exist (one per distinct rootMargin, ever). */
+function observer_count() {
+	return observers.size;
+}
+/** Observe until the FIRST time `el` intersects, then fire once and stop. */
+function once_visible(el, rootMargin, fire) {
+	const stop = observe(el, rootMargin, (intersecting) => {
+		if (!intersecting) return;
+		stop();
+		fire();
+	});
+	return stop;
+}
+export { observe, observer_count, once_visible };

package/dist/runtime/own-cost.d.ts

@@ -0,0 +1,9 @@
+/** Add the time since `t0` to `phase`. */
+export declare function charge(phase: string, t0: number): void;
+/** Run `fn`, charging its time to `phase`. */
+export declare function metered<T>(phase: string, fn: () => T): T;
+/** The cost so far, rounded: `{ ms, phases }`. */
+export declare function own_cost(): {
+  ms: number;
+  phases: Record<string, number>;
+};

package/dist/runtime/own-cost.js

@@ -0,0 +1,35 @@
+// src/runtime/own-cost.ts
+/**
+* What MEASURING costs the page's main thread, by phase (ms): the work devtools and the profiler's
+* beacon do only because someone measures — checking each island's markup as it hydrates, building the
+* visit, the testing API's reports. A visitor with devtools off pays none of it, so a test subtracts it
+* (`page().ogygia`) and a CPU comparison across ogygia versions stays about the page.
+*/
+const spent = globalThis[Symbol.for("ogygia.own-cost")] ??= {};
+/** Add the time since `t0` to `phase`. */
+function charge(phase, t0) {
+	spent[phase] = (spent[phase] ?? 0) + (performance.now() - t0);
+}
+/** Run `fn`, charging its time to `phase`. */
+function metered(phase, fn) {
+	const t0 = performance.now();
+	try {
+		return fn();
+	} finally {
+		charge(phase, t0);
+	}
+}
+/** The cost so far, rounded: `{ ms, phases }`. */
+function own_cost() {
+	const phases = {};
+	let ms = 0;
+	for (const k in spent) {
+		phases[k] = Math.round(spent[k] * 10) / 10;
+		ms += spent[k];
+	}
+	return {
+		ms: Math.round(ms * 10) / 10,
+		phases
+	};
+}
+export { charge, metered, own_cost };

package/dist/runtime/ownership.d.ts

@@ -0,0 +1,101 @@
+/**
+ * # DOM ownership — who owns a node inside a region (internal/notes/dom-ownership.md)
+ *
+ * Every ogygia DOM writer (the pre-hydration drift check and repair, the morph behind hole answers /
+ * live ticks / navigations, drift-watch) asks THIS module whether it may touch an element, instead of
+ * re-deriving the answer from its own subset of signals. One answer per element, one precedence:
+ *
+ * | owner     | what                                                                  |
+ * |-----------|-----------------------------------------------------------------------|
+ * | `foreign` | a subtree the app declared the live DOM's own (`data-ogygia-keep` / `data-persist` on a plain element) |
+ * | `region`  | a hydrated region root: Svelte's reactivity owns it now, not a morph  |
+ * | `page`    | `<ogygia-slot>`: host-page content an island adopts whole             |
+ * | `static`  | an element the compiler stamped `data-og-opaque` — render output Svelte's hydration never walks into (`{@html}`, `bind:innerHTML`, a custom element with static children) — or a child element of one stamped `data-og-html` (it may be `{@html}` content) |
+ * | `walk`    | everything else: render output Svelte's walk binds by position        |
+ *
+ * (Lakes are the sixth owner; the hydrate core lifts them out of both trees before any comparison,
+ * so no writer here meets one.) What each writer does with each owner is the contract table in the
+ * note; the short form:
+ *  - the DRIFT CHECK and the REPAIR keep only `walk` in the server's shape — every other owner is one
+ *    sibling to Svelte's walk (tag + position), never entered;
+ *  - the MORPH never enters `foreign` or `region` (nor a morph ROOT that is `foreign`), and patches
+ *    `static` / `page` / `walk` toward the answer;
+ *  - DRIFT-WATCH ignores a change made inside a non-`walk` subtree (a widget upgrading its own light
+ *    DOM is not the island drifting).
+ *
+ * `data-ogygia-keep` on an `<ogygia-region>` is NOT `foreign`: there it names an island that survives
+ * navigation (KeepHost) — Svelte owns that island, and it is repaired and hydrated like any other.
+ *
+ * FACETS (note §11): `owner_of` answers who writes INSIDE an element; the same module answers who
+ * writes its ATTRIBUTES (`attributes_writer`, `REGION_RENDER_ATTRS`), who ORDERS its children
+ * (`order_owner`), and whether a child EXISTS by the render's doing (`render_made`): one element, four
+ * facets, one place. The morph's matching, attribute sync and removal all read them.
+ */
+/** The owner of an element, for the writers that consult it. */
+export type Owner = "foreign" | "region" | "page" | "static" | "walk";
+/** The compiler's server-only stamp: Svelte's hydration never walks inside this element. */
+export declare const OPAQUE_ATTR = "data-og-opaque";
+/** The compiler's server-only stamp on an element holding an `{@html}` BESIDE other children: its
+ *  child elements may be `{@html}` content, which Svelte never walks into. (PROD output opens an
+ *  `{@html}` block with the same `<!---->` as any separator, so the exact range is not knowable from
+ *  the DOM; its child elements are compared by tag and position only, never entered.) */
+export declare const HTML_PARENT_ATTR = "data-og-html";
+/** The app declared this subtree the live DOM's own: a plain element carrying `data-ogygia-keep` or
+ *  `data-persist` (on a region, keep names a navigation-surviving island instead — not foreign). */
+export declare function is_declared_foreign(el: Element): boolean;
+/** A region whose subtree Svelte's reactivity owns (hydrated), or a kept island (it survives a
+ *  navigation untouched) — matched by a morph, never entered. `data-hydrated` is only ever set on
+ *  hyphenated roots, so its probe sits behind a cheap hyphen test. */
+export declare function is_region_owned(el: Element): boolean;
+/**
+ * Who owns `el`. First match wins: `foreign` (declared) → `region` → `page` → `static` → `walk`.
+ * `foreign` outranks `region` for plain elements only (a region never answers `foreign`), so a kept
+ * island is `region` and a kept widget is `foreign`.
+ */
+export declare function owner_of(el: Element): Owner;
+/** True when Svelte's hydration walk binds `el`'s CHILDREN by position — the only subtrees the drift
+ *  check and the repair keep in the server's shape. */
+export declare function walk_enters(el: Element): boolean;
+/**
+ * An UPGRADED CUSTOM ELEMENT: a live web component whose own runtime owns its host. Detected
+ * STRUCTURALLY — a hyphenated name with a shadow root or a registered definition — never by a
+ * library-specific attribute. The ONE detection every writer uses (the morph's attribute skip and
+ * self-owned children, the repair's conflict report).
+ */
+export declare function is_upgraded_ce(el: Element): boolean;
+/**
+ * An element whose CHILDREN are partly its own doing, not the render's: an upgraded custom element
+ * (it slots / rewrites its light DOM), or a `<dialog>` / `<details>` whose `open` the browser flips.
+ * A child it gave itself is `foreign` content inside a `walk`-owned element: the live morph keeps it;
+ * the repair removes it only where Svelte's walk needs the position (and reports the conflict).
+ */
+export declare function is_self_owned(el: Element): boolean;
+/** Who writes an element's attributes: its own runtime (an upgraded custom element's host), Svelte's
+ *  reactivity (a hydrated region root — but see {@link REGION_RENDER_ATTRS}), or the render. */
+export declare function attributes_writer(el: Element): "render" | "element" | "region";
+/** The attributes of a region root that stay the render's: its ADDRESS, which the render that minted
+ *  it writes (a re-minted hole fetches its new answer there); its content is its answer's. */
+export declare const REGION_RENDER_ATTRS: readonly string[];
+/** Who orders an element's children: the render (positions are its sequence), or the element itself
+ *  (a self-owned element relocates and wraps its light DOM — positions are not the render's). */
+export declare function order_owner(el: Element): "render" | "element";
+/**
+ * Does a self-owned element SLOT its light DOM — show it through a shadow root's `<slot>`s, in
+ * document order — rather than render it itself? Then it has no reason to move a child: the children
+ * are partly its own (it may add some), but the RENDER's nodes keep the render's order (morph.ts
+ * `reconcile_by_identity`). One with no shadow root may relocate and wrap them: its arrangement stands.
+ * (a closed shadow root is invisible here: such an element is taken to arrange, the safe side)
+ */
+export declare function slots_light_dom(el: Element): boolean;
+/** A live region whose first HTML was baked into the page by Svelte's `{@html}` (Region.svelte,
+ *  PromiseRegionAwait): kept for the element's life — Svelte's block anchors stay among its children. */
+export declare const BAKED_ATTR = "data-og-baked";
+/** Record that the render placed `node` (it may remove it once the render stops producing it). */
+export declare function mark_render_made(node: Node): void;
+/**
+ * Does `node`, a child of an element-ordered parent, EXIST by the render's doing? Marked by ogygia, or
+ * structurally: an `<ogygia-region>` is always render output, and an element whose tag the render
+ * produces at this level (`render_tags`) is render output — a runtime does not make the render's
+ * elements. Anything else is the element's own: never matched, never removed.
+ */
+export declare function render_made(node: Node, render_tags: ReadonlySet<string>): boolean;

package/dist/runtime/ownership.js

@@ -0,0 +1,115 @@
+// src/runtime/ownership.ts
+/** The compiler's server-only stamp: Svelte's hydration never walks inside this element. */
+const OPAQUE_ATTR = "data-og-opaque";
+/** The compiler's server-only stamp on an element holding an `{@html}` BESIDE other children: its
+*  child elements may be `{@html}` content, which Svelte never walks into. (PROD output opens an
+*  `{@html}` block with the same `<!---->` as any separator, so the exact range is not knowable from
+*  the DOM; its child elements are compared by tag and position only, never entered.) */
+const HTML_PARENT_ATTR = "data-og-html";
+const REGION = "ogygia-region";
+const SLOT = "ogygia-slot";
+/** The app declared this subtree the live DOM's own: a plain element carrying `data-ogygia-keep` or
+*  `data-persist` (on a region, keep names a navigation-surviving island instead — not foreign). */
+function is_declared_foreign(el) {
+	return el.localName !== REGION && (el.hasAttribute("data-ogygia-keep") || el.hasAttribute("data-persist"));
+}
+/** A region whose subtree Svelte's reactivity owns (hydrated), or a kept island (it survives a
+*  navigation untouched) — matched by a morph, never entered. `data-hydrated` is only ever set on
+*  hyphenated roots, so its probe sits behind a cheap hyphen test. */
+function is_region_owned(el) {
+	const name = el.localName;
+	if (!name.includes("-")) return false;
+	if (el.hasAttribute("data-hydrated")) return true;
+	return name === REGION && el.hasAttribute("data-ogygia-keep");
+}
+/**
+* Who owns `el`. First match wins: `foreign` (declared) → `region` → `page` → `static` → `walk`.
+* `foreign` outranks `region` for plain elements only (a region never answers `foreign`), so a kept
+* island is `region` and a kept widget is `foreign`.
+*/
+function owner_of(el) {
+	if (is_declared_foreign(el)) return "foreign";
+	if (is_region_owned(el)) return "region";
+	if (el.localName === SLOT) return "page";
+	if (el.hasAttribute("data-og-opaque") || el.parentElement?.hasAttribute("data-og-html")) return "static";
+	return "walk";
+}
+/** True when Svelte's hydration walk binds `el`'s CHILDREN by position — the only subtrees the drift
+*  check and the repair keep in the server's shape. */
+function walk_enters(el) {
+	return owner_of(el) === "walk";
+}
+/**
+* An UPGRADED CUSTOM ELEMENT: a live web component whose own runtime owns its host. Detected
+* STRUCTURALLY — a hyphenated name with a shadow root or a registered definition — never by a
+* library-specific attribute. The ONE detection every writer uses (the morph's attribute skip and
+* self-owned children, the repair's conflict report).
+*/
+function is_upgraded_ce(el) {
+	const name = el.localName;
+	if (!name.includes("-")) return false;
+	if (el.shadowRoot) return true;
+	return typeof customElements !== "undefined" && customElements.get(name) !== void 0;
+}
+/**
+* An element whose CHILDREN are partly its own doing, not the render's: an upgraded custom element
+* (it slots / rewrites its light DOM), or a `<dialog>` / `<details>` whose `open` the browser flips.
+* A child it gave itself is `foreign` content inside a `walk`-owned element: the live morph keeps it;
+* the repair removes it only where Svelte's walk needs the position (and reports the conflict).
+*/
+function is_self_owned(el) {
+	const name = el.localName;
+	return name === "dialog" || name === "details" || is_upgraded_ce(el);
+}
+/** Who writes an element's attributes: its own runtime (an upgraded custom element's host), Svelte's
+*  reactivity (a hydrated region root — but see {@link REGION_RENDER_ATTRS}), or the render. */
+function attributes_writer(el) {
+	if (el.localName === REGION || is_region_owned(el)) return "region";
+	return is_upgraded_ce(el) ? "element" : "render";
+}
+/** The attributes of a region root that stay the render's: its ADDRESS, which the render that minted
+*  it writes (a re-minted hole fetches its new answer there); its content is its answer's. */
+const REGION_RENDER_ATTRS = ["endpoint"];
+/** Who orders an element's children: the render (positions are its sequence), or the element itself
+*  (a self-owned element relocates and wraps its light DOM — positions are not the render's). */
+function order_owner(el) {
+	if (el.localName === REGION) return el.hasAttribute("data-og-baked") ? "element" : "render";
+	return is_self_owned(el) ? "element" : "render";
+}
+/**
+* Does a self-owned element SLOT its light DOM — show it through a shadow root's `<slot>`s, in
+* document order — rather than render it itself? Then it has no reason to move a child: the children
+* are partly its own (it may add some), but the RENDER's nodes keep the render's order (morph.ts
+* `reconcile_by_identity`). One with no shadow root may relocate and wrap them: its arrangement stands.
+* (a closed shadow root is invisible here: such an element is taken to arrange, the safe side)
+*/
+function slots_light_dom(el) {
+	return el.shadowRoot !== null && is_upgraded_ce(el);
+}
+/** A live region whose first HTML was baked into the page by Svelte's `{@html}` (Region.svelte,
+*  PromiseRegionAwait): kept for the element's life — Svelte's block anchors stay among its children. */
+const BAKED_ATTR = "data-og-baked";
+/** The nodes ogygia placed under an element-ordered parent (a morph's claim or insertion, the restore
+*  putting Svelte's children back into a planned host). One per document across bundles: the inlined
+*  restorer fills the same set (`window.__og_rendered`). */
+function rendered() {
+	const w = globalThis;
+	return w.__og_rendered ??= /* @__PURE__ */ new WeakSet();
+}
+/** Record that the render placed `node` (it may remove it once the render stops producing it). */
+function mark_render_made(node) {
+	rendered().add(node);
+}
+/**
+* Does `node`, a child of an element-ordered parent, EXIST by the render's doing? Marked by ogygia, or
+* structurally: an `<ogygia-region>` is always render output, and an element whose tag the render
+* produces at this level (`render_tags`) is render output — a runtime does not make the render's
+* elements. Anything else is the element's own: never matched, never removed.
+*/
+function render_made(node, render_tags) {
+	if (rendered().has(node)) return true;
+	if (node.nodeType !== 1) return false;
+	const name = node.localName;
+	return name === REGION || render_tags.has(name);
+}
+export { BAKED_ATTR, HTML_PARENT_ATTR, OPAQUE_ATTR, REGION_RENDER_ATTRS, attributes_writer, is_declared_foreign, is_region_owned, is_self_owned, is_upgraded_ce, mark_render_made, order_owner, owner_of, render_made, slots_light_dom, walk_enters };

package/dist/runtime/page-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bounded SPA HTML cache: TTL + max entries + approximate byte budget.
+ * Expired entries are dropped on read/insert; overflow drops oldest by timestamp.
+ */
+export type PageCacheEntry = {
+  html: string;
+  t: number;
+  bytes: number;
+};
+export declare class PageCache {
+  #private;
+  constructor(opts?: {
+    ttlMs?: number;
+    maxEntries?: number;
+    maxBytes?: number;
+  });
+  get(href: string): string | null;
+  set(href: string, html: string): void;
+  delete(href: string): void;
+  clear(): void;
+  get size(): number;
+  get bytes(): number;
+}

package/dist/runtime/page-cache.js

@@ -0,0 +1,74 @@
+// src/runtime/page-cache.ts
+var PageCache = class {
+	#map = /* @__PURE__ */ new Map();
+	#total_bytes = 0;
+	#ttlMs;
+	#maxEntries;
+	#maxBytes;
+	constructor(opts) {
+		this.#ttlMs = opts?.ttlMs ?? 8e3;
+		this.#maxEntries = opts?.maxEntries ?? 32;
+		this.#maxBytes = opts?.maxBytes ?? 4e6;
+	}
+	#drop(href) {
+		const e = this.#map.get(href);
+		if (!e) return;
+		this.#map.delete(href);
+		this.#total_bytes -= e.bytes;
+	}
+	#evict_expired(now) {
+		for (const [href, e] of this.#map) if (now - e.t >= this.#ttlMs) this.#drop(href);
+	}
+	#evict_overflow() {
+		while (this.#map.size > this.#maxEntries || this.#total_bytes > this.#maxBytes) {
+			let oldest_href = null;
+			let oldest_t = Infinity;
+			for (const [href, e] of this.#map) if (e.t < oldest_t) {
+				oldest_t = e.t;
+				oldest_href = href;
+			}
+			if (!oldest_href) break;
+			this.#drop(oldest_href);
+		}
+	}
+	get(href) {
+		const now = Date.now();
+		const e = this.#map.get(href);
+		if (!e) return null;
+		if (now - e.t >= this.#ttlMs) {
+			this.#drop(href);
+			return null;
+		}
+		this.#map.delete(href);
+		e.t = now;
+		this.#map.set(href, e);
+		return e.html;
+	}
+	set(href, html) {
+		const now = Date.now();
+		this.#evict_expired(now);
+		this.#drop(href);
+		const bytes = html.length * 2;
+		this.#map.set(href, {
+			html,
+			t: now,
+			bytes
+		});
+		this.#total_bytes += bytes;
+		this.#evict_overflow();
+	}
+	delete(href) {
+		this.#drop(href);
+	}
+	clear() {
+		this.#map.clear();
+		this.#total_bytes = 0;
+	}
+	get size() {
+		return this.#map.size;
+	}
+	get bytes() {
+		return this.#total_bytes;
+	}
+};
+export { PageCache };

package/dist/runtime/page-defer.d.ts

@@ -0,0 +1,14 @@
+import { PAGE_DEFER_BOOTSTRAP } from "../page-defer.js";
+/** Reviver: a defer marker `[id]` becomes a real Promise, pending until its resolve script lands (or
+ *  already-resolved if the resolve raced ahead of the seed). */
+export declare function create_deferred(id: number): Promise<unknown>;
+/** Install the live resolver (which parses the encoded value) and drain anything the inline bootstrap
+ *  queued before the runtime loaded. `extra_revivers` are the app's transport decoders (custom types in
+ *  a streamed value). Idempotent — safe to call on every boot; the first call's revivers win. */
+export declare function install_page_defer(extra_revivers?: Record<string, (payload: never) => unknown>): void;
+/** devalue reviver map for the page seed. A DEFER marker becomes a pending Promise (streaming path); a
+ *  SETTLED marker becomes an already resolved/rejected Promise (non-navigate path). Both keep
+ *  `page.data.x` a Promise, so `{#await}` works identically regardless of how the page was requested.
+ *  `extra` merges the app's transport decoders; ogygia's own keys always win on any name clash. */
+export declare function page_defer_revivers(extra?: Record<string, (payload: never) => unknown>): Record<string, (payload: never) => unknown>;
+export { PAGE_DEFER_BOOTSTRAP };