@moku-labs/web 1.13.1 → 1.14.0

package/dist/index.mjs

@@ -1071,6 +1071,38 @@ function dynamicSegmentCount(pattern) {
 	return count;
 }
 /**
+* Whether a route is rendered ENTIRELY on the client in `spa` mode: a dynamic route
+* (≥1 non-lang param) that declares no build-time `.generate()` enumerator, so its
+* concrete param paths are unknown until runtime.
+*
+* The build SKIPS such a route — emitting a static page for it would write one
+* param-less shell whose path (`/b/{id}`) matches no file (a 404) and carries no
+* param for the islands to read. Instead the SPA client-renders it from the URL on
+* boot and on navigation. Build and client share this ONE predicate (the same way
+* `dynamicSegmentCount`/`bySpecificity` are shared) so the two sides can never
+* disagree about which routes are pre-rendered vs. client-only.
+*
+* Static routes (`/`) and dynamic routes WITH `.generate()` are pre-rendered as
+* usual and so are NOT client-only. In `ssg`/`hybrid` mode nothing is client-only
+* (the build pre-renders every route), so this is always `false` outside `spa`.
+*
+* @param mode - The global render mode (`router.mode()`).
+* @param route - The route to test (only its `pattern` + `.generate()` presence are read).
+* @param route.pattern - The route's URL pattern string.
+* @param route._handlers - The route's handler bag.
+* @param route._handlers.generate - The build-only static-paths enumerator, if any (presence only).
+* @returns `true` when the route is client-only (spa mode, dynamic, no `.generate()`).
+* @example
+* ```ts
+* isClientOnlyRoute("spa", { pattern: "/b/{id}", _handlers: {} }); // true
+* isClientOnlyRoute("spa", { pattern: "/", _handlers: {} }); // false (static)
+* isClientOnlyRoute("hybrid", { pattern: "/b/{id}", _handlers: {} }); // false (not spa)
+* ```
+*/
+function isClientOnlyRoute(mode, route) {
+	return mode === "spa" && route._handlers.generate === void 0 && dynamicSegmentCount(route.pattern) > 0;
+}
+/**
 * Comparator that orders two routes most-specific-first (fewest dynamic segments
 * first). Equal specificity yields `0` so a stable sort preserves declaration
 * order — the exact ordering the compiled matcher table uses, guaranteeing
@@ -4515,16 +4547,23 @@ function resolveEntry(byPattern, definition) {
 * generate context is the spec `{ locale, require, has }`, so a `.generate()` handler
 * pulls sibling APIs the spec way.
 *
+* In `spa` mode a client-only route (dynamic, no `.generate()`) is SKIPPED entirely
+* (`[]`) — it is rendered on the client from the URL, so emitting a static param-less
+* shell here would only write a file at the wrong path (a 404 for any real param path)
+* carrying no param. See {@link isClientOnlyRoute}.
+*
 * @param definition - The route definition from the manifest.
 * @param locale - The active locale to generate param sets for.
+* @param mode - The global render mode (`router.mode()`); gates the spa client-only skip.
 * @param ctx - Plugin context (provides `require`/`has` for the generate context).
-* @returns The param sets for this route+locale (`[{}]` when there is no `.generate()`).
+* @returns The param sets for this route+locale (`[{}]` when there is no `.generate()`; `[]` when client-only).
 * @example
 * ```ts
-* const paramSets = await generateParamSets(def, "en", ctx);
+* const paramSets = await generateParamSets(def, "en", "hybrid", ctx);
 * ```
 */
