akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/client/csrTypes.ts

@@ -18,21 +18,10 @@ export type PageSafeAreaConfig =
       bottom?: boolean;
       android?: "auto" | "edge-to-edge" | "none";
     };
-/**
- * Server-render strategy for the initial full-document SSR pass.
- * - `"stream"` (default): flush the shell — including any `Loading` Suspense
- *   fallback — as soon as it is ready, then stream the resolved page. Redirects
- *   decided in the shell still become real HTTP redirects; redirects thrown
- *   inside suspended content degrade to soft (client) redirects.
- * - `"block"`: buffer the whole document until every Suspense boundary resolves
- *   before sending a byte. The `Loading` fallback never reaches the browser, but
- *   a non-redirect error thrown in slow content can still yield a clean error
- *   page. Use only for routes that need that guarantee and do not care about SEO
- *   or first-paint of the fallback.
- */
+/** `"stream"` flushes the shell (`Loading` included) then streams; a redirect in suspended content becomes a client one.
+ * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
 
-/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
   transition?: TransitionType;
   safeArea?: PageSafeAreaConfig;
@@ -44,20 +33,12 @@ export interface PageConfig {
   cache?: boolean;
   /** Initial full-document SSR strategy. Defaults to `"stream"`. */
   ssr?: SsrRenderMode;
-  /**
-   * Opt in to guarded RSC page suffix commits when the page does not require
-   * head/metadata updates and the retained route chain head is invariant for
-   * sibling navigations under the same layout.
-   */
+  /** Opt-in suffix-only RSC commits, for a page needing no head update under a layout head its siblings share. */
   rscPatchHeadSafe?: boolean;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
-  /**
-   * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
-   * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
-   * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
-   * the source without evaluating the module.
-   */
+  /** Keeps the route (on a `_layout`, its whole directory) out of `akan build` while `akan start` serves it. Write a
+   * literal `true`/`false`: the build reads it off the source without evaluating the module. */
   devOnly?: boolean;
 }
 
@@ -79,7 +60,6 @@ export interface PageProps {
   params: { [key: string]: string };
   searchParams: { [key: string]: string | string[] };
 }
-/** Props passed to Akan layout route modules. */
 export interface LayoutProps extends PageProps {
   children: ReactNode;
 }
@@ -109,7 +89,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
   node: Head | null | undefined;
-  hasExplicitLanguageAlternates: boolean;
   headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -125,8 +104,7 @@ export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
   Loading?: LayoutLoadingRender | PageLoadingRender;
-  /** Loads the module and populates `Loading` without running `render`/`resolveHead`.
-   * Used by the patch (suffix) compose path, which never calls `resolveHead`. */
+  /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
   resolveLoading?: () => void | Promise<void>;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -163,53 +141,24 @@ export interface WebAppManifest {
   screenshots?: WebAppManifestIcon[];
   [key: string]: unknown;
 }
-export interface AkanMetadata {
-  title?: string;
-  description?: string;
-  robots?: string;
-  openGraph?: {
-    title?: string;
-    description?: string;
-    type?: string;
-    url?: string;
-    siteName?: string;
-    images?: string | string[];
-  };
-  twitter?: {
-    card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
-    title?: string;
-    description?: string;
-    images?: string | string[];
-  };
-  alternates?: {
-    canonical?: string;
-    languages?: Record<string, string>;
-  };
-}
-export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
   default?: PageRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
-  gaTrackingId?: string;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -226,12 +175,10 @@ export interface Route {
   renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;
   isSpecialRoute?: boolean;
-
   loader?: () => unknown;
   pageState?: PageState;
   pageConfigChain?: PageConfig[];
   explicitPageConfigKeys?: Partial<Record<keyof PageConfig, boolean>>;
-
   children: Map<string, Route>;
 }
 

package/client/decorators.ts

@@ -5,7 +5,7 @@ interface ToastProps {
   root?: string;
   duration?: number;
 }
