@ogygia/core 0.0.0 → 0.11.1

package/dist/runtime/router.js

@@ -0,0 +1,593 @@
+import { kit_hydrates_page } from "./kit-boot.js";
+import { slots } from "./slots.js";
+import { publish_nav } from "./nav-handle.js";
+import { nearest_attr } from "./nearest-attr.js";
+// src/runtime/router.ts
+/**
+* Minimal SPA router for ogygia (Astro's ClientRouter equivalent).
+*
+* Intercepts same-origin <a> clicks, fetches the target page, swaps <body>,
+* merges <head>, and updates history. `data-ogygia-keep` keeps matching chrome.
+* Islands on the new page auto-initialise via custom-element connection; old ones
+* auto-unmount via disconnection (except inside persisted subtrees).
+*
+* This module is the router's BOOT half — the listeners, the lifecycle hooks, the link-preload
+* policy, and the pure helpers — and it stays small: the navigation itself (fetch + cache, head
+* merge, body reconcile, seeds, a11y) is ./router-nav.ts, loaded on the first prefetch or
+* intercepted click. A visitor who never leaves the page never downloads it.
+*/
+const WS = /\s+/;
+/**
+* The `<a>` a pointer event is about — through SHADOW ROOTS. A click inside a web component's
+* shadow tree (a web component such as `<x-link>`, `<x-button href>`, a breadcrumb item)
+* reaches the document with `event.target` retargeted to the host, so `target.closest('a')` finds
+* nothing and the browser navigates natively — a full reload instead of a body swap. The composed
+* path still holds the real anchor; Kit's own router reads it the same way.
+*/
+function anchor_of(event) {
+	const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+	for (const n of path) if (n instanceof Element && n.tagName === "A") return n;
+	const t = event.target;
+	return t instanceof Element ? t.closest("a") : null;
+}
+/**
+* The anchor a HOVER is about, cheaply: `mouseover` fires for every element the pointer crosses,
+* so the common case — not over a link at all — must cost one `closest('a')` and nothing else.
+* Only when the retargeted `target` is a shadow HOST (the anchor may be inside its shadow tree)
+* is the composed path read.
+*/
+function hovered_anchor(event) {
+	const t = event.target;
+	if (!(t instanceof Element)) return null;
+	const a = t.closest("a");
+	if (a) return a;
+	return t.shadowRoot ? anchor_of(event) : null;
+}
+const native_push = typeof History !== "undefined" ? History.prototype.pushState : null;
+const native_replace = typeof History !== "undefined" ? History.prototype.replaceState : null;
+const push_state = (state, url) => (native_push ?? history.pushState).call(history, state, "", url);
+const replace_state = (state, url) => {
+	const fn = native_replace ?? history.replaceState;
+	return url === void 0 ? fn.call(history, state, "") : fn.call(history, state, "", url);
+};
+const PRELOAD_RANK = {
+	eager: 0,
+	viewport: 1,
+	hover: 2,
+	tap: 3,
+	off: 4,
+	false: 4
+};
+/** Anchors that can carry a preload policy at all — under (or on) a marked element. The post-nav
+*  scan reads only these; an unmarked anchor has no trigger and was a wasted rank computation. */
+const PRELOAD_MARKED_ANCHORS = "[data-sveltekit-preload-data] a[href], [data-sveltekit-preload-code] a[href], a[href][data-sveltekit-preload-data], a[href][data-sveltekit-preload-code]";
+/** Does the page hold an element the fragment points at? `#top` and an empty `#` mean "the top",
+*  which the browser handles. A fragment that matches nothing is an app-managed one (a table row
+*  keyed by the hash): the browser would scroll to the top for it, so the router takes it over. */
+function hash_target_exists(hash) {
+	if (!hash || hash === "#") return true;
+	const raw = hash.slice(1);
+	let dec = raw;
+	try {
+		dec = decodeURIComponent(raw);
+	} catch {}
+	if (raw === "top" || dec === "top") return true;
+	return !!(document.getElementById(dec) || document.getElementById(raw) || document.getElementsByName(dec).length);
+}
+/** Same document = pathname + search. Hash is not part of document identity. */
+function same_document(a, b) {
+	return a.pathname === b.pathname && a.search === b.search;
+}
+/**
+* Kit's `data-sveltekit-reload` grammar, nearest ancestor wins (Kit walks up from the anchor and
+* takes the first element that carries the attribute): `""` / `"true"` = full-page load, `"off"` /
+* `"false"` = SPA navigation — so a layout can opt a whole subtree OUT of the SPA and a child
+* subtree can opt back IN. Presence alone used to force a reload, which turned a
+* `data-sveltekit-reload="false"` subtree (an app's way of saying "SPA here") into full loads.
+* Across shadow roots: a link a web component renders in its own shadow tree sits under the page's
+* markup all the same (a card's link in a full-load subtree was swapped in place).
+*/
+function reload_opt_out(anchor) {
+	const v = nearest_attr(anchor, "data-sveltekit-reload");
+	return v !== null && v !== "off" && v !== "false";
+}
+/**
+* What a click on a link to the CURRENT document means. `hash`: a fragment jump — the browser's.
+* `swallow`: the navigation to this exact address is already in flight — a web-component link
+* (`<x-link>`, `<x-button href>`) handles the click itself and re-dispatches one on
+* its inner anchor; the router pushed the URL for the first click, so the second one looks like a
+* link to the current page — left to the browser it would RELOAD the document mid-swap. `refresh`:
+* a real click on a link to the page one is on — re-render in place (Kit re-runs the navigation
+* too; a full reload is never the answer for a same-origin link).
+*/
+function same_document_link(url, current, in_flight) {
+	if (url.hash && url.href !== current.href) return "hash";
+	if (in_flight === url.href) return "swallow";
+	return "refresh";
+}
+function document_key(url) {
+	return url.pathname + url.search;
+}
+/** Instant scroll to a hash target (or top). Ignores CSS `scroll-behavior: smooth`. */
+function jump_to_hash(hash) {
+	const html_el = document.documentElement;
+	const prev = html_el.style.scrollBehavior;
+	html_el.style.scrollBehavior = "auto";
+	try {
+		if (hash) {
+			let id;
+			try {
+				id = decodeURIComponent(hash.startsWith("#") ? hash.slice(1) : hash);
+			} catch {
+				id = hash.startsWith("#") ? hash.slice(1) : hash;
+			}
+			const el = document.getElementById(id);
+			if (el) {
+				el.scrollIntoView();
+				return;
+			}
+		}
+		window.scrollTo(0, 0);
+	} finally {
+		html_el.style.scrollBehavior = prev;
+	}
+}
+/** Run `fn` when the browser is idle (bounded), else soon. */
+function on_idle(fn, timeout = 1e3) {
+	if (typeof requestIdleCallback === "function") requestIdleCallback(fn, { timeout });
+	else setTimeout(fn, 50);
+}
+let nav_promise = null;
+let loaded_nav = null;
+function nav() {
+	slots.router_link ??= {
+		document_key,
+		jump_to_hash,
+		push_state,
+		replace_state
+	};
+	if (!nav_promise) nav_promise = import("./router-nav.js").then((m) => loaded_nav = m, (err) => {
+		nav_promise = null;
+		throw err;
+	});
+	return nav_promise;
+}
+var SpaRouter = class {
+	#started = false;
+	#before_hooks = /* @__PURE__ */ new Set();
+	#after_hooks = /* @__PURE__ */ new Set();
+	/** href of the navigation in flight (set before the fetch, cleared when applied or aborted) */
+	nav_target = null;
+	/** The in-flight navigation's cancel handle: router-nav bumps `nav_gen` and sets `nav_abort` for
+	*  each navigation it starts, and stops at its next step once `nav_gen` moved on. */
+	nav_gen = 0;
+	nav_abort = null;
+	#viewport_io = null;
+	#viewport_seen = /* @__PURE__ */ new WeakSet();
+	/** pathname+search of the document currently in the DOM (hash ignored). */
+	doc_key = "";
+	/**
+	* Full URL of the document currently displayed in the DOM. `navigate()` uses this as its `from`
+	* instead of `location.href`, because on a `popstate` (back/forward) the browser has ALREADY
+	* changed `location` to the target — so `location.href` would equal the target and the
+	* same-document guard would wrongly bail into the hash-only branch, never swapping the body
+	* (browser back left the old page's DOM in place). POP-FROM.
+	*/
+	current_url = null;
+	beforeNavigate(fn) {
+		this.#before_hooks.add(fn);
+		return () => this.#before_hooks.delete(fn);
+	}
+	afterNavigate(fn) {
+		this.#after_hooks.add(fn);
+		try {
+			fn({
+				from: null,
+				to: this.#build_nav_target(new URL(location.href)),
+				type: "enter",
+				willUnload: false
+			});
+		} catch {}
+		return () => this.#after_hooks.delete(fn);
+	}
+	/**
+	* Keep the document in the DOM: the navigation in flight (if any) never swaps. The document key
+	* moves only when a swap commits, so every "same document" decision is about the page still on
+	* screen — and one made while the next page loads (back to this page, a link to it) must cancel
+	* that load, or it lands under this page's address (back pressed before `/plain` finished
+	* swapping left the URL on the old page and `/plain` in the DOM).
+	*/
+	supersede() {
+		if (this.nav_target === null && this.nav_abort === null) return;
+		this.nav_gen++;
+		this.nav_abort?.abort();
+		this.nav_abort = null;
+		this.nav_target = null;
+	}
+	bust_page_cache() {
+		loaded_nav?.bust_page_cache();
+	}
+	_page_cache_size() {
+		return loaded_nav?.page_cache_size() ?? 0;
+	}
+	fetch_page(href, signal, purpose) {
+		return nav().then((n) => n.fetch_page(href, signal, purpose));
+	}
+	async navigate(url, opts = {}) {
+		const { push = true, type = "link", replace = false } = opts;
+		const from = this.current_url ?? new URL(location.href);
+		if (same_document(url, from) && !replace) {
+			if (!this.run_before(from, url, type)) return;
+			this.supersede();
+			if (push && url.href !== location.href) push_state({
+				...history.state,
+				ogygia: true
+			}, url.href);
+			else if (url.href !== location.href) replace_state({
+				...history.state,
+				ogygia: true
+			}, url.href);
+			jump_to_hash(url.hash);
+			this.current_url = url;
+			this.run_after(from, url, type);
+			return;
+		}
+		this.nav_target = url.href;
+		const gen = this.nav_gen;
+		let n;
+		try {
+			n = await nav();
+		} catch {
+			if (this.nav_target === url.href) this.nav_target = null;
+			location.href = url.href;
+			return;
+		}
+		if (gen !== this.nav_gen) return;
+		return n.navigate(this, url, from, opts);
+	}
+	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) {
+			if (opts.external) {
+				location.assign(target.href);
+				return Promise.resolve();
+			}
+			throw new Error("[ogygia] goto() only supports same-origin URLs (pass { external: true } to leave)");
+		}
+		return this.navigate(target, {
+			push: !opts.replaceState,
+			replace: false,
+			type: "goto"
+		});
+	}
+	invalidateAll() {
+		return nav().then((n) => n.invalidate_all());
+	}
+	invalidate() {
+		return this.invalidateAll();
+	}
+	preloadData(url) {
+		const target = new URL(url, location.href);
+		if (target.origin !== location.origin) return Promise.resolve({
+			type: "loaded",
+			status: 200,
+			data: {}
+		});
+		this.fetch_page(target.href, void 0, "prefetch");
+		return Promise.resolve({
+			type: "loaded",
+			status: 200,
+			data: {}
+		});
+	}
+	preloadCode() {
+		return Promise.resolve();
+	}
+	disableScrollHandling() {
+		if (typeof console !== "undefined") console.warn("[ogygia] disableScrollHandling() is a no-op in the islands SPA router.");
+	}
+	pushState() {
+		console.warn("[ogygia] pushState() shallow routing is not supported; use goto().");
+	}
+	replaceState() {
+		console.warn("[ogygia] replaceState() shallow routing is not supported; use goto().");
+	}
+	start() {
+		if (this.#started || typeof document === "undefined") return;
+		if (!document.querySelector("meta[name=\"ogygia-router\"]")) return;
+		if (kit_hydrates_page()) return;
+		this.#started = true;
+		this.doc_key = document_key(new URL(location.href));
+		this.current_url = new URL(location.href);
+		document.addEventListener("click", (event) => {
+			const anchor = anchor_of(event);
+			const url = this.#should_intercept(event, anchor);
+			if (!url) return;
+			if (this.nav_target === url.href) {
+				event.preventDefault();
+				return;
+			}
+			if (same_document(url, new URL(location.href))) {
+				const kind = same_document_link(url, new URL(location.href), this.nav_target);
+				if (kind === "hash") {
+					if (!hash_target_exists(url.hash)) {
+						event.preventDefault();
+						if (location.hash !== url.hash) {
+							push_state(history.state || {}, url.href);
+							window.dispatchEvent(new HashChangeEvent("hashchange", {
+								oldURL: location.href,
+								newURL: url.href
+							}));
+						}
+					}
+					return;
+				}
+				event.preventDefault();
+				if (kind === "refresh") this.navigate(url, {
+					push: false,
+					replace: true
+				});
+				return;
+			}
+			event.preventDefault();
+			this.navigate(url, { push: true });
+		});
+		this.#install_prefetch();
+		window.addEventListener("popstate", () => {
+			const url = new URL(location.href);
+			if (document_key(url) === this.doc_key) {
+				this.supersede();
+				jump_to_hash(url.hash);
+				return;
+			}
+			const pop_scroll = history.state?.scroll || null;
+			this.navigate(url, {
+				push: false,
+				pop_scroll,
+				type: "popstate"
+			});
+		});
+		replace_state({
+			...history.state,
+			ogygia: true
+		});
+	}
+	#should_intercept(event, anchor) {
+		if (event.defaultPrevented) return false;
+		if (event.button !== 0) return false;
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+		if (!anchor || !anchor.href) return false;
+		if (anchor.target && anchor.target !== "_self") return false;
+		if (anchor.hasAttribute("download")) return false;
+		if (anchor.hasAttribute("data-no-spa")) return false;
+		if (reload_opt_out(anchor)) return false;
+		if ((anchor.getAttribute("rel") || "").split(WS).includes("external")) return false;
+		const url = new URL(anchor.href);
+		if (url.origin !== location.origin) return false;
+		return url;
+	}
+	run_before(from, to, type) {
+		let cancelled = false;
+		const nav = {
+			from: this.#build_nav_target(from),
+			to: this.#build_nav_target(to),
+			type,
+			cancel: () => cancelled = true,
+			willUnload: false
+		};
+		for (const fn of this.#before_hooks) try {
+			fn(nav);
+		} catch {}
+		return !cancelled;
+	}
+	run_after(from, to, type) {
+		for (const fn of this.#after_hooks) try {
+			fn({
+				from: this.#build_nav_target(from),
+				to: this.#build_nav_target(to),
+				type,
+				willUnload: false
+			});
+		} catch {}
+	}
+	#install_prefetch() {
+		document.addEventListener("mouseover", (event) => {
+			const anchor = hovered_anchor(event);
+			if (anchor && this.#preload_rank(anchor) <= PRELOAD_RANK.hover) this.#warm_anchor(anchor);
+		}, { passive: true });
+		const on_press = (event) => {
+			const anchor = anchor_of(event);
+			if (anchor && this.#preload_rank(anchor) <= PRELOAD_RANK.tap) this.#warm_anchor(anchor);
+		};
+		document.addEventListener("mousedown", on_press, { passive: true });
+		document.addEventListener("touchstart", on_press, { passive: true });
+		this.scan_preload_links();
+	}
+	/** After start + every navigation: drop detached IO targets, then re-observe the live body. */
+	#reset_viewport_io() {
+		this.#viewport_io?.disconnect();
+		this.#viewport_seen = /* @__PURE__ */ new WeakSet();
+		this.#viewport_io = new IntersectionObserver((entries) => {
+			for (const e of entries) if (e.isIntersecting) {
+				this.#viewport_io.unobserve(e.target);
+				this.#warm_anchor(e.target);
+			}
+		}, { rootMargin: "0px" });
+	}
+	/**
+	* After start + every navigation, in IDLE: eager links warm now; viewport links get observed.
+	* Only anchors under a preload-marked element are read — an unmarked anchor has no trigger. Idle,
+	* because the scan competes with the freshly swapped page's own islands for the main thread and
+	* a warm is speculation by definition.
+	*/
+	scan_preload_links() {
+		on_idle(() => {
+			this.#reset_viewport_io();
+			if (!this.#viewport_io) return;
+			for (const anchor of Array.from(document.querySelectorAll(PRELOAD_MARKED_ANCHORS))) {
+				const rank = this.#preload_rank(anchor);
+				if (rank === PRELOAD_RANK.eager) this.#warm_anchor(anchor);
+				else if (rank === PRELOAD_RANK.viewport && !this.#viewport_seen.has(anchor)) {
+					this.#viewport_seen.add(anchor);
+					this.#viewport_io.observe(anchor);
+				}
+			}
+		});
+	}
+	/** Warm the page-HTML cache for an anchor if it's a same-origin SPA target. */
+	#warm_anchor(anchor) {
+		const url = this.#should_intercept({
+			button: 0,
+			defaultPrevented: false
+		}, anchor);
+		if (!url) return;
+		if (same_document(url, new URL(location.href))) return;
+		if (url.href !== location.href) this.fetch_page(url.href, void 0, "prefetch");
+	}
+	/** Rank of the most-eager preload trigger that applies to `anchor` (5 = none). */
+	#preload_rank(anchor) {
+		let rank = 5;
+		const d = this.#preload_attr(anchor, "data-sveltekit-preload-data");
+		const c = this.#preload_attr(anchor, "data-sveltekit-preload-code");
+		if (d != null) rank = Math.min(rank, PRELOAD_RANK[d] ?? 5);
+		if (c != null) rank = Math.min(rank, PRELOAD_RANK[c] ?? 5);
+		return rank;
+	}
+	/** Nearest-ancestor value of `name` (Kit inheritance); empty value -> 'hover'. null if unset. */
+	#preload_attr(el, name) {
+		const holder = el.closest("[" + name + "]");
+		if (!holder) return null;
+		const v = holder.getAttribute(name);
+		return v === "" || v == null ? "hover" : v;
+	}
+	#build_nav_target(url) {
+		return {
+			url,
+			params: {},
+			route: { id: null }
+		};
+	}
+};
+const spa = new SpaRouter();
+/**
+* Register a callback before a client-side navigation.
+* Call `nav.cancel()` to abort. Returns an unsubscribe function. Inside a component, prefer the
+* `$app/navigation` / `ogygia/app` export, which unsubscribes on destroy.
+*/
+function beforeNavigate(fn) {
+	return spa.beforeNavigate(fn);
+}
+/**
+* Register a callback after a successful client-side navigation.
+* Returns an unsubscribe function. Inside a component, prefer the `$app/navigation` /
+* `ogygia/app` export, which unsubscribes on destroy.
+*/
+function afterNavigate(fn) {
+	return spa.afterNavigate(fn);
+}
+/** Drop all warmed page HTML (call after mutations / auth changes). */
+function bust_page_cache() {
+	spa.bust_page_cache();
+}
+/** Test helper — current warmed entry count. */
+function _page_cache_size() {
+	return spa._page_cache_size();
+}
+/**
+* Programmatic same-origin navigation. Mirrors Kit's `goto()` subset.
+* @param url - Absolute or relative URL (http(s) only).
+* @param opts.replaceState - Replace the current history entry instead of pushing.
+*/
+function goto(url, opts = {}) {
+	return spa.goto(url, opts);
+}
+/**
+* Soft-refresh the current URL's document seeds + head (not a navigation).
+* Busts the SPA HTML cache so the next real route change is fresh. Coarser than
+* Kit's dependency-scoped invalidate — see `invalidate_all` in ./router-nav.ts.
+*/
+function invalidateAll() {
+	return spa.invalidateAll();
+}
+/**
+* Refresh navigation data. Without Kit's client we cannot invalidate a single
+* dependency, so this refreshes everything (same as {@link invalidateAll}).
+*/
+function invalidate() {
+	return spa.invalidate();
+}
+/**
+* Warm the next page: fetch it into the swap-readable HTML cache (+ its island modules) — this is
+* what makes the eventual click instant, and no browser cache can feed a body swap. (Router OFF —
+* the browser owns navigation — is the MPA navigation handle's Speculation Rules hint, not this
+* module: ./nav-handle.ts. This module only loads with the router feature.)
+*/
+function preloadData(url) {
+	return spa.preloadData(url);
+}
+/** No-op with the router on: page “code” arrives with the HTML body swap (+ island chunks on
+*  connect). Router OFF is the MPA navigation handle's prefetch hint (./nav-handle.ts). */
+function preloadCode(_url) {
+	return spa.preloadCode();
+}
+/** Skip scroll restoration / scroll-to-top on the next client-side navigation. */
+function disableScrollHandling() {
+	spa.disableScrollHandling();
+}
+/**
+* Shallow routing is not supported without Kit's client runtime.
+* @throws Always — use full navigations instead.
+*/
+function pushState() {
+	spa.pushState();
+}
+/**
+* Shallow routing is not supported without Kit's client runtime.
+* @throws Always — use full navigations instead.
+*/
+function replaceState() {
+	spa.replaceState();
+}
+/**
+* Install click/popstate listeners and start SPA navigation.
+* Invoked by the runtime once the module loads (handle-injected on every ogygia page, or by an island).
+* @internal
+*/
+function startRouter() {
+	spa.start();
+}
+/**
+* Feature entry: start the SPA router once the DOM is ready, but only when the page carries
+* `<meta name="ogygia-router">` (the handle injects it globally unless `ogygia({ router: false })`)
+* and Kit is not already booting it.
+*/
+function install() {
+	if (typeof document === "undefined") return;
+	slots.nav = {
+		goto,
+		invalidateAll
+	};
+	publish_nav({
+		goto,
+		invalidate,
+		invalidateAll,
+		preloadData,
+		preloadCode,
+		disableScrollHandling,
+		pushState,
+		replaceState,
+		beforeNavigate,
+		afterNavigate,
+		bust_page_cache
+	});
+	const start = () => {
+		if (!document.querySelector("meta[name=\"ogygia-router\"]")) return;
+		if (kit_hydrates_page()) return;
+		startRouter();
+		document.dispatchEvent(new Event("og:page-load"));
+	};
+	if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start, { once: true });
+	else start();
+}
+export { SpaRouter, _page_cache_size, afterNavigate, anchor_of, beforeNavigate, bust_page_cache, disableScrollHandling, document_key, goto, install, invalidate, invalidateAll, jump_to_hash, preloadCode, preloadData, pushState, push_state, reload_opt_out, replaceState, replace_state, same_document, same_document_link, startRouter };

