akanjs 3.1.0-rc.21 → 3.1.0-rc.22

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;

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";
+  }
+}

package/client/router.ts

@@ -177,6 +177,7 @@ class Router {
   #listensToPopstate: boolean = false;
   #backsAwaitingPopstate = 0;
   #redirects = 0;
+  #navigations = 0;
   #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -390,6 +391,7 @@ class Router {
   }
   push(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
+    this.#navigations += 1;
     this.#track(this.#instance.push(href, routeOptions));
     this.#rememberHistoryState("push");
     this.#postDevSyncNavigation("push", href);
@@ -397,6 +399,7 @@ class Router {
   }
   replace(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
+    this.#navigations += 1;
     this.#track(this.#instance.replace(href, routeOptions));
     this.#rememberHistoryState("replace");
     this.#postDevSyncNavigation("replace", href);
@@ -433,6 +436,7 @@ class Router {
   back(routeOptions?: RouteOptions) {
     if (getEnv().side === "server") throw new Error("back is only available in client side");
     this.#checkInitialized();
+    this.#navigations += 1;
     this.#instance.back(routeOptions);
     return undefined as never;
   }
@@ -447,6 +451,11 @@ class Router {
   redirectCount(): number {
     return this.#redirects;
   }
+  /** Client-side moves so far — push, replace, back, redirect, notFound: a route guard that saw this change sent the
+   * visitor elsewhere, so its page does not draw. */
+  navigationCount(): number {
+    return this.#navigations;
+  }
   redirect(href: string, options: RedirectOptions = {}): never {
     const method = options.method ?? "replace";
     const status = options.status ?? 307;
@@ -463,6 +472,7 @@ class Router {
       throw new AkanRedirectError(fullHref, method, status);
     } else {
       this.#redirects += 1;
+      this.#navigations += 1;
       this.#instance[method](href);
     }
     return undefined as never;
@@ -474,6 +484,7 @@ class Router {
     }
     this.#checkInitialized();
     this.#redirects += 1;
+    this.#navigations += 1;
     this.#instance.replace("/404");
     return undefined as never;
   }

package/common/authCookie.ts

@@ -0,0 +1,13 @@
+
+
+/** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
+export const legacyAuthTokenKey = "jwt";
+
+/** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
+export const isAuthTokenKey = (key: string): boolean =>
+  key === legacyAuthTokenKey || key.startsWith(`${legacyAuthTokenKey}:`);
+
+const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
+
+export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
+  !!cookieHeader && authCookiePattern.test(cookieHeader);

package/common/authToken.ts

@@ -1,20 +1,9 @@
 import { getEnv } from "akanjs/base";
+import { legacyAuthTokenKey } from "./authCookie";
 import { decodeJwtPayload } from "./jwtDecode";
 
-/** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
-export const legacyAuthTokenKey = "jwt";
-
 export const authTokenKey = (): string => `${legacyAuthTokenKey}:${getEnv().appName}`;
 
-/** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
-export const isAuthTokenKey = (key: string): boolean =>
-  key === legacyAuthTokenKey || key.startsWith(`${legacyAuthTokenKey}:`);
-
-const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
-
-export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
-  !!cookieHeader && authCookiePattern.test(cookieHeader);
-
 export const isOwnAuthToken = (jwt: string): boolean => {
   const { appName, environment } = getEnv();
   try {