@ogygia/core 0.12.2 → 0.13.0

package/dist/runtime/hydrate-core.js

@@ -1,19 +1,21 @@
 import { set_current_region, set_foreign_hydrate } from "../current-region.js";
 import { capture_region_ids } from "./region-ids.js";
+import { nested_context } from "../nested.js";
 import { foreign_region_prop_revivers } from "./foreign-props.js";
 import { SEED_REF_KEY, seed_ref_reviver } from "../seed-ref-reviver.js";
 import { parse_sidecar_text } from "./wire-format.js";
 import { is_deferred, ours_on_kit_document, region_ssr_truncated } from "./region-attrs.js";
 import { boot_link, slots } from "./slots.js";
+import { report_thrown } from "../report-thrown.js";
 import { keep_host_classes, note_host_classes } from "./host-classes.js";
 import { emit } from "../events/bus.js";
+import { warn } from "../messages/lazy.js";
 import { hydrate, unmount } from "svelte";
-import NestedProvider from "../NestedProvider.svelte";
 import { install } from "virtual:ogygia/hydrate-features";
 // src/runtime/hydrate-core.ts
 /**
 * THE HYDRATE CORE — everything an island needs only at the moment it hydrates: Svelte's
-* `hydrate`/`unmount`, the `NestedProvider` host, the devalue props parse, the page seed, the
+* `hydrate`/`unmount`, the "inside an island" context, the devalue props parse, the page seed, the
 * DEV props guard. Loaded LAZILY by the region element on its first `#hydrate` (one dynamic
 * import, shared by every island), so a page whose islands all wake on `visible` or `interaction`
 * boots the runtime WITHOUT fetching Svelte's client runtime — that arrives with the first island
@@ -25,7 +27,7 @@ import { install } from "virtual:ogygia/hydrate-features";
 */
 const seed_page_once = () => slots.page?.seed_page_once();
 const seed_remote_once = () => slots.remoteSeeds?.seed_once();
-const kit_page_thread = () => slots.page?.kit_page_thread() ?? null;
+const kit_page_thread = (signal) => slots.page?.kit_page_thread(signal) ?? null;
 install();
 const kit_hydrates_page = () => boot_link().kit_hydrates_page();
 const props_sidecar_of = (region) => boot_link().props_sidecar_of(region);
@@ -35,14 +37,30 @@ const is_self_owned = (el) => boot_link().is_self_owned(el);
 const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
 /** The morph target for hydration repair: the server sequence Svelte's walk binds — see `repair_markup`. */
 const REPAIR_MORPH = { target: "walk" };
-/** The hydration ENVELOPE: `hydrate()` anchors on a top-level `<!--[-->` comment and then expects
-*  the component's OWN region envelope — but embedded SSR (Region.svelte) emits only the inner
-*  layer. Idempotent: the second attempt after a failed first one finds it in place. */
+/** The hydration ENVELOPE: `hydrate()` anchors on a top-level `<!--[-->` comment, then walks the
+*  component's own nodes. Every server shape carries it — a placed island's dynamic-component pair
+*  (Region.svelte), `render()`'s root pair (a hole's answer, a live region) — so this only adds one
+*  to markup that has none. Idempotent: the second attempt after a failed first one finds it.
+*
+*  A placed island an EARLIER build rendered (a hole's answer from a server still on it, mid rolling
+*  deploy) carries one pair more: its host's `{#if}` branch (`<!--[0-->`) around the component's
+*  pair. That outer pair goes, so the component's own is the envelope and the island is adopted
+*  instead of re-rendered. */
 function ensure_envelope(region) {
 	if (has_envelope(region)) return;
+	const first = region.firstChild;
+	const last = region.lastChild;
+	if (first && last && first !== last && is_comment(first, "[0") && is_comment(first.nextSibling, "[") && is_comment(last, "]")) {
+		first.remove();
+		last.remove();
+		return;
+	}
 	region.insertBefore(document.createComment("["), region.firstChild);
 	region.appendChild(document.createComment("]"));
 }
+function is_comment(node, data) {
+	return !!node && node.nodeType === 8 && node.data === data;
+}
 function has_envelope(region) {
 	const first = region.firstChild;
 	return !!first && first.nodeType === 8 && first.data === "[";
@@ -227,10 +245,11 @@ function describe_divergence(live, want, where = "the island") {
 	}
 	return null;
 }