-/** Decorates async actions with loading/success/error toast messages from `msg`. */
+/** Toasts `<root>.<key>-loading` / `-success` around the method; an error is toasted and logged, not rethrown. */
 export const Toast = ({ root, duration = 3 }: ToastProps = {}) => {
   return (target: any, key: string, descriptor: PropertyDescriptor) => {
     const originMethod = descriptor.value as (...args: any[]) => Promise<void>;

package/client/device.ts

@@ -6,16 +6,42 @@ import type {
   CapacitorKeyboardInfo,
   CapacitorKeyboardModule,
 } from "./capacitor";
-import { debugFrame } from "./frameDebug";
 
 type DeviceInfo = CapacitorDeviceInfo;
 type Keyboard = CapacitorKeyboardModule["Keyboard"];
 type Haptics = CapacitorHapticsModule["Haptics"];
 type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
 type ProcessEnvLike = { env?: Record<string, string | undefined> };
+type DebugPayload = Record<string, unknown>;
 
 const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessEnvLike };
 
+const debugSessionId = Math.random().toString(36).slice(2, 8);
+let debugSeq = 0;
+
+const isFrameDebugEnabled = () => {
+  if (typeof window === "undefined") return false;
+  const windowWithTarget = window as typeof window & { __AKAN_MOBILE_TARGET__?: unknown };
+  const search = new URLSearchParams(window.location.search);
+  return (
+    Boolean(windowWithTarget.__AKAN_MOBILE_TARGET__) ||
+    search.has("akanMobileTarget") ||
+    search.get("akanFrameDebug") === "1" ||
+    window.localStorage.getItem("akan:debug:frame") === "1"
+  );
+};
+
+export function debugFrame(event: string, payload: DebugPayload = {}) {
+  if (!isFrameDebugEnabled()) return;
+  debugSeq += 1;
+  const details = {
+    href: window.location.href,
+    now: Math.round(performance.now()),
+    ...payload,
+  };
+  console.info(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details, JSON.stringify(details));
+}
+
 interface DeviceInitOption {
   lang: string;
   info: DeviceInfo;
@@ -62,6 +88,11 @@ export const isMobileDevice = () => {
   return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
 };
 
+const langInPath = (pathname: string, supportLanguages: string[] | readonly string[]) => {
+  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
+  return supportLanguages.find((language) => language === predefinedLangPath);
+};
+
 const createWebDevice = ({
   lang,
   supportLanguages,
@@ -70,10 +101,8 @@ const createWebDevice = ({
   supportLanguages: string[] | readonly string[];
 }) => {
   const pathname = typeof window === "undefined" ? "" : window.location.pathname;
-  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
-  const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
   return new Device({
-    lang: lang ?? predefinedLang ?? getBrowserLanguage(),
+    lang: lang ?? langInPath(pathname, supportLanguages) ?? getBrowserLanguage(),
     info: { platform: "web", isVirtual: false, osVersion: "" },
     topSafeArea: 0,
     bottomSafeArea: 0,
@@ -83,7 +112,6 @@ const createWebDevice = ({
   });
 };
 
-/** Capacitor-aware device helper for platform info, safe areas, keyboard, haptics, and scroll state. */
 export class Device {
   static instance: Device | null = null;
   static async load({
@@ -95,9 +123,8 @@ export class Device {
   }) {
     if (Device.instance) return Device.instance;
     if (getRenderMode() !== "csr" || !isNativeTarget()) {
-      const device = createWebDevice({ lang, supportLanguages });
-      Device.instance = device;
-      return device;
+      Device.instance = createWebDevice({ lang, supportLanguages });
+      return Device.instance;
     }
     const { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } = await import(
       "./capacitor"
@@ -116,10 +143,8 @@ export class Device {
       },
     ] = await Promise.all([CapacitorDevice.getInfo(), CapacitorDevice.getLanguageCode(), SafeArea.getSafeAreaInsets()]);
     if (info.platform === "ios") await Keyboard.setResizeMode?.({ mode: "none" });
-    const predefinedLangPath = window.location.pathname.split("/")[1]?.split("?")[0];
-    const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
-    const device = new Device({
-      lang: lang ?? predefinedLang ?? languageCode,
+    Device.instance = new Device({
+      lang: lang ?? langInPath(window.location.pathname, supportLanguages) ?? languageCode,
       info,
       topSafeArea,
       bottomSafeArea,
@@ -127,8 +152,7 @@ export class Device {
       haptics: Haptics,
       impactStyle: ImpactStyle,
     });
-    Device.instance = device;
-    return device;
+    return Device.instance;
   }
   static getDevice() {
     if (!Device.instance) throw new Error("Device is not loaded yet");
@@ -174,18 +198,14 @@ export class Device {
       currentHeight = height;
       onKeyboardChanged(height);
     };
-    void this.#keyboard.addListener("keyboardWillShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardWillShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardDidShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardDidShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardWillHide", () => {
-      emitKeyboardHeight("keyboardWillHide", 0);
-    });
-    void this.#keyboard.addListener("keyboardDidHide", () => {
-      emitKeyboardHeight("keyboardDidHide", 0);
-    });
+    for (const event of ["keyboardWillShow", "keyboardDidShow"])
+      void this.#keyboard.addListener(event, (keyboard: CapacitorKeyboardInfo) => {
+        emitKeyboardHeight(event, keyboard.keyboardHeight);
+      });
+    for (const event of ["keyboardWillHide", "keyboardDidHide"])
+      void this.#keyboard.addListener(event, () => {
+        emitKeyboardHeight(event, 0);
+      });
   }
   unlistenKeyboardChanged() {
     if (this.info.platform === "web") return;
@@ -197,24 +217,12 @@ export class Device {
       return;
     }
     const handleImpact = {
-      light: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Light });
-      },
-      medium: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Medium });
-      },
-      heavy: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Heavy });
-      },
-      selectionStart: async () => {
-        await this.#haptics.selectionStart();
-      },
-      selectionChanged: async () => {
-        await this.#haptics.selectionChanged();
-      },
-      selectionEnd: async () => {
-        await this.#haptics.selectionEnd();
-      },
+      light: () => this.#haptics.impact({ style: this.#impactStyle.Light }),
+      medium: () => this.#haptics.impact({ style: this.#impactStyle.Medium }),
+      heavy: () => this.#haptics.impact({ style: this.#impactStyle.Heavy }),
+      selectionStart: () => this.#haptics.selectionStart(),
+      selectionChanged: () => this.#haptics.selectionChanged(),
+      selectionEnd: () => this.#haptics.selectionEnd(),
     };
     await handleImpact[type]();
   }

