akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/vendor/use-agentic/types.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from "react";
+
 export type JsonSchema = Record<string, unknown>;
 
 /** `true` asks with a default message, a string is the message, a function decides from the arguments. */
@@ -6,7 +8,24 @@ export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) =>
 /** Re-checked at the moment of execution; a string is the refusal reason the agent reads. */
 export type ToolGuard = (args: Record<string, unknown>) => true | string;
 
-export interface ToolEntry {
+/**
+ * What a card tool renders while its call waits, and the two ways the user ends that wait. `submit` is the call's
+ * result, `cancel` is its refusal; whichever comes first settles the call and takes the card off the screen, so a
+ * second call of either does nothing.
+ */
+export interface ToolCardControl {
+  args: Record<string, unknown>;
+  submit: (value: unknown) => void;
+  cancel: (reason?: string) => void;
+}
+
+/**
+ * Called, not mounted — the host invokes it inside its own render, so the returned tree keeps no state of its
+ * own between renders. Put anything stateful in a component the function returns.
+ */
+export type ToolCard = (control: ToolCardControl) => ReactNode;
+
+interface ToolEntryBase {
   name: string;
   description?: string;
   parameters?: JsonSchema;
@@ -17,7 +36,37 @@ export interface ToolEntry {
   settle?: boolean;
   confirm?: ToolConfirm;
   guard?: ToolGuard;
+}
+
+export interface ToolActionEntry extends ToolEntryBase {
   run: (args: Record<string, unknown>) => unknown;
+  card?: never;
+}
+
+/**
+ * A call the **user** answers rather than the screen: the host parks the call, renders `card`, and what the card
+ * submits is what the model reads back. `confirm` is not read for one — the card in front of the user is already
+ * the asking, and a gate before it would ask them twice for one thing.
+ */
+export interface ToolCardEntry extends ToolEntryBase {
+  card: ToolCard;
+  run?: never;
+}
+
+export type ToolEntry = ToolActionEntry | ToolCardEntry;
+
+/**
+ * That a call is happening, for a host drawing it on the screen rather than in a transcript.
+ *
+ * Emitted around the execution alone — after the approval card settled, and never for a call a guard or an
+ * approval refused before it ran, so a host may treat `start` as "this is being done to the page right now".
+ */
+export interface ToolActivity {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  phase: "start" | "end";
+  error?: string;
 }
 
 /** One call an agent made through the surface, in the order it made them. */
@@ -118,6 +167,30 @@ export interface ToolCallResult {
   error?: string;
 }
 
+/**
+ * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
+ * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
+ * neither is distinguishable from `end` without it.
+ */
+export type TurnStop = "end" | "toolUse" | "length";
+
+/** What the provider counted for one turn. `input` is the whole prompt, cached part included — what the window held. */
+export interface TurnUsage {
+  input: number;
+  output: number;
+}
+
+/**
+ * What the backend knows about the model it relays to, each only when it was told: a window it guesses is worse
+ * than none, because a guard placed on a wrong number fires at the wrong time and nothing says so.
+ */
+export interface TurnLimits {
+  /** The model's context window, prompt and answer together. */
+  window?: number;
+  /** The answer ceiling the backend actually requests. */
+  output?: number;
+}
+
 /**
  * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
  * tool, the same reason `askUser` belongs to the session and not to the surface.
@@ -131,13 +204,6 @@ export interface ToolCallResult {
  * model cannot read and says so in the transcript, because a silently dropped file is one the model then
  * hallucinates about.
  */
-/**
- * Why an assistant turn ended. `length` is the provider's own ceiling rather than the model's choice, so the turn
- * is incomplete — a truncated answer and a turn cut off before its tool call finished both arrive this way, and
- * neither is distinguishable from `end` without it.
- */
-export type TurnStop = "end" | "toolUse" | "length";
-
 export interface MessageAttachment {
   name: string;
   mimeType: string;
@@ -154,11 +220,42 @@ export interface MessageAttachment {
   ref?: string;
 }
 
+/**
+ * Data the user pointed at while they were talking, rather than a file they handed over — a record, or one field
+ * of one, named in the message the way they named it. It rides a message for the same reason an attachment does:
+ * what somebody referred to while asking is part of the asking, and the turn context is rebuilt from the screen
+ * every turn, so a screen-shaped carrier forgets what was pointed at three turns ago.
+ *
+ * **`value` is a snapshot, deliberately.** It is what the data was when the user sent the message, and it is never
+ * re-read on a later turn. Re-reading would be wrong twice over: it rewrites what the person was looking at when
+ * they spoke, and the common case is an agent that then *edits* the very field it was pointed at, which would
+ * leave the reference showing the result and no record of what was being changed from. `refName`, `refId` and
+ * `path` are the way back to the current value — a tool re-reads it when the answer needs it.
+ *
+ * **`value` arrives masked, and nothing downstream can mask it again.** Masking needs the model class
+ * (`mask(model, value)`), which no wire carries, so whichever model the host names when it stages the reference is
+ * the whole of the decision about what leaves the browser.
+ */
+export interface MessageReference {
+  /** The host's own `refName`, unchanged — the vocabulary its published tools already speak. */
+  refName: string;
+  refId: string;
+  /** What the chip draws and what the token in the text spells, so the two can never disagree. */
+  label: string;
+  /** A dotted path into the document, in `pathSet`'s vocabulary. Absent means the whole of it. */
+  path?: string;
+  value?: unknown;
+  /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+  note?: string;
+}
+
 export interface ChatMessage {
   role: ChatRole;
   text?: string;
   /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
   attachments?: MessageAttachment[];
+  /** Data the message points at. Content, framed like attachments and for the same reason. */
+  references?: MessageReference[];
   toolCalls?: ToolCallRequest[];
   toolResults?: ToolCallResult[];
   /** A failed or capped turn, recorded in the transcript rather than thrown past it. */
@@ -174,6 +271,12 @@ export interface ChatMessage {
    * a host renders it as one.
    */
   summary?: boolean;
+  /**
+   * What the provider counted for the turn that wrote this assistant message. Kept on the message so it moves,
+   * persists and is summarized away with it; never sent, and dropped from what a compaction keeps, since it
+   * measured a prompt that no longer exists.
+   */
+  usage?: TurnUsage;
 }
 
 /** One block of screen context the host assembles per turn. `kind` is the host's vocabulary; the wire forwards it verbatim. */
@@ -185,12 +288,20 @@ export interface ContextBlock {
 export type RunnerEvent =
   | { type: "text"; delta: string }
   | { type: "toolCall"; id: string; name: string; args: Record<string, unknown> }
-  | { type: "done"; stop: TurnStop }
+  | { type: "done"; stop: TurnStop; usage?: TurnUsage; limits?: TurnLimits }
   /**
    * `data` accompanies a message that is a code rather than a sentence — the values whoever resolves the code
    * interpolates into its text. A host that does not know the code shows the message as it stands.
+   *
+   * `overflow` marks the provider refusing a prompt too long for its window — the one refusal a session can undo
+   * on its own, by compacting and asking again. `limit` is the window when the refusal named it.
    */
-  | { type: "error"; message: string; data?: Record<string, string | number> };
+  | {
+      type: "error";
+      message: string;
+      data?: Record<string, string | number>;
+      overflow?: { limit?: number };
+    };
 
 export interface RunnerRequest {
   messages: ChatMessage[];

package/webkit/RenderLayer.tsx

@@ -0,0 +1,45 @@
+"use client";
+import type { RouteRender } from "akanjs/client";
+import { createElement, memo, type ReactNode, useRef } from "react";
+import { useFetch } from "./useFetch";
+
+interface RenderLayerProps {
+  renders: RouteRender[];
+  index: number;
+  params: Record<string, string>;
+  searchParams: Record<string, string | string[]>;
+  leaf?: ReactNode;
+}
+export const RenderLayer = memo(({ renders, index, params, searchParams, leaf = null }: RenderLayerProps) => {
+  const isLast = index >= renders.length - 1;
+  const children = isLast ? (
+    leaf
+  ) : (
+    <RenderLayer renders={renders} index={index + 1} params={params} searchParams={searchParams} leaf={leaf} />
+  );
+  const routeRender = renders[index];
+  const isAsyncRender = isAsyncRouteRender(routeRender);
+  const resultRef = useRef<ReactNode | Promise<ReactNode> | null>(null);
+  if (isAsyncRender && resultRef.current === null) {
+    resultRef.current = routeRender?.render({ children, params, searchParams } as never) ?? null;
+  }
+  const { fulfilled, value } = useFetch(resultRef.current);
+  if (!routeRender) return null;
+  if (!isAsyncRender) return createElement(routeRender.render as never, { children, params, searchParams } as never);
+  if (!fulfilled || !value) return <>{composeLoadingFallback(renders.slice(index), params)}</>;
+  return value;
+});
+
+function isAsyncRouteRender(routeRender?: RouteRender): boolean {
+  return Boolean(routeRender?.isAsync || routeRender?.render.constructor.name === "AsyncFunction");
+}
+
+function composeLoadingFallback(renders: RouteRender[], params: Record<string, string>): ReactNode {
+  let element: ReactNode = null;
+  for (let i = renders.length - 1; i >= 0; i--) {
+    const Loading = renders[i]?.Loading;
+    if (!Loading) continue;
+    element = Loading({ params, children: element } as never) as ReactNode;
+  }
+  return element;
+}

package/webkit/bootCsr.tsx

@@ -27,10 +27,9 @@ import {
   parseRouteModuleKey,
   routeSegmentToTreePath,
 } from "akanjs/common";
-import { createElement, memo, type ReactNode, useRef } from "react"; 
 import * as ReactDOM from "react-dom/client";
+import { RenderLayer } from "./RenderLayer";
 import { useCsrValues } from "./useCsrValues";
-import { useFetch } from "./useFetch";
 
 type RouteModuleWithConfig = RouteModule & { pageConfig?: PageConfig };
 type CsrRouteModuleLoader = () => Promise<RouteModuleSource>;
@@ -42,54 +41,23 @@ declare global {
   }
 }
 
-interface RootRenderLayerProps {
-  renders: RouteRender[];
-  index: number;
-  params: Record<string, string>;
-  searchParams: Record<string, string | string[]>;
-}
-const RootRenderLayer = memo(({ renders, index, params, searchParams }: RootRenderLayerProps) => {
-  const isLast = index >= renders.length - 1;
-  const children = isLast ? null : (
-    <RootRenderLayer renders={renders} index={index + 1} params={params} searchParams={searchParams} />
-  );
-  const routeRender = renders[index];
-  const isAsyncRender = isAsyncRouteRender(routeRender);
-  const resultRef = useRef<ReactNode | Promise<ReactNode> | null>(null);
-  if (isAsyncRender && resultRef.current === null) {
-    resultRef.current = routeRender?.render({ children, params, searchParams } as never) ?? null;
-  }
-  const { fulfilled, value: Layout } = useFetch(resultRef.current);
-  if (!routeRender) return null;
-  if (!isAsyncRender) return createElement(routeRender.render as never, { children, params, searchParams } as never);
-  if (!fulfilled || !Layout) return <>{composeLoadingFallback(renders.slice(index), params)}</>;
-  return Layout;
-});
-
-function isAsyncRouteRender(routeRender?: RouteRender): boolean {
-  return Boolean(routeRender?.isAsync || routeRender?.render.constructor.name === "AsyncFunction");
-}
-
-function composeLoadingFallback(renders: RouteRender[], params: Record<string, string>): ReactNode {
-  let element: ReactNode = null;
-  for (let i = renders.length - 1; i >= 0; i--) {
-    const Loading = renders[i]?.Loading;
-    if (!Loading) continue;
-    element = Loading({ params, children: element } as never) as ReactNode;
-  }
-  return element;
-}
-
 export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
   const i18n = parseAkanI18nEnv();
   window.document.body.style.overflow = "hidden";
   initializeMobileTargetFromSearch();
-  const mobileBasePath = window.__AKAN_MOBILE_TARGET__?.basePath?.replace(/^\/+|\/+$/g, "");
-  const pathname = mobileBasePath && window.location.pathname === "/" ? `/${mobileBasePath}` : window.location.pathname;
-  if (pathname === "/404") return;
+  if (window.location.pathname === "/404") return;
 
   const [device, jwt] = await Promise.all([Device.load({ supportLanguages: i18n.locales }), getStoredAuthToken()]);
-  if (!window.__AKAN_MOBILE_TARGET__ && !pathname.startsWith(`/${device.lang}`))
+  const mobileTarget = window.__AKAN_MOBILE_TARGET__;
+  
+  if (mobileTarget && window.location.pathname === "/")
+    window.history.replaceState(
+      window.history.state,
+      "",
+      `${mobileHomePath(device.lang, mobileTarget)}${window.location.search}${window.location.hash}`,
+    );
+  const pathname = window.location.pathname;
+  if (!mobileTarget && !pathname.startsWith(`/${device.lang}`))
     window.location.replace(`/${device.lang}${pathname}${window.location.search}${window.location.hash}`);
 
   if (jwt) initAuth({ jwt });
@@ -109,7 +77,7 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
       const parsed = parseRouteModuleKey(key);
       if (basePaths) {
         const pageBasePath = parsed.sourceRouteSegments.find((segment) => !/^\(.+\)$/.test(segment));
-        if (pageBasePath && otherBasePaths.includes(pageBasePath)) return; 
+        if (pageBasePath && otherBasePaths.includes(pageBasePath)) return;
       }
       const entry = typeof value === "function" ? { loader: value } : value;
       const loaded = await entry.loader();
@@ -140,7 +108,6 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
       if (!children) throw new Error("No children");
       return children;
     }, routeMap);
-    if (!targetRouteMap) continue;
 
     const targetPath = pathSegments[pathSegments.length - 1];
     if (!targetPath) continue;
@@ -169,7 +136,6 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
       resolveError: layoutPage ? () => layoutPage.Error : undefined,
     };
     targetRouteMap.set(targetPath, {
-
       ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
       ...(parsed.kind === "layout"
         ? { renderLayout: routeRender, layoutPageConfig: (page as RouteModuleWithConfig).pageConfig }
@@ -189,7 +155,7 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
     parentLayouts: RouteRender[] = [],
     parentPaths: string[] = [],
     parentPageConfigChain: PageConfig[] = [],
-    parentOverrides: RouteRender[] = [],
+    parentRootRenders: RouteRender[] = [],
   ): PathRoute[] => {
     const parentPath = parentPaths.filter((path) => path !== "/").join("");
     const isRouteGroup = /^\/\(.*\)$/.test(route.path);
@@ -200,21 +166,19 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
     const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
     const currentLayoutConfig = route.renderLayout && route.layoutPageConfig ? route.layoutPageConfig : null;
-
+    
     const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
-    const overrideRenders = [...parentOverrides, ...currentOverrideRenders];
+    const nodeRenders = [...currentOverrideRenders, ...(route.renderLayout ? [route.renderLayout] : [])];
     const rootLayoutStack = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderRootLayouts = [...overrideRenders, ...rootLayoutStack];
-    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
+    const renderRootLayouts = isRoot ? [...parentRootRenders, ...nodeRenders] : parentRootRenders;
+    const renderLayouts = isRoot ? parentLayouts : [...parentLayouts, ...nodeRenders];
     const pageConfigChain = [
       ...parentPageConfigChain,
       ...(currentRootLayout || currentLayout ? (currentLayoutConfig ? [currentLayoutConfig] : []) : []),
     ];
-    const pageRenderRootLayouts =
-      route.pageIncludesOwnLayout === false && currentRootLayout
-        ? [...overrideRenders, ...parentRootLayouts]
-        : renderRootLayouts;
-    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
+    const pageNodeRenders = route.pageIncludesOwnLayout === false ? currentOverrideRenders : nodeRenders;
+    const pageRenderRootLayouts = isRoot ? [...parentRootRenders, ...pageNodeRenders] : parentRootRenders;
+    const pageRenderLayouts = isRoot ? parentLayouts : [...parentLayouts, ...pageNodeRenders];
     const pageRenderConfigChain =
       route.pageIncludesOwnLayout === false && (currentRootLayout || currentLayout)
         ? parentPageConfigChain
@@ -247,7 +211,7 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
         : []),
       ...(route.children.size
         ? [...route.children.values()].flatMap((child) =>
-            getPathRoutes(child, rootLayoutStack, renderLayouts, pathSegments, pageConfigChain, overrideRenders),
+            getPathRoutes(child, rootLayoutStack, renderLayouts, pathSegments, pageConfigChain, renderRootLayouts),
           )
         : []),
     ];
@@ -276,7 +240,7 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
     return (
       <csrContext.Provider value={csrValues}>
         {location.pathRoute.renderRootLayouts.length > 0 ? (
-          <RootRenderLayer
+          <RenderLayer
             renders={location.pathRoute.renderRootLayouts}
             index={0}
             params={location.params}
@@ -305,6 +269,13 @@ function initializeMobileTargetFromSearch() {
   window.__AKAN_MOBILE_TARGET__ = { name, basePath, ...(indexPath ? { indexPath } : {}) };
 }
 
+function mobileHomePath(lang: string, target: { basePath?: string; indexPath?: string }) {
+  const segments = [lang, target.basePath, target.indexPath]
+    .flatMap((part) => (part ?? "").split("/"))
+    .filter((segment) => segment.length > 0);
+  return `/${segments.join("/")}`;
+}
+
 function validateRouteModuleExports(key: string, mod: RouteModule) {
   const parsed = parseRouteModuleKey(key);
   if (parsed.kind === "overrides") {
@@ -321,16 +292,4 @@ function validateRouteModuleExports(key: string, mod: RouteModule) {
   if ("head" in mod && "generateHead" in mod) {
     throw new Error(`[route-convention] head and generateHead cannot both be exported in ${key}`);
   }
-  if (
-    !parsed.isInternalRootLayout &&
-    ("head" in mod || "generateHead" in mod) &&
-    ("metadata" in mod || "generateMetadata" in mod)
-  ) {
-    throw new Error(
-      `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${key}`,
-    );
-  }
-  if ("metadata" in mod && "generateMetadata" in mod) {
-    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${key}`);
-  }
 }

package/webkit/index.ts

@@ -1,12 +1,9 @@
 export { bootCsr } from "./bootCsr";
-export { createRobotPage } from "./createRobotPage";
-export { createSitemapPage } from "./createSitemapPage";
 export { lazy } from "./lazy";
+export { createRobotPage, createSitemapPage } from "./seoPages";
 export type * from "./types";
 export { useBodyScrollLock } from "./useBodyScrollLock";
 export { useCamera } from "./useCamera";
-export { useCodepush } from "./useCodepush";
-export { useContact } from "./useContact";
 export { useCsrValues } from "./useCsrValues";
 export { useDebounce } from "./useDebounce";
 export { useEscapeKey } from "./useEscapeKey";

package/webkit/lazy.tsx

@@ -5,17 +5,8 @@ import { forwardRef, lazy as reactLazy } from "react";
 
 const isServer = typeof window === "undefined";
 
-/**
- * `suspense` puts a Suspense boundary around the lazy component, so a chunk that resolves *after* the
- * page is painted — a modal body, a dropdown menu — suspends only itself. Without one the suspension
- * travels up to the nearest boundary, which is the route (`server/routeElementComposer.tsx`), and the
- * whole page repaints as its loading fallback on the first open.
- *
- * It is opt-in rather than the default because a boundary also changes server rendering: under the
- * default `renderMode: "stream"` the boundary's subtree leaves the shell as `loading` and arrives later
- * in the stream. That is fine for an interaction shell and wrong for a page body, which SEO snapshots,
- * prerendering and pre-hydration E2E read out of the shell.
- */
+/** `suspense`: a late chunk suspends only itself, not the route. Opt-in: under streaming the boundary's subtree
+ * leaves the shell, which SEO snapshots, prerendering and pre-hydration E2E read. */
 type LazyOption = { ssr?: boolean; suspense?: boolean; loading?: () => ReactNode };
 type LazyProps = Record<string, unknown>;
 type LoadedOf<Loaded> = Loaded extends { default: infer T } ? T : Loaded;
@@ -26,7 +17,7 @@ const normalizeLazyModule = <Loaded,>(loaded: Loaded): LazyModule => {
   return { default: loaded as ComponentType<LazyProps> };
 };
 
-/** React lazy wrapper with Akan's `ssr: false` server stub and client mount gate. */
+/** `ssr: false` renders `loading` on the server and mounts the component only after hydration. */
 export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption): LoadedOf<Loaded> => {
   const ssrFalse = option?.ssr === false;
   const renderFallback = (): ReactNode => (option?.loading ? option.loading() : null);
@@ -38,7 +29,6 @@ export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption
   const LazyInner = reactLazy(async () => normalizeLazyModule(await loader()));
 
   if (!ssrFalse) {
-
     const Wrapper = forwardRef<unknown, LazyProps>((props, ref) =>
       option?.suspense ? (
         <React.Suspense fallback={renderFallback()}>

package/webkit/nativeNavigation.ts

@@ -0,0 +1,116 @@
+"use client";
+import { router as clientRouter, debugFrame, normalizeDeepLinkHref } from "akanjs/client";
+import { app, isNativeApp, push } from "akanjs/client/native";
+
+export interface NativeBackState {
+  path: string;
+  keyboardHeight: number;
+  keyboardVisible: boolean;
+  router: { back: () => void };
+}
+
+interface NativeNavigationOptions {
+  historyIdx: () => number;
+  backState: () => NativeBackState;
+  /** A back press while the keyboard is up only puts it away. */
+  dismissKeyboard: () => unknown;
+}
+
+/** A native shell's deep links, push taps and Android back button, for the CSR frame that owns the history. */
+export class NativeNavigation {
+  #mountedAt = Date.now();
+  #handled: { href: string; handledAt: number } | null = null;
+  #didResetStack = false;
+
+  constructor(readonly options: NativeNavigationOptions) {}
+
+  listen() {
+    if (!isNativeApp()) return () => undefined;
+    
+    if (push.isSupported("setForegroundPresentation"))
+      void push
+        .setForegroundPresentation({ banner: true, list: true, sound: true, badge: true })
+        .catch(() => undefined);
+    const stops = [
+      app.listen("urlOpen", ({ url }) => {
+        this.openDeepLink(url);
+      }),
+      app.listen("backButton", () => {
+        this.back();
+      }),
+      push.listen("action", ({ message }) => {
+        this.openPushLink(message.data.url);
+      }),
+    ];
+    return () => {
+      for (const stop of stops) stop();
+    };
+  }
+
+  openDeepLink(url: string) {
+    const href = normalizeDeepLinkHref(url);
+    const now = Date.now();
+    const lastHandled = this.#handled;
+    const resetStack = !lastHandled && now - this.#mountedAt < 5000;
+    if (lastHandled?.href === href && now - lastHandled.handledAt < 1000) return;
+    this.#handled = { href, handledAt: now };
+    debugFrame("native.deepLink", {
+      href,
+      resetStack,
+      historyIdx: this.options.historyIdx(),
+      mountedForMs: now - this.#mountedAt,
+      routerReady: clientRouter.isInitialized,
+    });
+    if (resetStack) this.#didResetStack = true;
+    this.#enterWhenReady(href, resetStack);
+  }
+
+  openPushLink(url: unknown) {
+    if (typeof url !== "string" || !url.startsWith("/") || url.startsWith("//")) {
+      debugFrame("native.pushLink.skipped", { url: typeof url === "string" ? url : null });
+      return;
+    }
+    this.openDeepLink(url);
+  }
+
+  back() {
+    const backState = this.options.backState();
+    debugFrame("native.backButton", {
+      historyIdx: this.options.historyIdx(),
+      path: backState.path,
+      keyboardHeight: backState.keyboardHeight,
+    });
+    if (backState.keyboardVisible) {
+      void this.options.dismissKeyboard();
+      return;
+    }
+    if (this.options.historyIdx() > 0) {
+      backState.router.back();
+      return;
+    }
+    const fallbackPath = window.__AKAN_MOBILE_TARGET__?.indexPath ?? "/";
+    
+    if (this.#didResetStack || NativeNavigation.#homeRelative(backState.path) === fallbackPath) {
+      void app.exit().catch(() => undefined);
+      return;
+    }
+    clientRouter.backOrFallback(fallbackPath, { scrollToTop: false });
+  }
+
+  static #homeRelative(routePath: string) {
+    const basePath = window.__AKAN_MOBILE_TARGET__?.basePath?.replace(/^\/+|\/+$/g, "");
+    const segments = routePath.split("/").filter(Boolean);
+    if (segments[0] === ":lang") segments.shift();
+    if (basePath && segments[0] === basePath) segments.shift();
+    return `/${segments.join("/")}`;
+  }
+
+  #enterWhenReady(href: string, resetStack: boolean, attempt = 0) {
+    if (!clientRouter.isInitialized) {
+      if (attempt < 40) window.setTimeout(() => this.#enterWhenReady(href, resetStack, attempt + 1), 50);
+      else debugFrame("native.deepLink.skipped", { href, reason: "router-not-ready" });
+      return;
+    }
+    clientRouter.enterDeepLink(href, { resetStack, scrollToTop: true });
+  }
+}