package/dist/runtime/schedule.d.ts

@@ -0,0 +1,49 @@
+export declare function yield_task(): Promise<void>;
+/**
+ * Run `fn` at background priority, off the current task: `scheduler.postTask` at 'background' where
+ * it exists, else a macrotask. This orders MAIN-THREAD work only — it lets a pending render or input
+ * task go first. It does not hold back the network: while the page's resources download the main
+ * thread is idle, so a background task runs at once and an `import()` it starts competes with them.
+ * Holding island code back until the page has painted is `after_document_painted`'s job.
+ */
+export declare function background_start(fn: () => void): void;
+/**
+ * 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
+ * script, so never before DOMContentLoaded), and an island's wake starts no earlier: the runtime
+ * boots from a module script that runs BEFORE DOMContentLoaded — the app's other deferred scripts
+ * may still be executing and the first paint (and its LCP image) not yet happened — and an island
+ * `import()` started there takes bandwidth from both.
+ *
+ * `readyState` cannot tell "DOMContentLoaded fired" from "about to fire" (it reads `interactive` for
+ * both), so the navigation timing entry decides; `load` backs up the listener where there is none.
+ * A hidden document paints no frame (`requestAnimationFrame` never fires there) — nothing to protect,
+ * 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>;
+/** 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.
+ */
+export declare function register_region(el: Element): 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
+ * the element was re-attached meanwhile, runs — exactly what an un-scheduled wait would have done).
+ */
+export declare function unregister_region(el: Element): void;
+/** The island's module is in flight: a viewport island here holds ready islands below the fold. */
+export declare function hydrate_started(el: Element): void;
+/** The hydrate attempt is over (turn taken, or it never got there — no entry, a failed import). */
+export declare function hydrate_settled(el: Element): void;
+/**
+ * Wait for this region's turn. Resolves in a task of its own, after every region ahead of it in
+ * priority has had its task. Call it when the island can hydrate right now (module loaded) — the
+ * continuation after the `await` IS the turn: keep the whole synchronous hydrate step in it.
+ */
+export declare function hydrate_turn(el: Element): Promise<void>;
+/** Test seam: is a hydration turn queued or being drained right now? */
+export declare function schedule_idle(): boolean;