-/** The first ownership conflict the current repair met (DEV / devtools read it), or `null`. */
+/** The element of the first ownership conflict the current repair met (DEV / devtools read it:
+*  `ownership_conflict`), or `null`. */
 let conflict = null;
 function note_conflict(el) {
-	conflict ??= `${node_label(el)} is a web component that changed its own children in a position Svelte's hydration reads, so the repair had to remove the nodes it added. Render that subtree with {@html} or as static markup (Svelte never reads inside it), put it in a lake (wake: 'none'), or mark the element data-ogygia-keep.`;
+	conflict ??= node_label(el);
 }
 /** Put the island's light DOM back to the server's node sequence when it drifted while the island
 *  slept. Returns whether a repair was made and, in DEV / devtools, WHY it drifted (the first
@@ -311,7 +330,6 @@ function quietly(fn) {
 		console.warn = warn;
 	}
 }
-const HEALED_WARNING = "[ogygia] island \"%s\" was edited while it slept (its light DOM no longer matched the server render — a design-system runtime, an A/B tool, a translator), so its server HTML was put back and hydrated instead of re-rendering it client-side. Whatever the edit added is gone; the script that made it should leave <ogygia-region> subtrees alone.";
 /** Is this entry another build's (fragment federation): absolute, different origin. */
 function is_foreign_entry(entry) {
 	return boot_link().ABSOLUTE_URL_SCHEME.test(entry) && new URL(entry).origin !== location.origin;
@@ -356,7 +374,10 @@ var PropMutationGuard = class {
 		const key = entry + "" + prop_path;
 		if (this.#warned.has(key)) return;
 		this.#warned.add(key);
-		console.warn(`[ogygia] mutating prop '${prop_path}' inside island ${entry} — island props are a serialized snapshot of the host, or a reference into page.data shared with every island that reads it: the write updates nothing (or leaks into page.data). Move mutable state inside the island component.`);
+		warn("prop_mutation", {
+			prop: prop_path,
+			entry
+		});
 	}
 	#guard_map(map, entry, prop_path) {
 		const mutators = /* @__PURE__ */ new Set([
@@ -418,24 +439,23 @@ var PropMutationGuard = class {
 		});
 	}
 	wrap(props, entry) {
-		if (!(import.meta.env && import.meta.env.DEV)) return props;
 		return this.#guard_value(props, entry, "");
 	}
 };
-const prop_guard = new PropMutationGuard();
+const dev_guard = import.meta.env?.DEV ? new PropMutationGuard() : null;
+const prop_guard = { wrap: (props, entry) => dev_guard ? dev_guard.wrap(props, entry) : props };
 /** Svelte's `unmount`, typed for the opaque app this module hands around. */
 const unmount_app = (app) => void unmount(app);
-/** A handle over a mounted Svelte app: dispose unmounts, `set_props` pushes through a host. */
-function handle(app, dispose_with, entry, host) {
+/** A handle over a mounted Svelte app: dispose unmounts, `set_props` pushes into its pushable props. */
+function handle(app, dispose_with, entry, pushed) {
 	const h = { dispose() {
 		try {
 			dispose_with(app);
-		} catch {}
+		} catch (error) {
+			report_thrown(error);
+		}
 	} };
-	if (host) {
-		const live = app;
-		h.set_props = (props) => live.setProps?.(prop_guard.wrap(props, entry));
-	}
+	if (pushed) h.set_props = (props) => pushed.push(prop_guard.wrap(props, entry));
 	return h;
 }
 /**
@@ -452,15 +472,15 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 	const props = capture_region_ids(region, () => read_region_props(region, foreign));
 	if (kit_hydrates_page() && !ours_on_kit_document(region)) {
 		region.setAttribute("data-kit-hydrated", "");
-		if (import.meta.env.DEV) console.warn(`[ogygia] island "${entry}" is on a csr=true page; Kit hydrates it, so the island directive is redundant here (it behaves as a normal component).`);
+		if (import.meta.env.DEV) warn("island_on_kit_page", { entry });
 		return null;
 	}
 	if (!kit_hydrates_page() && !head_markers_neutralized) {
 		head_markers_neutralized = true;
 		neutralize_head_hydration_markers();
 	}
-	if (import.meta.env.DEV && !is_deferred(region) && region_ssr_truncated(region)) console.warn(`[ogygia] island "${entry}" rendered a BLOCK element inline inside a <p> (or other phrasing-only context). The browser's HTML parser hoisted that block out of the paragraph before hydration, so this region is empty and a SECOND copy is about to mount here — the server-rendered copy is now an orphaned sibling of the paragraph. Fix: make the component render an inline element (e.g. <span> instead of <div>), or place the island on its own line (block context) rather than inside a sentence.`);
-	const head_before = new Set(document.head.children);
+	if (import.meta.env.DEV && !is_deferred(region) && region_ssr_truncated(region)) warn("island_block_in_inline", { entry });
+	let head_mark = null;
 	let lifted = slots.lakes.lift(region);
 	const drift = ssr_html !== null && touched && region.isConnected ? repair_if_drifted(region, ssr_html) : {
 		repaired: false,
@@ -469,23 +489,25 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 	};
 	const repaired = drift.repaired;
 	try {
+		head_mark = kit_hydrates_page() ? null : boot_link().runtime_session.mark_head();
 		if (!region.isConnected) return null;
 		const ssr_children = Array.from(region.children);
 		const foreign_delegate = foreign && typeof mod.__og_hydrate === "function";
 		const wrapped = foreign ? props : prop_guard.wrap(props, entry);
-		const KeepHost = slots.keep ?? slots.live;
-		const keep = region.hasAttribute("data-ogygia-keep") && !!KeepHost;
-		if (keep && import.meta.env.DEV && !document.querySelector("meta[name=\"ogygia-router\"]")) console.warn(`[ogygia] island "${entry}" has keep:'${region.getAttribute("data-ogygia-keep")}' but the SPA router is off (ogygia({ router: false })) — keep relies on SPA navigation; a full-page load replaces the DOM, so the attribute is a no-op here.`);
+		const keep = region.hasAttribute("data-ogygia-keep") && !!slots.Pushable;
+		if (keep && import.meta.env.DEV && !document.querySelector("meta[name=\"ogygia-router\"]")) warn("keep_without_router", {
+			entry,
+			key: region.getAttribute("data-ogygia-keep") || ""
+		});
 		/**
 		* ONE hydrate attempt. `recover: false` makes Svelte THROW on a mismatch (`hydration_failed`)
 		* instead of silently discarding the server DOM and re-rendering — that silent path is what
 		* the self-heal below replaces; `recover: true` is that path, the last resort.
 		*
-		* Hydration envelope: `render()` (region endpoint / deferred swap) has BOTH anchor layers —
-		* do not wrap again or hydration mismatches. (Verified against svelte 5.56.) Hydrate through
-		* NestedProvider so descendants see the "inside a hydrated island" context — any nested
-		* island wrapper then degrades to a plain inline component (single hydration with this
-		* parent). The provider adds no DOM, so this matches SSR.
+		* The component itself is hydrated, no host around it: every server shape is the component's
+		* nodes in one anchor pair (see ensure_envelope; a deferred answer carries `render()`'s own, so
+		* it is never wrapped again). Its context marks it "inside a hydrated island", so any nested
+		* island wrapper degrades to a plain inline component (one hydration, with this parent).
 		*/
 		const attempt = (recover) => {
 			if (!is_deferred(region) && !foreign_delegate) ensure_envelope(region);
@@ -496,28 +518,17 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 						origin: new URL(entry).origin,
 						entry
 					});
