akanjs 2.4.1-rc.2 → 2.4.1-rc.3

package/client/device.ts

@@ -1,12 +1,12 @@
 "use client";
 import type { RefObject } from "react";
-import { debugFrame } from "./frameDebug";
 import type {
   CapacitorDeviceInfo,
   CapacitorHapticsModule,
   CapacitorKeyboardInfo,
   CapacitorKeyboardModule,
 } from "./capacitor";
+import { debugFrame } from "./frameDebug";
 
 type DeviceInfo = CapacitorDeviceInfo;
 type Keyboard = CapacitorKeyboardModule["Keyboard"];

package/client/router.ts

@@ -112,7 +112,10 @@ const normalizeRouteManifestPath = (href: string, prefix = "") => {
   return segments.length === 0 ? "/" : `/${segments.join("/")}`;
 };
 
-export const normalizeDeepLinkHref = (href: string, origin = globalThis.window?.location?.origin ?? "http://localhost") => {
+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}` : "";
@@ -268,7 +271,11 @@ class Router {
     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);
+    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 };
@@ -336,7 +343,9 @@ class Router {
     }
     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];
+      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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.1-rc.2",
+  "version": "2.4.1-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -165,6 +165,11 @@
       "types": "./types/server/rscWorker.d.ts",
       "import": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
+    },
+    "./server/memoryLimit": {
+      "types": "./types/server/memoryLimit.d.ts",
+      "import": "./server/memoryLimit.ts",
+      "default": "./server/memoryLimit.ts"
     }
   },
   "dependencies": {

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -105,3 +105,19 @@ AKAN_RSC_WORKER_RECYCLE_GRACE_MS=5000
 ```
 
 Validate that recycle happens only when `rscPendingRenderCount` is `0`, and that the new `rscWorkerPid` becomes ready before traffic continues.
+
+## Dev Builder Recycle
+
+The dev builder has the same problem for a different reason: `Bun.build` retains native bundler arenas
+that no GC reclaims, so the process only returns that memory by exiting. `AkanAppHost` therefore
+recycles it — gracefully, after its queues drain and once it has stayed quiet — past a ceiling:
+
+```sh
+AKAN_BUILDER_MAX_RSS_MB=1200   # 0 leaves the builder unbounded; default is 1200 in dev
+AKAN_BUILDER_MAX_RSS=1200mb    # same ceiling with a unit suffix
+```
+
+Both resolve through `MemoryLimit.resolveMaxRssBytes`, so `AKAN_MEMORY_LIMIT` or a cgroup limit also
+applies (the builder takes 35% of it, the RSC worker 55%). Look for `recycling builder pid=…` followed
+by `exiting for recycle` and `announced boot state after recycle`; the last line is what re-points a
+running backend at the replacement's artifact.

package/server/akanApp.ts

