@moku-labs/web 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -2534,13 +2534,20 @@ function route(pattern) {
 			return set("load", loader);
 		},
 		/**
-		* Attach a layout wrapper component.
+		* Attach a ctx-aware layout wrapper that frames the page in persistent chrome.
+		* The wrapper receives the route's `LayoutContext` (render context + `.meta()`
+		* bag) and the page children. Applied in the SSG render path only — client
+		* navigation keeps the chrome and swaps just the inner region.
 		*
-		* @param component - The layout component.
+		* @param component - The layout component `(ctx, children) => VNode`.
 		* @returns The same builder for chaining.
 		* @example
 		* ```ts
-		* route("/").layout((children) => children);
+		* route("/")
+		*   .meta({ activeTab: "home" })
+		*   .layout((ctx, children) => (
+		*     <Shell locale={ctx.locale} active={ctx.meta.activeTab}>{children}</Shell>
+		*   ));
 		* ```
 		*/
 		layout(component) {
@@ -4431,7 +4438,12 @@ async function renderInstance(ctx, instance, shell) {
 	const headHtml = ctx.require(headPlugin).render(resolved, data);
 	const buildIdMeta = `<meta name="build-id" content="${ctx.state.runId ?? ""}">`;
 	const vnode = definition._handlers.render?.(routeContext);
-	const bodyHtml = vnode ? (0, preact_render_to_string.renderToString)(vnode) : "";
+	const layoutCtx = {
+		...routeContext,
+		meta: definition._meta
+	};
+	const page = vnode && definition._handlers.layout ? definition._handlers.layout(layoutCtx, vnode) : vnode;
+	const bodyHtml = page ? (0, preact_render_to_string.renderToString)(page) : "";
 	const parts = {
 		head: `${headHtml}${buildIdMeta}`,
 		body: bodyHtml,

package/dist/index.d.cts

@@ -542,7 +542,7 @@ type Api$5 = {
   t(locale: string, key: string): string;
 };
 declare namespace types_d_exports$7 {
-  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -582,6 +582,22 @@ interface RouteContext<S extends RouteState> {
   /** Active locale for this render. */
   readonly locale: string;
 }
+/**
+ * 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.
+ *
+ * @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.
+ */
+interface LayoutContext<S extends RouteState> extends RouteContext<S> {
+  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
+  readonly meta: Record<string, unknown>;
+}
 /** Head metadata produced by a route's `.head()` handler. */
 interface HeadConfig$1 {
   /** Document title. */
@@ -604,8 +620,14 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
     readonly params: S["params"];
     readonly data: Awaited<D>;
   }>;
-  /** Attach a layout wrapper component. */
-  layout(component: (children: ComponentChildren) => VNode): RouteBuilder<S>;
+  /**
+   * Attach a ctx-aware layout wrapper that frames this route's rendered page in
+   * persistent chrome. Receives the route's {@link LayoutContext} (render context +
+   * `meta`) and the page `children`. Applied in the SSG render path ONLY — on client
+   * navigation the chrome persists and only the inner swap region is replaced, so the
+   * layout is not re-run.
+   */
+  layout(component: (ctx: LayoutContext<S>, children: ComponentChildren) => VNode): RouteBuilder<S>;
   /** Attach the page render handler. */
   render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
   /**
@@ -635,8 +657,8 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
 interface RouteHandlers {
   /** Data loader. */
   readonly load?: (params: Record<string, string>, locale: string) => unknown;
-  /** Layout wrapper. */
-  readonly layout?: (children: ComponentChildren) => VNode;
+  /** Layout wrapper (ctx-aware): frames the page in persistent chrome. SSG-only. */
+  readonly layout?: (ctx: LayoutContext<RouteState>, children: ComponentChildren) => VNode;
   /** Page renderer. */
   readonly render?: (ctx: RouteContext<RouteState>) => VNode;
   /** Client-side validation gate: `unknown` (fetched JSON) → the route's data type, or throw. */

package/dist/index.d.mts

@@ -542,7 +542,7 @@ type Api$5 = {
   t(locale: string, key: string): string;
 };
 declare namespace types_d_exports$7 {
-  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
+  export { Api$4 as Api, ClientRoute, CompileInput, CompiledRoute, Config$4 as Config, ExtractRouteParams, ExtractSegmentParameter, HeadConfig$1 as HeadConfig, LayoutContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteState, RouterApi, RouterConfig, RouterState, State$4 as State, TypedRoute };
 }
 /**
  * Param contribution of a single path segment. `{name:?}` / `:name?` → optional;
@@ -582,6 +582,22 @@ interface RouteContext<S extends RouteState> {
   /** Active locale for this render. */
   readonly locale: string;
 }
+/**
+ * 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.
+ *
+ * @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.
+ */
+interface LayoutContext<S extends RouteState> extends RouteContext<S> {
+  /** The route's `.meta()` bag (e.g. `{ activeTab: "home" }`). */
+  readonly meta: Record<string, unknown>;
+}
 /** Head metadata produced by a route's `.head()` handler. */
 interface HeadConfig$1 {
   /** Document title. */
@@ -604,8 +620,14 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
     readonly params: S["params"];
     readonly data: Awaited<D>;
   }>;
-  /** Attach a layout wrapper component. */
-  layout(component: (children: ComponentChildren) => VNode): RouteBuilder<S>;
+  /**
+   * Attach a ctx-aware layout wrapper that frames this route's rendered page in
+   * persistent chrome. Receives the route's {@link LayoutContext} (render context +
+   * `meta`) and the page `children`. Applied in the SSG render path ONLY — on client
+   * navigation the chrome persists and only the inner swap region is replaced, so the
+   * layout is not re-run.
+   */
+  layout(component: (ctx: LayoutContext<S>, children: ComponentChildren) => VNode): RouteBuilder<S>;
   /** Attach the page render handler. */
   render(handler: (ctx: RouteContext<S>) => VNode): RouteBuilder<S>;
   /**
@@ -635,8 +657,8 @@ interface RouteBuilder<S extends RouteState> extends RouteDefinition {
 interface RouteHandlers {
   /** Data loader. */
   readonly load?: (params: Record<string, string>, locale: string) => unknown;
-  /** Layout wrapper. */
-  readonly layout?: (children: ComponentChildren) => VNode;
+  /** Layout wrapper (ctx-aware): frames the page in persistent chrome. SSG-only. */
+  readonly layout?: (ctx: LayoutContext<RouteState>, children: ComponentChildren) => VNode;
   /** Page renderer. */
   readonly render?: (ctx: RouteContext<RouteState>) => VNode;
   /** Client-side validation gate: `unknown` (fetched JSON) → the route's data type, or throw. */

package/dist/index.mjs

@@ -2521,13 +2521,20 @@ function route(pattern) {
 			return set("load", loader);
 		},
 		/**
-		* Attach a layout wrapper component.
+		* Attach a ctx-aware layout wrapper that frames the page in persistent chrome.
+		* The wrapper receives the route's `LayoutContext` (render context + `.meta()`
+		* bag) and the page children. Applied in the SSG render path only — client
+		* navigation keeps the chrome and swaps just the inner region.
 		*
-		* @param component - The layout component.
+		* @param component - The layout component `(ctx, children) => VNode`.
 		* @returns The same builder for chaining.
 		* @example
 		* ```ts
-		* route("/").layout((children) => children);
+		* route("/")
+		*   .meta({ activeTab: "home" })
+		*   .layout((ctx, children) => (
+		*     <Shell locale={ctx.locale} active={ctx.meta.activeTab}>{children}</Shell>
+		*   ));
 		* ```
 		*/
 		layout(component) {
@@ -4418,7 +4425,12 @@ async function renderInstance(ctx, instance, shell) {
 	const headHtml = ctx.require(headPlugin).render(resolved, data);
 	const buildIdMeta = `<meta name="build-id" content="${ctx.state.runId ?? ""}">`;
 	const vnode = definition._handlers.render?.(routeContext);
-	const bodyHtml = vnode ? renderToString(vnode) : "";
+	const layoutCtx = {
+		...routeContext,
+		meta: definition._meta
+	};
+	const page = vnode && definition._handlers.layout ? definition._handlers.layout(layoutCtx, vnode) : vnode;
+	const bodyHtml = page ? renderToString(page) : "";
 	const parts = {
 		head: `${headHtml}${buildIdMeta}`,
 		body: bodyHtml,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/web",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Content static-site generator + SPA web framework for TypeScript, built on @moku-labs/core.",
   "author": "Oleksandr Kucherenko",
   "license": "MIT",