@moku-labs/web 2.0.1 → 2.1.0

package/dist/index.mjs

@@ -1407,6 +1407,22 @@ function route(pattern) {
 	const builder = {
 		pattern: carrier.pattern,
 		_meta: carrier._meta,
+		/**
+		* The named view-transition behaviour set via `.transition()` (live read).
+		*
+		* @returns The transition mode, or undefined when unset (app default applies).
+		*/
+		get _transition() {
+			return carrier._transition;
+		},
+		/**
+		* The scroll behaviour set via `.scroll()` (live read).
+		*
+		* @returns The scroll mode, or undefined when unset (app default applies).
+		*/
+		get _scroll() {
+			return carrier._scroll;
+		},
 		_handlers: carrier._handlers,
 		...createBuilderMethods(set),
 		/**
@@ -1424,6 +1440,38 @@ function route(pattern) {
 		meta(meta) {
 			Object.assign(carrier._meta, meta);
 			return builder;
+		},
+		/**
+		* Declare the view-transition behaviour for navigations TO this route — a typed
+		* framework directive read by the SPA kernel, overriding the app-wide
+		* `spa.viewTransitions` default.
+		*
+		* @param mode - The {@link TransitionMode} (`none`/`crossfade`/`slide`/`morph`).
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/board/{id}/issue/{issueId}").transition("morph");
+		* ```
+		*/
+		transition(mode) {
+			carrier._transition = mode;
+			return builder;
+		},
+		/**
+		* Declare the scroll behaviour for navigations TO this route — a typed framework
+		* directive read by the SPA kernel, overriding the app-wide `spa.scrollRestoration`
+		* default.
+		*
+		* @param mode - The {@link ScrollMode} (`top`/`preserve`).
+		* @returns The same builder for chaining.
+		* @example
+		* ```ts
+		* route("/board/{id}/issue/{issueId}").scroll("preserve");
+		* ```
+		*/
+		scroll(mode) {
+			carrier._scroll = mode;
+			return builder;
 		}
 	};
 	return builder;
@@ -9148,11 +9196,12 @@ function createApi(ctx) {
 		* Programmatically navigate to a path (client runtime; no-op without a DOM).
 		*
 		* @param path - Target path (pathname, optionally with search/hash).
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
 		* @example
 		* app.spa.navigate("/about");
 		*/
-		navigate(path) {
-			ctx.state.kernel?.processNav(path);
+		navigate(path, options) {
+			ctx.state.kernel?.processNav(path, options);
 		},
 		/**
 		* Read the current resolved URL.
@@ -9343,13 +9392,15 @@ let commitVNodeFunction;
 * await loadRenderChunk();
 */
 async function loadRenderChunk() {
-	renderChunk ??= import("./render-yXHc9BWI.mjs");
+	renderChunk ??= import("./render-CkdqOmsm.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).
+* `replaceChildren`, `null` → Preact unmount via the lazy gate (`render(null, host)` —
+* stays re-mountable, the correct "empty" for a persistent render-island), `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 island's `render`.
@@ -9476,6 +9527,18 @@ function buildContext(state, instance) {
 			return instance.route.url;
 		},
 		/**
+		* Programmatically navigate the SPA (delegates to the kernel's navigator through
+		* `state.navigate` — the same decoupled seam as `island`). No-op before the kernel binds.
+		*
+		* @param path - The internal destination path.
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+		* @example
+		* ctx.navigate(ctx.url("issue", { id, issueId }));
+		*/
+		navigate(path, options) {
+			state.navigate?.(path, options);
+		},
+		/**
 		* The live per-instance state (`undefined` for legacy hooks-only islands).
 		*
 		* @returns The current state.
@@ -10095,20 +10158,48 @@ function prefersReducedMotion() {
 * Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
 * THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
 *
+* Named transitions (`transition.types`, e.g. `["slide"]`) are exposed to CSS two ways
+* for the transition's lifetime, so a consumer can style the motion per navigation:
+*   • a `:root[data-view-transition~="slide"]` attribute (works on EVERY View-Transitions
+*     engine, including those without the `types` dictionary form);
+*   • the standards-track `types` option (`:active-view-transition-type(slide)`) when the
+*     engine supports the `startViewTransition({ update, types })` dictionary form.
+* Empty `types` ⇒ the default root crossfade. A shared `view-transition-name` left on an
+* element across the swap (e.g. a card and the panel it opens) morphs one into the other.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
-* @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param transition - The resolved {@link SwapTransition} (enabled + named types).
 * @param beforeCapture - Optional hook run synchronously just before the swap/capture
 *   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
+* runSwap(() => current.replaceWith(next), { enabled: true, types: ["slide"] });
 */
-function runSwap(doSwap, viewTransitions, beforeCapture) {
+function runSwap(doSwap, transition, beforeCapture) {
 	const reduced = prefersReducedMotion();
 	const docWithVt = document;
-	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	const canUseViewTransitions = transition.enabled && !reduced && typeof docWithVt.startViewTransition === "function";
 	beforeCapture?.();
-	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
-	else doSwap();
+	if (!canUseViewTransitions) {
+		doSwap();
+		return;
+	}
+	const root = typeof document === "undefined" ? void 0 : document.documentElement;
+	const hasTypes = transition.types.length > 0;
+	if (hasTypes && root) root.dataset.viewTransition = transition.types.join(" ");
+	const clearMarker = () => {
+		if (hasTypes && root) delete root.dataset.viewTransition;
+	};
+	let result;
+	if (hasTypes) try {
+		result = docWithVt.startViewTransition({
+			update: doSwap,
+			types: transition.types
+		});
+	} catch {
+		result = docWithVt.startViewTransition(doSwap);
+	}
+	else result = docWithVt.startViewTransition(doSwap);
+	Promise.resolve(result?.finished).then(clearMarker).catch(clearMarker);
 }
 /**
 * Replace the `swapSelector` region of the live document with the matching
@@ -10122,22 +10213,22 @@ function runSwap(doSwap, viewTransitions, beforeCapture) {
 *
 * @param doc - The fetched document (DOMParser-parsed) holding the new region.
 * @param swapSelector - CSS selector for the region to replace.
-* @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param transition - The resolved {@link SwapTransition} (enabled + named types).
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
 * @param beforeCapture - Optional hook run synchronously just before the swap/capture
 *   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @returns `true` when the swap was dispatched, `false` when either document lacks the region.
 * @example
-* swapRegion(doc, "main > section", false, () => mountNew());
+* swapRegion(doc, "main > section", { enabled: false, types: [] }, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
+function swapRegion(doc, swapSelector, transition, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return false;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions, beforeCapture);
+	}, transition, beforeCapture);
 	return true;
 }
 /**
@@ -10294,10 +10385,25 @@ function attachRouter(handlers, navigate) {
 const ERROR_PREFIX$1 = "[web]";
 /** Last-resort `swapSelector` when neither config nor defaults supply one. */
 const FALLBACK_SWAP_SELECTOR = "main > section";
+/**
+* Resolve the `viewTransitions` config value into the default {@link TransitionMode}:
+* `true` → `"crossfade"`, `false` → `"none"`, a named mode → itself.
+*
+* @param raw - The raw `viewTransitions` config value (boolean or named mode).
+* @returns The resolved default transition mode.
+* @example
+* resolveDefaultTransition(true); // "crossfade"
+*/
+function resolveDefaultTransition(raw) {
+	if (raw === true) return "crossfade";
+	if (raw === false) return "none";
+	return raw;
+}
 /** Default SPA config (declared as a value — no inline assertion). */
 const defaultSpaConfig = {
 	swapSelector: "main > section",
 	viewTransitions: false,
+	scrollRestoration: "top",
 	progressBar: true,
 	islands: []
 };
@@ -10334,9 +10440,12 @@ function resolveSpaConfig(config) {
 	const swapSelector = config.swapSelector ?? defaultSpaConfig.swapSelector ?? FALLBACK_SWAP_SELECTOR;
 	if (swapSelector.trim() === "") throw new Error(`${ERROR_PREFIX$1} spa.swapSelector must be a non-empty string.\n  Set a CSS selector for the page region to swap (e.g. "main > section").`);
 	if (!isValidSelector(swapSelector)) throw new Error(`${ERROR_PREFIX$1} spa.swapSelector is not a valid CSS selector: "${swapSelector}".\n  Provide a syntactically valid selector.`);
+	const defaultTransition = resolveDefaultTransition(config.viewTransitions ?? false);
 	return {
 		swapSelector,
-		viewTransitions: config.viewTransitions ?? false,
+		viewTransitions: defaultTransition !== "none",
+		defaultTransition,
+		scrollRestoration: config.scrollRestoration ?? "top",
 		progressBar: config.progressBar ?? true,
 		islands: config.islands ?? []
 	};
@@ -10361,6 +10470,7 @@ function createState(_ctx) {
 		currentUrl: "",
 		destroyRouter: null,
 		started: false,
+		navigate: null,
 		kernel: null
 	};
 }
@@ -10431,6 +10541,52 @@ function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
 	let pendingScrollToTop = true;
+	let pendingTransition = resolveTransition(resolved.defaultTransition);
+	/**
+	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
+	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
+	* crossfade); any other mode ⇒ enabled with that name as the View-Transition type. The
+	* app-wide `viewTransitions` enabled flag gates everything: when it is off AND the route
+	* declares no transition, no transition runs.
+	*
+	* @param mode - The effective transition mode for this navigation.
+	* @returns The resolved swap descriptor (enabled + named types).
+	* @example
+	* pendingTransition = resolveTransition("slide");
+	*/
+	function resolveTransition(mode) {
+		if (mode === "none") return {
+			enabled: false,
+			types: []
+		};
+		if (mode === "crossfade") return {
+			enabled: true,
+			types: []
+		};
+		return {
+			enabled: true,
+			types: [mode]
+		};
+	}
+	/**
+	* Resolve the per-navigation scroll + transition intent from the DESTINATION route,
+	* falling back to the app-wide defaults. A route's `.scroll()`/`.transition()` win; an
+	* explicit per-call `scrollOverride` (from `ctx.navigate`/`app.spa.navigate`) wins over
+	* the route. `forwardScrollToTop` carries the navigation-type intent (forward ⇒ `true`,
+	* traverse ⇒ `false`); a `"preserve"` resolution forces no scroll-to-top either way.
+	*
+	* @param pathname - The destination pathname (search stripped for matching).
+	* @param forwardScrollToTop - Whether this nav would scroll to top by default (forward vs traverse).
+	* @param scrollOverride - An explicit per-call scroll override, if any.
+	* @example
+	* applyNavIntent("/board/abc/issue/1", true, undefined);
+	*/
+	const applyNavIntent = (pathname, forwardScrollToTop, scrollOverride) => {
+		const route = deps.router.match(pathname.split("?")[0] ?? pathname)?.route;
+		const scrollMode = scrollOverride ?? route?._scroll ?? resolved.scrollRestoration;
+		pendingScrollToTop = forwardScrollToTop && scrollMode !== "preserve";
+		pendingTransition = resolveTransition(route?._transition ?? resolved.defaultTransition);
+	};
 	/**
 	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
 	* For a forward nav it scrolls to top BEFORE the swap (and, with view transitions on,
@@ -10496,7 +10652,7 @@ function createSpaKernel(state, config, emit, deps) {
 		const doc = new DOMParser().parseFromString(html, "text/html");
 		syncHead(deps.head, doc);
 		unmountPageSpecific(state, emit);
-		if (!swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
+		if (!swapRegion(doc, resolved.swapSelector, pendingTransition, () => {
 			const routeSlice = islandRouteContext(pathname);
 			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 			notifyNavEnd(state, routeSlice);
@@ -10596,7 +10752,7 @@ function createSpaKernel(state, config, emit, deps) {
 	const commitDataRender = async (pathname, resolvedRender, signal) => {
 		if (signal?.aborted) return;
 		const { route, vnode, routeContext, region } = resolvedRender;
-		const { renderVNode } = await import("./render-yXHc9BWI.mjs");
+		const { renderVNode } = await import("./render-CkdqOmsm.mjs");
 		if (signal?.aborted) return;
 		syncDataHead(deps.head, route, routeContext);
 		unmountPageSpecific(state, emit);
@@ -10615,7 +10771,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 			notifyNavEnd(state, routeSlice);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
+		runSwap(renderAndMount, pendingTransition, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10665,7 +10821,7 @@ function createSpaKernel(state, config, emit, deps) {
 			return;
 		}
 		const { vnode, region } = resolvedRender;
-		const { renderVNode } = await import("./render-yXHc9BWI.mjs");
+		const { renderVNode } = await import("./render-CkdqOmsm.mjs");
 		renderVNode(vnode, region);
 		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 	};
@@ -10680,12 +10836,14 @@ function createSpaKernel(state, config, emit, deps) {
 	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @param signal - Aborts when this navigation is superseded (`navEvent.signal`);
 	*   a superseded navigation never applies its swap (no stale last-write-wins).
+	* @param scrollOverride - An explicit per-call scroll override (from `ctx.navigate`/
+	*   `app.spa.navigate`); wins over the destination route's `.scroll()` + the app default.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname, scrollToTop = true, signal) => {
-		pendingScrollToTop = scrollToTop;
+	const navigate = async (pathname, scrollToTop = true, signal, scrollOverride) => {
+		applyNavIntent(pathname, scrollToTop, scrollOverride);
 		handleStart(pathname);
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname, signal)) return;
 		if (signal?.aborted) return;
@@ -10701,6 +10859,10 @@ function createSpaKernel(state, config, emit, deps) {
 		init() {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
+			state.navigate = (path, options) => {
+				if (typeof document === "undefined") return;
+				navigate(path, true, void 0, options?.scroll).catch(() => {});
+			};
 		},
 		/**
 		* Boot navigation interception + initial scan (throws if already started).
@@ -10731,15 +10893,17 @@ function createSpaKernel(state, config, emit, deps) {
 			registerIsland(state, island);
 		},
 		/**
-		* Process a navigation to `path` (fetch then swap; full reload on error).
+		* Process a navigation to `path` (fetch then swap; full reload on error). An optional
+		* per-call `scroll` override flows through to the swap's scroll intent.
 		*
 		* @param path - The target path to navigate to.
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
 		* @example
 		* kernel.processNav("/about");
 		*/
-		processNav(path) {
+		processNav(path, options) {
 			if (typeof document === "undefined") return;
-			navigate(path).catch(() => {});
+			navigate(path, true, void 0, options?.scroll).catch(() => {});
 		},
 		/**
 		* Scan the swap region and mount islands for matching elements.
@@ -10831,6 +10995,255 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/channel.ts
+/** Default keepalive interval (ms). */
+const DEFAULT_KEEPALIVE_MS = 3e4;
+/** Default first reconnect delay (ms). */
+const DEFAULT_RECONNECT_BASE_MS = 500;
+/** Default reconnect ceiling (ms). */
+const DEFAULT_RECONNECT_MAX_MS = 8e3;
+/**
+* Default frame parser — `JSON.parse`, dropping frames that fail to parse.
+*
+* @param raw - The raw text frame.
+* @returns The parsed value, or undefined on a parse error.
+* @example
+* const msg = defaultParse<BoardPatch>('{"type":"x"}');
+*/
+function defaultParse(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+/**
+* Create a live realtime channel — a single self-healing WebSocket bound to one channel
+* `id` at a time, with refcounted subscription, auto-reconnect, an optional keepalive, a
+* pre-seed buffer, and an optimistic local-echo path. See the file header for the model.
+*
+* @param options - The channel configuration (see {@link ChannelOptions}).
+* @returns The {@link Channel} control surface.
+* @example
+* const board = createChannel<BoardPatch>({ url: (id) => `wss://host/ws/board/${id}` });
+*/
+function createChannel(options) {
+	const parse = options.parse ?? defaultParse;
+	const reconnectCfg = options.reconnect === false ? void 0 : options.reconnect ?? {};
+	const baseMs = reconnectCfg?.baseMs ?? DEFAULT_RECONNECT_BASE_MS;
+	const maxMs = reconnectCfg?.maxMs ?? DEFAULT_RECONNECT_MAX_MS;
+	const keepEveryMs = options.keepAlive?.everyMs ?? DEFAULT_KEEPALIVE_MS;
+	/** The live socket, or undefined when disconnected. */
+	let socket;
+	/** The id we WANT to stay subscribed to (drives reconnect); undefined ⇒ intentionally off. */
+	let desiredId;
+	/** Whether the consumer has seeded — gates live delivery vs. buffering. */
+	let seeded = false;
+	/** Frames received before {@link Channel.seed}, replayed in arrival order on seed. */
+	let buffer = [];
+	/** Message handlers fanned out on every delivered frame. */
+	const handlers = /* @__PURE__ */ new Set();
+	/** Consecutive closes since the last clean open — drives the backoff delay. */
+	let reconnectAttempts = 0;
+	/** Pending reconnect timer handle, or undefined when none is scheduled. */
+	let reconnectTimer;
+	/** Keepalive interval handle, or undefined when off. */
+	let keepAliveTimer;
+	/**
+	* Fan a message out to every handler now, or queue it when buffering before seed.
+	*
+	* @param message - The message to deliver or buffer.
+	* @example
+	* deliver(patch);
+	*/
+	function deliver(message) {
+		if (options.bufferUntilSeed && !seeded) {
+			buffer.push(message);
+			return;
+		}
+		for (const handler of handlers) handler(message);
+	}
+	/**
+	* Parse + route an incoming frame, dropping the keepalive reply and unparseable frames.
+	*
+	* @param event - The socket message event.
+	* @example
+	* socket.addEventListener("message", dispatch);
+	*/
+	function dispatch(event) {
+		if (typeof event.data !== "string") return;
+		if (options.keepAlive?.ignore !== void 0 && event.data === options.keepAlive.ignore) return;
+		const message = parse(event.data);
+		if (message !== void 0) deliver(message);
+	}
+	/**
+	* Send the keepalive frame when the socket is open (no-op otherwise).
+	*
+	* @example
+	* ping();
+	*/
+	function ping() {
+		if (options.keepAlive && socket?.readyState === WebSocket.OPEN) socket.send(options.keepAlive.send);
+	}
+	/**
+	* Open the live socket for {@link desiredId}, wiring delivery + auto-reconnect. Shared by
+	* the first connect and every backoff retry.
+	*
+	* @example
+	* openSocket();
+	*/
+	function openSocket() {
+		const id = desiredId;
+		if (id === void 0 || typeof WebSocket === "undefined") return;
+		const ws = new WebSocket(options.url(id));
+		socket = ws;
+		ws.addEventListener("message", dispatch);
+		ws.addEventListener("open", () => {
+			reconnectAttempts = 0;
+		});
+		ws.addEventListener("close", () => {
+			if (socket !== ws || desiredId === void 0) return;
+			socket = void 0;
+			if (reconnectCfg) scheduleReconnect();
+		});
+	}
+	/**
+	* Schedule a reconnect to {@link desiredId} with exponential backoff (capped), unless one
+	* is already pending or reconnection is off.
+	*
+	* @example
+	* scheduleReconnect();
+	*/
+	function scheduleReconnect() {
+		if (reconnectTimer !== void 0 || desiredId === void 0) return;
+		const delay = Math.min(baseMs * 2 ** reconnectAttempts, maxMs);
+		reconnectAttempts += 1;
+		reconnectTimer = setTimeout(() => {
+			reconnectTimer = void 0;
+			if (desiredId !== void 0) openSocket();
+		}, delay);
+	}
+	/**
+	* Tear down the live socket + timers and re-arm the pre-seed buffer, keeping handlers so a
+	* later connect resumes delivering to them. Clearing {@link desiredId} first marks the drop
+	* intentional (no reconnect).
+	*
+	* @example
+	* teardown();
+	*/
+	function teardown() {
+		desiredId = void 0;
+		if (reconnectTimer !== void 0) {
+			clearTimeout(reconnectTimer);
+			reconnectTimer = void 0;
+		}
+		if (keepAliveTimer !== void 0) {
+			clearInterval(keepAliveTimer);
+			keepAliveTimer = void 0;
+		}
+		if (socket) {
+			socket.removeEventListener("message", dispatch);
+			socket.close();
+			socket = void 0;
+		}
+		seeded = false;
+		buffer = [];
+	}
+	/**
+	* Open (or switch) the socket to `id`, re-arming the keepalive + pre-seed buffer.
+	*
+	* @param id - The channel id to connect to.
+	* @example
+	* connect("board-123");
+	*/
+	function connect(id) {
+		const alive = socket?.readyState === WebSocket.CONNECTING || socket?.readyState === WebSocket.OPEN;
+		if (desiredId === id && alive) return;
+		teardown();
+		desiredId = id;
+		seeded = false;
+		buffer = [];
+		reconnectAttempts = 0;
+		openSocket();
+		if (options.keepAlive) keepAliveTimer = setInterval(ping, keepEveryMs);
+	}
+	return {
+		/**
+		* Subscribe to `id`, connecting (or switching) the single active socket. Refcounted.
+		*
+		* @param id - The channel id to subscribe to.
+		* @param handler - Called with each delivered message.
+		* @returns A function that removes this handler (last out disconnects).
+		* @example
+		* const off = board.subscribe(boardId, (patch) => applyPatch(ctx, patch));
+		*/
+		subscribe(id, handler) {
+			handlers.add(handler);
+			connect(id);
+			return () => {
+				handlers.delete(handler);
+				if (handlers.size === 0) teardown();
+			};
+		},
+		/**
+		* Mark `id` seeded and flush the pre-seed buffer (no-op unless it is the active id).
+		*
+		* @param id - The channel id whose buffer to flush.
+		* @example
+		* board.seed(boardId);
+		*/
+		seed(id) {
+			if (id !== desiredId || seeded) return;
+			seeded = true;
+			const queued = buffer;
+			buffer = [];
+			for (const message of queued) for (const handler of handlers) handler(message);
+		},
+		/**
+		* Deliver a message to the local handlers immediately (optimistic echo) for the active id.
+		*
+		* @param id - The channel id (ignored unless it is the active id).
+		* @param message - The message to deliver locally now.
+		* @example
+		* board.deliverLocal(boardId, { type: "issue.moved", issueId });
+		*/
+		deliverLocal(id, message) {
+			if (id !== desiredId) return;
+			for (const handler of handlers) handler(message);
+		},
+		/**
+		* Send a raw text frame over the live socket (no-op when not open).
+		*
+		* @param raw - The frame to send.
+		* @example
+		* board.send("ping");
+		*/
+		send(raw) {
+			if (socket?.readyState === WebSocket.OPEN) socket.send(raw);
+		},
+		/**
+		* The currently-subscribed channel id, or undefined when disconnected.
+		*
+		* @returns The active id, or undefined.
+		* @example
+		* board.current();
+		*/
+		current() {
+			return desiredId;
+		},
+		/**
+		* Close the socket, cancel reconnect, and clear all handlers.
+		*
+		* @example
+		* board.disconnect();
+		*/
+		disconnect() {
+			handlers.clear();
+			teardown();
+		}
+	};
+}
+//#endregion
 //#region src/plugins/spa/lazy-embed.ts
 /**
 * @file `lazyEmbed` island — activates the static embed facades emitted by the
@@ -13176,4 +13589,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$5 as Head, types_exports$6 as Router, types_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$5 as Head, types_exports$6 as Router, types_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/{render-yXHc9BWI.mjs → render-CkdqOmsm.mjs}

@@ -39,12 +39,18 @@ function renderVNode(vnode, region) {
 * scheduler in `islands.ts`), so an app whose islands never return a VNode never
 * pulls Preact's `render` into its main bundle.
 *
-* @param vnode - The VNode produced by an island's `render(state, ctx)`.
+* Pass `null` to render NOTHING while keeping the host mountable: Preact's
+* `render(null, host)` unmounts the retained vdom AND resets its pointer, so a later
+* non-empty `commitVNode` re-mounts cleanly. (A persistent render-island that instead set
+* `host.innerHTML = ""` to "go empty" would desync Preact's retained vdom and never re-commit.)
+*
+* @param vnode - The VNode produced by an island's `render(state, ctx)`, or `null` to unmount.
 * @param host - The island's host element to render into.
 * @example
 * ```ts
 * const { commitVNode } = await import("./render");
 * commitVNode(h(BoardView, { snapshot }), host);
+* commitVNode(null, host); // close/empty: unmount but stay re-mountable
 * ```
 */
 function commitVNode(vnode, host) {

package/dist/{render-DHUcHCYs.cjs → render-rf8FAg_Z.cjs}

@@ -39,12 +39,18 @@ function renderVNode(vnode, region) {
 * scheduler in `islands.ts`), so an app whose islands never return a VNode never
 * pulls Preact's `render` into its main bundle.
 *
-* @param vnode - The VNode produced by an island's `render(state, ctx)`.
+* Pass `null` to render NOTHING while keeping the host mountable: Preact's
+* `render(null, host)` unmounts the retained vdom AND resets its pointer, so a later
+* non-empty `commitVNode` re-mounts cleanly. (A persistent render-island that instead set
+* `host.innerHTML = ""` to "go empty" would desync Preact's retained vdom and never re-commit.)
+*
+* @param vnode - The VNode produced by an island's `render(state, ctx)`, or `null` to unmount.
 * @param host - The island's host element to render into.
 * @example
 * ```ts
 * const { commitVNode } = await import("./render");
 * commitVNode(h(BoardView, { snapshot }), host);
+* commitVNode(null, host); // close/empty: unmount but stay re-mountable
 * ```
 */
 function commitVNode(vnode, host) {