akanjs 3.0.2 → 3.1.0-rc.1

package/webkit/McpAppView.ts

@@ -0,0 +1,258 @@
+"use client";
+import { router, setCookie } from "akanjs/client";
+import { Logger, parseAkanI18nEnv } from "akanjs/common";
+import { st } from "akanjs/store";
+import type { McpAppBridge, McpDownloadContent, McpHostContext } from "./McpAppBridge";
+
+export class McpAppView {
+  static readonly contentGap = 24;
+  
+  static readonly hostTokens = {
+    "--color-background-primary": ["--background", "--card", "--popover"],
+    "--color-background-secondary": ["--muted"],
+    "--color-text-primary": ["--foreground", "--card-foreground", "--popover-foreground"],
+    "--color-text-secondary": ["--muted-foreground"],
+    "--color-border-primary": ["--border", "--input"],
+    "--color-ring-primary": ["--ring"],
+    "--font-sans": ["--font-sans"],
+    "--font-mono": ["--font-mono"],
+  } as const;
+
+  readonly #bridge: McpAppBridge;
+  readonly #blobs = new Map<string, Blob>();
+  #lastHeight = 0;
+  #theme: string | undefined;
+
+  constructor(bridge: McpAppBridge) {
+    this.#bridge = bridge;
+  }
+
+  /** `href` in the host's language when the app speaks it: the page run used the server's MCP language. */
+  static localize(href: string, locale: string | undefined, locales: readonly string[]) {
+    const lang = locale?.split("-")[0]?.toLowerCase();
+    const current = /^\/([^/?#]+)/.exec(href)?.[1];
+    if (!lang || !current || !locales.includes(lang) || !locales.includes(current)) return href;
+    return `/${lang}${href.slice(current.length + 1)}`;
+  }
+
+  mount() {
+    this.#apply(this.#bridge.hostContext);
+    this.#bridge.onHostContext((context) => this.#apply(context));
+    this.#watchSize();
+    this.#keepBlobs();
+    this.#routeLinks();
+  }
+
+  /** In place of the app, for a result that names no screen: the host still sizes the view to what it shows. */
+  showUnavailable(message: string) {
+    this.#apply(this.#bridge.hostContext);
+    const notice = document.createElement("p");
+    notice.textContent = message;
+    notice.style.cssText = "margin:0;padding:16px;font:14px/1.5 system-ui,sans-serif;color:var(--foreground)";
+    document.getElementById("root")?.replaceChildren();
+    document.body.style.overflow = "visible";
+    document.body.replaceChildren(notice);
+    this.#bridge.notify("ui/notifications/size-changed", { height: Math.ceil(notice.getBoundingClientRect().height) });
+  }
+
+  #apply({ theme, displayMode, styles }: McpHostContext) {
+    const root = document.documentElement;
+    root.dataset.akanEmbed = displayMode ?? "inline";
+    
+    if (theme && theme !== this.#theme) {
+      this.#theme = theme;
+      setCookie("theme", theme);
+      root.dataset.theme = theme;
+      st.do.setTheme(theme);
+      
+      root.style.colorScheme = theme;
+    }
+    const variables = styles?.variables ?? {};
+    for (const [hostKey, tokens] of Object.entries(McpAppView.hostTokens)) {
+      const value = variables[hostKey];
+      for (const token of tokens)
+        if (value) root.style.setProperty(token, value);
+        else root.style.removeProperty(token);
+    }
+  }
+
+  #watchSize() {
+    let scheduled = false;
+    const report = () => {
+      if (scheduled) return;
+      scheduled = true;
+      requestAnimationFrame(() => {
+        scheduled = false;
+        const height = McpAppView.#contentHeight();
+        if (height === this.#lastHeight) return;
+        this.#lastHeight = height;
+        this.#bridge.notify("ui/notifications/size-changed", { height });
+      });
+    };
+    const resized = new ResizeObserver(report);
+    resized.observe(document.documentElement);
+    const observeContent = () => {
+      for (const content of document.querySelectorAll(".akan-page-content"))
+        for (const child of content.children) resized.observe(child);
+    };
+    new MutationObserver(() => {
+      observeContent();
+      report();
+    }).observe(document.body, { childList: true, subtree: true, attributes: true });
+    
+    document.addEventListener("load", report, true);
+    void document.fonts.ready.then(report);
+    observeContent();
+    report();
+  }
+
+  static #contentHeight() {
+    const content = document.querySelector<HTMLElement>('[id^="pageContainer-"]:not([inert]) .akan-page-content');
+    if (!content) return Math.ceil(document.documentElement.scrollHeight);
+    const viewport = window.innerHeight;
+    const style = getComputedStyle(content);
+    const top = content.getBoundingClientRect().top - content.scrollTop;
+    let bottom = top + Number.parseFloat(style.paddingTop || "0");
+    const pending: Element[] = [content];
+    for (let box = pending.pop(); box; box = pending.pop())
+      for (const child of box.children) {
+        const rect = child.getBoundingClientRect();
+        if (getComputedStyle(child).position === "fixed") continue;
+        if (rect.height === 0 || rect.height >= viewport - 1 || Math.abs(rect.bottom - viewport) <= 1)
+          pending.push(child);
+        else bottom = Math.max(bottom, rect.bottom);
+      }
+    const height = bottom - top + Number.parseFloat(style.paddingBottom || "0") + McpAppView.contentGap;
+    return Math.ceil(Math.max(height + McpAppView.#overlayHeight(), McpAppView.#dialogHeight()));
+  }
+
+  static #overlayHeight() {
+    let height = 0;
+    for (const overlay of document.querySelectorAll<HTMLElement>("[data-akan-embed-overlay]"))
+      height += overlay.getBoundingClientRect().height;
+    return height;
+  }
+
+  static #dialogHeight() {
+    let height = 0;
+    for (const dialog of document.querySelectorAll<HTMLElement>('[aria-modal="true"]')) {
+      if (!dialog.getClientRects().length) continue;
+      let natural = 0;
+      for (const child of dialog.children)
+        if (!["absolute", "fixed"].includes(getComputedStyle(child).position)) natural += child.scrollHeight;
+      height = Math.max(height, natural + McpAppView.contentGap * 2);
+    }
+    return height;
+  }
+
+  #routeLinks() {
+    const { locales } = parseAkanI18nEnv();
+    const base = McpAppView.#parse(document.baseURI);
+    const open = (raw: string) => {
+      if (!raw) return;
+      
+      if (raw.startsWith("#")) {
+        document.getElementById(decodeURIComponent(raw.slice(1)))?.scrollIntoView();
+        return;
+      }
+      const url = McpAppView.#parse(raw, document.baseURI);
+      if (!url) return;
+      const [, lang] = url.pathname.split("/");
+      if (url.origin === base?.origin && lang && locales.includes(lang))
+        router.push(`${url.pathname}${url.search}${url.hash}`);
+      else if (["http:", "https:", "mailto:", "tel:"].includes(url.protocol))
+        this.#bridge.openLink(url.href).catch((error: unknown) => {
+          Logger.warn(`The host did not open ${url.href}: ${error instanceof Error ? error.message : error}`);
+        });
+    };
+    const download = (href: string, name: string | null) =>
+      this.#download(href, name).catch((error: unknown) => {
+        Logger.warn(`The host did not save ${href}: ${error instanceof Error ? error.message : error}`);
+      });
+    document.addEventListener("click", (event) => {
+      if (event.defaultPrevented || event.button !== 0) return;
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      const anchor = (event.target as Element | null)?.closest?.("a[href]");
+      if (!(anchor instanceof HTMLAnchorElement)) return;
+      event.preventDefault();
+      const href = anchor.getAttribute("href") ?? "";
+      if (!anchor.hasAttribute("download")) open(href);
+      else void download(href, anchor.getAttribute("download"));
+    });
+    window.open = (url?: string | URL) => {
+      if (url !== undefined) open(String(url));
+      return null;
+    };
+    
+    const click = HTMLAnchorElement.prototype.click;
+    HTMLAnchorElement.prototype.click = function (this: HTMLAnchorElement) {
+      if (this.isConnected || !this.hasAttribute("download")) click.call(this);
+      else void download(this.getAttribute("href") ?? "", this.getAttribute("download"));
+    };
+  }
+
+  async #download(href: string, suggested: string | null) {
+    const content = await this.#downloadOf(href, suggested || null);
+    if (!content) throw new Error("it is neither a web address nor a file this view made");
+    if (this.#bridge.hostCapabilities.downloadFile) await this.#bridge.downloadFile([content]);
+    else if (content.type === "resource_link") await this.#bridge.openLink(content.uri);
+    else throw new Error("this host does not save files");
+  }
+
+  async #downloadOf(href: string, suggested: string | null): Promise<McpDownloadContent | null> {
+    const blob = this.#blobs.get(href) ?? (href.startsWith("data:") ? McpAppView.#dataBlob(href) : null);
+    if (blob) {
+      const name = suggested ?? "download";
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      return {
+        type: "resource",
+        resource: {
+          uri: `file:///${encodeURIComponent(name)}`,
+          mimeType: blob.type || "application/octet-stream",
+          blob: McpAppView.#base64(bytes),
+        },
+      };
+    }
+    const url = McpAppView.#parse(href, document.baseURI);
+    if (!url || !["http:", "https:"].includes(url.protocol)) return null;
+    return { type: "resource_link", uri: url.href, name: suggested ?? url.pathname.split("/").at(-1) ?? "download" };
+  }
+
+  #keepBlobs() {
+    const create = URL.createObjectURL.bind(URL);
+    const revoke = URL.revokeObjectURL.bind(URL);
+    URL.createObjectURL = (object: Blob | MediaSource) => {
+      const url = create(object);
+      if (object instanceof Blob) this.#blobs.set(url, object);
+      return url;
+    };
+    URL.revokeObjectURL = (url: string) => {
+      this.#blobs.delete(url);
+      revoke(url);
+    };
+  }
+
+  static #dataBlob(href: string) {
+    const match = /^data:([^,]*?)(;base64)?,(.*)$/s.exec(href);
+    if (!match) return null;
+    const [, type = "", base64, body = ""] = match;
+    const bytes = base64
+      ? Uint8Array.from(atob(body), (char) => char.charCodeAt(0))
+      : new TextEncoder().encode(decodeURIComponent(body));
+    return new Blob([bytes], { type: type.split(";")[0] });
+  }
+
+  static #base64(bytes: Uint8Array) {
+    let binary = "";
+    for (let at = 0; at < bytes.length; at += 0x8000) binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000));
+    return btoa(binary);
+  }
+
+  static #parse(raw: string, base?: string) {
+    try {
+      return new URL(raw, base);
+    } catch {
+      return null;
+    }
+  }
+}