-					return handle(mod.__og_hydrate(region, wrapped, recover ? void 0 : { recover: false }), mod.__og_unmount ?? (() => {}), entry, false);
+					return handle(mod.__og_hydrate(region, wrapped, recover ? void 0 : { recover: false }), mod.__og_unmount ?? (() => {}), entry, null);
 				}
 				const provided_ctx = capture_region_ids(region, () => slots.context?.(region));
 				const recovery = recover ? {} : { recover: false };
-				if (keep) return handle(hydrate(KeepHost, {
-					target: region,
-					props: {
-						component: Component,
-						initialProps: wrapped
-					},
-					...provided_ctx ? { context: provided_ctx } : {},
-					...recovery
-				}), unmount_app, entry, true);
-				return handle(hydrate(NestedProvider, {
+				const pushed = keep ? new slots.Pushable(wrapped) : null;
+				return handle(hydrate(Component, {
 					target: region,
-					props: {
-						component: Component,
-						props: wrapped
-					},
-					...provided_ctx ? { context: provided_ctx } : {},
+					props: pushed ? pushed.props : wrapped,
+					context: nested_context(provided_ctx),
 					...recovery
-				}), unmount_app, entry, false);
+				}), unmount_app, entry, pushed);
 			} finally {
 				set_current_region(null);
 				set_foreign_hydrate(null);
@@ -544,7 +555,10 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 				fp: region.getAttribute("data-og-fp") || void 0,
 				reason: drift.reason || void 0
 			});
