@moku-labs/web 1.15.1 → 1.16.1

package/dist/testing.mjs

@@ -0,0 +1,854 @@
+import { render } from "preact";
+import { act } from "preact/test-utils";
+//#region src/plugins/spa/types.ts
+/** Allowed hook names — single source of truth for fail-fast validation. */
+const COMPONENT_HOOK_NAMES = [
+	"onCreate",
+	"onMount",
+	"onNavStart",
+	"onNavEnd",
+	"onUnMount",
+	"onDestroy"
+];
+//#endregion
+//#region src/plugins/spa/components.ts
+/**
+* @file spa plugin — component lifecycle, mounting, the plugin-mirror authoring
+* surface (`createComponent` with a typed `{ state, render, events, api }` spec),
+* the per-instance state + microtask-batched render scheduler, declarative
+* delegated events, and the cross-island api registry.
+* @see README.md
+*/
+/** Error prefix for spa fail-fast failures (spec/11 Part-3). */
+const ERROR_PREFIX = "[web]";
+new Set(COMPONENT_HOOK_NAMES);
+/** Synchronous re-entrancy cap for the render scheduler (a render that calls `ctx.flush`). */
+const MAX_RENDER_DEPTH = 25;
+/**
+* No-op link builder for the {@link EMPTY_ROUTE} slice (used when no route matched).
+*
+* @returns An empty string.
+* @example
+* const href = noUrl();
+*/
+function noUrl() {
+	return "";
+}
+/** Empty route slice — used for mounts with no matched route (headless, tests, public `scan()`). */
+const EMPTY_ROUTE = {
+	params: {},
+	meta: {},
+	locale: "",
+	url: noUrl
+};
+/**
+* No-op placeholder for an instance's `flush` slot until the real one is bound at mount.
+*
+* @example
+* const instance = { flush: noop };
+*/
+function noop() {}
+/** Cached promise for the lazy `./render` chunk (loaded at most once per module). */
+let renderChunk;
+/** The resolved VNode committer once the chunk loads (undefined until then). */
+let commitVNodeFunction;
+/**
+* Load the lazy `./render` chunk (once) and cache its `commitVNode` for synchronous
+* use by later renders. Awaited by a component's `mountPromise` so the test harness's
+* `settle()` can deterministically flush a VNode render.
+*
+* @returns A promise that resolves once `commitVNode` is available.
+* @example
+* await loadRenderChunk();
+*/
+async function loadRenderChunk() {
+	renderChunk ??= import("./render-UO4nimWr.mjs");
+	commitVNodeFunction = (await renderChunk).commitVNode;
+}
+/**
+* Commit a {@link RenderResult} into a host: `string` → `innerHTML`, `Node` →
+* `replaceChildren`, `void`/`undefined` → no-op (the render mutated the DOM itself), and
+* a Preact `VNode` → committed through the lazy gate (loading it on demand if needed).
+*
+* @param host - The island host element to render into.
+* @param result - The value returned by the component's `render`.
+* @example
+* commitResult(host, h(View, { items }));
+*/
+function commitResult(host, result) {
+	if (result === void 0) return;
+	if (typeof result === "string") {
+		host.innerHTML = result;
+		return;
+	}
+	if (result instanceof Node) {
+		host.replaceChildren(result);
+		return;
+	}
+	const vnode = result;
+	if (commitVNodeFunction) {
+		commitVNodeFunction(vnode, host);
+		return;
+	}
+	loadRenderChunk().then(() => commitVNodeFunction?.(vnode, host)).catch(() => {});
+}
+/**
+* Run a component's `render(state, ctx)` and commit the result now. Guards against
+* synchronous re-entrancy (a render that calls `ctx.flush`) with a depth cap.
+*
+* @param instance - The instance to render.
+* @throws {Error} When the synchronous render depth exceeds {@link MAX_RENDER_DEPTH}.
+* @example
+* runRender(instance);
+*/
+function runRender(instance) {
+	const render = instance.def.spec?.render;
+	if (!render) return;
+	if (instance.renderDepth > MAX_RENDER_DEPTH) throw new Error(`${ERROR_PREFIX} component "${instance.def.name}" render re-entered ${MAX_RENDER_DEPTH}+ times\n  → a render must not synchronously trigger its own render (avoid ctx.flush() inside render)`);
+	instance.renderDepth += 1;
+	try {
+		commitResult(instance.el, render(instance.state ?? {}, instance.ctx));
+	} finally {
+		instance.renderDepth -= 1;
+	}
+}
+/**
+* Schedule a microtask-batched render for an instance (no-op when it has no `render`).
+* Multiple `ctx.set` calls in the same tick coalesce into a single render.
+*
+* @param instance - The instance to schedule a render for.
+* @example
+* scheduleRender(instance);
+*/
+function scheduleRender(instance) {
+	if (!instance.def.spec?.render || instance.renderScheduled) return;
+	instance.renderScheduled = true;
+	queueMicrotask(() => {
+		if (!instance.renderScheduled) return;
+		instance.renderScheduled = false;
+		runRender(instance);
+	});
+}
+/**
+* Build the single per-instance {@link ComponentContext} reused by every hook, event
+* handler, and render. Route fields (`params`/`meta`/`locale`/`url`) and `data` read
+* through the instance so a navigation update is reflected without rebuilding the ctx;
+* `state`/`set`/`flush`/`cleanup`/`component` are bound to the instance + plugin state.
+*
+* @param state - The plugin state (for the cross-island `component` resolver).
+* @param instance - The instance the context is bound to.
+* @returns The instance-bound context.
+* @example
+* instance.ctx = buildContext(state, instance);
+*/
+function buildContext(state, instance) {
+	return {
+		el: instance.el,
+		/**
+		* The current page data payload (live; updated across navigations).
+		*
+		* @returns The page data.
+		* @example
+		* ctx.data;
+		*/
+		get data() {
+			return instance.data;
+		},
+		/**
+		* The matched route's path params (live; updated across navigations).
+		*
+		* @returns The route params.
+		* @example
+		* ctx.params.id;
+		*/
+		get params() {
+			return instance.route.params;
+		},
+		/**
+		* The matched route's `.meta()` bag (live; updated across navigations).
+		*
+		* @returns The route meta.
+		* @example
+		* ctx.meta.focus;
+		*/
+		get meta() {
+			return instance.route.meta;
+		},
+		/**
+		* The active locale for the current route (live; updated across navigations).
+		*
+		* @returns The locale code.
+		* @example
+		* ctx.locale;
+		*/
+		get locale() {
+			return instance.route.locale;
+		},
+		/**
+		* The named-route link builder for the current route.
+		*
+		* @returns The link builder.
+		* @example
+		* ctx.url("board", { id });
+		*/
+		get url() {
+			return instance.route.url;
+		},
+		/**
+		* The live per-instance state (`undefined` for legacy hooks-only islands).
+		*
+		* @returns The current state.
+		* @example
+		* ctx.state.count;
+		*/
+		get state() {
+			return instance.state;
+		},
+		/**
+		* Merge a patch into the per-instance state and schedule one batched render.
+		*
+		* @param patch - A partial state object, or an updater `(prev) => partial`.
+		* @example
+		* ctx.set(prev => ({ count: prev.count + 1 }));
+		*/
+		set(patch) {
+			const previous = instance.state ?? {};
+			const next = typeof patch === "function" ? patch(previous) : patch;
+			instance.state = Object.assign({}, previous, next);
+			scheduleRender(instance);
+		},
+		/**
+		* Force a synchronous render now (drains any pending scheduled render).
+		*
+		* @example
+		* ctx.flush();
+		*/
+		flush() {
+			instance.flush();
+		},
+		/**
+		* Register a disposer run on destroy (subscriptions, timers, manual listeners).
+		*
+		* @param dispose - The teardown function.
+		* @example
+		* ctx.cleanup(off);
+		*/
+		cleanup(dispose) {
+			instance.cleanups.push(dispose);
+		},
+		/**
+		* Resolve another island's registered api by name (`undefined` when absent).
+		*
+		* @param name - The provider island's component name.
+		* @returns The provider's api, or `undefined`.
+		* @example
+		* ctx.component("lightbox");
+		*/
+		component(name) {
+			return state.componentApis.get(name);
+		}
+	};
+}
+/**
+* Resolve the element a delegated handler should receive for an event: the host for a
+* host-level binding (empty selector), else the nearest ancestor of `event.target`
+* matching the selector that is still inside the host.
+*
+* @param host - The island host element.
+* @param event - The dispatched DOM event.
+* @param selector - The key's selector (empty string → host-level).
+* @returns The matched element, or `undefined` when nothing matches inside the host.
+* @example
+* const target = matchTarget(host, event, "[data-action]");
+*/
+function matchTarget(host, event, selector) {
+	if (selector === "") return host;
+	const target = event.target;
+	if (!(target instanceof Element)) return void 0;
+	const matched = target.closest(selector);
+	return matched && host.contains(matched) ? matched : void 0;
+}
+/**
+* Attach a component's declarative `events` map: one real listener per event TYPE on
+* the host (dispatch walks `closest(selector)` for each registered selector), each
+* removed via the instance's cleanup registry on destroy.
+*
+* @param instance - The instance whose host the listeners attach to.
+* @param events - The declarative `{ "<type> <selector>": handler }` map.
+* @throws {Error} When a key has no event type.
+* @example
+* attachEvents(instance, { "click [data-action]": (ctx, e, el) => {} });
+*/
+function attachEvents(instance, events) {
+	const host = instance.el;
+	const byType = /* @__PURE__ */ new Map();
+	for (const [key, handler] of Object.entries(events)) {
+		const space = key.indexOf(" ");
+		const type = (space === -1 ? key : key.slice(0, space)).trim();
+		const selector = space === -1 ? "" : key.slice(space + 1).trim();
+		if (type === "") throw new Error(`${ERROR_PREFIX} component "${instance.def.name}" event key must start with an event type: "${key}"\n  → use "<type>" or "<type> <selector>" (e.g. "click [data-action]")`);
+		const list = byType.get(type) ?? [];
+		list.push({
+			selector,
+			handler
+		});
+		byType.set(type, list);
+	}
+	for (const [type, handlers] of byType) {
+		const listener = (event) => {
+			for (const { selector, handler } of handlers) {
+				const target = matchTarget(host, event, selector);
+				if (target) handler(instance.ctx, event, target);
+			}
+		};
+		host.addEventListener(type, listener);
+		instance.cleanups.push(() => host.removeEventListener(type, listener));
+	}
+}
+/**
+* Extracts the page data payload from the inline `script#__DATA__` element.
+* Returns an empty object when the script is absent, empty, or invalid JSON.
+*
+* @param doc - The document to read the data script from.
+* @returns The parsed page data, or `{}` when unavailable.
+* @example
+* const data = extractPageData(document);
+*/
+function extractPageData(doc) {
+	const text = doc.querySelector("script#__DATA__")?.textContent;
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return {};
+	}
+}
+/**
+* Read the current page data, or `{}` in a headless (non-browser) context.
+*
+* @returns The current page data payload.
+* @example
+* const data = currentPageData();
+*/
+function currentPageData() {
+	return typeof document === "undefined" ? {} : extractPageData(document);
+}
+/**
+* Invokes a single lifecycle hook on an instance with its bound context. Missing
+* hooks are skipped silently.
+*
+* @param instance - The instance whose hook to run.
+* @param hook - The hook name to invoke.
+* @example
+* runHook(instance, "onDestroy");
+*/
+function runHook(instance, hook) {
+	instance.def.hooks[hook]?.(instance.ctx);
+}
+/**
+* Run an instance's registered cleanup disposers (LIFO) and unregister its api. Each
+* disposer runs in isolation so a throwing one never strands the others during teardown.
+*
+* @param state - The plugin state (for the api registry).
+* @param instance - The instance being disposed.
+* @example
+* disposeInstance(state, instance);
+*/
+function disposeInstance(state, instance) {
+	for (let index = instance.cleanups.length - 1; index >= 0; index -= 1) try {
+		instance.cleanups[index]?.();
+	} catch {}
+	instance.cleanups.length = 0;
+	instance.renderScheduled = false;
+	if (instance.api !== void 0 && state.componentApis.get(instance.def.name) === instance.api) state.componentApis.delete(instance.def.name);
+}
+/**
+* Mounts a single `data-component` element: classifies persistent vs page-specific,
+* builds the instance + its bound context, initializes per-instance `state`, registers
+* its `api`, attaches declarative `events`, fires `onCreate` then `onMount` (capturing
+* an async `onMount` + render-chunk load as `mountPromise`), schedules the initial
+* render, records it, and emits `spa:component-mount`. No-ops if the element is already
+* mounted, has no component name, or names an unregistered component.
+*
+* @param state - The plugin state (registeredComponents + instances + componentApis).
+* @param emit - The event emitter for spa:component-mount.
+* @param swapArea - The swap-region element, or null when none was found.
+* @param data - The current page data payload.
+* @param element - The candidate element carrying a `data-component` attribute.
+* @param route - The matched-route slice for the current URL (params/meta/locale/url).
+* @example
+* mountElement(state, emit, swapArea, data, element, route);
+*/
+function mountElement(state, emit, swapArea, data, element, route = EMPTY_ROUTE) {
+	if (state.instances.has(element)) return;
+	const name = element.dataset.component;
+	if (!name) return;
+	const definition = state.registeredComponents.get(name);
+	if (!definition) return;
+	const instance = {
+		def: definition,
+		el: element,
+		persistent: swapArea ? !swapArea.contains(element) : true,
+		ctx: void 0,
+		state: void 0,
+		api: void 0,
+		route,
+		data,
+		cleanups: [],
+		flush: noop,
+		renderScheduled: false,
+		renderDepth: 0,
+		mountPromise: void 0
+	};
+	instance.ctx = buildContext(state, instance);
+	instance.flush = () => {
+		instance.renderScheduled = false;
+		runRender(instance);
+	};
+	const spec = definition.spec;
+	if (spec?.state) instance.state = spec.state(instance.ctx);
+	if (spec?.api) {
+		instance.api = spec.api(instance.ctx);
+		state.componentApis.set(definition.name, instance.api);
+	}
+	if (spec?.events) attachEvents(instance, spec.events);
+	runHook(instance, "onCreate");
+	const onMountResult = definition.hooks.onMount?.(instance.ctx);
+	if (spec?.render) scheduleRender(instance);
+	const pending = [];
+	if (spec?.render) pending.push(loadRenderChunk());
+	if (onMountResult && typeof onMountResult.then === "function") pending.push(onMountResult);
+	instance.mountPromise = pending.length > 0 ? Promise.all(pending).then(() => {}) : void 0;
+	state.instances.set(element, instance);
+	emit("spa:component-mount", {
+		name: definition.name,
+		el: element
+	});
+}
+/**
+* Scans the swap region, mounts components for matching `data-component` elements,
+* classifies persistent (outside swap area) vs page-specific (inside), runs
+* `onCreate`/`onMount` + initial render, and emits `spa:component-mount` per instance.
+* Already-mounted elements are skipped.
+*
+* @param state - The plugin state (registeredComponents + instances + componentApis).
+* @param emit - The event emitter for spa:component-mount.
+* @param swapSelector - CSS selector bounding page-specific components.
+* @param route - The matched-route slice for the current URL (params/meta/locale/url).
+* @example
+* scanAndMount(state, emit, "main > section", route);
+*/
+function scanAndMount(state, emit, swapSelector, route = EMPTY_ROUTE) {
+	if (typeof document === "undefined") return;
+	const swapArea = document.querySelector(swapSelector);
+	const data = extractPageData(document);
+	for (const element of document.querySelectorAll("[data-component]")) mountElement(state, emit, swapArea, data, element, route);
+}
+/**
+* Unmounts page-specific instances inside the swap region (runs `onUnMount` then
+* `onDestroy`, then their cleanup disposers + api unregister), removes them from state,
+* and emits `spa:component-unmount`. Persistent instances (outside the swap area) are
+* left in place.
+*
+* @param state - The plugin state holding live instances.
+* @param emit - The event emitter for spa:component-unmount.
+* @example
+* unmountPageSpecific(state, emit);
+*/
+function unmountPageSpecific(state, emit) {
+	const data = currentPageData();
+	for (const [element, instance] of state.instances) {
+		if (instance.persistent) continue;
+		instance.data = data;
+		runHook(instance, "onUnMount");
+		runHook(instance, "onDestroy");
+		disposeInstance(state, instance);
+		state.instances.delete(element);
+		emit("spa:component-unmount", {
+			name: instance.def.name,
+			el: element
+		});
+	}
+}
+/**
+* Disposes ALL live instances (persistent and page-specific) on teardown: runs
+* `onUnMount` then `onDestroy`, then their cleanup disposers + api unregister, emits
+* `spa:component-unmount`, and clears the instance + api maps. Used by the kernel's
+* `dispose` on plugin stop.
+*
+* @param state - The plugin state holding live instances.
+* @param emit - The event emitter for spa:component-unmount.
+* @example
+* unmountAll(state, emit);
+*/
+function unmountAll(state, emit) {
+	const data = currentPageData();
+	for (const [element, instance] of state.instances) {
+		instance.data = data;
+		runHook(instance, "onUnMount");
+		runHook(instance, "onDestroy");
+		disposeInstance(state, instance);
+		emit("spa:component-unmount", {
+			name: instance.def.name,
+			el: element
+		});
+	}
+	state.instances.clear();
+	state.componentApis.clear();
+}
+/**
+* Fires `onNavStart` on every currently-mounted instance (persistent instances
+* receive it across navigations; page-specific ones receive it before unmount).
+*
+* @param state - The plugin state holding live instances.
+* @example
+* notifyNavStart(state);
+*/
+function notifyNavStart(state) {
+	const data = currentPageData();
+	for (const instance of state.instances.values()) {
+		instance.data = data;
+		runHook(instance, "onNavStart");
+	}
+}
+/**
+* Fires `onNavEnd` on persistent instances that survived the swap (page-specific
+* instances were already destroyed and re-created by the swap), updating their route
+* slice to the destination first.
+*
+* @param state - The plugin state holding live instances.
+* @param route - The matched-route slice for the destination URL (params/meta/locale/url).
+* @example
+* notifyNavEnd(state, route);
+*/
+function notifyNavEnd(state, route = EMPTY_ROUTE) {
+	const data = currentPageData();
+	for (const instance of state.instances.values()) {
+		if (!instance.persistent) continue;
+		instance.data = data;
+		instance.route = route;
+		runHook(instance, "onNavEnd");
+	}
+}
+//#endregion
+//#region src/plugins/spa/state.ts
+/**
+* Creates initial spa plugin state. All kernel state lives here — never module
+* scope. The kernel itself is built in onInit and stored as `kernel`, so
+* api/onStart/onStop all reuse the single shared instance.
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global plugin registry.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns The initial SPA state with an empty kernel slot.
+* @example
+* const state = createState({ global: {}, config: defaultSpaConfig });
+*/
+function createState(_ctx) {
+	return {
+		registeredComponents: /* @__PURE__ */ new Map(),
+		instances: /* @__PURE__ */ new Map(),
+		componentApis: /* @__PURE__ */ new Map(),
+		currentUrl: "",
+		destroyRouter: null,
+		started: false,
+		kernel: null
+	};
+}
+//#endregion
+//#region src/testing.ts
+/**
+* @file `@moku-labs/web/testing` — a tiny headless test harness for SPA islands.
+*
+* Mounts ONE island through the REAL spa kernel internals (`createState` +
+* `scanAndMount` + `notifyNav*` + `unmountPageSpecific`/`unmountAll`) under a DOM
+* (happy-dom in Vitest), so a consumer can unit-test an island in a few lines without
+* reaching into framework internals or booting a whole `createApp`. It drives the
+* plugin-mirror API directly: read typed `state`/`api`, dispatch declarative `events`,
+* drain the `ctx.set → render` scheduler (`flush`/`settle`), simulate navigation, and
+* assert auto-teardown of `events` + `ctx.cleanup` on `unmount`.
+*
+* This module is a SEPARATE entry — NEVER imported by `browser.ts` — so test-only code
+* (and its static Preact import for {@link renderIsland}) never enters a client bundle.
+* @see README.md
+*/
+/** The swap selector the harness uses to bound page-specific islands. */
+const SWAP_SELECTOR = "main > section";
+/**
+* Parse a `"<type> <selector>"` event spec into its event type and selector (only the
+* first space splits, so descendant-combinator selectors work).
+*
+* @param spec - The event spec string.
+* @returns The event `type` and `selector` (selector empty for host-level).
+* @example
+* parseEventSpec("click [data-action='x']"); // { type: "click", selector: "[data-action='x']" }
+*/
+function parseEventSpec(spec) {
+	const space = spec.indexOf(" ");
+	return space === -1 ? {
+		type: spec.trim(),
+		selector: ""
+	} : {
+		type: spec.slice(0, space).trim(),
+		selector: spec.slice(space + 1).trim()
+	};
+}
+/**
+* Mount ONE island headlessly through the REAL spa kernel internals under a DOM. The
+* unit + light-integration tier: no `createApp`, no router, no network.
+*
+* @param definition - The component definition under test (from `createComponent`).
+* @param options - Host HTML/element, route slice, page data, persistence, stub apis.
+* @returns A handle exposing the instance's `state`/`api` + event/nav/flush drivers.
+* @example
+* const h = mountIsland(tabNav, { html: "<a></a><a></a><a></a>", persistent: true });
+* h.navEnd({ locale: "en" });
+* expect(h.el.querySelector("[aria-current]")).toBeTruthy();
+*/
+function mountIsland(definition, options = {}) {
+	const state = createState({
+		global: {},
+		config: {}
+	});
+	state.registeredComponents.set(definition.name, definition);
+	if (options.components) for (const [name, api] of Object.entries(options.components)) state.componentApis.set(name, api);
+	const host = options.el ?? document.createElement("div");
+	host.dataset.component = definition.name;
+	if (options.html !== void 0) host.innerHTML = options.html;
+	const dataScript = options.data ? `<script id="__DATA__" type="application/json">${JSON.stringify(options.data)}<\/script>` : "";
+	document.body.innerHTML = `<main><section id="__moku_swap"></section></main>${dataScript}`;
+	if (!options.el) {
+		const swapRegion = document.querySelector("#__moku_swap");
+		(options.persistent ? document.body : swapRegion ?? document.body).append(host);
+	}
+	const emitted = [];
+	const emit = (event, payload) => {
+		emitted.push({
+			event,
+			payload
+		});
+	};
+	const route = {
+		params: options.params ?? {},
+		meta: options.meta ?? {},
+		locale: options.locale ?? "",
+		url: options.url ?? ((name) => `/${name}`)
+	};
+	scanAndMount(state, emit, SWAP_SELECTOR, route);
+	const instance = state.instances.get(host);
+	return {
+		el: host,
+		/**
+		* The live per-instance state (typed), or undefined for hooks-only islands.
+		*
+		* @returns The current state.
+		* @example
+		* handle.state?.count;
+		*/
+		get state() {
+			return instance?.state;
+		},
+		/**
+		* The island's registered api (typed), or undefined when none was declared.
+		*
+		* @returns The api object.
+		* @example
+		* handle.api?.open();
+		*/
+		get api() {
+			return instance?.api;
+		},
+		emitted,
+		/**
+		* Dispatch a delegated event by `"<type> <selector>"` spec onto the first match.
+		*
+		* @param spec - The event spec (selector optional → host-level).
+		* @param init - Optional event init (bubbles/cancelable default true).
+		* @example
+		* handle.fire("click [data-inc]");
+		*/
+		fire(spec, init) {
+			const { type, selector } = parseEventSpec(spec);
+			(selector ? host.querySelector(selector) ?? host : host).dispatchEvent(new Event(type, {
+				bubbles: true,
+				cancelable: true,
+				...init
+			}));
+		},
+		/**
+		* Dispatch a pre-built event at a selector (raw control for DragEvent/dataTransfer).
+		*
+		* @param selector - The element to dispatch on (host when no match).
+		* @param event - The pre-built event.
+		* @example
+		* handle.dispatch("[data-cards]", dropEvent);
+		*/
+		dispatch(selector, event) {
+			(host.querySelector(selector) ?? host).dispatchEvent(event);
+		},
+		/**
+		* Synchronously drain any pending render now.
+		*
+		* @example
+		* handle.flush();
+		*/
+		flush() {
+			instance?.flush();
+		},
+		/**
+		* Await onMount + the render-chunk load + a microtask, then flush.
+		*
+		* @returns A promise resolving once mounted and rendered.
+		* @example
+		* await handle.settle();
+		*/
+		async settle() {
+			await instance?.mountPromise;
+			await Promise.resolve();
+			instance?.flush();
+		},
+		/**
+		* Fire onNavStart on the instance.
+		*
+		* @example
+		* handle.navStart();
+		*/
+		navStart() {
+			notifyNavStart(state);
+		},
+		/**
+		* Fire onNavEnd on a persistent instance with an optional destination route.
+		*
+		* @param next - Partial route slice to merge onto the current one.
+		* @example
+		* handle.navEnd({ params: { id: "2" } });
+		*/
+		navEnd(next) {
+			notifyNavEnd(state, {
+				...route,
+				...next
+			});
+		},
+		/**
+		* Run onUnMount + onDestroy (page-specific first, then persistent).
+		*
+		* @example
+		* handle.unmount();
+		*/
+		unmount() {
+			unmountPageSpecific(state, emit);
+			unmountAll(state, emit);
+		}
+	};
+}
+/**
+* Commit a {@link RenderResult} into a host for {@link renderIsland} (the pure tier):
+* `string` → innerHTML, `Node` → replaceChildren, VNode → Preact `render` (wrapped in
+* `act` so effects flush), `void` → no-op.
+*
+* @param host - The host element to render into.
+* @param result - The render result.
+* @example
+* commit(host, h(View, { items }));
+*/
+function commit(host, result) {
+	if (result === void 0) return;
+	if (typeof result === "string") {
+		host.innerHTML = result;
+		return;
+	}
+	if (result instanceof Node) {
+		host.replaceChildren(result);
+		return;
+	}
+	act(() => {
+		render(result, host);
+	});
+}
+/**
+* No-op stand-in for a context method the pure `renderIsland` tier never invokes.
+*
+* @example
+* const ctx = { set: noopStub };
+*/
+function noopStub() {}
+/**
+* Stand-in link builder for the pure `renderIsland` tier.
+*
+* @param name - The route name.
+* @returns A `/<name>` placeholder href.
+* @example
+* stubUrl("board"); // "/board"
+*/
+function stubUrl(name) {
+	return `/${name}`;
+}
+/**
+* The cheapest unit tier: render a controller/view island's pure `render(state, ctx)`
+* against fixture state, with no kernel and no `mountIsland`. Uses `preact/test-utils`
+* `act` (which ships WITH Preact — no new dependency) so effects flush deterministically.
+*
+* @param render - The island's `render` function (e.g. `boardList.spec.render`).
+* @param input - Fixture inputs.
+* @param input.state - The fixture per-instance state to render.
+* @param input.ctx - Optional partial context overrides.
+* @returns A {@link RenderIslandResult} for asserting the rendered DOM.
+* @example
+* const r = renderIsland(render, { state: { boards: [{ id: "1", title: "Alpha" }] } });
+* expect(r.find("[data-board]")).toBeTruthy();
+*/
+function renderIsland(render$1, input) {
+	const host = document.createElement("div");
+	document.body.append(host);
+	const ctx = {
+		el: host,
+		data: {},
+		params: {},
+		meta: {},
+		locale: "",
+		url: stubUrl,
+		state: input.state,
+		set: noopStub,
+		flush: noopStub,
+		cleanup: noopStub,
+		component: noopStub,
+		...input.ctx
+	};
+	commit(host, render$1(input.state, ctx));
+	return {
+		host,
+		/**
+		* The host's current `innerHTML`.
+		*
+		* @returns The serialized markup.
+		* @example
+		* result.html();
+		*/
+		html() {
+			return host.innerHTML;
+		},
+		/**
+		* Query the host for the first element matching a selector.
+		*
+		* @param selector - A CSS selector.
+		* @returns The first match, or `null`.
+		* @example
+		* result.find("[data-board]");
+		*/
+		find(selector) {
+			return host.querySelector(selector);
+		},
+		/**
+		* Unmount the Preact tree and remove the host from the document.
+		*
+		* @example
+		* result.unmount();
+		*/
+		unmount() {
+			act(() => render(null, host));
+			host.remove();
+		}
+	};
+}
+//#endregion
+export { mountIsland, renderIsland };