package/webkit/RenderLayer.tsx

@@ -3,6 +3,7 @@ import { debugFrame, RouteDefinition, type RouteRender, router, usePathCtx } fro
 import { isThenable, Logger } from "akanjs/common";
 import { createContext, createElement, memo, type ReactNode, useContext, useEffect, useRef, useState } from "react";
 import { CsrFrameDump } from "./csrFrameDump";
+import { EmbeddedLayout, LayoutOutlet } from "./EmbeddedLayout";
 import { RenderFailure } from "./RenderFailure";
 import { useFetch } from "./useFetch";
 import { usePageActivity } from "./usePageActivity";
@@ -28,15 +29,28 @@ interface RenderLayerProps {
   params: Record<string, string>;
   searchParams: Record<string, string | string[]>;
   leaf?: ReactNode;
+  /** A page in an MCP view: every layout above it runs, and only the page is shown. */
+  isEmbedded?: boolean;
 }
-export const RenderLayer = memo(({ renders, index, params, searchParams, leaf = null }: RenderLayerProps) => {
+export const RenderLayer = memo((props: RenderLayerProps) => {
+  const { renders, index, params, searchParams, leaf = null, isEmbedded = false } = props;
   const isLast = index >= renders.length - 1;
-  const children = isLast ? (
+  const below = isLast ? (
     leaf
   ) : (
-    <RenderLayer renders={renders} index={index + 1} params={params} searchParams={searchParams} leaf={leaf} />
+    <RenderLayer
+      renders={renders}
+      index={index + 1}
+      params={params}
+      searchParams={searchParams}
+      leaf={leaf}
+      isEmbedded={isEmbedded}
+    />
   );
   const routeRender = renders[index];
+  const isEmbeddedLayout = isEmbedded && routeRender?.kind === "layout";
+  const children = isEmbeddedLayout ? <LayoutOutlet>{below}</LayoutOutlet> : below;
+  const frame = (drawn: ReactNode) => (isEmbeddedLayout ? <EmbeddedLayout>{drawn}</EmbeddedLayout> : drawn);
   const isAsyncRender = isAsyncRouteRender(routeRender);
   const renderedRef = useRef<RenderedRoute | null>(null);
   const [, setFailures] = useState(0);
@@ -106,7 +120,8 @@ export const RenderLayer = memo(({ renders, index, params, searchParams, leaf =
     };
   }, [record]);
   if (!routeRender) return null;
-  if (!isAsyncRender) return createElement(routeRender.render as never, { children, params, searchParams } as never);
+  if (!isAsyncRender)
+    return frame(createElement(routeRender.render as never, { children, params, searchParams } as never));
   const failure = renderedRef.current?.failure;
   if (failure)
     return (
@@ -119,7 +134,7 @@ export const RenderLayer = memo(({ renders, index, params, searchParams, leaf =
       />
     );
   if (!value) return <>{composeLoadingFallback(renders.slice(index), params)}</>;
-  return <layerChildContext.Provider value={children}>{value}</layerChildContext.Provider>;
+  return frame(<layerChildContext.Provider value={children}>{value}</layerChildContext.Provider>);
 });
 
 function reportFailure(result: ReactNode | Promise<ReactNode>, layer: string): ReactNode | Promise<ReactNode> {

package/webkit/bootCsr.tsx

@@ -1,9 +1,14 @@
 "use client";
-import { csrContext, Device, getStoredAuthToken, initAuth } from "akanjs/client";
+import { csrContext, csrLocation, Device, getStoredAuthToken, initAuth } from "akanjs/client";
 import { Logger, parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
+import { FetchClient } from "akanjs/fetch";
+import { st } from "akanjs/store";
 import { useSyncExternalStore } from "react";
 import * as ReactDOM from "react-dom/client";
 import { type CsrRouteContext, CsrRouteTable } from "./CsrRouteTable";
+import { McpAppAgent } from "./McpAppAgent";
+import { McpAppBridge } from "./McpAppBridge";
+import { McpAppView } from "./McpAppView";
 import { RenderLayer } from "./RenderLayer";
 import { useCsrValues } from "./useCsrValues";
 
@@ -18,8 +23,15 @@ export const bootCsr = async (context: CsrRouteContext) => {
   window.document.body.style.overflow = "hidden";
   initializeMobileTargetFromSearch();
   if (window.location.pathname === "/404") return;
+  
+  let remount: () => void = () => undefined;
+  const embedded = globalThis.__AKAN_EMBED__ ? await bootMcpApp(i18n.locales, () => remount()) : false;
+  if (embedded === null) return;
 
-  const [device, jwt] = await Promise.all([Device.load({ supportLanguages: i18n.locales }), getStoredAuthToken()]);
+  const [device, jwt] = await Promise.all([
+    Device.load({ supportLanguages: i18n.locales }),
+    embedded ? undefined : getStoredAuthToken(),
+  ]);
   const mobileTarget = window.__AKAN_MOBILE_TARGET__;
   
   if (mobileTarget && window.location.pathname === "/")
@@ -28,8 +40,8 @@ export const bootCsr = async (context: CsrRouteContext) => {
       "",
       `${mobileHomePath(device.lang, mobileTarget)}${window.location.search}${window.location.hash}`,
     );
-  const pathname = window.location.pathname;
-  if (!mobileTarget && !pathname.startsWith(`/${device.lang}`))
+  const pathname = csrLocation.pathname;
+  if (!mobileTarget && !embedded && !pathname.startsWith(`/${device.lang}`))
     window.location.replace(`/${device.lang}${pathname}${window.location.search}${window.location.hash}`);
 
   if (jwt) initAuth({ jwt });
@@ -62,10 +74,19 @@ export const bootCsr = async (context: CsrRouteContext) => {
     );
   };
 
+  st.set({ searchParams: searchParamsOf(csrLocation.search) });
   const el = document.getElementById("root");
   if (!el) throw new Error("No root element");
-  const root = ReactDOM.createRoot(el);
+  let root = ReactDOM.createRoot(el);
   root.render(<RouterProvider />);
+
+  remount = () => {
+    setTimeout(() => {
+      root.unmount();
+      root = ReactDOM.createRoot(el);
+      root.render(<RouterProvider />);
+    }, 0);
+  };
 };
 
 /**
@@ -74,6 +95,34 @@ export const bootCsr = async (context: CsrRouteContext) => {
  */
 export const replacePages = async (context: CsrRouteContext) => (await CsrRouteTable.active?.replace(context)) ?? false;
 
+function searchParamsOf(search: string): { [key: string]: string | string[] } {
+  const params: { [key: string]: string | string[] } = {};
+  for (const [key, value] of new URLSearchParams(search)) {
+    const current = params[key];
+    params[key] = current === undefined ? value : Array.isArray(current) ? [...current, value] : [current, value];
+  }
+  return params;
+}
+
+async function bootMcpApp(locales: readonly string[], reload: () => void) {
+  const bridge = new McpAppBridge();
+  const view = new McpAppView(bridge);
+  const start = await bridge.connect();
+  if (!start.ok) {
+    view.showUnavailable(start.message);
+    return null;
+  }
+  if (globalThis.__AKAN_EMBED__) globalThis.__AKAN_EMBED__.account = start.account;
+  csrLocation.useMemory(McpAppView.localize(start.href, bridge.hostContext.locale, locales), {
+    leave: () => view.showUnavailable("This screen is not available here."),
+    reload,
+  });
+  FetchClient.setBridge(bridge.fetchBridge(start.snapshot));
+  view.mount();
+  new McpAppAgent(bridge).start();
+  return true;
+}
+
 function initializeMobileTargetFromSearch() {
   if (window.__AKAN_MOBILE_TARGET__) return;
 

package/webkit/index.ts

@@ -19,3 +19,4 @@ export { usePageTool } from "./usePageTool";
 export type { ScreenScopeItem } from "./useScreenScope";
 export { useScreenScope } from "./useScreenScope";
 export { useThrottle } from "./useThrottle";
+export { useVisualViewportFrame, type VisualViewportFrame } from "./useVisualViewportFrame";

package/webkit/useCsrValues.ts

@@ -4,6 +4,7 @@ import { useDrag } from "@use-gesture/react";
 import {
   type CsrContextType,
   router as clientRouter,
+  csrLocation,
   Device,
   debugFrame,
   defaultPageState,
@@ -109,6 +110,7 @@ const pageContentStyle = ({ frameLayout }: RouteState, pageState: FramePageState
       (frameLayout.keyboard.sticky ? frameLayout.keyboardAccessory.height : 0),
   ),
   height: frameLayout.contentViewport.height,
+  "--akan-content-height": `${frameLayout.contentViewport.height}px`,
 });
 
 const prevPageContentStyle = (clientHeight: number, prevPageState: FramePageState) => ({
@@ -132,6 +134,10 @@ const tweenedSafeAreas = (
   bottomSafeArea: {
     containerStyle: {
       backgroundColor: pageState.bottomSafeAreaColor,
+      visibility:
+        pageState.bottomInset > 0 || pageState.bottomSafeAreaColor !== defaultPageState.bottomSafeAreaColor
+          ? ("visible" as const)
+          : ("hidden" as const),
       top: tween(progress, clientHeight - prevPageState.bottomSafeArea, clientHeight - pageState.bottomSafeArea),
       height: tween(progress, prevPageState.bottomSafeArea, pageState.bottomSafeArea),
     },
@@ -603,7 +609,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
 
   const { getLocation } = useLocation({ rootRouteGuide });
   const [initialStack] = useState(() => {
-    const current = getLocation(window.location.href.replace(window.location.origin, ""));
+    const current = getLocation(csrLocation.href);
     return CsrStack.restore(current, getLocation) ?? { locations: [current], idx: 0 };
   });
   const {
@@ -876,8 +882,8 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       if (!usePendingNavigation) {
         setHistoryForward({ type: kind, location: toLocation, scrollTop, scrollToTop });
         settle(kind === "replace" ? prevLocation : fromLocation);
-        if (kind === "push") window.history.pushState({ akanEntryId: toLocation.entryId }, "", href);
-        else window.history.replaceState({ akanEntryId: toLocation.entryId }, "", href);
+        if (kind === "push") csrLocation.push({ akanEntryId: toLocation.entryId }, href);
+        else csrLocation.replace({ akanEntryId: toLocation.entryId }, href);
         return;
       }
 
@@ -951,8 +957,8 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
           navigationIntent: intent,
           phase: "transitioning",
         });
-        if (kind === "push") window.history.pushState({ akanEntryId: toLocation.entryId }, "", href);
-        else window.history.replaceState({ akanEntryId: toLocation.entryId }, "", href);
+        if (kind === "push") csrLocation.push({ akanEntryId: toLocation.entryId }, href);
+        else csrLocation.replace({ akanEntryId: toLocation.entryId }, href);
         debugFrame("navigation.commit", { id: intent.id, kind, to: href });
         window.setTimeout(
           () => {
@@ -1038,7 +1044,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
   ]);
   useEffect(() => {
     debugFrame("csr.mount", { path: resolvedLocation.pathRoute.path, viewport });
-    window.history.replaceState({ ...(window.history.state ?? {}), akanEntryId: getCurrentLocation().entryId }, "");
+    csrLocation.replace({ ...((csrLocation.state as object | null) ?? {}), akanEntryId: getCurrentLocation().entryId });
     return () => debugFrame("csr.unmount", { lastPath: resolvedLocation.pathRoute.path });
   }, []);
   const getRouter = useCallback((): RouterInstance => {
@@ -1058,7 +1064,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       push: forward("push"),
       replace: forward("replace"),
       refresh: () => {
-        window.location.reload();
+        csrLocation.reload();
       },
       back: async ({ scrollToTop }: RouteOptions = {}) => {
         const targetLocation = getPrevLocation();
@@ -1072,12 +1078,12 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
         const scrollTop = pageContentRef.current?.scrollTop ?? 0;
         setHistoryBack({ type: "back", location, scrollTop, scrollToTop });
         settle(getPrevLocation());
-        window.history.back();
+        csrLocation.back();
       },
     };
     window.onpopstate = async (event) => {
-      const href = window.location.href.replace(window.location.origin, "");
-      const entryId = (window.history.state as { akanEntryId?: string } | null)?.akanEntryId;
+      const href = csrLocation.href;
+      const entryId = (csrLocation.state as { akanEntryId?: string } | null)?.akanEntryId;
       const isAt = (target: Location | null | undefined) =>
         !!target && (entryId ? target.entryId === entryId : target.href === href);
       const routeType = isAt(getNextLocation()) ? "forward" : isAt(getPrevLocation()) ? "back" : null;

package/webkit/useFrameRuntime.ts

@@ -74,7 +74,16 @@ export function applyFrameSlots(
 ) {
   const slots = getFrameSlotsForPath(pathRoute, frameSlots, pathRoutes, visiblePaths);
   const pageState = clonePageState(basePageState);
-  if (!pathRoute.explicitPageConfigKeys?.cache && slots.some((slot) => slot.cache)) pageState.cache = true;
+  const explicit = pathRoute.explicitPageConfigKeys ?? {};
+  if (!explicit.cache && slots.some((slot) => slot.cache)) pageState.cache = true;
+  
+  for (const side of ["topInset", "bottomInset"] as const) {
+    if (explicit[side]) continue;
+    const heights = slots
+      .filter((slot) => slot.type === side && !isKeyboardAccessorySlot(slot))
+      .map(resolveFrameSlotHeight);
+    if (heights.length) pageState[side] = Math.max(...heights);
+  }
   return pageState;
 }
 

package/webkit/useLocation.ts

@@ -1,5 +1,5 @@
 "use client";
-import type { Location, PathRoute, RouteGuide } from "akanjs/client";
+import { csrLocation, type Location, type PathRoute, type RouteGuide } from "akanjs/client";
 import { useCallback, useRef } from "react";
 import { CsrStack } from "./CsrStack";
 
@@ -34,7 +34,8 @@ export const useLocation = ({ rootRouteGuide }: UseLocationOptions) => {
       const targetRouteGuide = getTargetRouteGuide(pathSegments, routeGuide.current);
       const pathRoute = targetRouteGuide.pathRoute;
       if (!pathRoute) {
-        window.location.assign("/404");
+        
+        if (!csrLocation.isMemory || pathname === csrLocation.pathname) csrLocation.assign("/404");
         throw new Error("404");
       }
       return pathRoute;
@@ -57,7 +58,7 @@ export const useLocation = ({ rootRouteGuide }: UseLocationOptions) => {
         {},
       );
     };
-    const hrefWithoutOrigin = href.replace(window.location.origin, "");
+    const hrefWithoutOrigin = csrLocation.strip(href);
     const [hrefWithoutHash, hash = ""] = hrefWithoutOrigin.split("#");
     const [pathname, search] = hrefWithoutHash.split("?");
     const pathRoute = getPathRoute(pathname);

package/webkit/useVisualViewportFrame.tsx

@@ -0,0 +1,52 @@
+"use client";
+import { useEffect, useState } from "react";
+
+export interface VisualViewportFrame {
+  /** The on-screen keyboard's height over the layout viewport's bottom; 0 while it is closed. */
+  keyboardHeight: number;
+  /** The visible rectangle's height and its scroll offset from the layout viewport's top, in CSS px. */
+  height: number;
+  offsetTop: number;
+}
+
+const closedFrame = (): VisualViewportFrame => ({
+  keyboardHeight: 0,
+  height: typeof window === "undefined" ? 0 : window.innerHeight,
+  offsetTop: 0,
+});
+
+/**
+ * The visible part of the page while the on-screen keyboard is up, on the web. Only `visualViewport` reports the
+ * keyboard: `dvh` tracks the browser's own chrome, and iOS pans the visual viewport to the field instead of shrinking
+ * the page, so a fixed bottom bar stays behind the keyboard until it is placed at `offsetTop + height`.
+ */
+export const useVisualViewportFrame = (): VisualViewportFrame => {
+  const [frame, setFrame] = useState<VisualViewportFrame>(closedFrame);
+  useEffect(() => {
+    const viewport = window.visualViewport;
+    if (!viewport) return;
+    const measure = () => {
+      
+      const zoomed = viewport.scale > 1.01;
+      const keyboardHeight = zoomed
+        ? 0
+        : Math.max(0, Math.round(window.innerHeight - viewport.height - viewport.offsetTop));
+      const next = zoomed
+        ? closedFrame()
+        : { keyboardHeight, height: Math.round(viewport.height), offsetTop: Math.round(viewport.offsetTop) };
+      setFrame((prev) =>
+        prev.keyboardHeight === next.keyboardHeight && prev.height === next.height && prev.offsetTop === next.offsetTop
+          ? prev
+          : next,
+      );
+    };
+    measure();
+    viewport.addEventListener("resize", measure);
+    viewport.addEventListener("scroll", measure);
+    return () => {
+      viewport.removeEventListener("resize", measure);
+      viewport.removeEventListener("scroll", measure);
+    };
+  }, []);
+  return frame;
+};

package/service/predefinedAdaptor/sql/driver/libsql.ts

@@ -1,45 +0,0 @@
-import type { Client as LibsqlClient, Transaction as LibsqlTransaction } from "@libsql/client";
-import type { AkanSqlClient, AkanSqlStatement } from "../types";
-import { toLibsqlArgs } from "../values";
-import { openTurn, type SqliteWriteTurn, waitForTurn } from "./bunSqlite";
-
-export class LibsqlStatement implements AkanSqlStatement {
-  readonly #turn: () => Promise<void>;
-  constructor(
-    private readonly client: LibsqlClient | LibsqlTransaction,
-    private readonly sql: string,
-    writeTurn: SqliteWriteTurn = openTurn,
-  ) {
-    this.#turn = waitForTurn(sql, writeTurn);
-  }
-  async run(...params: unknown[]) {
-    await this.#turn();
-    return await this.client.execute({ sql: this.sql, args: toLibsqlArgs(params) });
-  }
-  async get<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row | null> {
-    await this.#turn();
-    const result = await this.client.execute({ sql: this.sql, args: toLibsqlArgs(params) });
-    return (result.rows[0] as Row | undefined) ?? null;
-  }
-  async all<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row[]> {
-    await this.#turn();
-    const result = await this.client.execute({ sql: this.sql, args: toLibsqlArgs(params) });
-    return result.rows as Row[];
-  }
-}
-
-export class LibsqlAkanClient implements AkanSqlClient {
-  constructor(
-    readonly client: LibsqlClient | LibsqlTransaction,
-    private readonly writeTurn: SqliteWriteTurn = openTurn,
-  ) {}
-  async execute(sql: string, params: unknown[] | Record<string, unknown> = []) {
-    return await this.prepare(sql).run(...(Array.isArray(params) ? params : [params]));
-  }
-  prepare(sql: string): AkanSqlStatement {
-    return new LibsqlStatement(this.client, sql, this.writeTurn);
-  }
-  async close() {
-    this.client.close();
-  }
-}

package/types/service/predefinedAdaptor/sql/driver/libsql.d.ts

@@ -1,20 +0,0 @@
-import type { Client as LibsqlClient, Transaction as LibsqlTransaction } from "@libsql/client";
-import type { AkanSqlClient, AkanSqlStatement } from "../types.d.ts";
-import { type SqliteWriteTurn } from "./bunSqlite.d.ts";
-export declare class LibsqlStatement implements AkanSqlStatement {
-    #private;
-    private readonly client;
-    private readonly sql;
-    constructor(client: LibsqlClient | LibsqlTransaction, sql: string, writeTurn?: SqliteWriteTurn);
-    run(...params: unknown[]): Promise<import("@libsql/client").ResultSet>;
-    get<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row | null>;
-    all<Row = Record<string, unknown>>(...params: unknown[]): Promise<Row[]>;
-}
-export declare class LibsqlAkanClient implements AkanSqlClient {
-    readonly client: LibsqlClient | LibsqlTransaction;
-    private readonly writeTurn;
-    constructor(client: LibsqlClient | LibsqlTransaction, writeTurn?: SqliteWriteTurn);
-    execute(sql: string, params?: unknown[] | Record<string, unknown>): Promise<unknown>;
-    prepare(sql: string): AkanSqlStatement;
-    close(): Promise<void>;
-}