akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/vendor/use-agentic/useAgentResource.ts

@@ -0,0 +1,30 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useScopePath, useSurface } from "./surfaceContext";
+
+export interface AgentResourceMeta {
+  description?: string;
+  serialize?: (value: unknown) => unknown;
+  report?: boolean;
+}
+
+/** Publishes a read-only view of any value the component already holds — derived totals, statuses, labels. */
+export const useAgentResource = (name: string, value: unknown, meta: AgentResourceMeta = {}): void => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const live = useRef({ value, meta });
+  live.current = { value, meta };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    const { meta: declared } = live.current;
+    return surface.registerResource(scope, {
+      name,
+      description: declared.description,
+      report: declared.report,
+      read: () => {
+        const { value: current, meta: currentMeta } = live.current;
+        return currentMeta.serialize ? currentMeta.serialize(current) : current;
+      },
+    });
+  }, [surface, scopeKey, name]);
+};

package/vendor/use-agentic/useAgentState.ts

@@ -0,0 +1,61 @@
+"use client";
+import { type Dispatch, type SetStateAction, useEffect, useRef, useState } from "react";
+import { useScopePath, useSurface } from "./surfaceContext";
+import type { JsonSchema } from "./types";
+
+export interface AgentStateMeta<T> {
+  description?: string;
+  serialize?: (value: T) => unknown;
+  report?: boolean;
+  /** Schema of the setter's `value` argument. Without it the state is published read-only. */
+  set?: JsonSchema;
+  /** Validates or coerces the setter's incoming `value` — throw to refuse the write. Nothing else enforces `set`. */
+  parse?: (value: unknown) => T;
+}
+
+/** `useState` the agent can read — and write only through a named setter tool, and only when `set` declares one. */
+export const useAgentState = <T>(
+  name: string,
+  initial: T | (() => T),
+  meta: AgentStateMeta<T> = {},
+): [T, Dispatch<SetStateAction<T>>] => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const [value, setValue] = useState(initial);
+  const live = useRef({ value, meta });
+  live.current = { value, meta };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    const { meta: declared } = live.current;
+    return surface.registerResource(scope, {
+      name,
+      description: declared.description,
+      report: declared.report,
+      read: () => {
+        const { value: current, meta: currentMeta } = live.current;
+        return currentMeta.serialize ? currentMeta.serialize(current) : current;
+      },
+    });
+  }, [surface, scopeKey, name]);
+  const writable = !!meta.set;
+  useEffect(() => {
+    const { meta: declared } = live.current;
+    if (!declared.set) return;
+    return surface.registerTool(scope, {
+      name: `set${name.charAt(0).toUpperCase()}${name.slice(1)}`,
+      description: `Set ${name}.${declared.description ? ` ${declared.description}` : ""}`,
+      parameters: {
+        type: "object",
+        properties: { value: declared.set },
+        required: ["value"],
+        additionalProperties: false,
+      },
+      effect: "state",
+      run: (args) => {
+        const parse = live.current.meta.parse;
+        setValue(parse ? parse(args.value) : (args.value as T));
+      },
+    });
+  }, [surface, scopeKey, name, writable]);
+  return [value, setValue];
+};

package/vendor/use-agentic/useAgentTool.ts

