akanjs 3.0.0-beta.9 → 3.0.1

package/client/csrTypes.ts

@@ -18,21 +18,10 @@ export type PageSafeAreaConfig =
       bottom?: boolean;
       android?: "auto" | "edge-to-edge" | "none";
     };
-/**
- * Server-render strategy for the initial full-document SSR pass.
- * - `"stream"` (default): flush the shell — including any `Loading` Suspense
- *   fallback — as soon as it is ready, then stream the resolved page. Redirects
- *   decided in the shell still become real HTTP redirects; redirects thrown
- *   inside suspended content degrade to soft (client) redirects.
- * - `"block"`: buffer the whole document until every Suspense boundary resolves
- *   before sending a byte. The `Loading` fallback never reaches the browser, but
- *   a non-redirect error thrown in slow content can still yield a clean error
- *   page. Use only for routes that need that guarantee and do not care about SEO
- *   or first-paint of the fallback.
- */
+/** `"stream"` flushes the shell (`Loading` included) then streams; a redirect in suspended content becomes a client one.
+ * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
 
-/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
   transition?: TransitionType;
   safeArea?: PageSafeAreaConfig;
@@ -44,20 +33,12 @@ export interface PageConfig {
   cache?: boolean;
   /** Initial full-document SSR strategy. Defaults to `"stream"`. */
   ssr?: SsrRenderMode;
-  /**
-   * Opt in to guarded RSC page suffix commits when the page does not require
-   * head/metadata updates and the retained route chain head is invariant for
-   * sibling navigations under the same layout.
-   */
+  /** Opt-in suffix-only RSC commits, for a page needing no head update under a layout head its siblings share. */
   rscPatchHeadSafe?: boolean;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
-  /**
-   * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
-   * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
-   * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
-   * the source without evaluating the module.
-   */
+  /** Keeps the route (on a `_layout`, its whole directory) out of `akan build` while `akan start` serves it. Write a
+   * literal `true`/`false`: the build reads it off the source without evaluating the module. */
   devOnly?: boolean;
 }
 
@@ -79,7 +60,6 @@ export interface PageProps {
   params: { [key: string]: string };
   searchParams: { [key: string]: string | string[] };
 }
-/** Props passed to Akan layout route modules. */
 export interface LayoutProps extends PageProps {
   children: ReactNode;
 }
@@ -109,7 +89,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
   node: Head | null | undefined;
-  hasExplicitLanguageAlternates: boolean;
   headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -124,9 +103,11 @@ export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<Rea
 export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
+  /** CSR: a page's render reads the query; a layout's reads only the params of its own path (`paramNames`). */
+  kind?: "page" | "layout";
+  paramNames?: string[];
   Loading?: LayoutLoadingRender | PageLoadingRender;
-  /** Loads the module and populates `Loading` without running `render`/`resolveHead`.
-   * Used by the patch (suffix) compose path, which never calls `resolveHead`. */
+  /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
   resolveLoading?: () => void | Promise<void>;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -135,6 +116,8 @@ export interface RouteRender {
   resolveHead?: ResolveHead;
   getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
+  /** A root layout's `theme`, readable before it renders. */
+  getLayoutTheme?: () => PromiseOrObject<string | undefined>;
   /** The `page()` chain behind a page render, when it was declared as one — what a page prompt is read off. */
   getRouteDefinition?: () => PromiseOrObject<RouteDefinition | undefined>;
 }
@@ -163,53 +146,24 @@ export interface WebAppManifest {
   screenshots?: WebAppManifestIcon[];
   [key: string]: unknown;
 }
-export interface AkanMetadata {
-  title?: string;
-  description?: string;
-  robots?: string;
-  openGraph?: {
-    title?: string;
-    description?: string;
-    type?: string;
-    url?: string;
-    siteName?: string;
-    images?: string | string[];
-  };
-  twitter?: {
-    card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
-    title?: string;
-    description?: string;
-    images?: string | string[];
-  };
-  alternates?: {
-    canonical?: string;
-    languages?: Record<string, string>;
-  };
-}
-export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
   default?: PageRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
