@moku-labs/web 1.13.2 → 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

@@ -2473,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.
 *
@@ -2560,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
 	};
 }
 /**
@@ -2585,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);
@@ -2613,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`
@@ -2686,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
@@ -3334,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
@@ -3351,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;
@@ -3421,6 +3469,7 @@ function createSpaKernel(state, config, emit, deps) {
 			params: hit.params,
 			data,
 			locale,
+			meta: hit.route._meta,
 			url: (routeName, routeParams = {}) => deps.router.toUrl(routeName, routeParams)
 		};
 		const vnode = hit.route._handlers.render(routeContext);
@@ -3452,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).
@@ -3463,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;
@@ -3509,15 +3559,16 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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);
+			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);
+		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 	};
 	/**
 	* Unified navigation: try the client DATA path first (only when the `data`
@@ -3567,7 +3618,7 @@ function createSpaKernel(state, config, emit, deps) {
 			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);
+			else scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(state.currentUrl));
 			state.started = true;
 		},
 		/**
@@ -3598,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.

package/dist/index.cjs

@@ -4738,8 +4738,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
@@ -4749,11 +4749,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 (0, preact_render_to_string.renderToString)(definition._handlers.layout ? definition._handlers.layout(layoutContext, vnode) : vnode);
+	return (0, preact_render_to_string.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
@@ -4887,6 +4883,7 @@ async function renderInstance(ctx, instance, shell, reuse) {
 		params,
 		data,
 		locale,
+		meta: definition._meta,
 		url: (routeName, routeParams = {}) => router.toUrl(routeName, routeParams)
 	};
 	const parts = {
@@ -9098,6 +9095,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.
 *
@@ -9185,18 +9199,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
 	};
 }
 /**
@@ -9210,17 +9231,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);
@@ -9238,14 +9260,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`
@@ -9311,12 +9334,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
@@ -9959,6 +9983,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
@@ -9976,8 +10020,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;
@@ -10046,6 +10091,7 @@ function createSpaKernel(state, config, emit, deps) {
 			params: hit.params,
 			data,
 			locale,
+			meta: hit.route._meta,
 			url: (routeName, routeParams = {}) => deps.router.toUrl(routeName, routeParams)
 		};
 		const vnode = hit.route._handlers.render(routeContext);
@@ -10077,6 +10123,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).
@@ -10088,8 +10135,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;
@@ -10134,15 +10181,16 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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);
+			scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 			return;
 		}
 		const { vnode, region } = resolvedRender;
 		const { renderVNode } = await Promise.resolve().then(() => require("./render-DLZEOe4M.cjs"));
 		renderVNode(vnode, region);
-		scanAndMount(state, emit, resolved.swapSelector);
+		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 	};
 	/**
 	* Unified navigation: try the client DATA path first (only when the `data`
@@ -10192,7 +10240,7 @@ function createSpaKernel(state, config, emit, deps) {
 			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);
+			else scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(state.currentUrl));
 			state.started = true;
 		},
 		/**
@@ -10223,7 +10271,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/dist/index.d.cts

@@ -288,7 +288,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"];
@@ -296,6 +299,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
@@ -376,21 +386,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. */
@@ -945,12 +950,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/index.d.mts

@@ -286,7 +286,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"];
@@ -294,6 +297,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
@@ -374,21 +384,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. */
@@ -943,12 +948,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/index.mjs

@@ -4725,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
@@ -4736,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
@@ -4874,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 = {
@@ -9085,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.
 *
@@ -9172,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
 	};
 }
 /**
@@ -9197,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);
@@ -9225,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`
@@ -9298,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
@@ -9946,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
@@ -9963,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;
@@ -10033,6 +10078,7 @@ function createSpaKernel(state, config, emit, deps) {
 			params: hit.params,
 			data,
 			locale,
+			meta: hit.route._meta,
 			url: (routeName, routeParams = {}) => deps.router.toUrl(routeName, routeParams)
 		};
 		const vnode = hit.route._handlers.render(routeContext);
@@ -10064,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).
@@ -10075,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;
@@ -10121,15 +10168,16 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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);
+			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);
+		scanAndMount(state, emit, resolved.swapSelector, routeSlice);
 	};
 	/**
 	* Unified navigation: try the client DATA path first (only when the `data`
@@ -10179,7 +10227,7 @@ function createSpaKernel(state, config, emit, deps) {
 			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);
+			else scanAndMount(state, emit, resolved.swapSelector, componentRouteContext(state.currentUrl));
 			state.started = true;
 		},
 		/**
@@ -10210,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.2"
+  "version": "1.14.0"
 }