@@ -0,0 +1,55 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useScopePath, useSurface } from "./surfaceContext";
+import type { JsonSchema, ToolConfirm, ToolEffect, ToolGuard } from "./types";
+
+export interface AgentToolMeta {
+  description?: string;
+  parameters?: JsonSchema;
+  effect?: ToolEffect;
+  confirm?: ToolConfirm;
+  guard?: ToolGuard;
+}
+
+/**
+ * Publishes one tool for as long as the component is mounted.
+ *
+ * Identity is the scoped name, not the callback — `run`, `guard`, and `confirm` read the latest render through a
+ * ref, so there is no dependency array and no stale closure for the agent to hit. `description` and `parameters`
+ * are declaration data, read once at mount.
+ */
+export const useAgentTool = <Args extends Record<string, unknown> = Record<string, unknown>, Result = unknown>(
+  name: string,
+  meta: AgentToolMeta,
+  run: (args: Args) => Result | Promise<Result>,
+): ((args?: Args) => Promise<Result>) => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const live = useRef({ meta, run });
+  live.current = { meta, run };
+  const call = useRef<((args?: Args) => Promise<Result>) | null>(null);
+  if (!call.current) call.current = async (args = {} as Args) => await live.current.run(args);
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    const { meta: declared } = live.current;
+    return surface.registerTool(scope, {
+      name,
+      description: declared.description,
+      parameters: declared.parameters,
+      effect: declared.effect,
+      ...(declared.confirm === undefined
+        ? {}
+        : {
+            confirm: (args: Record<string, unknown>) => {
+              const confirm = live.current.meta.confirm;
+              return typeof confirm === "function" ? confirm(args) : (confirm ?? false);
+            },
+          }),
+      ...(declared.guard === undefined
+        ? {}
+        : { guard: (args: Record<string, unknown>) => live.current.meta.guard?.(args) ?? true }),
+      run: (args) => live.current.run(args as Args),
+    });
+  }, [surface, scopeKey, name]);
+  return call.current;
+};

package/webkit/bootCsr.tsx