package/client/frameConfig.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "akanjs/common";
 import type { PageConfig, PageSafeAreaConfig, PageState, SsrRenderMode, TransitionType } from "./csrTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
@@ -30,9 +31,6 @@ const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "st
 const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 const hasOwn = <Key extends PropertyKey>(value: object, key: Key) => Object.hasOwn(value, key);
 
 export function validatePageConfig(routeKey: string, config?: PageConfig) {
@@ -53,15 +51,11 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (pageConfig.ssr !== undefined && !ssrRenderModes.has(pageConfig.ssr)) {
     throw new Error(`[route-convention] unsupported pageConfig.ssr "${pageConfig.ssr}" in ${routeKey}`);
   }
-  if (pageConfig.topInset !== undefined && !isValidInsetValue(pageConfig.topInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.topInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
-  }
-  if (pageConfig.bottomInset !== undefined && !isValidInsetValue(pageConfig.bottomInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.bottomInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
+  for (const key of ["topInset", "bottomInset"] as const) {
+    if (pageConfig[key] !== undefined && !isValidInsetValue(pageConfig[key]))
+      throw new Error(
+        `[route-convention] pageConfig.${key} in ${routeKey} must be a boolean or non-negative px number.`,
+      );
   }
   validateSafeAreaConfig(routeKey, pageConfig.safeArea);
 }
@@ -78,11 +72,9 @@ function validateSafeAreaConfig(routeKey: string, safeArea?: PageSafeAreaConfig)
       throw new Error(`[route-convention] unsupported pageConfig.safeArea option "${key}" in ${routeKey}`);
     }
   }
-  if (safeArea.top !== undefined && typeof safeArea.top !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.top in ${routeKey} must be a boolean.`);
-  }
-  if (safeArea.bottom !== undefined && typeof safeArea.bottom !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.bottom in ${routeKey} must be a boolean.`);
+  for (const side of ["top", "bottom"] as const) {
+    if (safeArea[side] !== undefined && typeof safeArea[side] !== "boolean")
+      throw new Error(`[route-convention] pageConfig.safeArea.${side} in ${routeKey} must be a boolean.`);
   }
   if (
     safeArea.android !== undefined &&
@@ -165,8 +157,8 @@ export function resolvePageState({
         : (config.gesture ?? false),
     cache: config.cache ?? false,
     ssr: config.ssr ?? "stream",
-    topSafeAreaColor: config.topSafeAreaColor ?? "var(color-background, Canvas)",
-    bottomSafeAreaColor: config.bottomSafeAreaColor ?? "var(color-background, Canvas)",
+    topSafeAreaColor: config.topSafeAreaColor ?? defaultPageState.topSafeAreaColor,
+    bottomSafeAreaColor: config.bottomSafeAreaColor ?? defaultPageState.bottomSafeAreaColor,
   };
 }
 
@@ -208,14 +200,11 @@ function resolveSafeArea({
   cssSafeArea?: SafeAreaInsets;
 }): SafeAreaInsets {
   if (safeArea === false) return { top: 0, bottom: 0 };
-  const topEnabled =
-    safeArea === true ||
-    safeArea === "top" ||
-    (isRecord(safeArea) ? safeArea.top !== false : safeArea === undefined && platform !== "web");
-  const bottomEnabled =
+  const enabledAt = (side: "top" | "bottom") =>
     safeArea === true ||
-    safeArea === "bottom" ||
-    (isRecord(safeArea) ? safeArea.bottom !== false : safeArea === undefined && platform !== "web");
+    safeArea === side ||
+    (isRecord(safeArea) ? safeArea[side] !== false : safeArea === undefined && platform !== "web");
+  const [topEnabled, bottomEnabled] = [enabledAt("top"), enabledAt("bottom")];
   if (platform === "android") {
     const androidMode = isRecord(safeArea)
       ? (safeArea.android as "auto" | "edge-to-edge" | "none" | undefined)

package/client/index.ts

@@ -6,7 +6,6 @@ export * from "./csrTypes";
 export * from "./decorators";
 export * from "./device";
 export * from "./frameConfig";
-export * from "./frameDebug";
 export * from "./locale";
 export * from "./makePageProto";
 export * from "./route";

package/client/makePageProto.tsx

@@ -29,12 +29,12 @@ const getPageInfo = (): { locale: string; path: string } => {
   if (getEnv().side !== "server") {
     const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
-
+    
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
     return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname) };
   }
   const h = untrackedHeaders();
-
+  
   const localeHeader = h.get("x-locale");
   const pathHeader = h.get("x-path");
   if (localeHeader && pathHeader) return { locale: localeHeader, path: pathHeader };
@@ -164,13 +164,12 @@ export const makePageProto = <
             dangerouslySetInnerHTML={{
               __html: translator.translate(lang, key, {
                 ...param,
-
                 br: `<br />`,
               }),
             }}
           />
         ) as ReactNode;
-
+      
       l.trans = <Returns extends ReactNode>(
         translation: Record<"en" | "ko" | (string & {}), Returns>,
       ): Returns extends string ? string : Returns => {

package/client/route/RootLayoutDefinition.ts

@@ -12,7 +12,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
   #reconnect?: boolean;
   #wsConnect?: boolean;
   #layoutStyle?: "mobile" | "web";
-  #gaTrackingId?: string;
 
   fonts(fonts: ReactFont[]) {
     this.#fonts = fonts;
@@ -38,10 +37,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
     this.#layoutStyle = style;
     return this;
   }
-  gaTrackingId(id: string) {
-    this.#gaTrackingId = id;
-    return this;
-  }
 
   protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
     return {
@@ -52,7 +47,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
       ...(this.#reconnect !== undefined ? { reconnect: this.#reconnect } : {}),
       ...(this.#wsConnect !== undefined ? { wsConnect: this.#wsConnect } : {}),
       ...(this.#layoutStyle ? { layoutStyle: this.#layoutStyle } : {}),
-      ...(this.#gaTrackingId ? { gaTrackingId: this.#gaTrackingId } : {}),
     };
   }
 }

package/client/route/RouteDefinition.ts

@@ -9,7 +9,7 @@ import {
 import { parseAkanI18nEnv } from "akanjs/common";
 import { deserialize } from "akanjs/constant";
 import type { ReactNode } from "react";
-import type { AkanMetadata, Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
+import type { Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
 import { AkanNotFoundError } from "../router";
 import { RouteArgError, type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs";
 
@@ -19,7 +19,6 @@ export type RouteKind = "page" | "layout" | "rootLayout";
 export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
 
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
-type MetadataStage<Args> = AkanMetadata | ((args: Args) => PromiseOrObject<AkanMetadata | null | undefined>);
 
 interface RouteRenderProps {
   params: Record<string, string>;
@@ -32,10 +31,7 @@ export interface RouteArgResolveOption {
   strict?: boolean;
 }
 
-/**
- * What a route file declares in place of named exports. The chain is the only surface — the module exports the
- * finished definition and the loader turns it back into the module shape every renderer already reads.
- */
+/** What a route file declares in place of named exports; the loader turns it back into the module shape. */
 export abstract class RouteDefinition<
   Args extends RouteArgsShape = Record<never, never>,
   Extra extends object = Record<never, never>,
@@ -46,7 +42,6 @@ export abstract class RouteDefinition<
   #config?: PageConfig;
 
   #head?: HeadStage<never>;
-  #metadata?: MetadataStage<never>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
 
@@ -58,10 +53,6 @@ export abstract class RouteDefinition<
     this.#head = head as HeadStage<never>;
     return this;
   }
-  metadata(metadata: MetadataStage<RouteBaseArgs & Args>) {
-    this.#metadata = metadata as MetadataStage<never>;
-    return this;
-  }
   loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
     this.#loading = render as (args: never) => PromiseOrObject<ReactNode>;
     return this;
@@ -83,11 +74,7 @@ export abstract class RouteDefinition<
     this.args.push(arg);
   }
 
-  /**
-   * Typed values out of the URL halves the router matched. A path value the declared type refuses is a URL that
-   * matched the pattern and nothing under it, so a page answers not-found; a search value that fails is dropped
-   * the way an absent one is. Under `strict` both are refused by name, which is what a prompt caller can act on.
-   */
+  /** A path value the type refuses answers not-found; a failing search value is dropped. `strict` refuses both by name. */
   resolveArgs(input: RouteArgInput, { strict = false }: RouteArgResolveOption = {}): Record<string, unknown> {
     const resolved: Record<string, unknown> = {};
     for (const arg of this.args) {
@@ -107,10 +94,7 @@ export abstract class RouteDefinition<
     return resolved;
   }
 
-  /**
-   * The `[x]` segments of the file's path against the `.param()` stages. A page must name every segment it sits
-   * under, so nothing reaches its body undeclared; a layout may name a subset, since most read none of them.
-   */
+  /** A page must declare every `[x]` segment it sits under with `.param()`; a layout may declare a subset. */
   assertPattern(pattern: string, key: string) {
     const inPath = pattern
       .split("/")
@@ -136,7 +120,6 @@ export abstract class RouteDefinition<
     if (!render)
       throw new Error(`[route-convention] a ${this.kind}() chain ends with .render(), and this one has none`);
     const head = this.#head;
-    const metadata = this.#metadata;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
       default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
@@ -146,11 +129,6 @@ export abstract class RouteDefinition<
         : typeof head === "function"
           ? { generateHead: async (props: RouteRenderProps) => await head(this.#argsOf(props) as never) }
           : { head }),
-      ...(metadata === undefined
-        ? {}
-        : typeof metadata === "function"
-          ? { generateMetadata: async (props: RouteRenderProps) => await metadata(this.#argsOf(props) as never) }
-          : { metadata }),
       ...(loading
         ? {
             Loading: ((props: RouteRenderProps) =>
@@ -172,10 +150,7 @@ export abstract class RouteDefinition<
     return (this.kind === "page" ? args : { ...args, children: props.children }) as RouteBaseArgs & Args & Extra;
   }
 
-  /**
-   * A single value where a list was declared is a one-item list: the URL spells `?tags=a` for one tag. A prompt
-   * argument is one string whatever it holds, so under `strict` a list is read comma-separated.
-   */
+  /** One value where a list was declared is a one-item list (`?tags=a`); under `strict` a list is comma-separated. */
   static #lift(arg: RouteArgInfo, raw: string | string[], strict: boolean): unknown {
     if (!arg.list) return Array.isArray(raw) ? raw[0] : raw;
     if (Array.isArray(raw)) return raw;

package/client/route/resolveRouteModule.ts

@@ -20,11 +20,7 @@ export interface ResolvedRouteModule {
 export const isRouteDefinition = (value: unknown): value is RouteDefinition =>
   typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[routeDefinitionMarker] === true;
 
-/**
- * Every loader — the RSC worker, the CSR boot, the generated root layout — reads route modules by their named
- * exports. A chain module has one export, so it is unfolded into that shape here and nothing downstream learns
- * which of the two it was reading; a legacy module passes through untouched.
- */
+/** Unfolds a chain module into the named-export shape every loader reads; a legacy module passes through untouched. */
 export const resolveRouteModule = (
   mod: RouteModuleSource,
   key: string,