akanjs 3.1.0-rc.8 → 3.1.0

package/README.ko.md

@@ -22,7 +22,7 @@
 ```text
 Akan.js(https://akanjs.com) 워크스페이스를 새로 만들어 줘.
 
-1. Bun 1.4 이상이 설치돼 있는지 확인해 줘(`bun --version`). 없거나 버전이 낮으면 https://bun.sh 안내대로 설치하거나 업그레이드해 줘.
+1. Bun 1.4.4 이상이 설치돼 있는지 확인해 줘(`bun --version`). 없거나 버전이 낮으면 https://bun.sh 안내대로 설치하거나 업그레이드해 줘.
 2. 워크스페이스 이름과 첫 앱 이름을 물어봐 줘. 짧은 영문 소문자로, 아래에 적어 뒀다면 그걸 쓰면 돼.
 3. 이 디렉터리에서 `bunx create-akan-workspace@latest <워크스페이스> --app <앱>`을 실행해 줘. akan CLI를 전역으로 설치하고, ./<워크스페이스>를 만들어 의존성까지 설치해.
 4. ./<워크스페이스> 안에서 `akan start <앱>`으로 개발 서버를 백그라운드에 띄우고, 출력된 주소(기본 http://localhost:8282)가 열리는지 확인해 줘.
@@ -35,7 +35,7 @@ Claude Code·Codex·Cursor에 등록된 Akan MCP 서버입니다. 워크스페
 
 ### 터미널로 시작하기
 
-[Bun](https://bun.sh) `>=1.4.0`이 필요합니다.
+[Bun](https://bun.sh) `>=1.4.4`이 필요합니다.
 
 ```bash
 bunx create-akan-workspace@latest

package/README.md

@@ -22,7 +22,7 @@ or let the agent ask.
 ```text
 Set up a new Akan.js workspace for me (https://akanjs.com).
 
-1. Check that Bun 1.4 or newer is installed (`bun --version`). If it isn't, install or upgrade it as https://bun.sh describes.
+1. Check that Bun 1.4.4 or newer is installed (`bun --version`). If it isn't, install or upgrade it as https://bun.sh describes.
 2. Ask me for a workspace name and a first app name, short and lowercase, unless I wrote them below.
 3. In this directory, run `bunx create-akan-workspace@latest <workspace> --app <app>`. It installs the akan CLI globally, creates ./<workspace> and installs its dependencies.
 4. Inside ./<workspace>, start the dev server in the background with `akan start <app>` and check that the URL it prints (http://localhost:8282 by default) loads.
@@ -34,7 +34,7 @@ Akan MCP server registered for Claude Code, Codex and Cursor. Reopen the agent i
 
 ### In a terminal
 
-Requires [Bun](https://bun.sh) `>=1.4.0`.
+Requires [Bun](https://bun.sh) `>=1.4.4`.
 
 ```bash
 bunx create-akan-workspace@latest

package/client/cookie.ts