-async function generateParameterSets(definition, locale, ctx) {
+async function generateParameterSets(definition, locale, mode, ctx) {
+	if (isClientOnlyRoute(mode, definition)) return [];
 	const generateContext = {
 		locale,
 		require: ctx.require,
@@ -4548,21 +4587,22 @@ async function generateParameterSets(definition, locale, ctx) {
 * @param locales - Active locale codes from i18n.
 * @param defaultLocale - The i18n default locale (kept when locales collapse to one file).
 * @param byPattern - Pattern→compiled-`TypedRoute` map (see {@link makeEntryMap}).
+* @param mode - The global render mode (`router.mode()`); gates the spa client-only skip.
 * @param ctx - Plugin context (provides `require`/`has` for the generate context).
 * @returns The flattened, file-deduplicated list of page instances for this route.
 * @example
 * ```ts
-* await expandRoute(def, ["en"], "en", byPattern, ctx);
+* await expandRoute(def, ["en"], "en", byPattern, "hybrid", ctx);
 * ```
 */
-async function expandRoute(definition, locales, defaultLocale, byPattern, ctx) {
+async function expandRoute(definition, locales, defaultLocale, byPattern, mode, ctx) {
 	const entry = resolveEntry(byPattern, definition);
 	const { name } = entry;
 	const orderedLocales = [defaultLocale, ...locales.filter((locale) => locale !== defaultLocale)];
 	const instances = [];
 	const claimedFiles = /* @__PURE__ */ new Set();
 	for (const locale of orderedLocales) {
-		const parameterSets = await generateParameterSets(definition, locale, ctx);
+		const parameterSets = await generateParameterSets(definition, locale, mode, ctx);
 		for (const raw of parameterSets) {
 			const params = raw ?? {};
 			const file = entry.toFile(params);
@@ -4685,8 +4725,8 @@ function composeHeadHtml(ctx, instance, url, routeContext, data) {
 * layout is NOT re-applied on navigation), then serialize with
 * preact-render-to-string. Returns `""` when the route has no `.render()`.
 *
-* @param definition - The route definition (provides `.render()`/`.layout()`/`._meta`).
-* @param routeContext - The route context (params/data/locale/url) — extended with `meta` for the layout.
+* @param definition - The route definition (provides `.render()`/`.layout()`).
+* @param routeContext - The route context (params/data/locale/meta/url); `meta` flows to the layout.
 * @returns The SSR-rendered body HTML, or `""` when the route has no `.render()`.
 * @example
 * ```ts
@@ -4696,11 +4736,7 @@ function composeHeadHtml(ctx, instance, url, routeContext, data) {
 function renderBody(definition, routeContext) {
 	const vnode = definition._handlers.render?.(routeContext);
 	if (!vnode) return "";
-	const layoutContext = {
-		...routeContext,
-		meta: definition._meta
-	};
-	return renderToString(definition._handlers.layout ? definition._handlers.layout(layoutContext, vnode) : vnode);
+	return renderToString(definition._handlers.layout ? definition._handlers.layout(routeContext, vnode) : vnode);
 }
 /**
 * Hash a page's render inputs (its loaded data) for the render cache. `null` when the
@@ -4834,6 +4870,7 @@ async function renderInstance(ctx, instance, shell, reuse) {
 		params,
 		data,
 		locale,
+		meta: definition._meta,
 		url: (routeName, routeParams = {}) => router.toUrl(routeName, routeParams)
 	};
 	const parts = {
@@ -4896,15 +4933,16 @@ async function prepareShell(ctx) {
 * @param locales - Active locale codes from i18n.
 * @param defaultLocale - The i18n default locale (kept when a route's locales collapse).
 * @param byPattern - Pattern→compiled-`TypedRoute` map (see {@link makeEntryMap}).
+* @param mode - The global render mode (`router.mode()`); gates the spa client-only skip.
 * @param ctx - Plugin context (provides `require`/`has` for generate contexts).
 * @returns The flattened list of page instances to render.
 * @example
 * ```ts
-* const instances = await expandAllInstances(manifest, ["en"], "en", byPattern, ctx);
+* const instances = await expandAllInstances(manifest, ["en"], "en", byPattern, "hybrid", ctx);
 * ```
 */
-async function expandAllInstances(manifest, locales, defaultLocale, byPattern, ctx) {
-	return (await Promise.all(manifest.map((definition) => expandRoute(definition, locales, defaultLocale, byPattern, ctx)))).flat();
+async function expandAllInstances(manifest, locales, defaultLocale, byPattern, mode, ctx) {
+	return (await Promise.all(manifest.map((definition) => expandRoute(definition, locales, defaultLocale, byPattern, mode, ctx)))).flat();
 }
 /**
 * Persist per-page client-data sidecars when the app opts into client navigation
@@ -5014,14 +5052,15 @@ async function renderInBatches(items, batchSize, worker) {
 async function renderPages(ctx, options) {
 	const reuse = options?.reuse === true;
 	const router = ctx.require(routerPlugin);
+	const mode = router.mode();
 	const manifest = router.manifest();
 	ctx.state.manifest = [...manifest];
 	const locales = ctx.require(i18nPlugin).locales();
 	const byPattern = makeEntryMap(router);
 	if (!reuse) ctx.state.renderCache.clear();
 	const shell = await prepareShell(ctx);
-	const rendered = (await renderInBatches(await expandAllInstances(manifest, locales, shell.defaultLocale, byPattern, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse))).flat();
-	await writeDataSidecars(ctx, rendered, router.mode());
+	const rendered = (await renderInBatches(await expandAllInstances(manifest, locales, shell.defaultLocale, byPattern, mode, ctx), reuse ? INCREMENTAL_BATCH_SIZE : RENDER_BATCH_SIZE, (instance) => renderInstance(ctx, instance, shell, reuse))).flat();
+	await writeDataSidecars(ctx, rendered, mode);
 	ctx.log.debug("build:pages", { count: rendered.length });
 	return {
 		pageCount: rendered.length,
@@ -9043,6 +9082,23 @@ const ERROR_PREFIX$2 = "[web]";
 /** The set of legal hook names, frozen for O(1) membership checks. */
 const HOOK_NAME_SET = new Set(COMPONENT_HOOK_NAMES);
 /**
+* 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
+};
+/**
 * Validate a single hook entry: its key must be a known hook name and its value
 * must be a function. Throws fail-fast on the first violation.
 *
@@ -9130,18 +9186,25 @@ function runHook(instance, hook, ctx) {
 	instance.def.hooks[hook]?.(ctx);
 }
 /**
-* Builds the component context handed to a hook (the bound element + page data).
+* Builds the component context handed to a hook: the bound element + page data, merged
+* with the matched route's slice (params/meta/locale/url). Defaults to {@link EMPTY_ROUTE}
+* when no route is supplied (headless, tests, public `scan()`).
 *
 * @param element - The element the instance is bound to.
 * @param data - The current page data payload.
+* @param route - The matched-route slice for the current URL.
 * @returns The hook context.
 * @example
-* const ctx = makeContext(element, data);
+* const ctx = makeContext(element, data, route);
 */
-function makeContext(element, data) {
+function makeContext(element, data, route = EMPTY_ROUTE) {
 	return {
 		el: element,
-		data
+		data,
+		params: route.params,
+		meta: route.meta,
+		locale: route.locale,
+		url: route.url
 	};
 }
 /**
@@ -9155,17 +9218,18 @@ function makeContext(element, data) {
 * @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);
+* mountElement(state, emit, swapArea, data, element, route);
 */
-function mountElement(state, emit, swapArea, data, element) {
+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 = createInstance(definition, element, swapArea ? !swapArea.contains(element) : true);
-	const ctx = makeContext(element, data);
+	const ctx = makeContext(element, data, route);
 	runHook(instance, "onCreate", ctx);
 	runHook(instance, "onMount", ctx);
 	state.instances.set(element, instance);
@@ -9183,14 +9247,15 @@ function mountElement(state, emit, swapArea, data, element) {
 * @param state - The plugin state (registeredComponents + instances).
 * @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");
+* scanAndMount(state, emit, "main > section", route);
 */
-function scanAndMount(state, emit, swapSelector) {
+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);
+	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`
@@ -9256,12 +9321,13 @@ function notifyNavStart(state) {
 * instances were already destroyed and re-created by the swap).
 *
 * @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);
+* notifyNavEnd(state, route);
 */
-function notifyNavEnd(state) {
+function notifyNavEnd(state, route = EMPTY_ROUTE) {
 	const data = typeof document === "undefined" ? {} : extractPageData(document);
-	for (const [element, instance] of state.instances) if (instance.persistent) runHook(instance, "onNavEnd", makeContext(element, data));
+	for (const [element, instance] of state.instances) if (instance.persistent) runHook(instance, "onNavEnd", makeContext(element, data, route));
 }
 //#endregion
 //#region src/plugins/spa/head.ts
@@ -9904,6 +9970,26 @@ function createSpaKernel(state, config, emit, deps) {
 		});
 	};
 	/**
+	* Build the matched-route slice (params/meta/locale/url) for the component context at `path`,
+	* so islands read their route's params/meta directly. An unmatched path yields an empty slice.
+	*
+	* @param path - The URL (pathname + search) to match.
+	* @returns The route slice for the matched route.
+	* @example
+	* scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(pathname));
+	*/
+	const componentRouteContext = (path) => {
+		const matchPath = path.split("?")[0] ?? path;
+		const hit = deps.router.match(matchPath);
+		const locale = hit?.params.lang ?? (typeof document === "undefined" ? "" : document.documentElement.lang) ?? "";
+		return {
+			params: hit?.params ?? {},
+			meta: hit?.route._meta ?? {},
+			locale,
+			url: (name, params = {}) => deps.router.toUrl(name, params)
+		};
+	};
+	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	* When the region cannot be swapped (either document lacks the swap selector)
 	* the SPA nav cannot complete — the head is already synced and the islands torn
@@ -9921,8 +10007,9 @@ function createSpaKernel(state, config, emit, deps) {
 		syncHead(deps.head, doc);
 		unmountPageSpecific(state, emit);
 		if (!swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
-			scanAndMount(state, emit, resolved.swapSelector);
-			notifyNavEnd(state);
+			const routeSlice = componentRouteContext(pathname);
+			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+			notifyNavEnd(state, routeSlice);
 		}, applyPendingScroll)) {
 			handleError();
 			location.href = pathname;
@@ -9976,17 +10063,22 @@ function createSpaKernel(state, config, emit, deps) {
 	* const resolved = await resolveDataRender("/en/world/");
 	*/
 	const resolveDataRender = async (pathname) => {
-		if (!deps.dataAt) return false;
 		const matchPath = pathname.split("?")[0] ?? pathname;
 		const hit = deps.router.match(matchPath);
 		if (!hit?.route._handlers.render) return false;
-		const data = await deps.dataAt(pathname);
-		if (data === null) return false;
+		let data = {};
+		if (!isClientOnlyRoute(deps.router.mode(), hit.route)) {
+			if (!deps.dataAt) return false;
+			const persisted = await deps.dataAt(pathname);
+			if (persisted === null) return false;
+			data = persisted;
+		}
 		const locale = hit.params.lang ?? document.documentElement.lang ?? "";
 		const routeContext = {
 			params: hit.params,
 			data,
 			locale,
+			meta: hit.route._meta,
 			url: (routeName, routeParams = {}) => deps.router.toUrl(routeName, routeParams)
 		};
 		const vnode = hit.route._handlers.render(routeContext);
@@ -10018,6 +10110,7 @@ function createSpaKernel(state, config, emit, deps) {
 		if (signal?.aborted) return;
 		syncDataHead(deps.head, route, routeContext);
 		unmountPageSpecific(state, emit);
+		const routeSlice = componentRouteContext(pathname);
 		/**
 		* Render the VNode into the region and re-mount its islands in one paint — the
 		* swap body handed to `runSwap` (optionally wrapped in a View Transition).
@@ -10029,8 +10122,8 @@ function createSpaKernel(state, config, emit, deps) {
 		*/
 		const renderAndMount = () => {
 			renderVNode(vnode, region);
-			scanAndMount(state, emit, resolved.swapSelector);
-			notifyNavEnd(state);
+			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+			notifyNavEnd(state, routeSlice);
 		};
 		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
@@ -10063,6 +10156,30 @@ function createSpaKernel(state, config, emit, deps) {
 		}
 	};
 	/**
+	* Initial-load render for a spa client-only route (dynamic, no `.generate()`): the build emitted
+	* no static HTML for it, so the host served a fallback shell. Client-render the matched route into
+	* the swap region from the URL, then mount its islands — the deep-link / refresh paint. Unlike a
+	* navigation there is nothing to unmount and no `spa:navigated` to emit. If the route cannot be
+	* resolved (defensive — a matched client-only route always resolves), fall back to mounting the
+	* served body so boot still wires up whatever islands the shell does carry.
+	*
+	* @param pathname - The current document path (pathname + search).
+	* @example
+	* await bootRender("/b/abc123");
+	*/
+	const bootRender = async (pathname) => {
+		const routeSlice = componentRouteContext(pathname);
+		const resolvedRender = await resolveDataRender(pathname);
+		if (resolvedRender === false) {
+			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+			return;
+		}
+		const { vnode, region } = resolvedRender;
+		const { renderVNode } = await import("./render-BNe0s7fr.mjs");
+		renderVNode(vnode, region);
+		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
+	};
+	/**
 	* Unified navigation: try the client DATA path first (only when the `data`
 	* plugin is composed), then fall back to HTML-over-fetch (which itself falls
 	* back to a full `location.href` reload). Injected into the router so every
@@ -10107,7 +10224,10 @@ function createSpaKernel(state, config, emit, deps) {
 			progress = createProgressBar(resolved.progressBar);
 			state.currentUrl = currentLocationUrl();
 			state.destroyRouter = attachRouter(handlers, navigate);
-			scanAndMount(state, emit, resolved.swapSelector);
+			const matchPath = state.currentUrl.split("?")[0] ?? state.currentUrl;
+			const hit = deps.router.match(matchPath);
+			if (hit?.route._handlers.render && isClientOnlyRoute(deps.router.mode(), hit.route)) bootRender(state.currentUrl);
+			else scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(state.currentUrl));
 			state.started = true;
 		},
 		/**
@@ -10138,7 +10258,7 @@ function createSpaKernel(state, config, emit, deps) {
 		* kernel.scan();
 		*/
 		scan() {
-			scanAndMount(state, emit, resolved.swapSelector);
+			scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(state.currentUrl));
 		},
 		/**
 		* Tear down router listeners, dispose all instances, reset boot state.

package/package.json

@@ -126,5 +126,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.13.1"
+  "version": "1.14.0"
 }