akanjs 2.3.9 → 2.3.10-rc.0

package/capacitor.base.config.ts

@@ -85,6 +85,7 @@ const localCsrUrl = (ip: string, target: AkanMobileTargetConfig, appInfo: AppSca
   const port = resolveLocalCsrPort(appInfo);
   const params = new URLSearchParams({ csr: "true", akanMobileTarget: target.name });
   if (basePath) params.set("akanMobileBasePath", basePath);
+  if (target.indexPath) params.set("akanMobileIndexPath", target.indexPath);
   return `http://${ip}:${port}/${pathname}?${params}`;
 };
 
@@ -97,8 +98,20 @@ export const withBase = (
   const appInfo = appData;
   if (!appInfo) throw new Error("withBase requires apps/<app>/akan.app.json metadata.");
   const target = resolveTarget(appInfo, targetName);
+  const {
+    name: _name,
+    basePath: _basePath,
+    indexPath: _indexPath,
+    version: _version,
+    buildNum: _buildNum,
+    assets: _assets,
+    permissions: _permissions,
+    deepLinks: _deepLinks,
+    files: _files,
+    ...capacitorTarget
+  } = target;
   const baseConfig: CapacitorConfig = {
-    ...target,
+    ...capacitorTarget,
     appId: target.appId,
     appName: target.appName,
     webDir: "dist",

package/client/capacitor.ts

@@ -16,6 +16,7 @@ export type CapacitorAppModule = {
     addListener: (eventName: string, listenerFunc: (...args: unknown[]) => void) => Promise<unknown> | unknown;
     removeAllListeners: () => Promise<void> | void;
     exitApp?: () => Promise<void> | void;
+    getLaunchUrl?: () => Promise<{ url?: string | null }>;
     getInfo: () => Promise<{ id: string; version: string; build: string; [key: string]: unknown }>;
   };
 };

package/client/router.ts

@@ -4,6 +4,14 @@ import { getBasePathFromPathname, Logger, parseAkanI18nEnv, parseBasePaths } fro
 export interface RouteOptions {
   scrollToTop?: boolean;
 }
+export interface RouteManifest {
+  routes: string[];
+}
+export interface DeepLinkOptions extends RouteOptions {
+  resetStack?: boolean;
+}
+
+const DEEP_LINK_STACK_STEP_DELAY = 450;
 
 export interface RouterInstance {
   push: (href: string, routeOptions?: RouteOptions) => void;
@@ -20,6 +28,8 @@ interface InternalRouterInstance {
 interface RouterOptions {
   prefix?: string;
   lang?: string;
+  routeManifest?: RouteManifest | string[];
+  indexPath?: string;
 }
 interface SsrServerRouterOption extends RouterOptions {
   type: "ssr";
@@ -72,13 +82,44 @@ function getServerRequestContext() {
 const getConfiguredBasePaths = () => new Set(parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS));
 
 const shouldExposeBasePath = () => getEnv().operationMode === "local";
-const CSR_RUNTIME_SEARCH_PARAMS = ["csr", "akanMobileTarget", "akanMobileBasePath"] as const;
+const CSR_RUNTIME_SEARCH_PARAMS = ["csr", "akanMobileTarget", "akanMobileBasePath", "akanMobileIndexPath"] as const;
 
 const getLocaleFromPathname = (pathname: string) => {
   const [firstSegment] = pathname.split("/").filter(Boolean);
   return parseAkanI18nEnv().locales.find((locale) => locale === firstSegment);
 };
 
+const normalizeRoutePath = (path: string | undefined) => {
+  const normalized = path?.trim();
+  if (!normalized) return undefined;
+  const [pathWithoutHash, hash = ""] = normalized.split("#");
+  const [pathname, search = ""] = pathWithoutHash.split("?");
+  const routePath = `/${pathname.replace(/^\/+|\/+$/g, "")}`;
+  return `${routePath === "/" ? "/" : routePath}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
+};
+
+const splitHref = (href: string) => {
+  const [hrefWithoutHash, hash = ""] = href.split("#");
+  const [path, search = ""] = hrefWithoutHash.split("?");
+  return { path: normalizeRoutePath(path) ?? "/", search, hash };
+};
+
+const normalizeRouteManifestPath = (href: string, prefix = "") => {
+  const { path } = splitHref(href);
+  const segments = path.split("/").filter(Boolean);
+  if (segments[0] === ":lang") segments.shift();
+  if (prefix && segments[0] === prefix) segments.shift();
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+};
+
+export const normalizeDeepLinkHref = (href: string, origin = globalThis.window?.location?.origin ?? "http://localhost") => {
+  const url = new URL(href, origin);
+  if (url.protocol === "http:" || url.protocol === "https:") return `${url.pathname}${url.search}${url.hash}`;
+  const hostPath = url.hostname ? `/${url.hostname}` : "";
+  const pathname = `${hostPath}${url.pathname === "/" ? "" : url.pathname}`;
+  return `${normalizeRoutePath(pathname) ?? "/"}${url.search}${url.hash}`;
+};
+
 const getServerBasePath = (reqPathname: string, lang: string, headerBasePath: string | undefined, fallback: string) => {
   return (
     getBasePathFromPathname(reqPathname, {
@@ -117,6 +158,9 @@ class Router {
   isInitialized = false;
   #prefix = "";
   #lang = parseAkanI18nEnv().defaultLocale;
+  #routePaths = new Set<string>();
+  #indexPath = "/";
+  #historyIdx = 0;
   #instance: InternalRouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -137,6 +181,17 @@ class Router {
     
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
+    this.#routePaths = new Set(
+      (Array.isArray(options.routeManifest) ? options.routeManifest : (options.routeManifest?.routes ?? []))
+        .map((path) => normalizeRouteManifestPath(path, this.#prefix))
+        .filter(Boolean),
+    );
+    this.#indexPath = splitHref(options.indexPath ?? "/").path;
+    if (this.#routePaths.size > 0 && !this.#routePaths.has(this.#indexPath)) {
+      Logger.log(`[router] indexPath '${this.#indexPath}' was not found in route manifest. Falling back to '/'.`);
+      this.#indexPath = "/";
+    }
+    this.#ensureHistoryState();
     if (options.type === "csr") this.#initCsrClientRouter(options);
     else if (options.side === "server") this.#initSsrServerRouter(options);
     else this.#initSsrClientRouter(options);
@@ -206,6 +261,31 @@ class Router {
     if (!this.isInitialized) throw new Error("Router is not initialized");
   }
 
+  #ensureHistoryState() {
+    if (getEnv().side === "server") return;
+    const history = globalThis.window?.history;
+    if (!history?.replaceState) return;
+    const state = (history.state ?? {}) as Record<string, unknown>;
+    const akanState = (state.__akanRouter ?? {}) as { idx?: number };
+    this.#historyIdx = Number.isInteger(akanState.idx) ? (akanState.idx as number) : this.#historyIdx;
+    history.replaceState({ ...state, __akanRouter: { ...akanState, idx: this.#historyIdx } }, "", globalThis.window.location.href);
+    if (!globalThis.window.addEventListener) return;
+    globalThis.window.addEventListener("popstate", (event) => {
+      const nextState = ((event.state as Record<string, unknown> | null)?.__akanRouter ?? {}) as { idx?: number };
+      if (Number.isInteger(nextState.idx)) this.#historyIdx = nextState.idx as number;
+    });
+  }
+
+  #rememberHistoryState(kind: "push" | "replace") {
+    if (getEnv().side === "server") return;
+    const history = globalThis.window?.history;
+    if (!history) return;
+    if (kind === "push") this.#historyIdx += 1;
+    const state = (history.state ?? {}) as Record<string, unknown>;
+    const nextState = { ...state, __akanRouter: { ...((state.__akanRouter ?? {}) as object), idx: this.#historyIdx } };
+    if (history.replaceState) history.replaceState(nextState, "", globalThis.window.location.href);
+  }
+
   #getPathInfo(href: string, prefix = this.#prefix) {
     return getPathInfo(href, this.#lang, prefix);
   }
@@ -239,18 +319,69 @@ class Router {
     const { path, search, hash } = this.#getPathInfo(href);
     globalThis.__AKAN_DEV_SYNC_NAVIGATION__?.(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`, kind);
   }
+  #getExistingSegmentStack(path: string) {
+    const segments = path.split("/").filter(Boolean);
+    if (segments.length === 0) return this.#routePaths.has("/") ? ["/"] : [];
+    return segments
+      .map((_, index) => `/${segments.slice(0, index + 1).join("/")}`)
+      .filter((candidate) => this.#routePaths.has(candidate));
+  }
+  resolveDeepLinkStack(href: string) {
+    this.#checkInitialized();
+    const normalizedHref = normalizeDeepLinkHref(href);
+    const { path, search, hash } = splitHref(normalizedHref);
+    if (this.#routePaths.size > 0 && !this.#routePaths.has(path)) {
+      Logger.log(`[router] deep link target '${path}' was not found in route manifest.`);
+      return [];
+    }
+    const stack = this.#routePaths.size > 0 ? this.#getExistingSegmentStack(path) : [path];
+    const baseStack =
+      stack.length > 1 || this.#indexPath === path || stack.includes(this.#indexPath) ? stack : [this.#indexPath, ...stack];
+    const dedupedStack = baseStack.filter((candidate, index) => baseStack.indexOf(candidate) === index);
+    const target = `${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
+    return dedupedStack.map((candidate, index) => (index === dedupedStack.length - 1 ? target : candidate));
+  }
+  enterDeepLink(href: string, options: DeepLinkOptions = {}) {
+    this.#checkInitialized();
+    if (!options.resetStack) {
+      this.push(normalizeDeepLinkHref(href), options);
+      return true;
+    }
+    const stack = this.resolveDeepLinkStack(href);
+    if (stack.length === 0) return false;
+    const { resetStack: _resetStack, ...routeOptions } = options;
+    this.replace(stack[0], routeOptions);
+    stack.slice(1).forEach((target, index) => {
+      setTimeout(() => this.push(target, routeOptions), DEEP_LINK_STACK_STEP_DELAY * (index + 1));
+    });
+    return true;
+  }
   push(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
     this.#instance.push(href, routeOptions);
+    this.#rememberHistoryState("push");
     this.#postDevSyncNavigation("push", href);
     return undefined as never;
   }
   replace(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
     this.#instance.replace(href, routeOptions);
+    this.#rememberHistoryState("replace");
     this.#postDevSyncNavigation("replace", href);
     return undefined as never;
   }
+  canGoBack() {
+    if (getEnv().side === "server") return false;
+    return this.#historyIdx > 0;
+  }
+  backOrFallback(fallbackHref = this.#indexPath, routeOptions?: RouteOptions) {
+    if (this.canGoBack()) {
+      this.back(routeOptions);
+      return undefined as never;
+    }
+    this.replace(fallbackHref, routeOptions);
+    return undefined as never;
+  }
   back(routeOptions?: RouteOptions) {
     if (getEnv().side === "server") throw new Error("back is only available in client side");
     

package/index.ts

@@ -33,10 +33,15 @@ export interface AkanMobileTargetAssets {
   splash?: string;
 }
 
-export interface AkanMobileTargetLinks {
+export interface AkanMobileTargetDeepLinks {
   schemes?: string[];
-  associatedDomains?: string[];
-  androidHosts?: string[];
+  domains?: string[];
+  ios?: {
+    teamId?: string;
+  };
+  android?: {
+    sha256CertFingerprints?: string[];
+  };
 }
 
 export interface AkanMobileTargetFiles {
@@ -54,13 +59,14 @@ export interface AkanCapacitorLikeConfig {
 export interface AkanMobileTargetConfig extends AkanCapacitorLikeConfig {
   name: string;
   basePath?: string;
+  indexPath?: string;
   appName: string;
   appId: string;
   version: string;
   buildNum: number;
   assets?: AkanMobileTargetAssets;
   permissions?: MobilePermission[];
-  links?: AkanMobileTargetLinks;
+  deepLinks?: AkanMobileTargetDeepLinks;
   files?: AkanMobileTargetFiles;
 }
 
@@ -83,6 +89,7 @@ export interface AppConfigResult {
   i18n: AkanI18nConfig;
   publicEnv: string[];
   mobile: AkanMobileConfig;
+  secrets: string[];
 }
 
 export interface LibConfigResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.9",
+  "version": "2.3.10-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/proxy/localeWebProxy.ts

@@ -49,7 +49,7 @@ export class LocaleWebProxy implements WebProxy {
       (locale) => !pathname.startsWith(`/${locale}/`) && pathname !== `/${locale}`,
     );
 
-    if (!isInternalProxyRequest(requestUrl) && pathnameIsMissingLocale) {
+    if (!isInternalProxyRequest(requestUrl) && !isWellKnownRequest(pathname) && pathnameIsMissingLocale) {
       return Response.redirect(
         new URL(`/${getLocale(request)}/${pathname.slice(1)}${targetUrl.search}`, getPublicRequestUrl(request)),
         307,
@@ -86,3 +86,7 @@ function getPublicRequestUrl(request: Bun.BunRequest): URL {
 function isInternalProxyRequest(requestUrl: URL): boolean {
   return requestUrl.pathname === "/__rsc";
 }
+
+function isWellKnownRequest(pathname: string): boolean {
+  return pathname === "/.well-known" || pathname.startsWith("/.well-known/");
+}

package/server/types.tsx

@@ -99,8 +99,17 @@ export type BaseBuildArtifact = {
   branches: string[];
   i18n: AkanI18nConfig;
   imageConfig: AkanImageConfig;
+  deepLinkAssociations?: MobileDeepLinkAssociation[];
 };
 
+export interface MobileDeepLinkAssociation {
+  targetName: string;
+  appId: string;
+  domains: string[];
+  iosTeamId?: string;
+  androidSha256CertFingerprints?: string[];
+}
+
 export interface CssAsset {
   cssUrl: string;
   cssRelPath: string;

package/server/webRouter.ts

@@ -56,6 +56,8 @@ import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 const RESERVED_BASE_PATHS = new Set(["admin"]);
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
 export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
+const APPLE_APP_SITE_ASSOCIATION_PATH = "/.well-known/apple-app-site-association";
+const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
 
 export function createRscRedirectResponse(
   location: string,
@@ -459,6 +461,14 @@ export class WebRouter {
         new Response(JSON.stringify(this.#routeCache.merged.clientManifest, null, 2), {
           headers: { "Content-Type": "application/json; charset=utf-8" },
         }),
+      [APPLE_APP_SITE_ASSOCIATION_PATH]: () =>
+        WebRouter.#deepLinkAssociationResponse(APPLE_APP_SITE_ASSOCIATION_PATH, this.#artifact, {
+          cacheControl: this.#prodMode ? "public, max-age=3600" : "no-store",
+        }) ?? new Response("Not Found", { status: 404 }),
+      [ANDROID_ASSET_LINKS_PATH]: () =>
+        WebRouter.#deepLinkAssociationResponse(ANDROID_ASSET_LINKS_PATH, this.#artifact, {
+          cacheControl: this.#prodMode ? "public, max-age=3600" : "no-store",
+        }) ?? new Response("Not Found", { status: 404 }),
       "/*": async (req) => {
         const url = new URL(req.url);
         if (WebRouter.#isImageOptimizerPath(url.pathname)) {
@@ -1046,6 +1056,49 @@ export class WebRouter {
     return new Response(file.stream(), { headers });
   }
 
+  static #deepLinkAssociationResponse(
+    pathname: string,
+    artifact: BaseBuildArtifact,
+    { cacheControl }: { cacheControl: string },
+  ) {
+    if (pathname !== APPLE_APP_SITE_ASSOCIATION_PATH && pathname !== ANDROID_ASSET_LINKS_PATH) return null;
+    const associations = artifact.deepLinkAssociations ?? [];
+    if (pathname === APPLE_APP_SITE_ASSOCIATION_PATH) {
+      const details = associations
+        .filter((association) => association.domains.length > 0 && association.iosTeamId)
+        .map((association) => ({
+          appIDs: [`${association.iosTeamId}.${association.appId}`],
+          components: [{ "/": "/*" }],
+        }));
+      if (details.length === 0) return null;
+      return WebRouter.#jsonResponse({ applinks: { apps: [], details } }, cacheControl);
+    }
+    const assetLinks = associations
+      .filter(
+        (association) =>
+          association.domains.length > 0 && (association.androidSha256CertFingerprints?.length ?? 0) > 0,
+      )
+      .map((association) => ({
+        relation: ["delegate_permission/common.handle_all_urls"],
+        target: {
+          namespace: "android_app",
+          package_name: association.appId,
+          sha256_cert_fingerprints: association.androidSha256CertFingerprints,
+        },
+      }));
+    if (assetLinks.length === 0) return null;
+    return WebRouter.#jsonResponse(assetLinks, cacheControl);
+  }
+
+  static #jsonResponse(body: unknown, cacheControl: string) {
+    return new Response(JSON.stringify(body, null, 2), {
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": cacheControl,
+      },
+    });
+  }
+
   static #bytesResponse(
     _req: Request,
     bytes: Uint8Array,

package/types/client/capacitor.d.ts

@@ -13,6 +13,9 @@ export type CapacitorAppModule = {
         addListener: (eventName: string, listenerFunc: (...args: unknown[]) => void) => Promise<unknown> | unknown;
         removeAllListeners: () => Promise<void> | void;
         exitApp?: () => Promise<void> | void;
+        getLaunchUrl?: () => Promise<{
+            url?: string | null;
+        }>;
         getInfo: () => Promise<{
             id: string;
             version: string;

package/types/client/router.d.ts

@@ -1,6 +1,12 @@
 export interface RouteOptions {
     scrollToTop?: boolean;
 }
+export interface RouteManifest {
+    routes: string[];
+}
+export interface DeepLinkOptions extends RouteOptions {
+    resetStack?: boolean;
+}
 export interface RouterInstance {
     push: (href: string, routeOptions?: RouteOptions) => void;
     replace: (href: string, routeOptions?: RouteOptions) => void;
@@ -10,6 +16,8 @@ export interface RouterInstance {
 interface RouterOptions {
     prefix?: string;
     lang?: string;
+    routeManifest?: RouteManifest | string[];
+    indexPath?: string;
 }
 interface SsrServerRouterOption extends RouterOptions {
     type: "ssr";
@@ -41,6 +49,7 @@ export declare class AkanNotFoundError extends Error {
     readonly digest = "AKAN_NOT_FOUND";
     constructor();
 }
+export declare const normalizeDeepLinkHref: (href: string, origin?: string) => string;
 declare global {
     var __AKAN_ROUTER__: Router | undefined;
     var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
@@ -57,8 +66,12 @@ declare class Router {
     #private;
     isInitialized: boolean;
     init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption): void;
+    resolveDeepLinkStack(href: string): string[];
+    enterDeepLink(href: string, options?: DeepLinkOptions): boolean;
     push(href: string, routeOptions?: RouteOptions): never;
     replace(href: string, routeOptions?: RouteOptions): never;
+    canGoBack(): boolean;
+    backOrFallback(fallbackHref?: string, routeOptions?: RouteOptions): never;
     back(routeOptions?: RouteOptions): never;
     refresh(): never;
     redirect(href: string, options?: RedirectOptions): never;

package/types/index.d.ts

@@ -32,10 +32,15 @@ export interface AkanMobileTargetAssets {
     icon?: string;
     splash?: string;
 }
-export interface AkanMobileTargetLinks {
+export interface AkanMobileTargetDeepLinks {
     schemes?: string[];
-    associatedDomains?: string[];
-    androidHosts?: string[];
+    domains?: string[];
+    ios?: {
+        teamId?: string;
+    };
+    android?: {
+        sha256CertFingerprints?: string[];
+    };
 }
 export interface AkanMobileTargetFiles {
     ios?: Record<string, string>;
@@ -50,13 +55,14 @@ export interface AkanCapacitorLikeConfig {
 export interface AkanMobileTargetConfig extends AkanCapacitorLikeConfig {
     name: string;
     basePath?: string;
+    indexPath?: string;
     appName: string;
     appId: string;
     version: string;
     buildNum: number;
     assets?: AkanMobileTargetAssets;
     permissions?: MobilePermission[];
-    links?: AkanMobileTargetLinks;
+    deepLinks?: AkanMobileTargetDeepLinks;
     files?: AkanMobileTargetFiles;
 }
 export interface AkanMobileConfig extends AkanCapacitorLikeConfig {
@@ -77,6 +83,7 @@ export interface AppConfigResult {
     i18n: AkanI18nConfig;
     publicEnv: string[];
     mobile: AkanMobileConfig;
+    secrets: string[];
 }
 export interface LibConfigResult {
     externalLibs: string[];

package/types/server/types.d.ts

@@ -59,7 +59,15 @@ export type BaseBuildArtifact = {
     branches: string[];
     i18n: AkanI18nConfig;
     imageConfig: AkanImageConfig;
+    deepLinkAssociations?: MobileDeepLinkAssociation[];
 };
+export interface MobileDeepLinkAssociation {
+    targetName: string;
+    appId: string;
+    domains: string[];
+    iosTeamId?: string;
+    androidSha256CertFingerprints?: string[];
+}
 export interface CssAsset {
     cssUrl: string;
     cssRelPath: string;

package/types/ui/System/Client.d.ts

@@ -3,6 +3,9 @@ import { type Location, type PageState, type TransitionStyle } from "akanjs/clie
 import type { AkanTheme } from "akanjs/fetch";
 import type { SerializedSignal } from "akanjs/signal";
 import { type HTMLAttributes, type ReactNode, type RefObject } from "react";
+declare global {
+    var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
+}
 export declare const Client: {
     (): import("react/jsx-runtime").JSX.Element;
     Wrapper: ({ children, theme, lang, path, dictionary, signals, reconnect, }: ClientWrapperProps) => import("react/jsx-runtime").JSX.Element;

package/types/webkit/bootCsr.d.ts

@@ -9,6 +9,7 @@ declare global {
         __AKAN_MOBILE_TARGET__?: {
             name: string;
             basePath?: string;
+            indexPath?: string;
         };
     }
 }

package/ui/Dialog/Modal.tsx

@@ -5,7 +5,7 @@ import { animated } from "akanjs/ui";
 import { type ReactNode, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { BiX } from "react-icons/bi";
-import { config, useSpring } from "react-spring";
+import { config, useReducedMotion, useSpring } from "react-spring";
 
 import { DialogContext } from "./context";
 
@@ -30,7 +30,10 @@ export const Modal = ({ className, bodyClassName, confirmClose, children, onCanc
   const { l } = usePage();
   const ref = useRef<HTMLDivElement>(null);
   const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeFallbackRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const closingRef = useRef(false);
+
+  useReducedMotion();
   const focusedElementRef = useRef<HTMLElement | null>(null);
   const titleId = useId();
   const contentId = useId();
@@ -42,6 +45,8 @@ export const Modal = ({ className, bodyClassName, confirmClose, children, onCanc
   const openModal = useCallback(
     async ({ canceled }: { canceled?: boolean } = {}) => {
       closingRef.current = false;
+      if (closeFallbackRef.current) clearTimeout(closeFallbackRef.current);
+      closeFallbackRef.current = null;
       setIsMounted(true);
       if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
       closeTimerRef.current = setTimeout(() => {
@@ -52,6 +57,19 @@ export const Modal = ({ className, bodyClassName, confirmClose, children, onCanc
     [api],
   );
 
+  const finalizeClose = useCallback(
+    ({ notifyCancel }: { notifyCancel: boolean }) => {
+      if (!closingRef.current) return;
+      if (closeFallbackRef.current) clearTimeout(closeFallbackRef.current);
+      closeFallbackRef.current = null;
+      setIsMounted(false);
+      setOpen(false);
+      if (notifyCancel) onCancel?.();
+      closingRef.current = false;
+    },
+    [onCancel, setOpen],
+  );
+
   const closeModal = useCallback(
     async ({
       velocity = 0,
@@ -72,13 +90,19 @@ export const Modal = ({ className, bodyClassName, confirmClose, children, onCanc
       closeTimerRef.current = setTimeout(() => {
         setShowBackground(false);
       }, 100);
-      await Promise.all(api.start({ translate: 1, immediate: false, config: { ...config.stiff, velocity } }));
-      setIsMounted(false);
-      setOpen(false);
-      if (notifyCancel) onCancel?.();
-      closingRef.current = false;
+
+      if (closeFallbackRef.current) clearTimeout(closeFallbackRef.current);
+      closeFallbackRef.current = setTimeout(() => {
+        finalizeClose({ notifyCancel });
+      }, 400);
+
+      try {
+        await Promise.all(api.start({ translate: 1, immediate: false, config: { ...config.stiff, velocity } }));
+      } finally {
+        finalizeClose({ notifyCancel });
+      }
     },
-    [api, l, onCancel, setOpen],
+    [api, l, finalizeClose],
   );
 
   const requestClose = useCallback(
@@ -177,6 +201,7 @@ export const Modal = ({ className, bodyClassName, confirmClose, children, onCanc
   useEffect(() => {
     return () => {
       if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
+      if (closeFallbackRef.current) clearTimeout(closeFallbackRef.current);
     };
   }, []);
 

package/ui/System/CSR.tsx

@@ -133,7 +133,15 @@ const CSRWrapper = ({
       document.documentElement.classList.add("akan-mobile-document");
       document.body.classList.add("akan-mobile-document");
     }
-    if (!router.isInitialized) router.init({ type: "csr", lang, prefix, router: reactRouter });
+    if (!router.isInitialized)
+      router.init({
+        type: "csr",
+        lang,
+        prefix,
+        router: reactRouter,
+        routeManifest: pathRoutes.map((pathRoute) => pathRoute.path),
+        indexPath: window.__AKAN_MOBILE_TARGET__?.indexPath,
+      });
     st.do.setCsrLoaded(true);
     const onVisibilityChange = () => debugFrame("document.visibility", { visibilityState: document.visibilityState });
     const onPageHide = (event: PageTransitionEvent) => debugFrame("window.pagehide", { persisted: event.persisted });

package/ui/System/Client.tsx

@@ -42,6 +42,10 @@ import { Messages } from "./Messages";
 import { Reconnect } from "./Reconnect";
 import { getFrameCssVars } from "./frameCssVars";
 
+declare global {
+  var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
+}
+
 export const Client = () => {
   return <></>;
 };

package/webkit/bootCsr.tsx

@@ -35,7 +35,7 @@ type CsrRouteModuleEntry = CsrRouteModuleLoader | { loader: CsrRouteModuleLoader
 
 declare global {
   interface Window {
-    __AKAN_MOBILE_TARGET__?: { name: string; basePath?: string };
+    __AKAN_MOBILE_TARGET__?: { name: string; basePath?: string; indexPath?: string };
   }
 }
 
@@ -274,7 +274,8 @@ function initializeMobileTargetFromSearch() {
   if (!name) return;
 
   const basePath = params.get("akanMobileBasePath")?.replace(/^\/+|\/+$/g, "") ?? "";
-  window.__AKAN_MOBILE_TARGET__ = { name, basePath };
+  const indexPath = params.get("akanMobileIndexPath") ?? undefined;
+  window.__AKAN_MOBILE_TARGET__ = { name, basePath, ...(indexPath ? { indexPath } : {}) };
 }
 
 function validateRouteModuleExports(key: string, mod: RouteModule) {

package/webkit/useCsrValues.ts

@@ -10,6 +10,7 @@ import {
   getPathInfo,
   type LocationState,
   type NavigationIntent,
+  normalizeDeepLinkHref,
   type PageState,
   type PathRoute,
   type RouteGuide,
@@ -61,7 +62,7 @@ const STACK_VELOCITY_DISMISS_THRESHOLD = 0.45;
 const STACK_SETTLE_MIN_DURATION = 90;
 const STACK_SETTLE_MAX_DURATION = 260;
 const ANDROID_SCALE_TRANSITION_DURATION = 220;
-const CSR_RUNTIME_SEARCH_PARAMS = ["csr", "akanMobileTarget", "akanMobileBasePath"] as const;
+const CSR_RUNTIME_SEARCH_PARAMS = ["csr", "akanMobileTarget", "akanMobileBasePath", "akanMobileIndexPath"] as const;
 
 const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
 
@@ -1240,6 +1241,8 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
     keyboardVisible: keyboardFrame.visible,
     router,
   });
+  const handledDeepLinkRef = useRef<{ href: string; handledAt: number; resetStack: boolean } | null>(null);
+  const didResetDeepLinkStackRef = useRef(false);
 
   useEffect(() => {
     if (pageContentRef.current) pageContentRef.current.scrollTop = getScrollTop(location);
@@ -1256,6 +1259,74 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
     };
   }, [keyboardFrame.height, keyboardFrame.visible, resolvedLocation.pathRoute.path, router]);
 
+  useEffect(() => {
+    const isMobileTarget = Boolean(window.__AKAN_MOBILE_TARGET__);
+    if (Device.getDevice().info.platform === "web" && !isMobileTarget) return;
+    let removeListener: (() => void) | undefined;
+    let disposed = false;
+    const mountedAt = Date.now();
+
+    const enterDeepLinkWhenReady = (href: string, resetStack: boolean, attempt = 0) => {
+      if (!clientRouter.isInitialized) {
+        if (attempt < 40) window.setTimeout(() => enterDeepLinkWhenReady(href, resetStack, attempt + 1), 50);
+        else debugFrame("native.deepLink.skipped", { href, reason: "router-not-ready" });
+        return;
+      }
+      clientRouter.enterDeepLink(href, { resetStack, scrollToTop: true });
+    };
+
+    const handleDeepLink = (url: string | null | undefined, resetStack: boolean) => {
+      if (!url) return;
+      const href = normalizeDeepLinkHref(url);
+      const now = Date.now();
+      const lastHandled = handledDeepLinkRef.current;
+      const shouldResetStack = resetStack || (!lastHandled && now - mountedAt < 5000);
+      if (lastHandled?.href === href && now - lastHandled.handledAt < 1000 && (!shouldResetStack || lastHandled.resetStack))
+        return;
+      handledDeepLinkRef.current = { href, handledAt: now, resetStack: shouldResetStack };
+      debugFrame("native.deepLink", {
+        href,
+        resetStack: shouldResetStack,
+        sourceResetStack: resetStack,
+        historyIdx: history.current.idx,
+        mountedForMs: now - mountedAt,
+        routerReady: clientRouter.isInitialized,
+      });
+      if (shouldResetStack) didResetDeepLinkStackRef.current = true;
+      enterDeepLinkWhenReady(href, shouldResetStack);
+    };
+
+    void loadCapacitorApp()
+      .then(({ App }) => {
+        debugFrame("native.deepLink.listener", { platform: Device.getDevice().info.platform, isMobileTarget });
+        const listener = App.addListener("appUrlOpen", (event: unknown) => {
+          handleDeepLink((event as { url?: string | null } | undefined)?.url, false);
+        });
+
+        void Promise.resolve(listener).then((handle) => {
+          const remove =
+            typeof (handle as { remove?: unknown } | undefined)?.remove === "function"
+              ? () => void (handle as { remove: () => Promise<void> | void }).remove()
+              : undefined;
+          if (disposed) remove?.();
+          else removeListener = remove;
+        });
+
+        void App.getLaunchUrl?.()
+          .then((launch) => {
+            debugFrame("native.deepLink.launchUrl", { url: launch?.url ?? null });
+            handleDeepLink(launch?.url, true);
+          })
+          .catch((error) => debugFrame("native.deepLink.launchUrlError", { error: String(error) }));
+      })
+      .catch((error) => debugFrame("native.deepLink.listenerError", { error: String(error) }));
+
+    return () => {
+      disposed = true;
+      removeListener?.();
+    };
+  }, []);
+
   useEffect(() => {
     if (Device.getDevice().info.platform === "web") return;
     let removeListener: (() => void) | undefined;
@@ -1277,6 +1348,15 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
           nativeBackState.router.back();
           return;
         }
+        const fallbackPath = window.__AKAN_MOBILE_TARGET__?.indexPath ?? "/";
+        if (didResetDeepLinkStackRef.current) {
+          void App.exitApp?.();
+          return;
+        }
+        if (nativeBackState.path !== fallbackPath) {
+          clientRouter.backOrFallback(fallbackPath, { scrollToTop: false });
+          return;
+        }
         void App.exitApp?.();
       });