@moku-labs/web 1.13.1 → 1.14.0

package/dist/browser.d.mts

@@ -287,7 +287,10 @@ interface RouteState<P extends string = string, D = unknown> {
   /** Loaded data type produced by `.load()` (widened only by `.load()`). */
   readonly data: D;
 }
-/** Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return. */
+/**
+ * Render-time context handed to `.render()` / `.head()`; `data` is `.load()`'s return,
+ * `meta` the route's `.meta()` bag.
+ */
 interface RouteContext<S extends RouteState> {
   /** Resolved path params. */
   readonly params: S["params"];
@@ -295,6 +298,13 @@ interface RouteContext<S extends RouteState> {
   readonly data: S["data"];
   /** Active locale for this render. */
   readonly locale: string;
+  /**
+   * The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). Available in `.render()` and
+   * `.head()`, identically at build and on the client — `meta` is compiled into the route and
+   * shipped in the client manifest, so a client-only route (dynamic, no `.generate()`, whose
+   * `.load()` data is `{}` on the client) can feed static per-route config into its render.
+   */
+  readonly meta: Record<string, unknown>;
   /**
    * Build a link to a named route by pattern substitution — the framework delivers
    * this on the context (same output as `app.router.toUrl`), so render/head build
@@ -375,21 +385,16 @@ interface GenerateContext {
   readonly has: (name: string) => boolean;
 }
 /**
- * Context handed to a route's `.layout()` wrapper: the render-time
- * {@link RouteContext} plus the route's `.meta()` bag, so persistent chrome (e.g. a
- * TopBar/TabNav) can read `locale` and `meta.activeTab`. Distinct from
- * `RouteContext` because the layout is the only handler that needs `meta`; keeping
- * it on its own type leaves `.render()`/`.head()` contexts unchanged.
+ * Context handed to a route's `.layout()` wrapper — identical to {@link RouteContext}
+ * (which now carries `meta` for every handler). Retained as a named alias so existing
+ * `.layout((ctx, children) => …)` typings keep compiling.
  *
  * @remarks
  * The layout is applied in the SSG render path ONLY. On client (SPA) navigation the
- * chrome is persistent and the layout is intentionally NOT re-applied — only the
- * inner swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
+ * chrome is persistent and the layout is intentionally NOT re-applied — only the inner
+ * swap region is replaced. See `build`'s pages phase and `spa`'s kernel.
  */
-interface LayoutContext<S extends RouteState> extends RouteContext<S> {
-  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
-  readonly meta: Record<string, unknown>;
-}
+type LayoutContext<S extends RouteState> = RouteContext<S>;
 /** Head metadata produced by a route's `.head()` handler. */
 interface HeadConfig$1 {
   /** Document title. */
@@ -944,12 +949,25 @@ interface ResolvedSpaConfig {
   /** Pre-registered components. */
   components: ComponentDef[];
 }
-/** Context handed to every component lifecycle hook. */
+/**
+ * Context handed to every component lifecycle hook — the bound element + page data,
+ * plus the matched route's `params`/`meta`/`locale` and a link builder, so an island
+ * can read its route context (e.g. a `card` route's `ctx.meta.focus` + `ctx.params.id`)
+ * directly, without the page bridging it through `data-*` attributes.
+ */
 interface ComponentContext {
   /** The element the component instance is bound to. */
   el: Element;
   /** Page data extracted from the `script#__DATA__` payload. */
   data: PageData;
+  /** Resolved path params of the route matched for the current URL (empty if unmatched). */
+  readonly params: Record<string, string | undefined>;
+  /** The matched route's `.meta()` bag (empty if unmatched). */
+  readonly meta: Record<string, unknown>;
+  /** Active locale for the current route (empty string if unknown). */
+  readonly locale: string;
+  /** Build a link to a named route by pattern substitution (same output as `app.router.toUrl`). */
+  readonly url: (name: string, params?: Record<string, string>) => string;
 }
 /** Lifecycle hooks a component may implement. */
 interface ComponentHooks {

package/dist/browser.mjs

@@ -471,6 +471,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
@@ -2441,6 +2473,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.
 *
@@ -2528,18 +2577,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
 	};
 }
 /**
@@ -2553,17 +2609,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);
@@ -2581,14 +2638,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`
@@ -2654,12 +2712,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
@@ -3302,6 +3361,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
@@ -3319,8 +3398,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;
@@ -3374,17 +3454,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);
@@ -3416,6 +3501,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).
@@ -3427,8 +3513,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;
@@ -3461,6 +3547,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
@@ -3505,7 +3615,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;
 		},
 		/**
@@ -3536,7 +3649,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.