@moku-labs/web 1.13.1 → 1.14.0

package/dist/index.cjs

@@ -1084,6 +1084,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
@@ -4528,16 +4560,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,
@@ -4561,21 +4600,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);
@@ -4698,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
@@ -4709,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
@@ -4847,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 = {
@@ -4909,15 +4946,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
@@ -5027,14 +5065,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,
@@ -9056,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.
 *
@@ -9143,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
 	};
 }
 /**
@@ -9168,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);
@@ -9196,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`
@@ -9269,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
@@ -9917,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
@@ -9934,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;
@@ -9989,17 +10076,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);
@@ -10031,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).
@@ -10042,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;
@@ -10076,6 +10169,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 Promise.resolve().then(() => require("./render-DLZEOe4M.cjs"));
+		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
@@ -10120,7 +10237,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;
 		},
 		/**
@@ -10151,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 {