@@ -1197,7 +1197,7 @@ export class AkanApp {
     const reader = stream.getReader();
     const decoder = new TextDecoder();
     try {
-      while (true) {
+      for (;;) {
         const { done, value } = await reader.read();
         if (done) break;
         const text = decoder.decode(value, { stream: true });
@@ -1213,7 +1213,7 @@ export class AkanApp {
 
   #writeChildOutput(idx: number, role: AkanChildRole, type: "stdout" | "stderr", bufferKey: string, text: string) {
     let buffered = `${this.#childOutputBuffers.get(bufferKey) ?? ""}${text}`;
-    while (true) {
+    for (;;) {
       const newlineIdx = buffered.indexOf("\n");
       if (newlineIdx === -1) break;
       const line = buffered.slice(0, newlineIdx + 1);

package/server/artifact/ipcTypes.ts

@@ -9,11 +9,21 @@ export interface BuildRouteResultPayload {
   generation?: number;
 }
 
+/**
+ * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
+ * A recycled builder rebuilds every artifact from scratch, but a running backend read
+ * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
+ * host drops such a payload when the hashed output did not actually move, which keeps a clean
+ * recycle invisible to connected browsers.
+ */
+export type BuilderStateReason = "builder-recycle";
+
 export interface CssPayload {
   cssAssets: Record<string, { cssUrl: string; cssRelPath: string }>;
   cssBase64ByUrl: Record<string, string>;
   generation?: number;
   changedFiles?: string[];
+  reason?: BuilderStateReason;
 }
 
 export type DevChangeRole = "server" | "client" | "shared" | "barrel" | "config" | "css";
@@ -71,11 +81,34 @@ export type BuilderCsrRes =
   | { type: "build-csr-res"; id: number; ok: true }
   | { type: "build-csr-res"; id: number; ok: false; error: string };
 
+/**
+ * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
+ * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
+ * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
+ * truncated.
+ */
+export type BuilderControl = { type: "builder-shutdown"; reason: string };
+
 export interface PagesBundlePayload {
   bundlePath: string;
   buildId: number;
   generation?: number;
   changedFiles?: string[];
+  reason?: BuilderStateReason;
+}
+
+/**
+ * `Bun.build` retains native bundler arenas the process never returns — `Bun.gc(true)` reclaims
+ * nothing and the JS heap stays flat while RSS climbs — so the builder's memory only comes back when
+ * it exits. It reports its own RSS here whenever its queues drain, and the dev host recycles it past
+ * a ceiling to turn unbounded growth into a bounded sawtooth.
+ */
+export interface BuilderMetrics {
+  rssBytes: number;
+  /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
+  generation: number;
+  /** Work items completed since this builder spawned, so a host can require real work before recycling. */
+  workCount: number;
 }
 
 export type BuilderEvent =
@@ -90,6 +123,7 @@ export type BuilderEvent =
     }
   | { type: "css-updated"; data: CssPayload }
   | { type: "pages-updated"; data: PagesBundlePayload }
-  | { type: "build-status"; data: DevBuildStatus };
+  | { type: "build-status"; data: DevBuildStatus }
+  | { type: "builder-metrics"; data: BuilderMetrics };
 
-export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderEvent;
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;

package/server/memoryLimit.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+
+/**
+ * Where a process's RSS ceiling comes from, shared by every host that recycles a child to bound it.
+ *
+ * A budget can be declared explicitly, discovered from the container, or absent altogether, so each
+ * host asks for a fraction of whatever limit it can find and supplies its own fallback for the last
+ * case. Kept as its own module rather than living on a host class because both `akanjs/server` and
+ * the dev host in `@akanjs/devkit` need it, and neither should import the other's stack to get it.
+ */
+export class MemoryLimit {
+  static readonly #cgroupLimitFiles = ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"];
+  /** Host-level cgroup files report effectively-unlimited sentinels; anything this large means "no limit". */
+  static readonly #unlimitedSentinelBytes = 1024 ** 5;
+
+  static parsePositiveIntEnv(name: string): number | null {
+    const parsed = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  }
+
+  /** Reads a byte count with an optional unit suffix, e.g. `512mb`, `2GiB`, `1073741824`. */
+  static parseBytesEnv(name: string): number | null {
+    const value = process.env[name];
+    if (!value) return null;
+    const match = /^(\d+)(b|kb|kib|mb|mib|gb|gib)?$/i.exec(value.trim());
+    if (!match) return null;
+    const amount = Number.parseInt(match[1] ?? "", 10);
+    const unit = (match[2] ?? "b").toLowerCase();
+    if (!Number.isFinite(amount) || amount <= 0) return null;
+    if (unit === "gb" || unit === "gib") return amount * 1024 * 1024 * 1024;
+    if (unit === "mb" || unit === "mib") return amount * 1024 * 1024;
+    if (unit === "kb" || unit === "kib") return amount * 1024;
+    return amount;
+  }
+
+  static readCgroupBytes(): number | null {
+    for (const filePath of MemoryLimit.#cgroupLimitFiles) {
+      try {
+        if (!fs.existsSync(filePath)) continue;
+        const raw = fs.readFileSync(filePath, "utf8").trim();
+        if (!raw || raw === "max") continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed > 0 && parsed < MemoryLimit.#unlimitedSentinelBytes) return parsed;
+      } catch {
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Resolves a ceiling from, in order: an explicit MiB env, an explicit byte env, a fraction of the
+   * container's memory limit, and finally the caller's fallback (`null` to leave the process
+   * unbounded).
+   */
+  static resolveMaxRssBytes({
+    megabytesEnv,
+    bytesEnv,
+    limitFraction,
+    fallbackBytes,
+  }: {
+    megabytesEnv: string;
+    bytesEnv: string;
+    limitFraction: number;
+    fallbackBytes: number | null;
+  }): number | null {
+    const explicitMb = MemoryLimit.parsePositiveIntEnv(megabytesEnv);
+    if (explicitMb) return explicitMb * 1024 * 1024;
+
+    const explicitBytes = MemoryLimit.parseBytesEnv(bytesEnv);
+    if (explicitBytes) return explicitBytes;
+
+    const memoryLimitBytes = MemoryLimit.parseBytesEnv("AKAN_MEMORY_LIMIT") ?? MemoryLimit.readCgroupBytes();
+    if (memoryLimitBytes) return Math.floor(memoryLimitBytes * limitFraction);
+
+    return fallbackBytes;
+  }
+}

package/server/rscWorkerHost.ts

@@ -6,6 +6,7 @@ import type { AkanTheme } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { ClientManifest } from "./artifact";
 import type { RouteCacheInvalidation, RouteCacheRenderState } from "./cachePolicy";
+import { MemoryLimit } from "./memoryLimit";
 import type { RscTraceMetadata, SsrLateRedirect } from "./ssrTypes";
 import type { BaseBuildArtifact, CssAsset } from "./types";
 
@@ -813,7 +814,7 @@ export class RscWorker {
       this.restartWhenIdle(`rss>${Math.round(maxRssBytes / 1024 / 1024)}MiB`);
       return;
     }
-    const maxRenderCount = RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RENDER_COUNT");
+    const maxRenderCount = MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RENDER_COUNT");
     if (maxRenderCount && (metrics.rscRenderCount ?? 0) >= maxRenderCount) {
       this.restartWhenIdle(`renderCount>${maxRenderCount}`);
       return;
@@ -824,46 +825,12 @@ export class RscWorker {
     }
   }
 
-  static #parsePositiveIntEnv(name: string): number | null {
-    const parsed = Number.parseInt(process.env[name] ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-  }
-
   static #isProductionRuntime(): boolean {
     return process.env.NODE_ENV === "production";
   }
 
-  static #parseBytesEnv(name: string): number | null {
-    const value = process.env[name];
-    if (!value) return null;
-    const match = /^(\d+)(b|kb|kib|mb|mib|gb|gib)?$/i.exec(value.trim());
-    if (!match) return null;
-    const amount = Number.parseInt(match[1] ?? "", 10);
-    const unit = (match[2] ?? "b").toLowerCase();
-    if (!Number.isFinite(amount) || amount <= 0) return null;
-    if (unit === "gb" || unit === "gib") return amount * 1024 * 1024 * 1024;
-    if (unit === "mb" || unit === "mib") return amount * 1024 * 1024;
-    if (unit === "kb" || unit === "kib") return amount * 1024;
-    return amount;
-  }
-
-  static #readCgroupMemoryLimitBytes(): number | null {
-    for (const filePath of ["/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory/memory.limit_in_bytes"]) {
-      try {
-        if (!fs.existsSync(filePath)) continue;
-        const raw = fs.readFileSync(filePath, "utf8").trim();
-        if (!raw || raw === "max") continue;
-        const parsed = Number.parseInt(raw, 10);
-        
-        if (Number.isFinite(parsed) && parsed > 0 && parsed < 1024 ** 5) return parsed;
-      } catch {
-      }
-    }
-    return null;
-  }
-
   static #getRscRecycleGraceMs(): number {
-    return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_RECYCLE_GRACE_MS") ?? 5_000;
+    return MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_RECYCLE_GRACE_MS") ?? 5_000;
   }
 
   /**
@@ -872,28 +839,25 @@ export class RscWorker {
    */
   static #getRscMaxReloads(): number | null {
     if (process.env.AKAN_RSC_WORKER_MAX_RELOADS !== undefined)
-      return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RELOADS");
+      return MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RELOADS");
     return RscWorker.#isProductionRuntime() ? null : RscWorker.#devMaxReloads;
   }
 
   static #getRscMinRecycleIntervalMs(): number {
-    return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS") ?? 1_000;
+    return MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS") ?? 1_000;
   }
 
   static #getRscMaxRssBytes(): number | null {
-    const explicitMb = RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RSS_MB");
-    if (explicitMb) return explicitMb * 1024 * 1024;
+    return MemoryLimit.resolveMaxRssBytes({
+      megabytesEnv: "AKAN_RSC_WORKER_MAX_RSS_MB",
+      bytesEnv: "AKAN_RSC_WORKER_MAX_RSS",
+      limitFraction: 0.55,
 
-    const explicitBytes = RscWorker.#parseBytesEnv("AKAN_RSC_WORKER_MAX_RSS");
-    if (explicitBytes) return explicitBytes;
-
-    const memoryLimitBytes = RscWorker.#parseBytesEnv("AKAN_MEMORY_LIMIT") ?? RscWorker.#readCgroupMemoryLimitBytes();
-    if (memoryLimitBytes) return Math.floor(memoryLimitBytes * 0.55);
-
-    return RscWorker.#isProductionRuntime() ? null : RscWorker.#devMaxRssBytes;
+      fallbackBytes: RscWorker.#isProductionRuntime() ? null : RscWorker.#devMaxRssBytes,
+    });
   }
 
   static #getRscMaxRouteModules(): number | null {
-    return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_ROUTE_MODULES");
+    return MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_ROUTE_MODULES");
   }
 }