-  gaTrackingId?: string;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -222,16 +176,15 @@ export interface Route {
   path: string;
   renderPage?: RouteRender;
   renderLayout?: RouteRender;
+  /** `renderLayout` is a generated `__root_layout`: a root boundary the page generator found. */
+  isRootLayout?: boolean;
   /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
   renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;
-  isSpecialRoute?: boolean;
-
   loader?: () => unknown;
   pageState?: PageState;
   pageConfigChain?: PageConfig[];
   explicitPageConfigKeys?: Partial<Record<keyof PageConfig, boolean>>;
-
   children: Map<string, Route>;
 }
 
@@ -274,6 +227,7 @@ export interface Location {
   searchParams: { [key: string]: string | string[] };
   pathRoute: PathRoute;
   hash: string;
+  entryId?: string; 
 }
 export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
 export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
@@ -300,6 +254,7 @@ export interface History {
   idxMap: Map<string, number>;
   cachedLocationMap: Map<string, Location>;
   idx: number;
+  dormant?: Set<string>; 
 }
 
 export interface RouterProps {
@@ -309,14 +264,24 @@ export interface RouterProps {
   back: () => void | Promise<void>;
 }
 
+export type CsrPageType = "current" | "prev" | "pending" | "cached";
+export interface CsrStackEntry {
+  key: string; 
+  location: Location;
+  pageType: CsrPageType;
+  zIndex: number;
+}
+
 export interface RouteState {
   clientWidth: number;
   clientHeight: number;
   location: Location;
   prevLocation: Location | null;
   pendingLocation: Location | null;
+  stackEntries: CsrStackEntry[];
   navigationIntent: NavigationIntent | null;
   phase: CsrNavigationPhase;
+  isBackgrounded: boolean;
   history: RefObject<History>;
   topSafeAreaRef: RefObject<HTMLDivElement | null>;
   bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -341,14 +306,24 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
+
+export const csrContext = sharedContext<CsrContextType>("csr", {
+  history: { current: null },
+  topSafeAreaRef: { current: null },
+  bottomSafeAreaRef: { current: null },
+  prevPageContentRef: { current: null },
+  pageContentRef: { current: null },
+  frameRootRef: { current: null },
+  onBack: { current: {} },
+} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
 };
 
 export interface PathContextType {
-  pageType: "current" | "prev" | "cached" | "pending";
+  pageType: CsrPageType;
+  pageKey?: string;
   location: Location;
   prefix?: string;
   gestureEnabled: boolean;
@@ -361,6 +336,16 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
+export type PageActivity = "current" | "prev" | "pending" | "hidden";
+export interface PageActivityState {
+  activity: PageActivity;
+  focused: boolean;
+}
+export const pageActivityContext = sharedContext<PageActivityState>("pageActivity", {
+  activity: "current",
+  focused: true,
+});
+
 export interface PathRoute {
   path: string;
   pathSegments: string[];
@@ -371,7 +356,6 @@ export interface PathRoute {
   renderRootLayouts: RouteRender[];
   renderLayouts: RouteRender[];
   resolveHead?: ResolveHead;
-  isSpecialRoute?: boolean;
 }
 
 export type FrameSlotScope = "page" | "layout";

package/client/decorators.ts

@@ -5,7 +5,7 @@ interface ToastProps {
   root?: string;
   duration?: number;
 }
-/** Decorates async actions with loading/success/error toast messages from `msg`. */
+/** Toasts `<root>.<key>-loading` / `-success` around the method; an error is toasted and logged, not rethrown. */
 export const Toast = ({ root, duration = 3 }: ToastProps = {}) => {
   return (target: any, key: string, descriptor: PropertyDescriptor) => {
     const originMethod = descriptor.value as (...args: any[]) => Promise<void>;

package/client/device.ts

@@ -1,57 +1,81 @@
 "use client";
 import type { RefObject } from "react";
-import type {
-  CapacitorDeviceInfo,
-  CapacitorHapticsModule,
-  CapacitorKeyboardInfo,
-  CapacitorKeyboardModule,
-} from "./capacitor";
-import { debugFrame } from "./frameDebug";
-
-type DeviceInfo = CapacitorDeviceInfo;
-type Keyboard = CapacitorKeyboardModule["Keyboard"];
-type Haptics = CapacitorHapticsModule["Haptics"];
-type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
+import { readCssSafeAreaInsets } from "./frameConfig";
+import type { DeviceInfo } from "./native";
+
+type NativeModule = typeof import("./native");
+type NativeControls = Pick<NativeModule, "haptics" | "keyboard">;
 type ProcessEnvLike = { env?: Record<string, string | undefined> };
+type DebugPayload = Record<string, unknown>;
 
 const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessEnvLike };
 
+const debugSessionId = Math.random().toString(36).slice(2, 8);
+let debugSeq = 0;
+
+const FRAME_TRACE_LIMIT = 2000;
+const frameTrace: { seq: number; event: string; details: DebugPayload }[] = [];
+
+const readFrameDebugFlag = () => {
+  const fromSearch = new URLSearchParams(window.location.search).get("akanFrameDebug");
+  if (fromSearch) return fromSearch;
+  try {
+    return window.localStorage.getItem("akan:debug:frame");
+  } catch {
+    
+    return null;
+  }
+};
+
+const frameDebugMode = (): "console" | "memory" | null => {
+  if (typeof window === "undefined") return null;
+  const flag = readFrameDebugFlag();
+  return flag === "1" ? "console" : flag === "memory" ? "memory" : null;
+};
+
+export function debugFrame(event: string, payload: DebugPayload = {}) {
+  const mode = frameDebugMode();
+  if (!mode) return;
+  debugSeq += 1;
+  const details = {
+    href: window.location.href,
+    now: Math.round(performance.now()),
+    ...payload,
+  };
+  if (mode === "memory") {
+    frameTrace.push({ seq: debugSeq, event, details });
+    if (frameTrace.length > FRAME_TRACE_LIMIT) frameTrace.splice(0, frameTrace.length - FRAME_TRACE_LIMIT);
+    (window as { __AKAN_FRAME_TRACE__?: typeof frameTrace }).__AKAN_FRAME_TRACE__ = frameTrace;
+    return;
+  }
+  
+  console.debug(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details);
+}
+
 interface DeviceInitOption {
   lang: string;
   info: DeviceInfo;
   topSafeArea: number;
   bottomSafeArea: number;
-  keyboard: Keyboard;
-  haptics: Haptics;
-  impactStyle: ImpactStyle;
+  /** The shell's keyboard and haptics; a page outside a native shell has neither. */
+  native: NativeControls | null;
 }
 
-const noopKeyboard: Keyboard = {
-  show: async () => undefined,
-  hide: async () => undefined,
-  addListener: async () => undefined,
-  removeAllListeners: async () => undefined,
-};
-
-const noopHaptics: Haptics = {
-  vibrate: async () => undefined,
-  impact: async () => undefined,
-  selectionStart: async () => undefined,
-  selectionChanged: async () => undefined,
-  selectionEnd: async () => undefined,
-};
-
-const noopImpactStyle: ImpactStyle = {
-  Light: "light",
-  Medium: "medium",
-  Heavy: "heavy",
+const webDeviceInfo: DeviceInfo = {
+  platform: "web",
+  model: "",
+  manufacturer: "unknown",
+  osName: "unknown",
+  osVersion: "",
+  isVirtual: false,
+  webViewVersion: null,
 };
 
 const getRenderMode = () => globalWithProcess.process?.env?.AKAN_PUBLIC_RENDER_ENV ?? "csr";
 
 const getBrowserLanguage = () => globalThis.navigator?.language?.split("-")[0] ?? "en";
 
-const isNativeTarget = () => {
+export const isNativeTarget = () => {
   if (typeof window === "undefined") return false;
   return Boolean((window as typeof window & { __AKAN_MOBILE_TARGET__?: unknown }).__AKAN_MOBILE_TARGET__);
 };
@@ -62,6 +86,11 @@ export const isMobileDevice = () => {
   return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
 };
 
+const langInPath = (pathname: string, supportLanguages: string[] | readonly string[]) => {
+  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
+  return supportLanguages.find((language) => language === predefinedLangPath);
+};
+
 const createWebDevice = ({
   lang,
   supportLanguages,
@@ -70,20 +99,15 @@ const createWebDevice = ({
   supportLanguages: string[] | readonly string[];
 }) => {
   const pathname = typeof window === "undefined" ? "" : window.location.pathname;
-  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
-  const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
   return new Device({
-    lang: lang ?? predefinedLang ?? getBrowserLanguage(),
-    info: { platform: "web", isVirtual: false, osVersion: "" },
+    lang: lang ?? langInPath(pathname, supportLanguages) ?? getBrowserLanguage(),
+    info: webDeviceInfo,
     topSafeArea: 0,
     bottomSafeArea: 0,
-    keyboard: noopKeyboard,
-    haptics: noopHaptics,
-    impactStyle: noopImpactStyle,
+    native: null,
   });
 };
 
-/** Capacitor-aware device helper for platform info, safe areas, keyboard, haptics, and scroll state. */
 export class Device {
   static instance: Device | null = null;
   static async load({
@@ -95,40 +119,26 @@ export class Device {
   }) {
     if (Device.instance) return Device.instance;
     if (getRenderMode() !== "csr" || !isNativeTarget()) {
-      const device = createWebDevice({ lang, supportLanguages });
-      Device.instance = device;
-      return device;
+      Device.instance = createWebDevice({ lang, supportLanguages });
+      return Device.instance;
     }
-    const { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } = await import(
-      "./capacitor"
-    );
-    const [{ Device: CapacitorDevice }, { Keyboard }, { Haptics, ImpactStyle }, { SafeArea }] = await Promise.all([
-      loadCapacitorDevice(),
-      loadCapacitorKeyboard(),
-      loadCapacitorHaptics(),
-      loadCapacitorSafeArea(),
-    ]);
-    const [
-      info,
-      { value: languageCode },
-      {
-        insets: { top: topSafeArea, bottom: bottomSafeArea },
-      },
-    ] = await Promise.all([CapacitorDevice.getInfo(), CapacitorDevice.getLanguageCode(), SafeArea.getSafeAreaInsets()]);
-    if (info.platform === "ios") await Keyboard.setResizeMode?.({ mode: "none" });
-    const predefinedLangPath = window.location.pathname.split("/")[1]?.split("?")[0];
-    const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
-    const device = new Device({
-      lang: lang ?? predefinedLang ?? languageCode,
+    const native = await import("./native");
+    
+    if (!native.isNativeApp()) {
+      Device.instance = createWebDevice({ lang, supportLanguages });
+      return Device.instance;
+    }
+    const [info, { code: languageCode }] = await Promise.all([native.device.getInfo(), native.device.getLanguage()]);
+    
+    const { top: topSafeArea, bottom: bottomSafeArea } = readCssSafeAreaInsets();
+    Device.instance = new Device({
+      lang: lang ?? langInPath(window.location.pathname, supportLanguages) ?? languageCode,
       info,
       topSafeArea,
       bottomSafeArea,
-      keyboard: Keyboard,
-      haptics: Haptics,
-      impactStyle: ImpactStyle,
+      native: { keyboard: native.keyboard, haptics: native.haptics },
     });
-    Device.instance = device;
-    return device;
+    return Device.instance;
   }
   static getDevice() {
     if (!Device.instance) throw new Error("Device is not loaded yet");
@@ -140,33 +150,26 @@ export class Device {
   topSafeArea: number;
   bottomSafeArea: number;
   isMobile = isMobileDevice();
-  #keyboard: DeviceInitOption["keyboard"];
-  #haptics: DeviceInitOption["haptics"];
-  #impactStyle: DeviceInitOption["impactStyle"];
+  #native: NativeControls | null;
+  #stopKeyboardListeners: (() => void)[] = [];
   #pageContentRef: RefObject<HTMLDivElement | null> | null = null;
 
-  constructor({ lang, info, topSafeArea, bottomSafeArea, keyboard, haptics, impactStyle }: DeviceInitOption) {
+  constructor({ lang, info, topSafeArea, bottomSafeArea, native }: DeviceInitOption) {
     this.info = info;
     this.lang = lang;
     this.topSafeArea = topSafeArea;
     this.bottomSafeArea = bottomSafeArea;
-    this.#keyboard = keyboard;
-    this.#haptics = haptics;
-    this.#impactStyle = impactStyle;
+    this.#native = native;
   }
   setPageContentRef(pageContentRef: RefObject<HTMLDivElement | null>) {
     this.#pageContentRef = pageContentRef;
   }
-  async showKeyboard() {
-    if (this.info.platform === "web") return;
-    await this.#keyboard.show();
-  }
   async hideKeyboard() {
-    if (this.info.platform === "web") return;
-    await this.#keyboard.hide();
+    await this.#native?.keyboard.hide();
   }
   listenKeyboardChanged(onKeyboardChanged: (height: number) => void) {
-    if (this.info.platform === "web") return;
+    const keyboard = this.#native?.keyboard;
+    if (!keyboard) return;
     let currentHeight = 0;
     const emitKeyboardHeight = (event: string, height: number) => {
       debugFrame("keyboard.event", { event, height, previousHeight: currentHeight });
@@ -174,49 +177,22 @@ export class Device {
       currentHeight = height;
       onKeyboardChanged(height);
     };
-    void this.#keyboard.addListener("keyboardWillShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardWillShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardDidShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardDidShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardWillHide", () => {
-      emitKeyboardHeight("keyboardWillHide", 0);
-    });
-    void this.#keyboard.addListener("keyboardDidHide", () => {
-      emitKeyboardHeight("keyboardDidHide", 0);
-    });
+    this.#stopKeyboardListeners.push(
+      ...(["willShow", "didShow", "willHide", "didHide"] as const).map((event) =>
+        keyboard.listen(event, ({ height }) => {
+          emitKeyboardHeight(event, height);
+        }),
+      ),
+    );
   }
   unlistenKeyboardChanged() {
-    if (this.info.platform === "web") return;
-    void this.#keyboard.removeAllListeners();
+    for (const stop of this.#stopKeyboardListeners.splice(0)) stop();
   }
   async vibrate(type: "light" | "medium" | "heavy" | number = "medium") {
-    if (typeof type === "number") {
-      await this.#haptics.vibrate({ duration: type });
-      return;
-    }
-    const handleImpact = {
-      light: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Light });
-      },
-      medium: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Medium });
-      },
-      heavy: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Heavy });
-      },
-      selectionStart: async () => {
-        await this.#haptics.selectionStart();
-      },
-      selectionChanged: async () => {
-        await this.#haptics.selectionChanged();
-      },
-      selectionEnd: async () => {
-        await this.#haptics.selectionEnd();
-      },
-    };
-    await handleImpact[type]();
+    const haptics = this.#native?.haptics;
+    if (!haptics) return;
+    if (typeof type === "number") await haptics.vibrate({ duration: type });
+    else await haptics.impact({ style: type });
   }
   getScrollTop() {
     if (this.info.platform === "web") return window.scrollY;

package/client/frameConfig.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "akanjs/common";
 import type { PageConfig, PageSafeAreaConfig, PageState, SsrRenderMode, TransitionType } from "./csrTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
@@ -30,9 +31,6 @@ const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "st
 const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 const hasOwn = <Key extends PropertyKey>(value: object, key: Key) => Object.hasOwn(value, key);
 
 export function validatePageConfig(routeKey: string, config?: PageConfig) {
@@ -53,15 +51,11 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (pageConfig.ssr !== undefined && !ssrRenderModes.has(pageConfig.ssr)) {
     throw new Error(`[route-convention] unsupported pageConfig.ssr "${pageConfig.ssr}" in ${routeKey}`);
   }
-  if (pageConfig.topInset !== undefined && !isValidInsetValue(pageConfig.topInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.topInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
-  }
-  if (pageConfig.bottomInset !== undefined && !isValidInsetValue(pageConfig.bottomInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.bottomInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
+  for (const key of ["topInset", "bottomInset"] as const) {
+    if (pageConfig[key] !== undefined && !isValidInsetValue(pageConfig[key]))
+      throw new Error(
+        `[route-convention] pageConfig.${key} in ${routeKey} must be a boolean or non-negative px number.`,
+      );
   }
   validateSafeAreaConfig(routeKey, pageConfig.safeArea);
 }
@@ -78,11 +72,9 @@ function validateSafeAreaConfig(routeKey: string, safeArea?: PageSafeAreaConfig)
       throw new Error(`[route-convention] unsupported pageConfig.safeArea option "${key}" in ${routeKey}`);
     }
   }
-  if (safeArea.top !== undefined && typeof safeArea.top !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.top in ${routeKey} must be a boolean.`);
-  }
-  if (safeArea.bottom !== undefined && typeof safeArea.bottom !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.bottom in ${routeKey} must be a boolean.`);
+  for (const side of ["top", "bottom"] as const) {
+    if (safeArea[side] !== undefined && typeof safeArea[side] !== "boolean")
+      throw new Error(`[route-convention] pageConfig.safeArea.${side} in ${routeKey} must be a boolean.`);
   }
   if (
     safeArea.android !== undefined &&
@@ -165,8 +157,8 @@ export function resolvePageState({
         : (config.gesture ?? false),
     cache: config.cache ?? false,
     ssr: config.ssr ?? "stream",
-    topSafeAreaColor: config.topSafeAreaColor ?? "var(color-background, Canvas)",
-    bottomSafeAreaColor: config.bottomSafeAreaColor ?? "var(color-background, Canvas)",
+    topSafeAreaColor: config.topSafeAreaColor ?? defaultPageState.topSafeAreaColor,
+    bottomSafeAreaColor: config.bottomSafeAreaColor ?? defaultPageState.bottomSafeAreaColor,
   };
 }
 
@@ -208,14 +200,11 @@ function resolveSafeArea({
   cssSafeArea?: SafeAreaInsets;
 }): SafeAreaInsets {
   if (safeArea === false) return { top: 0, bottom: 0 };
-  const topEnabled =
-    safeArea === true ||
-    safeArea === "top" ||
-    (isRecord(safeArea) ? safeArea.top !== false : safeArea === undefined && platform !== "web");
-  const bottomEnabled =
+  const enabledAt = (side: "top" | "bottom") =>
     safeArea === true ||
-    safeArea === "bottom" ||
-    (isRecord(safeArea) ? safeArea.bottom !== false : safeArea === undefined && platform !== "web");
+    safeArea === side ||
+    (isRecord(safeArea) ? safeArea[side] !== false : safeArea === undefined && platform !== "web");
+  const [topEnabled, bottomEnabled] = [enabledAt("top"), enabledAt("bottom")];
   if (platform === "android") {
     const androidMode = isRecord(safeArea)
       ? (safeArea.android as "auto" | "edge-to-edge" | "none" | undefined)
@@ -249,8 +238,8 @@ export function readCssSafeAreaInsets(): SafeAreaInsets {
   if (typeof window === "undefined") return { top: 0, bottom: 0 };
   const style = window.getComputedStyle?.(document.documentElement);
   return {
-    top: readCssPixel(style?.getPropertyValue("--safe-area-inset-top")) || readCssEnvProbe("top"),
-    bottom: readCssPixel(style?.getPropertyValue("--safe-area-inset-bottom")) || readCssEnvProbe("bottom"),
+    top: readCssPixel(style?.getPropertyValue("--akan-native-safe-area-top")) || readCssEnvProbe("top"),
+    bottom: readCssPixel(style?.getPropertyValue("--akan-native-safe-area-bottom")) || readCssEnvProbe("bottom"),
   };
 }
 

package/client/index.ts

@@ -6,9 +6,9 @@ export * from "./csrTypes";
 export * from "./decorators";
 export * from "./device";
 export * from "./frameConfig";
-export * from "./frameDebug";
 export * from "./locale";
 export * from "./makePageProto";
+export * from "./resolveServerUrl";
 export * from "./route";
 export * from "./router";
 export * from "./rscNavigation";