@@ -18,6 +18,7 @@ import {
 } from "akanjs/client";
 import {
   assertUniqueRoutePatterns,
+  getRouteExports,
   Logger,
   parseAkanI18nEnv,
   parseBasePaths,
@@ -303,39 +304,7 @@ function validateRouteModuleExports(key: string, mod: RouteModule) {
     if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
     return;
   }
-  const allowed =
-    parsed.kind === "page"
-      ? new Set(["default", "pageConfig", "head", "metadata", "generateHead", "generateMetadata", "Loading"])
-      : parsed.isInternalRootLayout
-        ? new Set([
-            "default",
-            "pageConfig",
-            "head",
-            "metadata",
-            "generateHead",
-            "generateMetadata",
-            "fonts",
-            "manifest",
-            "theme",
-            "reconnect",
-            "wsConnect",
-            "layoutStyle",
-            "gaTrackingId",
-            "Loading",
-            "NotFound",
-            "Error",
-          ])
-        : new Set([
-            "default",
-            "pageConfig",
-            "head",
-            "metadata",
-            "generateHead",
-            "generateMetadata",
-            "Loading",
-            "NotFound",
-            "Error",
-          ]);
+  const allowed = getRouteExports(parsed.kind, { rootLayout: parsed.isInternalRootLayout });
   for (const exportName of Object.keys(mod)) {
     if (!allowed.has(exportName)) {
       throw new Error(`[route-convention] unsupported export "${exportName}" in ${key}`);

package/webkit/index.ts

@@ -8,9 +8,12 @@ export { useCodepush } from "./useCodepush";
 export { useContact } from "./useContact";
 export { useCsrValues } from "./useCsrValues";
 export { useDebounce } from "./useDebounce";
+export { useEscapeKey } from "./useEscapeKey";
 export { useFetch, useFetchFn } from "./useFetch";
 export { useGeoLocation } from "./useGeoLocation";
 export { useHistory } from "./useHistory";
 export { useInterval } from "./useInterval";
 export { useLocation } from "./useLocation";
+export type { ScreenScopeItem } from "./useScreenScope";
+export { useScreenScope } from "./useScreenScope";
 export { useThrottle } from "./useThrottle";

package/webkit/lazy.tsx

@@ -5,7 +5,18 @@ import { forwardRef, lazy as reactLazy } from "react";
 
 const isServer = typeof window === "undefined";
 
-type LazyOption = { ssr?: boolean; loading?: () => ReactNode };
+/**
+ * `suspense` puts a Suspense boundary around the lazy component, so a chunk that resolves *after* the
+ * page is painted — a modal body, a dropdown menu — suspends only itself. Without one the suspension
+ * travels up to the nearest boundary, which is the route (`server/routeElementComposer.tsx`), and the
+ * whole page repaints as its loading fallback on the first open.
+ *
+ * It is opt-in rather than the default because a boundary also changes server rendering: under the
+ * default `renderMode: "stream"` the boundary's subtree leaves the shell as `loading` and arrives later
+ * in the stream. That is fine for an interaction shell and wrong for a page body, which SEO snapshots,
+ * prerendering and pre-hydration E2E read out of the shell.
+ */
+type LazyOption = { ssr?: boolean; suspense?: boolean; loading?: () => ReactNode };
 type LazyProps = Record<string, unknown>;
 type LoadedOf<Loaded> = Loaded extends { default: infer T } ? T : Loaded;
 type LazyModule = { default: ComponentType<LazyProps> };
@@ -27,7 +38,16 @@ export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption
   const LazyInner = reactLazy(async () => normalizeLazyModule(await loader()));
 
   if (!ssrFalse) {
-    const Wrapper = forwardRef<unknown, LazyProps>((props, ref) => <LazyInner {...props} ref={ref as never} />);
+
+    const Wrapper = forwardRef<unknown, LazyProps>((props, ref) =>
+      option?.suspense ? (
+        <React.Suspense fallback={renderFallback()}>
+          <LazyInner {...props} ref={ref as never} />
+        </React.Suspense>
+      ) : (
+        <LazyInner {...props} ref={ref as never} />
+      ),
+    );
     Wrapper.displayName = "LazyWrapper";
     return Wrapper as unknown as LoadedOf<Loaded>;
   }
@@ -36,7 +56,11 @@ export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption
     const [mounted, setMounted] = React.useState(false);
     React.useEffect(() => setMounted(true), []);
     if (!mounted) return <>{renderFallback()}</>;
-    return <LazyInner {...props} ref={ref as never} />;
+    return (
+      <React.Suspense fallback={renderFallback()}>
+        <LazyInner {...props} ref={ref as never} />
+      </React.Suspense>
+    );
   });
   Gate.displayName = "LazySsrFalseGate";
   return Gate as unknown as LoadedOf<Loaded>;

package/webkit/useCsrValues.ts

@@ -13,6 +13,7 @@ import {
   type NavigationIntent,
   normalizeDeepLinkHref,
   type PageState,
+  type PageTransition,
   type PathRoute,
   type RouteGuide,
   type RouteOptions,
@@ -23,13 +24,14 @@ import {
 } from "akanjs/client";
 import { loadCapacitorApp } from "akanjs/client/capacitor";
 import { parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import {
   createFrameSnapshot,
   createTransitionPlan,
   FRAME_Z_INDEX,
   getFramePlatformProfile,
   getFrameSlotsForSnapshot,
+  hasBottomAnchoredKeyboardSlot,
   hasKeyboardStickySlot,
   isPendingFrameReady,
   PENDING_FRAME_READY_TIMEOUT_MS,
@@ -492,7 +494,6 @@ const useStackTrans = (routeState: RouteState): UseCsrTransition => {
         gestureIntent.current = "pending";
         stackBackConfigRef.current = null;
         unlockPageScroll();
-        void Device.getDevice().hideKeyboard();
       }
       if (ix > initThreshold) {
         gestureIntent.current = "scroll";
@@ -511,6 +512,7 @@ const useStackTrans = (routeState: RouteState): UseCsrTransition => {
         if (absX < GESTURE_INTENT_THRESHOLD || absX <= absY * GESTURE_AXIS_LOCK_RATIO) return;
         gestureIntent.current = "gesture";
         lockPageScroll();
+        void Device.getDevice().hideKeyboard();
       }
       if (gestureIntent.current !== "gesture") {
         cancel();
@@ -668,11 +670,11 @@ const useBottomUpTrans = (routeState: RouteState): UseCsrTransition => {
 
   const pageBind = useDrag(
     ({ first, last, movement: [, my], initial: [, iy], cancel }) => {
-      if (first) void Device.getDevice().hideKeyboard();
       if (iy > initThreshold) {
         cancel();
         return;
       }
+      if (first) void Device.getDevice().hideKeyboard();
       if (my < transUnitRange[1]) void transUnit.start(transUnitRange[1], { immediate: true });
       else if (my > transUnitRange[0]) void transUnit.start(transUnitRange[0], { immediate: true });
       else if (!last) void transUnit.start(my, { immediate: true });
@@ -864,6 +866,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
   const resolvedPendingLocation = resolveLocationWithFrameState(pendingLocation, resolvedPathRouteMap);
   const platformProfile = getFramePlatformProfile();
   const accessoryHeight = resolveKeyboardAccessoryHeight(resolvedLocation.pathRoute.path, frameSlots);
+  const shouldAnchorContentBottom = hasBottomAnchoredKeyboardSlot(resolvedLocation.pathRoute.path, frameSlots);
   const keyboardFrame = useKeyboardFrame({
     bottomSafeArea: resolvedLocation.pathRoute.pageState.bottomSafeArea,
     sticky: hasKeyboardStickySlot(resolvedLocation.pathRoute.path, frameSlots),
@@ -881,6 +884,103 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       }),
     [viewport, keyboardFrame, accessoryHeight, resolvedLocation.pathRoute.pageState.bottomSafeArea],
   );
+  const contentBottomAnchorRef = useRef<{
+    path: string;
+    contentViewportHeight: number;
+    bottomDistance: number;
+  } | null>(null);
+  const contentBottomAnchorRafRef = useRef<number | null>(null);
+  useLayoutEffect(() => {
+    const element = pageContentRef.current;
+    const path = resolvedLocation.pathRoute.path;
+    if (!element || !shouldAnchorContentBottom || !keyboardFrame.sticky) {
+      contentBottomAnchorRef.current = null;
+      if (contentBottomAnchorRafRef.current !== null) {
+        cancelAnimationFrame(contentBottomAnchorRafRef.current);
+        contentBottomAnchorRafRef.current = null;
+      }
+      return;
+    }
+
+    const previous = contentBottomAnchorRef.current;
+    const currentBottomDistance = Math.max(0, element.scrollHeight - element.scrollTop - element.clientHeight);
+    if (!previous || previous.path !== path) {
+      contentBottomAnchorRef.current = {
+        path,
+        contentViewportHeight: keyboardLayout.contentViewport.height,
+        bottomDistance: currentBottomDistance,
+      };
+      return;
+    }
+
+    const shouldRestoreBottom = previous.contentViewportHeight !== keyboardLayout.contentViewport.height;
+    const bottomDistance = previous.bottomDistance;
+    if (shouldRestoreBottom) {
+      const nextScrollTop = Math.max(0, element.scrollHeight - element.clientHeight - bottomDistance);
+      if (Math.abs(element.scrollTop - nextScrollTop) > 1) {
+        debugFrame("keyboard.contentAnchor", {
+          path,
+          from: element.scrollTop,
+          to: nextScrollTop,
+          bottomDistance,
+          contentViewportHeight: keyboardLayout.contentViewport.height,
+        });
+        element.scrollTop = nextScrollTop;
+      }
+      const startedAt = performance.now();
+      const duration = (keyboardFrame.animationDuration ?? 0) + 50;
+      const keepBottomAnchored = () => {
+        const scrollTop = Math.max(0, element.scrollHeight - element.clientHeight - bottomDistance);
+        if (Math.abs(element.scrollTop - scrollTop) > 1) element.scrollTop = scrollTop;
+        if (performance.now() - startedAt < duration) {
+          contentBottomAnchorRafRef.current = requestAnimationFrame(keepBottomAnchored);
+        } else {
+          contentBottomAnchorRafRef.current = null;
+        }
+      };
+      if (contentBottomAnchorRafRef.current !== null) cancelAnimationFrame(contentBottomAnchorRafRef.current);
+      contentBottomAnchorRafRef.current = requestAnimationFrame(keepBottomAnchored);
+    }
+
+    contentBottomAnchorRef.current = {
+      path,
+      contentViewportHeight: keyboardLayout.contentViewport.height,
+      bottomDistance: Math.max(0, element.scrollHeight - element.scrollTop - element.clientHeight),
+    };
+    return () => {
+      if (contentBottomAnchorRafRef.current !== null) {
+        cancelAnimationFrame(contentBottomAnchorRafRef.current);
+        contentBottomAnchorRafRef.current = null;
+      }
+    };
+  }, [
+    pageContentRef,
+    resolvedLocation.pathRoute.path,
+    shouldAnchorContentBottom,
+    keyboardFrame.sticky,
+    keyboardFrame.animationDuration,
+    keyboardLayout.contentViewport.height,
+  ]);
+  useEffect(() => {
+    const element = pageContentRef.current;
+    const path = resolvedLocation.pathRoute.path;
+    if (!element || !shouldAnchorContentBottom || !keyboardFrame.sticky) return;
+    const updateBottomDistance = () => {
+      contentBottomAnchorRef.current = {
+        path,
+        contentViewportHeight: keyboardLayout.contentViewport.height,
+        bottomDistance: Math.max(0, element.scrollHeight - element.scrollTop - element.clientHeight),
+      };
+    };
+    element.addEventListener("scroll", updateBottomDistance, { passive: true });
+    return () => element.removeEventListener("scroll", updateBottomDistance);
+  }, [
+    pageContentRef,
+    resolvedLocation.pathRoute.path,
+    shouldAnchorContentBottom,
+    keyboardFrame.sticky,
+    keyboardLayout.contentViewport.height,
+  ]);
   useFrameRuntimeResync({ updateViewport });
   const shouldPrepareFrameTransition = useCallback(
     (nextHref?: string) => {
@@ -1245,6 +1345,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
       keyboard: keyboardFrame,
       contentViewport: keyboardLayout.contentViewport,
       keyboardAccessory: keyboardLayout.keyboardAccessory,
+      contentAnchor: shouldAnchorContentBottom ? "bottom" : undefined,
       platformProfile,
       zIndex: FRAME_Z_INDEX,
       pageStateByPath: effectivePageStateByPath,
@@ -1262,6 +1363,21 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
     bottomUp: useBottomUpTransition,
     scaleOut: useScaleOutTransition,
   };
+
+  const contentResizeStyle = useMemo(() => {
+    if (!shouldAnchorContentBottom || !keyboardFrame.sticky) return null;
+    const duration = keyboardFrame.animationDuration ?? 420;
+    const easing = keyboardFrame.animationEasing ?? "cubic-bezier(0.16, 1, 0.3, 1)";
+    return {
+      transition: `height ${duration}ms ${easing}, padding-bottom ${duration}ms ${easing}`,
+      willChange: "height, padding-bottom",
+    };
+  }, [shouldAnchorContentBottom, keyboardFrame.sticky, keyboardFrame.animationDuration, keyboardFrame.animationEasing]);
+  const csrTransition = useCsrTransitionMap[resolvedLocation.pathRoute.pageState.transition];
+  const page: PageTransition | null =
+    contentResizeStyle && csrTransition.page
+      ? { ...csrTransition.page, contentStyle: { ...csrTransition.page.contentStyle, ...contentResizeStyle } }
+      : csrTransition.page;
   const nativeBackStateRef = useRef({
     path: resolvedLocation.pathRoute.path,
     keyboardHeight: keyboardFrame.height,
@@ -1409,6 +1525,7 @@ export const useCsrValues = (rootRouteGuide: RouteGuide, pathRoutes: PathRoute[]
 
   return {
     ...routeState,
-    ...useCsrTransitionMap[resolvedLocation.pathRoute.pageState.transition],
+    ...csrTransition,
+    page,
   } satisfies CsrContextType;
 };

package/webkit/useEscapeKey.tsx

@@ -0,0 +1,42 @@
+"use client";
+import { useEffect, useRef } from "react";
+
+/**
+ * Escape belongs to the topmost dismissable surface only.
+ *
+ * A per-component `window` listener cannot know that: every open surface hears the same keydown, so a
+ * dialog opened from another dialog took both down at once, and a confirm popover inside a modal would
+ * have closed the modal under it. One shared stack keeps the order surfaces actually opened in and
+ * hands the key to the last one.
+ */
+const stack: (() => void)[] = [];
+
+const onKeyDown = (event: KeyboardEvent) => {
+  if (event.key !== "Escape") return;
+  const topmost = stack.at(-1);
+  if (!topmost) return;
+  event.preventDefault();
+  topmost();
+};
+
+/**
+ * Close `onEscape` on Escape while `active`, but only while this surface is the topmost active one.
+ * The callback is read through a ref, so a fresh closure per render does not reshuffle the stack.
+ */
+export const useEscapeKey = (active: boolean, onEscape: () => void) => {
+  const callbackRef = useRef(onEscape);
+  useEffect(() => {
+    callbackRef.current = onEscape;
+  });
+  useEffect(() => {
+    if (!active) return;
+    const entry = () => callbackRef.current();
+    stack.push(entry);
+    if (stack.length === 1) window.addEventListener("keydown", onKeyDown);
+    return () => {
+      const index = stack.lastIndexOf(entry);
+      if (index !== -1) stack.splice(index, 1);
+      if (stack.length === 0) window.removeEventListener("keydown", onKeyDown);
+    };
+  }, [active]);
+};

package/webkit/useFrameRuntime.ts

@@ -25,7 +25,10 @@ export type FrameSlotBucket = "active" | "pending";
 export type FrameSlotMapByBucket = Record<FrameSlotBucket, FrameSlotMap>;
 export const PENDING_FRAME_READY_TIMEOUT_MS = 80;
 export const PENDING_FRAME_READY_MAX_TIMEOUT_MS = 120;
-export const KEYBOARD_FALLBACK_ANIMATION_DURATION_MS = 285;
+export const KEYBOARD_SHOW_ANIMATION_DURATION_MS = 420;
+export const KEYBOARD_HIDE_ANIMATION_DURATION_MS = 90;
+export const KEYBOARD_SHOW_ANIMATION_EASING = "cubic-bezier(0.16, 1, 0.3, 1)";
+export const KEYBOARD_HIDE_ANIMATION_EASING = "cubic-bezier(0.7, 0, 0.84, 0)";
 
 export const FRAME_Z_INDEX = {
   page: 10,
@@ -204,29 +207,37 @@ export function useFrameViewport() {
     visualOffsetTop: window.visualViewport?.offsetTop ?? 0,
   }));
 
-  const updateViewport = useCallback((reason = "viewport.change") => {
-    const visualViewport = window.visualViewport;
-    const platform = getCurrentPlatform();
-    const nextViewport = {
-      width: Math.round(visualViewport?.width ?? window.innerWidth),
-      height: Math.round(platform === "ios" ? window.innerHeight : (visualViewport?.height ?? window.innerHeight)),
-      visualWidth: Math.round(visualViewport?.width ?? window.innerWidth),
-      visualHeight: Math.round(visualViewport?.height ?? window.innerHeight),
-      visualOffsetTop: Math.round(visualViewport?.offsetTop ?? 0),
-    };
-    setViewport((prev) => {
-      if (
-        prev.width === nextViewport.width &&
-        prev.height === nextViewport.height &&
-        prev.visualWidth === nextViewport.visualWidth &&
-        prev.visualHeight === nextViewport.visualHeight &&
-        prev.visualOffsetTop === nextViewport.visualOffsetTop
-      )
-        return prev;
-      debugFrame(reason, { from: prev, to: nextViewport, platform });
-      return nextViewport;
-    });
-  }, []);
+  const updateViewport = useCallback(
+    (reason = "viewport.change") => {
+      const visualViewport = window.visualViewport;
+      const platform = getCurrentPlatform();
+      const usesAkanKeyboardResize = platform === "ios" || platform === "android";
+      const width = Math.round(visualViewport?.width ?? window.innerWidth);
+      const currentHeight = Math.round(window.innerHeight);
+      const stableHeight =
+        usesAkanKeyboardResize && width === viewport.width ? Math.max(viewport.height, currentHeight) : currentHeight;
+      const nextViewport = {
+        width,
+        height: usesAkanKeyboardResize ? stableHeight : Math.round(visualViewport?.height ?? window.innerHeight),
+        visualWidth: Math.round(visualViewport?.width ?? window.innerWidth),
+        visualHeight: Math.round(visualViewport?.height ?? window.innerHeight),
+        visualOffsetTop: Math.round(visualViewport?.offsetTop ?? 0),
+      };
+      setViewport((prev) => {
+        if (
+          prev.width === nextViewport.width &&
+          prev.height === nextViewport.height &&
+          prev.visualWidth === nextViewport.visualWidth &&
+          prev.visualHeight === nextViewport.visualHeight &&
+          prev.visualOffsetTop === nextViewport.visualOffsetTop
+        )
+          return prev;
+        debugFrame(reason, { from: prev, to: nextViewport, platform });
+        return nextViewport;
+      });
+    },
+    [viewport.height],
+  );
 
   useEffect(() => {
     updateViewport("viewport.init");
@@ -259,6 +270,10 @@ export function hasKeyboardStickySlot(path: string, frameSlots: FrameSlotMap) {
   return getKeyboardAccessorySlots(path, frameSlots).length > 0;
 }
 
+export function hasBottomAnchoredKeyboardSlot(path: string, frameSlots: FrameSlotMap) {
+  return getKeyboardAccessorySlots(path, frameSlots).some((slot) => slot.contentAnchor === "bottom");
+}
+
 export function resolveKeyboardFrame({
   keyboardHeight,
   bottomSafeArea,
@@ -274,22 +289,36 @@ export function resolveKeyboardFrame({
   sticky: boolean;
   freeze?: boolean;
 }): KeyboardFrameState {
+  const useVisualViewportHeight = platformProfile === "android" && 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 effectiveKeyboardHeight = useVisualViewportHeight
+    ? visualViewportKeyboardHeight
+    : keyboardHeight > 0
+      ? keyboardHeight
+      : visualFallbackHeight;
+  const source = useVisualViewportHeight
+    ? "visualViewport"
+    : keyboardHeight > 0
+      ? "native"
+      : visualFallbackHeight > 0
+        ? "visualViewport"
+        : "fallback";
   const visualCompensation =
-    platformProfile === "ios" ? 0 : Math.min(visualViewportKeyboardHeight, effectiveKeyboardHeight);
+    platformProfile === "web" || platformProfile === "mobileWeb"
+      ? Math.min(visualViewportKeyboardHeight, effectiveKeyboardHeight)
+      : 0;
   const offset = sticky && !freeze ? Math.max(0, effectiveKeyboardHeight - visualCompensation) : 0;
+  const isShowing = effectiveKeyboardHeight > 0 && !freeze;
   return {
     height: effectiveKeyboardHeight,
     offset,
-    visible: effectiveKeyboardHeight > 0 && !freeze,
+    visible: isShowing,
     sticky,
     frozen: freeze,
     source,
-    animationDuration: KEYBOARD_FALLBACK_ANIMATION_DURATION_MS,
-    animationEasing: "ease-out",
+    animationDuration: isShowing ? KEYBOARD_SHOW_ANIMATION_DURATION_MS : KEYBOARD_HIDE_ANIMATION_DURATION_MS,
+    animationEasing: isShowing ? KEYBOARD_SHOW_ANIMATION_EASING : KEYBOARD_HIDE_ANIMATION_EASING,
   };
 }
 
@@ -344,14 +373,18 @@ export function useKeyboardFrame({
 }: {
   bottomSafeArea: number;
   sticky: boolean;
-  viewport: { visualHeight: number; visualOffsetTop: number };
+  viewport: { height: number; visualHeight: number; visualOffsetTop: number };
   platformProfile: FramePlatformProfile;
   freeze?: boolean;
 }) {
   const keyboardHeight = st.use.keyboardHeight();
+  const androidViewportKeyboardHeight =
+    platformProfile === "android" ? Math.max(0, Math.round(viewport.height - window.innerHeight)) : 0;
   const visualViewportKeyboardHeight = Math.max(
     0,
-    Math.round(window.innerHeight - viewport.visualHeight - viewport.visualOffsetTop),
+    androidViewportKeyboardHeight > 0
+      ? androidViewportKeyboardHeight
+      : Math.round(viewport.height - viewport.visualHeight - viewport.visualOffsetTop),
   );
   return useMemo(
     () =>