@@ -128,6 +128,9 @@ export interface GetOption {
 interface SetAuthOption {
   jwt: string;
 }
+const announceAuth = () => {
+  if (typeof window !== "undefined") window.dispatchEvent(new Event("akan:auth"));
+};
 /** Sets the active auth token on fetch, the cookie jar (except on a CSR client), and client storage. */
 export const setAuth = ({ jwt }: SetAuthOption) => {
   fetch.setJwt(jwt);
@@ -137,6 +140,7 @@ export const setAuth = ({ jwt }: SetAuthOption) => {
   
   removeCookie(legacyAuthTokenKey);
   void secretStorage.removeItem(legacyAuthTokenKey);
+  announceAuth();
 };
 
 interface InitAuthOption {
@@ -162,4 +166,5 @@ export const resetAuth = () => {
   removeCookie(legacyAuthTokenKey);
   void secretStorage.removeItem(authTokenKey());
   void secretStorage.removeItem(legacyAuthTokenKey);
+  announceAuth();
 };

package/client/csrLocation.ts

@@ -1,120 +1,65 @@
-interface CsrLocationEntry {
-  href: string;
-  state: unknown;
-}
-
-export interface CsrMemoryOwner {
-  leave: (href: string) => void;
-  reload: () => void;
-}
-
 declare global {
   var __AKAN_CSR_LOCATION__: CsrLocation | undefined;
   
   var __AKAN_EMBED__: { kind: "mcp-app"; origin?: string; account?: Record<string, unknown> | null } | undefined;
 }
 
+/** The document's location and history, as the CSR router reads and moves them. */
 export class CsrLocation {
-  #memory: { entries: CsrLocationEntry[]; idx: number } | null = null;
-  #owner: CsrMemoryOwner = { leave: () => undefined, reload: () => undefined };
-
-  get isMemory() {
-    return this.#memory !== null;
-  }
+  
+  #view: URL | null = null;
 
-  /** The owner takes what a document load would do, which a view cannot: it has no document to load in its place. */
-  useMemory(href: string, owner: CsrMemoryOwner) {
-    this.#memory = { entries: [{ href, state: null }], idx: 0 };
-    this.#owner = owner;
+  /** Reads `href`, a path on the app's origin, as this document's location from now on; a view never moves. */
+  view(href: string) {
+    this.#view = new URL(href, "http://view.invalid");
   }
 
   /** Path, search and hash, without the origin. */
   get href() {
-    const entry = this.#entry();
-    if (entry) return entry.href;
-    return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    return `${this.pathname}${this.search}${this.hash}`;
   }
 
   get pathname() {
-    if (!this.#memory) return window.location.pathname;
-    return this.href.split(/[?#]/)[0] ?? "/";
+    return (this.#view ?? window.location).pathname;
   }
 
   get search() {
-    if (!this.#memory) return window.location.search;
-    const [beforeHash] = this.href.split("#");
-    const at = beforeHash?.indexOf("?") ?? -1;
-    return at >= 0 ? (beforeHash?.slice(at) ?? "") : "";
+    return (this.#view ?? window.location).search;
   }
 
   get hash() {
-    if (!this.#memory) return window.location.hash;
-    const at = this.href.indexOf("#");
-    return at >= 0 ? this.href.slice(at) : "";
+    return (this.#view ?? window.location).hash;
   }
 
   get state(): unknown {
-    const entry = this.#entry();
-    return entry ? entry.state : window.history.state;
+    return window.history.state;
   }
 
   /** `href` as a route reads it: an absolute URL on this document's origin loses the origin, anything else is kept. */
   strip(href: string) {
-    if (this.#memory) return href;
     const origin = window.location.origin;
     return origin !== "null" && href.startsWith(origin) ? href.slice(origin.length) : href;
   }
 
   push(state: unknown, href: string) {
-    const memory = this.#memory;
-    if (!memory) {
-      window.history.pushState(state, "", href);
-      return;
-    }
-    memory.entries = [...memory.entries.slice(0, memory.idx + 1), { href, state }];
-    memory.idx = memory.entries.length - 1;
+    window.history.pushState(state, "", href);
   }
 
   replace(state: unknown, href?: string) {
-    const memory = this.#memory;
-    if (!memory) {
-      if (href === undefined) window.history.replaceState(state, "");
-      else window.history.replaceState(state, "", href);
-      return;
-    }
-    const current = memory.entries[memory.idx];
-    memory.entries[memory.idx] = { href: href ?? current?.href ?? "/", state };
+    if (href === undefined) window.history.replaceState(state, "");
+    else window.history.replaceState(state, "", href);
   }
 
   back() {
-    const memory = this.#memory;
-    if (!memory) {
-      window.history.back();
-      return;
-    }
-    if (memory.idx === 0) return;
-    memory.idx -= 1;
-    const state = memory.entries[memory.idx]?.state ?? null;
-    
-    setTimeout(() => window.dispatchEvent(new PopStateEvent("popstate", { state })), 0);
+    window.history.back();
   }
 
   assign(href: string) {
-    if (!this.#memory) {
-      window.location.assign(href);
-      return;
-    }
-    this.#owner.leave(href);
+    window.location.assign(href);
   }
 
   reload() {
-    if (!this.#memory) window.location.reload();
-    else this.#owner.reload();
-  }
-
-  #entry() {
-    const memory = this.#memory;
-    return memory ? memory.entries[memory.idx] : undefined;
+    window.location.reload();
   }
 }
 

package/client/csrTypes.ts

@@ -109,6 +109,13 @@ export type PageLoadingRender = (props: PageLoadingProps) => PromiseOrObject<Rea
 export type LayoutLoadingRender = (props: LayoutLoadingProps) => PromiseOrObject<ReactNode>;
 export type LayoutNotFoundRender = (props: LayoutNotFoundProps) => PromiseOrObject<ReactNode>;
 export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<ReactNode>;
+export interface RouteGuardProps {
+  params: Record<string, string>;
+  searchParams: Record<string, string | string[]>;
+  /** MCP is listing the screen, so no argument is known: a guard reading one throws `RouteArgPending`. */
+  listing?: boolean;
+}
+export type RouteGuard = (props: RouteGuardProps) => Promise<void>;
 export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
@@ -125,6 +132,8 @@ export interface RouteRender {
   resolveHead?: ResolveHead;
   /** Parses the declared args without rendering, so a path value the type refuses answers not-found before any byte. */
   checkArgs?: (props: PageProps) => Promise<void>;
+  /** The route's `.guard()`, which `RouteGuards.run` calls root layout first, ahead of every layout body. */
+  guard?: RouteGuard;
   getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   /** A root layout's `theme`, readable before it renders. */
@@ -175,12 +184,14 @@ export interface PageModule {
   head?: Head;
   generateHead?: GenerateHead;
   Loading?: PageLoadingRender;
+  guard?: RouteGuard;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   pageConfig?: PageConfig;
   head?: Head;
   generateHead?: GenerateHead;
+  guard?: RouteGuard;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
@@ -279,6 +290,12 @@ export interface History {
   cachedLocationMap: Map<string, Location>;
   idx: number;
   dormant?: Set<string>; 
+  account?: CsrStackAccount;
+}
+export interface CsrStackAccount {
+  token: string | null; 
+  generation: number; 
+  leaving?: { key: string; generation: number }; 
 }
 
 export interface RouterProps {
@@ -360,10 +377,6 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
-/** Inside a layout's own markup that an MCP view hides while the page is drawn on its own: frame chrome draws nothing. */
-export const hiddenLayoutContext = sharedContext<boolean>("hiddenLayout", false);
-export const useInHiddenLayout = () => useContext(hiddenLayoutContext);
-
 export type PageActivity = "current" | "prev" | "pending" | "hidden";
 export interface PageActivityState {
   activity: PageActivity;
@@ -485,5 +498,7 @@ export interface LayoutFallbackRoute {
 export interface RouteGuide {
   pathSegment: string;
   pathRoute?: PathRoute;
+  /** CSR: the page a path under this node that no route matches draws, made for the pathname that was asked for. */
+  notFoundRouteOf?: (pathname: string) => PathRoute;
   children: { [key: string]: RouteGuide };
 }

package/client/href.ts

@@ -25,6 +25,14 @@ export class Href {
     return /^https?:/i.test(href);
   }
 
+  /** Whether an http(s) href resolves, against `base`, to another origin than `base`'s. Any other href stays a path in
+   * the app; no base, as outside a request, leaves for anywhere. */
+  static leavesOrigin(href: string, base: string | undefined): boolean {
+    if (!Href.hasWebScheme(href)) return false;
+    const origin = base === undefined ? undefined : Href.#parse(base)?.origin;
+    return !origin || Href.#parse(href, base)?.origin !== origin;
+  }
+
   /** Canonical absolute URL for an external href: follows the browser on an http(s) document base; on a native
    * `app://` base an absolute URL resolves as written and a network path resolves against https:. */
   static toExternalUrl(href: string, base: string): string {

package/client/makePageProto.tsx

@@ -28,11 +28,12 @@ const getPageInfo = (): { locale: string; path: string } => {
   const activePath = Translator.getActivePath();
   if (activePath) return { locale: activeLocale ?? defaultLocale, path: activePath };
   if (getEnv().side !== "server") {
-    const [, firstSegment = "", ...rest] = csrLocation.pathname.split("/");
+    const pathname = Translator.getRenderPath() ?? csrLocation.pathname;
+    const [, firstSegment = "", ...rest] = pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
     
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
-    return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : csrLocation.pathname) };
+    return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : pathname };
   }
   const h = untrackedHeaders();
   

package/client/route/PageDefinition.ts

@@ -1,8 +1,13 @@
+import type { PromiseOrObject } from "akanjs/base";
+import { AppScope } from "akanjs/fetch";
+import type { ReactNode } from "react";
 import { type RouteArgsShape, RouteDefinition } from "./RouteDefinition";
 import type {
+  RouteArgInfo,
   RouteArgOption,
   RouteArgType,
   RouteArgValue,
+  RouteBaseArgs,
   RoutePromptArgument,
   RoutePromptMeta,
   RouteSearchType,
@@ -13,7 +18,19 @@ interface PagePrompt {
   description: string;
 }
 
-export class PageDefinition<Args extends RouteArgsShape = Record<never, never>> extends RouteDefinition<Args> {
+interface PageApp {
+  name: string;
+  description: string;
+  load: (args: never) => PromiseOrObject<ReactNode>;
+}
+
+/** `never` for a name the page's render already receives, so a clash fails to compile as well as at definition. */
+type FreeName<Name extends string, Taken> = Name extends "lang" | keyof Taken ? never : Name;
+
+export class PageDefinition<
+  Args extends RouteArgsShape = Record<never, never>,
+  Apps extends RouteArgsShape = Record<never, never>,
+> extends RouteDefinition<Args> {
   /** MCP names an entry by `^[A-Za-z0-9_-]{1,64}$`; a prompt name outside it never reaches a client's slash menu. */
   static readonly promptName = /^[A-Za-z0-9_-]{1,64}$/;
   /** Appended to a list argument's description: the flat string map of `prompts/get` has no other spelling. */
@@ -21,33 +38,109 @@ export class PageDefinition<Args extends RouteArgsShape = Record<never, never>>
 
   readonly kind = "page" as const;
   #prompt?: PagePrompt;
+  readonly #apps: PageApp[] = [];
 
-  param<Name extends string, Type extends RouteArgType>(name: Name, type: Type, option: RouteArgOption = {}) {
+  param<Name extends string, Type extends RouteArgType>(
+    name: Name & FreeName<Name, Apps>,
+    type: Type,
+    option: RouteArgOption = {},
+  ) {
     this.declare({ kind: "param", name, type, list: false, desc: option.desc });
-    return this as unknown as PageDefinition<Args & { [Key in Name]: RouteArgValue<Type> }>;
+    return this as unknown as PageDefinition<Args & { [Key in Name]: RouteArgValue<Type> }, Apps>;
   }
 
-  search<Name extends string, Type extends RouteSearchType>(name: Name, type: Type, option: RouteArgOption = {}) {
+  search<Name extends string, Type extends RouteSearchType>(
+    name: Name & FreeName<Name, Apps>,
+    type: Type,
+    option: RouteArgOption = {},
+  ) {
     const list = Array.isArray(type);
     this.declare({ kind: "search", name, type: (list ? type[0] : type) as RouteArgType, list, desc: option.desc });
-    return this as unknown as PageDefinition<Args & { [Key in Name]?: RouteArgValue<Type> }>;
+    return this as unknown as PageDefinition<Args & { [Key in Name]?: RouteArgValue<Type> }, Apps>;
   }
 
   /** Publishes this screen as an MCP prompt: the description is the whole instruction a model receives. English. */
   prompt(name: string, description: string) {
-    if (!PageDefinition.promptName.test(name))
-      throw new Error(`[route-convention] prompt name "${name}" must match ${PageDefinition.promptName}`);
-    if (!description.trim()) throw new Error(`[route-convention] prompt "${name}" needs a description`);
+    PageDefinition.#assertEntry("prompt", name, description);
+    if (this.#apps.some((app) => app.name === name))
+      throw new Error(`[route-convention] page() names "${name}" as both an app and its prompt; MCP lists both`);
     this.#prompt = { name, description };
     return this;
   }
 
+  /**
+   * Publishes one component of this screen as an MCP App: a read-only tool whose arguments are the page's `.param()`
+   * and `.search()`, and whose result a host draws with `load`'s element. `load` may only query. On the web the
+   * element arrives as the render argument `name`. English description.
+   */
+  app<Name extends string>(
+    name: Name & FreeName<Name, Args & Apps>,
+    description: string,
+    load: (args: RouteBaseArgs & Args) => PromiseOrObject<ReactNode>,
+  ) {
+    PageDefinition.#assertEntry("app", name, description);
+    if (name === "lang")
+      throw new Error(`[route-convention] app "lang" would hide the lang every route receives; name it otherwise`);
+    if (this.args.some((arg) => arg.name === name) || this.#apps.some((app) => app.name === name))
+      throw new Error(
+        `[route-convention] page() names "${name}" twice; an app's element arrives as the render argument of its name`,
+      );
+    if (this.#prompt?.name === name)
+      throw new Error(`[route-convention] page() names "${name}" as both an app and its prompt; MCP lists both`);
+    this.#apps.push({ name, description, load: load as PageApp["load"] });
+    return this as unknown as PageDefinition<Args, Apps & { [Key in Name]: ReactNode }>;
+  }
+
+  override render(render: (args: RouteBaseArgs & Args & Apps) => PromiseOrObject<ReactNode>) {
+    return super.render(render as never);
+  }
+
   get promptMeta(): RoutePromptMeta | undefined {
     if (!this.#prompt) return undefined;
-    const args: RoutePromptArgument[] = this.args.map((arg) => {
+    return { ...this.#prompt, arguments: this.#entryArguments() };
+  }
+
+  get appMetas(): RoutePromptMeta[] {
+    return this.#apps.map(({ name, description }) => ({ name, description, arguments: this.#entryArguments() }));
+  }
+
+  /** One app's element for these args, alone: what an MCP call runs after the route guards, and its view draws. */
+  async loadApp(name: string, args: RouteBaseArgs & Args): Promise<ReactNode> {
+    const app = this.#apps.find((candidate) => candidate.name === name);
+    if (!app) throw new Error(`[route-convention] this page declares no app "${name}"`);
+    return await PageDefinition.#load(app, args);
+  }
+
+  protected override declare(arg: RouteArgInfo) {
+    if (this.#apps.some((app) => app.name === arg.name))
+      throw new Error(
+        `[route-convention] page() names "${arg.name}" twice; an app's element arrives as the render argument of its name`,
+      );
+    super.declare(arg);
+  }
+
+  protected override renderArgsOf(args: RouteBaseArgs & Args): PromiseOrObject<RouteBaseArgs & Args> {
+    if (!this.#apps.length) return args;
+    return Promise.all(this.#apps.map((app) => PageDefinition.#load(app, args))).then((elements) => ({
+      ...args,
+      ...Object.fromEntries(this.#apps.map((app, idx) => [app.name, elements[idx]])),
+    }));
+  }
+
+  #entryArguments(): RoutePromptArgument[] {
+    return this.args.map((arg) => {
       const description = [arg.desc, arg.list ? PageDefinition.commaSeparated : undefined].filter(Boolean).join(" ");
       return { name: arg.name, ...(description ? { description } : {}), required: arg.kind === "param" };
     });
-    return { ...this.#prompt, arguments: args };
+  }
+
+  static async #load(app: PageApp, args: object): Promise<ReactNode> {
+    return await AppScope.run(app.name, () => app.load(args as never));
+  }
+
+  static #assertEntry(kind: "prompt" | "app", name: string, description: string) {
+    if (!PageDefinition.promptName.test(name))
+      throw new Error(`[route-convention] ${kind} name "${name}" must match ${PageDefinition.promptName}`);
+    if (!description.trim()) throw new Error(`[route-convention] ${kind} "${name}" needs a description`);
   }
 }

package/client/route/RouteDefinition.ts

@@ -9,9 +9,10 @@ import {
 import { parseAkanI18nEnv } from "akanjs/common";
 import { deserialize } from "akanjs/constant";
 import type { ReactNode } from "react";
-import type { Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
+import type { Head, LayoutModule, PageConfig, PageModule, RouteGuardProps } from "../csrTypes";
 import { AkanNotFoundError } from "../router";
-import { RouteArgError, type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs";
+import { Translator } from "../translator";
+import { RouteArgError, type RouteArgInfo, type RouteArgInput, RouteArgPending, type RouteBaseArgs } from "./routeArgs";
 
 export type RouteArgsShape = Record<string, unknown>;
 export type RouteKind = "page" | "layout" | "rootLayout";
@@ -44,6 +45,7 @@ export abstract class RouteDefinition<
   #config?: PageConfig;
 
   #head?: HeadStage<never>;
+  #guard?: (args: never) => void | Promise<void>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
   #renderRoute?: {
@@ -60,6 +62,13 @@ export abstract class RouteDefinition<
     this.#head = head as HeadStage<never>;
     return this;
   }
+  /** Runs before any layout body; refuses with `router.redirect()` or `router.notFound()`. */
+  guard(guard: (args: RouteBaseArgs & Args) => void | Promise<void>) {
+    if (this.#guard)
+      throw new Error(`[route-convention] ${this.kind}() declares .guard() twice; run every check from one guard`);
+    this.#guard = guard as (args: never) => void | Promise<void>;
+    return this;
+  }
   loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
     this.#loading = render as (args: never) => PromiseOrObject<ReactNode>;
     return this;
@@ -127,10 +136,12 @@ 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 guard = this.#guard;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
       default: this.#renderRouteOf(render) as never,
       ...(this.#config ? { pageConfig: this.#config } : {}),
+      ...(guard ? { guard: this.#guardRouteOf(guard) } : {}),
       ...(head === undefined
         ? {}
         : typeof head === "function"
@@ -150,10 +161,28 @@ export abstract class RouteDefinition<
     return module;
   }
 
+  /** What `.render()` receives beyond the declared args; a page adds its apps' elements. */
+  protected renderArgsOf(args: RouteBaseArgs & Args & Extra): PromiseOrObject<RouteBaseArgs & Args & Extra> {
+    return args;
+  }
+
+  #guardRouteOf(guard: (args: never) => void | Promise<void>) {
+    const route = async (props: RouteGuardProps) => await guard(this.#guardArgsOf(props) as never);
+    Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
+    return route;
+  }
+
   #renderRouteOf(render: (args: never) => PromiseOrObject<ReactNode>) {
     const kept = this.#renderRoute;
     if (kept?.render === render && kept.argCount === this.args.length) return kept.route;
-    const route = async (props: RouteRenderProps) => await render(this.#argsOf(props) as never);
+
+    const route = async (props: RouteRenderProps) => {
+      const args = this.renderArgsOf(this.#argsOf(props));
+      if (!(args instanceof Promise)) return await render(args as never);
+      const path = Translator.getRenderPath();
+      const resolved = await args;
+      return await Translator.renderAt(path, () => render(resolved as never));
+    };
     Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
     this.#renderRoute = { render, argCount: this.args.length, route };
     return route;
@@ -190,6 +219,18 @@ export abstract class RouteDefinition<
     return (this.kind === "page" ? args : { ...args, children: props.children }) as RouteBaseArgs & Args & Extra;
   }
 
+  #guardArgsOf({ params, searchParams, listing }: RouteGuardProps): RouteBaseArgs & Args {
+    const { lang = parseAkanI18nEnv().defaultLocale } = params;
+    if (!listing) return { lang, ...this.resolveArgs({ params, searchParams }) } as RouteBaseArgs & Args;
+    const declared = new Set(this.args.map((arg) => arg.name));
+    return new Proxy({ lang } as RouteBaseArgs & Args, {
+      get: (target, key, receiver) => {
+        if (typeof key === "string" && declared.has(key)) throw new RouteArgPending(key);
+        return Reflect.get(target, key, receiver);
+      },
+    });
+  }
+
   /** 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;

package/client/route/RouteGuards.ts

@@ -0,0 +1,64 @@
+import type { RouteGuard, RouteGuardProps, RouteRender } from "../csrTypes";
+import { AkanNotFoundError } from "../router";
+import { routeArgsMarker } from "./RouteDefinition";
+
+/** Runs a route's `.guard()` stages: the root layout's first, the page's last, each before any layout body. */
+export class RouteGuards {
+  static readonly #refusedAt = new WeakMap<object, number>();
+
+  /** The first refusal stops the chain and is thrown: a redirect, a not-found, or the error a guard leaked. */
+  static async run(renders: (RouteRender | undefined)[], props: RouteGuardProps): Promise<void> {
+    for (const [idx, render] of renders.entries()) {
+      if (!render?.guard) continue;
+      try {
+        await render.guard(props);
+      } catch (error) {
+        const refusal = RouteGuards.refusalOf(error);
+        
+        const thrown = typeof refusal === "object" && refusal !== null ? refusal : new Error(String(refusal));
+        RouteGuards.#refusedAt.set(thrown, idx);
+        throw thrown;
+      }
+    }
+  }
+
+  /** The index, in the renders `run` was given, whose guard threw `error`; `undefined` for anything else. */
+  static refusedAt(error: unknown): number | undefined {
+    return typeof error === "object" && error !== null ? RouteGuards.#refusedAt.get(error) : undefined;
+  }
+
+  /** Whether MCP may list the screen to this caller: a guard that reads an argument leaves the verdict to the call. */
+  static async admits(renders: (RouteRender | undefined)[], props: RouteGuardProps): Promise<boolean> {
+    for (const render of renders) {
+      if (!render?.guard) continue;
+      try {
+        await render.guard({ ...props, listing: true });
+      } catch (error) {
+        if (!RouteGuards.isArgPending(error)) return false;
+      }
+    }
+    return true;
+  }
+
+  static refusalOf(error: unknown): unknown {
+    const status = (error as { statusCode?: unknown } | null)?.statusCode;
+    return status === 403 || status === 404 ? new AkanNotFoundError() : error;
+  }
+
+  static isArgPending(error: unknown): boolean {
+    return (error as { digest?: unknown } | null)?.digest === "AKAN_ROUTE_ARG_PENDING";
+  }
+
+  /** One guard running each of `guards` in order, or none when no guard is given. */
+  static compose(...guards: (RouteGuard | undefined)[]): RouteGuard | undefined {
+    const chain = guards.filter((guard): guard is RouteGuard => !!guard);
+    if (chain.length <= 1) return chain[0];
+    const composed: RouteGuard = async (props) => {
+      for (const guard of chain) await guard(props);
+    };
+    
+    const reads = chain.map((guard) => (guard as { [routeArgsMarker]?: unknown[] })[routeArgsMarker]);
+    if (reads.every(Array.isArray)) Object.defineProperty(composed, routeArgsMarker, { value: reads.flat() });
+    return composed;
+  }
+}

package/client/route/index.ts

@@ -2,6 +2,7 @@ export * from "./LayoutDefinition";
 export * from "./PageDefinition";
 export * from "./RootLayoutDefinition";
 export * from "./RouteDefinition";
+export * from "./RouteGuards";
 export * from "./RouteHead";
 export * from "./resolveRouteModule";
 export * from "./routeArgs";

package/client/route/resolveRouteModule.ts

@@ -40,3 +40,11 @@ export const resolveRouteModule = (
   if (pattern) definition.assertPattern(pattern, key);
   return { module: definition.toRouteModule(), definition };
 };
+
+/** The export sets allow `guard` for an unfolded chain and the generated root layout; the legacy shape never gained it. */
+export const assertGuardOnChain = (label: string, resolved: ResolvedRouteModule): ResolvedRouteModule => {
+  if (resolved.definition || !("guard" in resolved.module)) return resolved;
+  throw new Error(
+    `[route-convention] ${label} exports guard beside a legacy default; declare it with .guard() on its chain`,
+  );
+};

package/client/route/routeArgs.ts

@@ -49,3 +49,12 @@ export class RouteArgError extends Error {
     this.arg = arg;
   }
 }
+
+/** A guard read an argument while MCP listed its screen, when none is known yet: the call decides with them. */
+export class RouteArgPending extends Error {
+  readonly digest = "AKAN_ROUTE_ARG_PENDING";
+  constructor(name: string) {
+    super(`Argument "${name}" is not known while the screen is listed`);
+    this.name = "RouteArgPending";
+  }
+}