-			if (import.meta.env.DEV) console.warn(HEALED_WARNING + (drift.reason ? `\nWhat drifted: ${drift.reason}` : ""), entry);
+			if (import.meta.env.DEV) warn("island_healed", {
+				entry,
+				drift: drift.reason
+			});
 		}
 		if (drift.conflict) {
 			if (DEVTOOLS) emit({
@@ -554,7 +568,7 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 				fp: region.getAttribute("data-og-fp") || void 0,
 				reason: drift.conflict
 			});
-			if (import.meta.env.DEV) console.warn(`[ogygia] ${drift.conflict}`, entry);
+			if (import.meta.env.DEV) warn("ownership_conflict", { element: drift.conflict }, entry);
 		}
 		slots.lakes.restore(region, lifted);
 		lifted = null;
@@ -571,38 +585,40 @@ function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
 				fp: region.getAttribute("data-og-fp") || void 0,
 				reason: drift.reason || void 0
 			});
-			console.warn(`[ogygia] island "${entry}" discarded its ENTIRE server-rendered DOM during hydration and re-rendered client-side (Svelte hydration-mismatch recovery). Three things cause this. (1) Something changed this region's HTML between SSR and wake — a post-SSR transform (transformPageChunk / an HTML-rewriting middleware), an A/B-testing snippet, or an edge rewriter; whatever it injected (e.g. declarative shadow DOM) was just destroyed, and the swap is timing-dependent, so symptoms look erratic. (2) A component in this island reads a page/layout CONTEXT via plain Svelte setContext — on csr=false that runs only on the server, so getContext returns undefined on the client and the island renders a different tree. (3) A block in this island ({#if} / {:else if} / {#each} / {#await}) took a DIFFERENT branch on the client than on the server — its condition reads something that differs between the two (a browser global, a store's client default, url/page state, a Date). Svelte recovers a branch mismatch SILENTLY (no throw); the walk is then off and the rest of the tree follows.` + (drift.reason ? `\nWhat changed: ${drift.reason}` : "") + (strict_error ? `\nSvelte threw on the strict attempt (after repair): ${strict_error instanceof Error ? strict_error.message : String(strict_error)}` : drift.reason ? `\nSvelte did not throw after the repair — the mismatch is one this walk does not model.` : "\nThe server node sequence was INTACT and Svelte did not throw: nothing mutated this region's DOM, so this is (3) (or (2)). Find the block whose branch differs: in the server markup its anchor reads <!--[N--> where N is the branch the SERVER chose.") + "\nFix: for (1) make the mutation invisible to hydration (mutate only <head>, attributes, or shadow templates — never the region's light DOM), or freeze the foreign-owned subtree with a wake:'none' (lake) boundary; for (2) provide the value with setContext / <Provide> / createContext imported from 'ogygia', read it with the same getContext(key); for (3) make the condition read the same value on both sides (a prop / page.data), or move the browser-only branch behind an $effect / hydratedBy().");
+			warn("hydration_discarded", {
+				entry,
+				drift: drift.reason,
+				strict: strict_error === null ? null : strict_error instanceof Error ? strict_error.message : String(strict_error)
+			});
 		}