package/types/server/artifact/ipcTypes.d.ts

@@ -18,6 +18,14 @@ export interface BuildRouteResultPayload {
     routeId?: string;
     generation?: number;
 }
+/**
+ * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
+ * A recycled builder rebuilds every artifact from scratch, but a running backend read
+ * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
+ * host drops such a payload when the hashed output did not actually move, which keeps a clean
+ * recycle invisible to connected browsers.
+ */
+export type BuilderStateReason = "builder-recycle";
 export interface CssPayload {
     cssAssets: Record<string, {
         cssUrl: string;
@@ -26,6 +34,7 @@ export interface CssPayload {
     cssBase64ByUrl: Record<string, string>;
     generation?: number;
     changedFiles?: string[];
+    reason?: BuilderStateReason;
 }
 export type DevChangeRole = "server" | "client" | "shared" | "barrel" | "config" | "css";
 export type DevChangeAction = "restart-backend" | "restart-builder" | "rebuild-client" | "rebuild-css" | "sync-generated" | "restart-dev-host" | "report-error";
@@ -85,11 +94,35 @@ export type BuilderCsrRes = {
     ok: false;
     error: string;
 };
+/**
+ * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
+ * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
+ * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
+ * truncated.
+ */
+export type BuilderControl = {
+    type: "builder-shutdown";
+    reason: string;
+};
 export interface PagesBundlePayload {
     bundlePath: string;
     buildId: number;
     generation?: number;
     changedFiles?: string[];
+    reason?: BuilderStateReason;
+}
+/**
+ * `Bun.build` retains native bundler arenas the process never returns — `Bun.gc(true)` reclaims
+ * nothing and the JS heap stays flat while RSS climbs — so the builder's memory only comes back when
+ * it exits. It reports its own RSS here whenever its queues drain, and the dev host recycles it past
+ * a ceiling to turn unbounded growth into a bounded sawtooth.
+ */
+export interface BuilderMetrics {
+    rssBytes: number;
+    /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
+    generation: number;
+    /** Work items completed since this builder spawned, so a host can require real work before recycling. */
+    workCount: number;
 }
 export type BuilderEvent = {
     type: "builder-ready";
@@ -112,5 +145,8 @@ export type BuilderEvent = {
 } | {
     type: "build-status";
     data: DevBuildStatus;
+} | {
+    type: "builder-metrics";
+    data: BuilderMetrics;
 };
-export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderEvent;
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;

package/types/server/memoryLimit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a process's RSS ceiling comes from, shared by every host that recycles a child to bound it.
+ *
+ * A budget can be declared explicitly, discovered from the container, or absent altogether, so each
+ * host asks for a fraction of whatever limit it can find and supplies its own fallback for the last
+ * case. Kept as its own module rather than living on a host class because both `akanjs/server` and
+ * the dev host in `@akanjs/devkit` need it, and neither should import the other's stack to get it.
+ */
+export declare class MemoryLimit {
+    #private;
+    static parsePositiveIntEnv(name: string): number | null;
+    /** Reads a byte count with an optional unit suffix, e.g. `512mb`, `2GiB`, `1073741824`. */
+    static parseBytesEnv(name: string): number | null;
+    static readCgroupBytes(): number | null;
+    /**
+     * Resolves a ceiling from, in order: an explicit MiB env, an explicit byte env, a fraction of the
+     * container's memory limit, and finally the caller's fallback (`null` to leave the process
+     * unbounded).
+     */
+    static resolveMaxRssBytes({ megabytesEnv, bytesEnv, limitFraction, fallbackBytes, }: {
+        megabytesEnv: string;
+        bytesEnv: string;
+        limitFraction: number;
+        fallbackBytes: number | null;
+    }): number | null;
+}

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

@@ -1,5 +1,5 @@
-import type { CSSProperties } from "react";
 import type { PageState } from "akanjs/client";
+import type { CSSProperties } from "react";
 export type AkanFrameCssVarName = "--akan-top-safe-area" | "--akan-bottom-safe-area" | "--akan-top-inset" | "--akan-bottom-inset" | "--akan-page-padding-top" | "--akan-page-padding-bottom";
 export type AkanFrameCssVars = CSSProperties & Record<AkanFrameCssVarName, string>;
 export declare function getFrameCssVars(pageState: PageState): AkanFrameCssVars;

package/types/webkit/useFrameRuntime.d.ts

@@ -1,4 +1,4 @@
-import { type FrameLayoutState, type FramePlatformProfile, type FrameSnapshot, type FrameSlotRegistration, type KeyboardFrameState, type Location, type NavigationIntent, type PageState, type PathRoute, type TransitionPlan, type TransitionType } from "akanjs/client";
+import { type FrameLayoutState, type FramePlatformProfile, type FrameSlotRegistration, type FrameSnapshot, type KeyboardFrameState, type Location, type NavigationIntent, type PageState, type PathRoute, type TransitionPlan, type TransitionType } from "akanjs/client";
 export type FrameSlotMap = Record<string, Record<string, FrameSlotRegistration>>;
 export type FrameSlotBucket = "active" | "pending";
 export type FrameSlotMapByBucket = Record<FrameSlotBucket, FrameSlotMap>;

package/ui/Layout/TopInset.tsx

@@ -1,6 +1,6 @@
 "use client";
 import { getEnv } from "akanjs/base";
-import { clsx, debugFrame, DEFAULT_TOP_INSET, usePathCtx } from "akanjs/client";
+import { clsx, DEFAULT_TOP_INSET, debugFrame, usePathCtx } from "akanjs/client";
 import { type ReactNode, useLayoutEffect } from "react";
 
 import { Portal } from "../Portal";
@@ -22,18 +22,15 @@ export const TopInset = ({ className, children, estimatedHeight = DEFAULT_TOP_IN
     debugFrame("topInset.mount", { path, estimatedHeight });
     return () => debugFrame("topInset.unmount", { path, estimatedHeight });
   }, [path, estimatedHeight]);
-  useLayoutEffect(
-    () => {
-      if (!path) return;
-      return registerFrameSlot({
-        type: "topInset",
-        scope: "page",
-        source: "topInset",
-        estimatedHeight,
-      });
-    },
-    [registerFrameSlot, estimatedHeight, path],
-  );
+  useLayoutEffect(() => {
+    if (!path) return;
+    return registerFrameSlot({
+      type: "topInset",
+      scope: "page",
+      source: "topInset",
+      estimatedHeight,
+    });
+  }, [registerFrameSlot, estimatedHeight, path]);
 
   return (
     <Portal id={`topInsetContent${suffix}`}>

package/ui/ServerPortal.tsx

@@ -1,5 +1,5 @@
-import type { ReactNode } from "react";
 import { getRequestStore } from "akanjs/fetch";
+import type { ReactNode } from "react";
 
 interface ServerPortalStore {
   capture: (id: string, children: ReactNode) => void;

package/ui/System/CSR.tsx

@@ -3,8 +3,8 @@
 import { getEnv } from "akanjs/base";
 import {
   clsx,
-  debugFrame,
   Device,
+  debugFrame,
   getPathInfo,
   type PathRoute,
   type ReactFont,
@@ -16,7 +16,7 @@ import {
 import { st } from "akanjs/store";
 import { animated } from "akanjs/ui";
 import { useFetch } from "akanjs/webkit";
-import { createElement, memo, type ComponentProps, type ReactNode, type RefObject, useEffect, useRef } from "react";
+import { type ComponentProps, createElement, memo, type ReactNode, type RefObject, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
 
 import { FontFace } from "../FontFace";
@@ -369,12 +369,14 @@ const CSRFrameSlotTargets = ({ slot }: { slot: FrameSlotTarget }) => {
                 (pageType === "prev" && (slot === "bottomInset" || slot === "keyboardInset")),
               "pointer-events-none absolute opacity-0": pageType === "pending",
             })}
-            style={{
-              ...getFrameCssVars(pathRoute.pageState),
-              ...(style ?? {}),
-              zIndex: pageType === "pending" ? -1 : zIndex,
-              ...(pageType === "pending" ? { opacity: 0 } : {}),
-            } as ComponentProps<typeof animated.div>["style"]}
+            style={
+              {
+                ...getFrameCssVars(pathRoute.pageState),
+                ...(style ?? {}),
+                zIndex: pageType === "pending" ? -1 : zIndex,
+                ...(pageType === "pending" ? { opacity: 0 } : {}),
+              } as ComponentProps<typeof animated.div>["style"]
+            }
           />
         );
       })}
@@ -447,14 +449,7 @@ const CSRPageContainer = ({ pathRoute, prefix, layoutStyle }: CSRPageContainerPr
   if (!pageType) return null;
   const pageContainers = document.getElementById("pageContainers");
   if (!pageContainers) return null;
-  const {
-    location,
-    page,
-    pageContentRef,
-    pageClassName,
-    pageBind,
-    zIndex,
-  } =
+  const { location, page, pageContentRef, pageClassName, pageBind, zIndex } =
     pageType === "current"
       ? {
           location: currentLocation,
@@ -473,23 +468,23 @@ const CSRPageContainer = ({ pathRoute, prefix, layoutStyle }: CSRPageContainerPr
             pageBind: () => ({}),
             zIndex: history.current.idxMap.get(prevLocation?.pathname ?? "") ?? 0,
           }
-          : pageType === "pending"
-            ? {
-                location: pendingLocation,
-                page: null,
-                pageContentRef: null,
-                pageClassName: "",
-                pageBind: () => ({}),
-                zIndex: history.current.idx + 1,
-              }
-        : {
-            location: history.current.cachedLocationMap.get(pathRoute.path),
-            page: null,
-            pageContentRef: null,
-            pageClassName: "",
-            pageBind: () => ({}),
-            zIndex: 0,
-          };
+        : pageType === "pending"
+          ? {
+              location: pendingLocation,
+              page: null,
+              pageContentRef: null,
+              pageClassName: "",
+              pageBind: () => ({}),
+              zIndex: history.current.idx + 1,
+            }
+          : {
+              location: history.current.cachedLocationMap.get(pathRoute.path),
+              page: null,
+              pageContentRef: null,
+              pageClassName: "",
+              pageBind: () => ({}),
+              zIndex: 0,
+            };
   if (!location) return null;
   return (
     <>
@@ -514,7 +509,8 @@ const CSRPageContainer = ({ pathRoute, prefix, layoutStyle }: CSRPageContainerPr
             bind={pageBind}
             className={clsx("akan-page-content relative isolate w-full overflow-x-hidden bg-base-100 shadow-inner", {
               "relative isolate overflow-x-hidden bg-base-100 shadow-inner": pageType === "current",
-              "pointer-events-none isolate h-screen w-screen overflow-hidden": pageType === "prev" || pageType === "pending",
+              "pointer-events-none isolate h-screen w-screen overflow-hidden":
+                pageType === "prev" || pageType === "pending",
               [pageClassName]: pathRoute.pageState.gesture,
             })}
             style={page?.contentStyle}

package/ui/System/Client.tsx

@@ -10,8 +10,8 @@ import {
   getPathInfo,
   initAuth,
   type Location,
-  type PageState,
   navigateRsc,
+  type PageState,
   type PathRoute,
   pathContext,
   router,
@@ -36,11 +36,10 @@ import {
   useRef,
   useState,
 } from "react";
-
+import { getFrameCssVars } from "./frameCssVars";
 import { Gtag } from "./Gtag";
 import { Messages } from "./Messages";
 import { Reconnect } from "./Reconnect";
-import { getFrameCssVars } from "./frameCssVars";
 
 declare global {
   var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
@@ -415,8 +414,8 @@ export const ClientSsrBridge = ({ lang, prefix = "", initialPageState }: ClientS
       }, 1000);
     };
     const handleSyncNavigation = (event: Event) => {
-      const { href, kind = "push" } = (event as CustomEvent<{ href?: string; kind?: "push" | "replace" | "back" | "pop" }>)
-        .detail ?? {};
+      const { href, kind = "push" } =
+        (event as CustomEvent<{ href?: string; kind?: "push" | "replace" | "back" | "pop" }>).detail ?? {};
       if (!href) return;
       const target = new URL(href, window.location.origin);
       const targetHref = `${target.pathname}${target.search}${target.hash}`;

package/ui/System/SSR.tsx

@@ -11,7 +11,7 @@ import {
   type WebAppManifest,
 } from "akanjs/client";
 import { getRequestFrameState, setRequestTheme } from "akanjs/fetch";
-import { Children, Fragment, type CSSProperties, type ReactNode, Suspense } from "react";
+import { Children, type CSSProperties, Fragment, type ReactNode, Suspense } from "react";
 import { FontCss } from "../fontCss";
 import { Load } from "../Load";
 import { createServerPortalStore, ServerPortalOutlet, setActiveServerPortalStore } from "../ServerPortal";
@@ -187,81 +187,81 @@ const SSRWrapper = ({
           initialHash={hash}
           initialPageState={pageState}
         >
-            <div
-              key="top-safe-area"
-              id="topSafeArea"
-              className={clsx("fixed inset-x-0 top-0 bg-base-100")}
-              style={topSafeAreaStyle}
-            />
-            <div key="page-containers" id="pageContainers" className={clsx("isolate")}>
-              <div id="pageContainer">
-                <div
-                  id="pageContent"
-                  style={pageContentStyle}
-                  className={clsx("relative isolate", {
-                    "w-full": layoutStyle === "web",
-                    "left-1/2 h-screen w-[600px] -translate-x-1/2": layoutStyle === "mobile",
-                  })}
-                >
-                  {Children.toArray(children)}
-                </div>
+          <div
+            key="top-safe-area"
+            id="topSafeArea"
+            className={clsx("fixed inset-x-0 top-0 bg-base-100")}
+            style={topSafeAreaStyle}
+          />
+          <div key="page-containers" id="pageContainers" className={clsx("isolate")}>
+            <div id="pageContainer">
+              <div
+                id="pageContent"
+                style={pageContentStyle}
+                className={clsx("relative isolate", {
+                  "w-full": layoutStyle === "web",
+                  "left-1/2 h-screen w-[600px] -translate-x-1/2": layoutStyle === "mobile",
+                })}
+              >
+                {Children.toArray(children)}
               </div>
             </div>
-            <div
-              key="top-inset"
-              id="topInsetContainer"
-              className={clsx("fixed inset-x-0 top-0 isolate bg-base-100", {
-                "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
-                "w-full": layoutStyle === "web",
-              })}
-              style={topInsetStyle}
-            >
-              <div id="topInsetContent" className={clsx("relative isolate size-full")}>
-                <ServerPortalOutlet id="topInsetContent" />
-              </div>
+          </div>
+          <div
+            key="top-inset"
+            id="topInsetContainer"
+            className={clsx("fixed inset-x-0 top-0 isolate bg-base-100", {
+              "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
+              "w-full": layoutStyle === "web",
+            })}
+            style={topInsetStyle}
+          >
+            <div id="topInsetContent" className={clsx("relative isolate size-full")}>
+              <ServerPortalOutlet id="topInsetContent" />
             </div>
-            <div
-              key="top-left-action"
-              id="topLeftActionContainer"
-              className="absolute top-0 left-0 isolate flex aspect-1 items-center justify-center"
-              style={topInsetStyle}
-            >
-              <div id="topLeftActionContent" className="isolate flex size-full items-center justify-center">
-                <ServerPortalOutlet id="topLeftActionContent" />
-              </div>
+          </div>
+          <div
+            key="top-left-action"
+            id="topLeftActionContainer"
+            className="absolute top-0 left-0 isolate flex aspect-1 items-center justify-center"
+            style={topInsetStyle}
+          >
+            <div id="topLeftActionContent" className="isolate flex size-full items-center justify-center">
+              <ServerPortalOutlet id="topLeftActionContent" />
             </div>
-            <div
-              key="bottom-inset"
-              id="bottomInsetContainer"
-              className={clsx("pointer-events-none fixed inset-x-0 bottom-0 isolate overflow-hidden", {
-                "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
-                "w-full": layoutStyle === "web",
-              })}
-              style={bottomInsetStyle}
-            >
-              <div id="bottomInsetContent" className="pointer-events-none isolate size-full">
-                <ServerPortalOutlet id="bottomInsetContent" />
-              </div>
+          </div>
+          <div
+            key="bottom-inset"
+            id="bottomInsetContainer"
+            className={clsx("pointer-events-none fixed inset-x-0 bottom-0 isolate overflow-hidden", {
+              "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
+              "w-full": layoutStyle === "web",
+            })}
+            style={bottomInsetStyle}
+          >
+            <div id="bottomInsetContent" className="pointer-events-none isolate size-full">
+              <ServerPortalOutlet id="bottomInsetContent" />
             </div>
-            <div
-              key="keyboard-inset"
-              id="keyboardInsetContainer"
-              className={clsx("pointer-events-none fixed inset-x-0 bottom-0 isolate overflow-hidden", {
-                "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
-                "w-full": layoutStyle === "web",
-              })}
-              style={bottomInsetStyle}
-            >
-              <div id="keyboardInsetContent" className="pointer-events-none isolate size-full">
-                <ServerPortalOutlet id="keyboardInsetContent" />
-              </div>
+          </div>
+          <div
+            key="keyboard-inset"
+            id="keyboardInsetContainer"
+            className={clsx("pointer-events-none fixed inset-x-0 bottom-0 isolate overflow-hidden", {
+              "left-1/2 w-[600px] -translate-x-1/2": layoutStyle === "mobile",
+              "w-full": layoutStyle === "web",
+            })}
+            style={bottomInsetStyle}
+          >
+            <div id="keyboardInsetContent" className="pointer-events-none isolate size-full">
+              <ServerPortalOutlet id="keyboardInsetContent" />
             </div>
-            <div
-              key="bottom-safe-area"
-              id="bottomSafeArea"
-              className="fixed inset-x-0 bg-base-100"
-              style={bottomSafeAreaStyle}
-            />
+          </div>
+          <div
+            key="bottom-safe-area"
+            id="bottomSafeArea"
+            className="fixed inset-x-0 bg-base-100"
+            style={bottomSafeAreaStyle}
+          />
         </ClientPathWrapper>
       </div>
     </>

package/ui/System/frameCssVars.ts

@@ -1,5 +1,5 @@
-import type { CSSProperties } from "react";
 import type { PageState } from "akanjs/client";
+import type { CSSProperties } from "react";
 
 export type AkanFrameCssVarName =
   | "--akan-top-safe-area"

package/webkit/useCsrValues.ts

@@ -4,8 +4,9 @@ import { useDrag } from "@use-gesture/react";
 import {
   type CsrContextType,
   type CsrTransitionStyles,
-  debugFrame,
+  router as clientRouter,
   Device,
+  debugFrame,
   defaultPageState,
   getPathInfo,
   type LocationState,
@@ -17,12 +18,11 @@ import {
   type RouteOptions,
   type RouterInstance,
   type RouteState,
-  router as clientRouter,
   type TransitionType,
   type UseCsrTransition,
 } from "akanjs/client";
-import { parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
 import { loadCapacitorApp } from "akanjs/client/capacitor";
+import { parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   createFrameSnapshot,
@@ -30,13 +30,13 @@ import {
   FRAME_Z_INDEX,
   getFramePlatformProfile,
   getFrameSlotsForSnapshot,
-  resolveKeyboardAccessoryHeight,
-  resolveKeyboardLayout,
   hasKeyboardStickySlot,
   isPendingFrameReady,
-  prepareForFrameTransition,
   PENDING_FRAME_READY_TIMEOUT_MS,
+  prepareForFrameTransition,
   resolveFramePageStateMap,
+  resolveKeyboardAccessoryHeight,
+  resolveKeyboardLayout,
   resolveLocationWithFrameState,
   resolvePathRoutesWithFrameState,
   useFrameRuntimeResync,
@@ -72,7 +72,12 @@ const getVelocityAwareDuration = (distance: number, velocity: number, fallback:
   return clamp(Math.round(Math.abs(distance) / absVelocity), STACK_SETTLE_MIN_DURATION, STACK_SETTLE_MAX_DURATION);
 };
 
-const getSyncRouteHref = (location: { pathname: string; search: string; hash: string; params?: { [key: string]: string } }) => {
+const getSyncRouteHref = (location: {
+  pathname: string;
+  search: string;
+  hash: string;
+  params?: { [key: string]: string };
+}) => {
   const segments = location.pathname.split("/").filter(Boolean);
   const lang = location.params?.lang ?? parseAkanI18nEnv().locales.find((locale) => locale === segments[0]) ?? "";
   const configuredBasePaths = new Set(parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS));
@@ -91,7 +96,9 @@ const getKeyboardAwarePageHeight = ({ frameLayout }: RouteState) => frameLayout.
 const getKeyboardAwareBottomPadding = ({ frameLayout }: RouteState, pageState: PathRoute["pageState"]) =>
   Math.max(
     pageState.bottomSafeArea,
-    pageState.bottomInset + pageState.bottomSafeArea - (frameLayout.keyboard.sticky ? frameLayout.keyboardAccessory.height : 0),
+    pageState.bottomInset +
+      pageState.bottomSafeArea -
+      (frameLayout.keyboard.sticky ? frameLayout.keyboardAccessory.height : 0),
   );
 
 const useNoneTrans = (routeState: RouteState): UseCsrTransition => {
@@ -822,7 +829,14 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
         ],
         basePageStateMap: basePageStateMap.current,
       }),
-    [pathRoutes, frameSlots, pendingFrameSlots, pendingLocation?.pathRoute.path, location.pathRoute.path, prevLocation?.pathRoute.path],
+    [
+      pathRoutes,
+      frameSlots,
+      pendingFrameSlots,
+      pendingLocation?.pathRoute.path,
+      location.pathRoute.path,
+      prevLocation?.pathRoute.path,
+    ],
   );
   useEffect(() => {
     if (!transitionPageStateSnapshot) pageStateByPathRef.current = pageStateByPath;
@@ -991,18 +1005,21 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
         if (kind === "push") window.history.pushState({}, "", href);
         else window.history.replaceState({}, "", href);
         debugFrame("navigation.commit", { id: intent.id, kind, to: href });
-        window.setTimeout(() => {
-          setTransitionPageStateSnapshot(null);
-          setLocationState((current) => ({
-            ...current,
-            pendingLocation: null,
-            navigationIntent: null,
-            phase: "idle",
-          }));
-          navigationLocked.current = false;
-          clearPendingSlots();
-          debugFrame("transition.actionEnd", { id: plan.id, phase: "idle" });
-        }, Math.max(360, plan.duration));
+        window.setTimeout(
+          () => {
+            setTransitionPageStateSnapshot(null);
+            setLocationState((current) => ({
+              ...current,
+              pendingLocation: null,
+              navigationIntent: null,
+              phase: "idle",
+            }));
+            navigationLocked.current = false;
+            clearPendingSlots();
+            debugFrame("transition.actionEnd", { id: plan.id, phase: "idle" });
+          },
+          Math.max(360, plan.duration),
+        );
       };
 
       const waitUntilReady = () => {
@@ -1170,8 +1187,17 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
     if (lastBroadcastSyncHref.current === syncHref) return;
     lastBroadcastSyncHref.current = syncHref;
     if (applyingSyncNavigation.current || globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
-    broadcastSyncNavigation(history.current.type === "back" ? "back" : history.current.type === "forward" ? "push" : "pop", syncHref);
-  }, [resolvedLocation.pathRoute.path, resolvedLocation.search, resolvedLocation.hash, broadcastSyncNavigation, history]);
+    broadcastSyncNavigation(
+      history.current.type === "back" ? "back" : history.current.type === "forward" ? "push" : "pop",
+      syncHref,
+    );
+  }, [
+    resolvedLocation.pathRoute.path,
+    resolvedLocation.search,
+    resolvedLocation.hash,
+    broadcastSyncNavigation,
+    history,
+  ]);
   useEffect(() => {
     const resetSyncNavigation = () => {
       window.setTimeout(() => {
@@ -1180,15 +1206,16 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       }, 1000);
     };
     const handleSyncNavigation = (event: Event) => {
-      const { href, kind = "push" } = (event as CustomEvent<{ href?: string; kind?: "push" | "replace" | "back" | "pop" }>)
-        .detail ?? {};
+      const { href, kind = "push" } =
+        (event as CustomEvent<{ href?: string; kind?: "push" | "replace" | "back" | "pop" }>).detail ?? {};
       if (!href) return;
       const target = new URL(href, window.location.origin);
       const targetHref = `${target.pathname}${target.search}${target.hash}`;
       if (targetHref === getSyncRouteHref(getCurrentLocation())) return;
       applyingSyncNavigation.current = true;
       globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__ = true;
-      if (kind === "replace" || kind === "back" || kind === "pop") clientRouter.replace(targetHref, { scrollToTop: false });
+      if (kind === "replace" || kind === "back" || kind === "pop")
+        clientRouter.replace(targetHref, { scrollToTop: false });
       else clientRouter.push(targetHref, { scrollToTop: false });
       resetSyncNavigation();
     };
@@ -1281,7 +1308,11 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       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))
+      if (
+        lastHandled?.href === href &&
+        now - lastHandled.handledAt < 1000 &&
+        (!shouldResetStack || lastHandled.resetStack)
+      )
         return;
       handledDeepLinkRef.current = { href, handledAt: now, resetStack: shouldResetStack };
       debugFrame("native.deepLink", {

package/webkit/useFrameRuntime.ts

@@ -1,12 +1,12 @@
 "use client";
 import {
+  Device,
   debugFrame,
   defaultPageState,
-  Device,
   type FrameLayoutState,
   type FramePlatformProfile,
-  type FrameSnapshot,
   type FrameSlotRegistration,
+  type FrameSnapshot,
   type KeyboardAccessoryFrameState,
   type KeyboardFrameState,
   type Location,
@@ -119,34 +119,37 @@ export function useFrameSlots() {
   });
   const frameSlotId = useRef(0);
 
-  const registerFrameSlot = useCallback((path: string, slot: FrameSlotRegistration, bucket: FrameSlotBucket = "active") => {
-    const id = `${slot.source ?? slot.type}-${frameSlotId.current++}`;
-    debugFrame("frameSlot.register", { path, id, bucket, slot });
-    setFrameSlotsByBucket((prev) => ({
-      ...prev,
-      [bucket]: {
-        ...prev[bucket],
-        [path]: {
-          ...(prev[bucket][path] ?? {}),
-          [id]: slot,
+  const registerFrameSlot = useCallback(
+    (path: string, slot: FrameSlotRegistration, bucket: FrameSlotBucket = "active") => {
+      const id = `${slot.source ?? slot.type}-${frameSlotId.current++}`;
+      debugFrame("frameSlot.register", { path, id, bucket, slot });
+      setFrameSlotsByBucket((prev) => ({
+        ...prev,
+        [bucket]: {
+          ...prev[bucket],
+          [path]: {
+            ...(prev[bucket][path] ?? {}),
+            [id]: slot,
+          },
         },
-      },
-    }));
-    return () => {
-      debugFrame("frameSlot.unregister", { path, id, bucket, type: slot.type, source: slot.source, role: slot.role });
-      setFrameSlotsByBucket((prev) => {
-        const pathSlots = prev[bucket][path];
-        if (!pathSlots?.[id]) return prev;
-        const nextPathSlots = { ...pathSlots };
-        delete nextPathSlots[id];
-        const nextBucket = { ...prev[bucket] };
-        if (Object.keys(nextPathSlots).length > 0) nextBucket[path] = nextPathSlots;
-        else delete nextBucket[path];
-        const next = { ...prev, [bucket]: nextBucket };
-        return next;
-      });
-    };
-  }, []);
+      }));
+      return () => {
+        debugFrame("frameSlot.unregister", { path, id, bucket, type: slot.type, source: slot.source, role: slot.role });
+        setFrameSlotsByBucket((prev) => {
+          const pathSlots = prev[bucket][path];
+          if (!pathSlots?.[id]) return prev;
+          const nextPathSlots = { ...pathSlots };
+          delete nextPathSlots[id];
+          const nextBucket = { ...prev[bucket] };
+          if (Object.keys(nextPathSlots).length > 0) nextBucket[path] = nextPathSlots;
+          else delete nextBucket[path];
+          const next = { ...prev, [bucket]: nextBucket };
+          return next;
+        });
+      };
+    },
+    [],
+  );
 
   const promotePendingSlots = useCallback(() => {
     setFrameSlotsByBucket((prev) => ({
@@ -188,9 +191,7 @@ export function getFramePlatformProfile(): FramePlatformProfile {
     (window.matchMedia?.("(display-mode: standalone)")?.matches ||
       (navigator as Navigator & { standalone?: boolean }).standalone === true);
   const hasCssSafeArea =
-    typeof document !== "undefined" &&
-    typeof CSS !== "undefined" &&
-    CSS.supports("top: env(safe-area-inset-top)");
+    typeof document !== "undefined" && typeof CSS !== "undefined" && CSS.supports("top: env(safe-area-inset-top)");
   return isStandalone || hasCssSafeArea ? "mobileWeb" : "web";
 }
 
@@ -273,10 +274,12 @@ export function resolveKeyboardFrame({
   sticky: boolean;
   freeze?: boolean;
 }): KeyboardFrameState {
-  const visualFallbackHeight = keyboardHeight <= 0 && visualViewportKeyboardHeight > 0 ? visualViewportKeyboardHeight : 0;
+  const visualFallbackHeight =
+    keyboardHeight <= 0 && visualViewportKeyboardHeight > 0 ? visualViewportKeyboardHeight : 0;
   const effectiveKeyboardHeight = keyboardHeight > 0 ? keyboardHeight : visualFallbackHeight;
   const source = keyboardHeight > 0 ? "native" : visualFallbackHeight > 0 ? "visualViewport" : "fallback";
-  const visualCompensation = platformProfile === "ios" ? 0 : Math.min(visualViewportKeyboardHeight, effectiveKeyboardHeight);
+  const visualCompensation =
+    platformProfile === "ios" ? 0 : Math.min(visualViewportKeyboardHeight, effectiveKeyboardHeight);
   const offset = sticky && !freeze ? Math.max(0, effectiveKeyboardHeight - visualCompensation) : 0;
   return {
     height: effectiveKeyboardHeight,