-		if (!kit_hydrates_page()) boot_link().runtime_session.record_island_head(head_before);
+		if (head_mark) boot_link().runtime_session.record_island_head(head_mark);
 		return out;
 	} finally {
+		head_mark?.stop();
 		if (lifted) slots.lakes.restore(region, lifted);
 	}
 }
 /**
-* 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.
 */
 function hydrate_live(region, entry, mod, props) {
 	seed_remote_once();
 	seed_page_once();
-	const LiveHost = slots.live;
-	if (!LiveHost) {
-		if (import.meta.env.DEV) console.warn("[ogygia] live region needs the live feature plugin (LiveHost missing)");
+	if (!slots.Pushable) {
+		if (import.meta.env.DEV) warn("live_feature_missing");
 		return null;
 	}
 	const provided_ctx = capture_region_ids(region, () => slots.context?.(region));
 	const host_classes = note_host_classes(region);
-	const app = hydrate(LiveHost, {
+	const pushed = new slots.Pushable(prop_guard.wrap(props, entry));
+	const app = hydrate(mod.default, {
 		target: region,
-		props: {
-			component: mod.default,
-			initialProps: prop_guard.wrap(props, entry)
-		},
-		...provided_ctx ? { context: provided_ctx } : {}
+		props: pushed.props,
+		context: nested_context(provided_ctx)
 	});
 	keep_host_classes(host_classes);
-	return handle(app, unmount_app, entry, true);
+	return handle(app, unmount_app, entry, pushed);
 }
 export { hydrate_island, hydrate_live, is_foreign_entry, kit_page_thread, neutralize_head_hydration_markers, read_region_props, repair_if_drifted, seed_page_once, seed_remote_once, sequence_differs };

package/dist/runtime/import-again.d.ts

@@ -0,0 +1,33 @@
+/** Whether `error` is a dynamic import that failed to load (any engine's wording), not an error the
+ *  module threw as it ran. */
+export declare function is_failed_import(error: unknown): boolean;
+/**
+ * The URL a failed dynamic import names, if it names one we can load again (http(s), this origin).
+ * WebKit names none: there `known`, the file the caller imported, is it (#383).
+ */
+export declare function failed_import_url(error: unknown, known?: string): string | null;
+/** `url` with its retry mark: a URL the module map has not seen. */
+export declare function retry_url(url: string, attempt: number): string;
+/** The status of the response the browser's resource timing holds for `url` (0 where the browser does
+ *  not say), or `null` when none came: a download that failed (or no timing for it). */
+export declare function response_of(url: string): number | null;
+/** The boot hands over its message for a chunk no retry can load. Said once per page (for the first
+ *  such chunk: one reload loads them all). */
+export declare function on_reload_needed(say: (url: string, error: unknown) => void): void;
+/**
+ * `load` (a bundler-resolved `() => import('./x.ts')`), and after it fails to download, the same
+ * file under a fresh URL on each later call; once it has loaded, every later call is that load (a
+ * fresh URL after a success would be a second copy of the module). A retry whose own file came and
+ * still failed is a dependency's failure, which no URL fixes: from then on every call fails at once
+ * with its error, asking nothing. Pair it with `flights()` from `@ogygia/machine`, which calls it
+ * again on a failure and never keeps one.
+ */
+export declare function import_again<T>(load: () => Promise<T>, fresh?: (url: string) => Promise<unknown>, known?: string): () => Promise<T>;
+/**
+ * The module at `url` (an island's own file), through {@link import_again}: a download that fails is
+ * asked for again at once under a fresh URL, and by every later load of that file. A plain
+ * `import()` of it once left an island whose file dropped one download dead for the tab (#261). A
+ * file the server answered for (a 404 after a deploy) is not asked for again at once: the caller's
+ * own recovery (./entry-locations.ts, the current build's file) is what helps there.
+ */
+export declare function import_file<T>(url: string): Promise<T>;

package/dist/runtime/import-again.js

@@ -0,0 +1,217 @@
+import { STALE, flights, machine, scope } from "@ogygia/machine";
+// src/runtime/import-again.ts
+/**
+* A LAZY CHUNK THAT FAILED TO DOWNLOAD, ASKED FOR AGAIN. A browser keeps a module whose download
+* failed in its module map for the life of the page: a second `import()` of the same URL fails at
+* once, without a request (Chromium and Firefox both do; the e2e lazy-chunk-retry spec proves it).
+* Retrying the same `import()` therefore does nothing. What works is the same file under a new URL:
+* the failed import's error names the URL, so the next attempt imports it with an `og-retry` query
+* (a static server ignores it; a module never evaluated, so no second copy of its state exists).
+*
+* Safari's error names no URL: there the retry is the plain import again (it fails the same way),
+* so a dropped chunk stays dropped until the page reloads, as before.
+*
+* One failure no URL fixes: a static dependency of the chunk that failed. The error names the chunk
+* all the same, and the chunk under a fresh URL imports the dependency's own URL, which the browser
+* keeps failed: every retry fails the same way (#262). Told apart by the retry itself — it failed,
+* yet its own file came (the browser's resource timing holds its response): asking again cannot
+* help, so the loader stops asking, and the page says once that it needs a reload.
+*
+* A leaf: the boot and island-side code (devalue's lane, the entry locations) import it, so it
+* imports nothing of the boot (only `@ogygia/machine`, which the boot runs on); the boot hands it
+* its message (`on_reload_needed`).
+*/
+/** How long a failed import waits for its file's timing entry before it reads as "no response". */
+const ENTRY_WAIT_MS = 1e3;
+/**
+* The resource-timing entries for `url` once the browser has one, or none after
+* {@link ENTRY_WAIT_MS}. An engine can reject a failed import before the entry lands, and later
+* than one task: Firefox on a loaded machine. Chromium and Firefox give every download an entry (a
+* dropped one too, with a status of 0); WebKit gives a dropped one none, so only there the wait
+* runs out. Its own scope: it ends itself, and no page's visit owns a file's load.
+*/
+function entries_landed(url) {
+	if (typeof PerformanceObserver === "undefined") return Promise.resolve([]);
+	const wait = scope();
+	return new Promise((resolve) => {
+		const done = (entries) => {
+			wait.close();
+			resolve(entries);
+		};
+		wait.watch(new PerformanceObserver((list) => {
+			const entries = list.getEntriesByName(url);
+			if (entries.length > 0) done(entries);
+		})).observe({
+			type: "resource",
+			buffered: true
+		});
+		wait.timeout(() => done([]), ENTRY_WAIT_MS);
+	});
+}
+/** The URL in a failed dynamic import's message: Chromium "Failed to fetch dynamically imported
+*  module: <url>", Firefox "error loading dynamically imported module: <url>". */
+const FAILED_IMPORT_RE = /dynamically imported module:?\s+(\S+)/i;
+/** WebKit's (Safari's) failed import, which names no URL: "Importing a module script failed." */
+const WEBKIT_IMPORT_FAILED_RE = /^importing a module script failed\.?$/i;
+/** Whether `error` is a dynamic import that failed to load (any engine's wording), not an error the
+*  module threw as it ran. */
+function is_failed_import(error) {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	return FAILED_IMPORT_RE.test(message) || WEBKIT_IMPORT_FAILED_RE.test(message);
+}
+/**
+* The URL a failed dynamic import names, if it names one we can load again (http(s), this origin).
+* WebKit names none: there `known`, the file the caller imported, is it (#383).
+*/
+function failed_import_url(error, known) {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	const match = FAILED_IMPORT_RE.exec(message);
+	const named = match ? match[1] : known !== void 0 && WEBKIT_IMPORT_FAILED_RE.test(message) ? known : null;
+	if (named === null) return null;
+	try {
+		const url = new URL(named, typeof location !== "undefined" ? location.href : void 0);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+		if (typeof location !== "undefined" && url.origin !== location.origin) return null;
+		return url.href;
+	} catch {
+		return null;
+	}
+}
+/** `url` with its retry mark: a URL the module map has not seen. */
+function retry_url(url, attempt) {
+	const u = new URL(url);
+	u.searchParams.set("og-retry", String(attempt));
+	return u.href;
+}
+/** The status of the response the browser's resource timing holds for `url` (0 where the browser does
+*  not say), or `null` when none came: a download that failed (or no timing for it). */
+function response_of(url) {
+	if (typeof performance === "undefined" || typeof performance.getEntriesByName !== "function") return null;
+	return status_of(performance.getEntriesByName(url, "resource"));
+}
+/** {@link response_of}, read from `entries` (one file's resource-timing entries). */
+function status_of(entries) {
+	let status = null;
+	for (const e of entries) {
+		const t = e;
+		if (typeof t.responseStatus === "number") {
+			if (t.responseStatus > 0) status = t.responseStatus;
+		} else if (t.responseStart > 0) status = 0;
+	}
+	return status;
+}
+/** What the page says when a chunk cannot load until it reloads: the boot's message (./core.ts). */
+let say_reload_needed = () => {};
+let said = false;
+/** The boot hands over its message for a chunk no retry can load. Said once per page (for the first
+*  such chunk: one reload loads them all). */
+function on_reload_needed(say) {
+	say_reload_needed = say;
+}
+/**
+* `load` (a bundler-resolved `() => import('./x.ts')`), and after it fails to download, the same
+* file under a fresh URL on each later call; once it has loaded, every later call is that load (a
+* fresh URL after a success would be a second copy of the module). A retry whose own file came and
+* still failed is a dependency's failure, which no URL fixes: from then on every call fails at once
+* with its error, asking nothing. Pair it with `flights()` from `@ogygia/machine`, which calls it
+* again on a failure and never keeps one.
+*/
+function import_again(load, fresh = (url) => import(
+	/* @vite-ignore */
+	url
+), known) {
+	const file = file_definition.create();
+	return () => {
+		const s = file.now;
+		if (s.kind === "loaded") return s.run;
+		if (s.kind === "stuck") return Promise.reject(s.error);
+		let run;
+		if (s.kind === "failed") {
+			const attempt = s.attempt + 1;
+			file.go("failed", {
+				url: s.url,
+				attempt
+			});
+			const url = retry_url(s.url, attempt);
+			run = fresh(url).catch((error) => {
+				const status = response_of(url);
+				if (status !== null && status < 400 && file.move("failed", "stuck", { error })) {
+					if (!said) {
+						said = true;
+						say_reload_needed(url, error);
+					}
+				}
+				throw error;
+			});
+		} else run = load().catch((error) => {
+			const url = failed_import_url(error, known);
+			if (url !== null) file.move("fresh", "failed", {
+				url,
+				attempt: 0
+			});
+			throw error;
+		});
+		run.then(() => {
+			if (file.now.kind !== "loaded") file.go("loaded", { run });
+		}, () => {});
+		return run;
+	};
+}
+/**
+* One file's loads, as a machine:
+*
+*   fresh ─ failed{url, attempt} ⟲ ─ loaded{run}
+*     ╲──────────────────────────╱ ╲ stuck{error}
+*
+* `fresh`: nothing failed yet (or a failure named no URL): a call loads the bundler's way. `failed`:
+* a download failed; each call asks under a fresh URL. `loaded`: a load landed, and every later call
+* is that load (a fresh URL after a success would be a second copy of the module). `stuck`: a retry's
+* own file came and it still failed, a dependency's failure: every later call fails at once with it.
+*/
+const file_definition = machine()({
+	name: "import-again",
+	initial: "fresh",
+	steps: {
+		fresh: ["failed", "loaded"],
+		failed: [
+			"failed",
+			"loaded",
+			"stuck"
+		],
+		loaded: [],
+		stuck: ["loaded"]
+	}
+});
+/** Each file's loader, by URL (an island's own file: its load, and the warm ahead of it): what it
+*  asks for next (the file, or a fresh URL after a failed download). */
+const file_loaders = /* @__PURE__ */ new Map();
+/** One load of each file at a time, kept once it lands: loads of one file that fail together share
+*  one retry, so a failure gets one fresh URL and the module runs once (#271). */
+const file_loads = flights({
+	name: "island file",
+	run: (url) => {
+		let again = file_loaders.get(url);
+		if (!again) file_loaders.set(url, again = import_again(() => import(
+			/* @vite-ignore */
+			url
+), void 0, url));
+		const load = again;
+		return load().catch(async (error) => {
+			const failed = failed_import_url(error, url);
+			if (failed === null) throw error;
+			if ((response_of(failed) ?? status_of(await entries_landed(failed))) === null) return load();
+			throw error;
+		});
+	}
+});
+/**
+* The module at `url` (an island's own file), through {@link import_again}: a download that fails is
+* asked for again at once under a fresh URL, and by every later load of that file. A plain
+* `import()` of it once left an island whose file dropped one download dead for the tab (#261). A
+* file the server answered for (a 404 after a deploy) is not asked for again at once: the caller's
+* own recovery (./entry-locations.ts, the current build's file) is what helps there.
+*/
+function import_file(url) {
+	return file_loads.get(url).then((m) => m === STALE ? import_file(url) : m);
+}
+export { failed_import_url, import_again, import_file, is_failed_import, on_reload_needed, response_of, retry_url };

package/dist/runtime/interaction-replay.d.ts

@@ -1,11 +1,13 @@
 import { FieldSnapshot, QueuedClick } from "./interaction.js";
+import { Scope } from "@ogygia/machine";
 /**
  * Replay the queued clicks in arrival order at each click's address (tag-checked against drift).
  * One frame later: hydration just (re)bound the island's web-component wiring (a dropdown web
  * component's `target` element, set by a reactive statement) and many components apply such
  * changes in their own render tick. A synchronous replay lands before that tick and toggles
- * nothing; after a frame the component is settled.
+ * nothing; after a frame the component is settled. The frame is `owner`'s (the region's lifetime in
+ * the page): a region gone by then replays nothing.
  */
-export declare function replay_clicks(region: Element, queued: QueuedClick[]): void;
+export declare function replay_clicks(region: Element, queued: QueuedClick[], owner: Scope): void;
 /** The island is live: fields back, focus back, clicks replayed. */
-export declare function after_wake(region: Element, fields: FieldSnapshot[], active_addr: number[] | null, queued: QueuedClick[]): void;
+export declare function after_wake(region: Element, fields: FieldSnapshot[], active_addr: number[] | null, queued: QueuedClick[], owner: Scope): void;

package/dist/runtime/interaction-replay.js

@@ -34,9 +34,10 @@ function restore_fields(region, fields) {
 * One frame later: hydration just (re)bound the island's web-component wiring (a dropdown web
 * component's `target` element, set by a reactive statement) and many components apply such
 * changes in their own render tick. A synchronous replay lands before that tick and toggles
-* nothing; after a frame the component is settled.
+* nothing; after a frame the component is settled. The frame is `owner`'s (the region's lifetime in
+* the page): a region gone by then replays nothing.
 */
-function replay_clicks(region, queued) {
+function replay_clicks(region, queued, owner) {
 	const replay = () => {
 		for (const q of queued) {
 			const t = resolve_address(region, q.addr);
@@ -46,18 +47,17 @@ function replay_clicks(region, queued) {
 		}
 		queued.length = 0;
 	};
-	if (typeof requestAnimationFrame === "function") requestAnimationFrame(replay);
-	else replay();
+	owner.timeout(replay, "frame");
 }
 /** The island is live: fields back, focus back, clicks replayed. */
-function after_wake(region, fields, active_addr, queued) {
+function after_wake(region, fields, active_addr, queued, owner) {
 	restore_fields(region, fields);
 	if (active_addr) {
 		const el = resolve_address(region, active_addr);
 		if (el instanceof HTMLElement && document.activeElement !== el) el.focus();
 	}
 	const replayed = queued.length;
-	replay_clicks(region, queued);
+	replay_clicks(region, queued, owner);
 	if (DEVTOOLS) emit({
 		domain: "runtime",
 		name: "interaction.replay",

package/dist/runtime/interaction.d.ts

@@ -1,3 +1,4 @@
+import { Scope } from "@ogygia/machine";
 /** Feature entry: fill the `interaction` slot — wake a cold island on first use, warm on hover. */
 export declare function install(): void;
 /** Child-index path from `region` down to `el` — survives node replacement by position. */
@@ -13,6 +14,13 @@ export type FieldSnapshot = {
   addr: number[];
   tag: string;
 };
+/**
+ * Wake the island for a visitor. `replayed` is what replays their input once it is live (the replay
+ * half, loading): the island's wake waits for it before it goes live, so the input lands AT wake. An
+ * island that went live first left the replay to come in later, over a slow network, beside the
+ * visitor's next click (#260). Resolves when the island is live; rejects when it failed to wake.
+ */
+export type WakeFn = (replayed: Promise<unknown>) => Promise<void> | void;
 export type QueuedClick = {
   addr: number[];
   /** The deepest node of the click's composed path when it lies INSIDE a web component's shadow
@@ -27,7 +35,10 @@ export type QueuedClick = {
  *
  * @param region the `<ogygia-region>` element
  * @param warm   prefetch the island module (no hydrate) — wired to the pointer entering the region
- * @param fire   begin hydration; resolves when the island is live
- * @returns disarm() — forget the region (disconnected before any interaction)
+ * @param fire   begin hydration ({@link WakeFn}); resolves when the island is live
+ * @param owner  the region's lifetime in the page: the frame its clicks replay in is its
+ * @returns disarm(over?) — end this arming (the island is live or failed, or the region left
+ *          before any interaction); `over`: the region left while it was woken, so its queued clicks
+ *          are dropped instead of replayed
  */
-export declare function arm_interaction(region: Element, warm: () => void, fire: () => Promise<void> | void): () => void;
+export declare function arm_interaction(region: Element, warm: () => void, fire: WakeFn, owner: Scope): (over?: boolean) => void;