@pablozaiden/webapp 0.5.8 → 0.6.0

package/src/web/api-client.ts

@@ -98,13 +98,14 @@ export async function appRequest(input: RequestInfo | URL, init?: RequestInit):
 }
 
 export async function appFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  const headers = new Headers(init?.headers);
+  if (!headers.has("accept")) {
+    headers.set("accept", "application/json");
+  }
   const response = await appRequest(input, {
     ...init,
     credentials: init?.credentials ?? "same-origin",
-    headers: {
-      accept: "application/json",
-      ...init?.headers,
-    },
+    headers,
   });
   if (response.headers.get("x-webapp-passkey-required") === "true" || response.headers.get("x-passkey-auth-required") === "true") {
     emitAuthRequired();
@@ -121,6 +122,15 @@ export async function appFetch(input: RequestInfo | URL, init?: RequestInit): Pr
   return response;
 }
 
+export async function appJson<T>(input: RequestInfo | URL, init: RequestInit = {}): Promise<T> {
+  const headers = new Headers(init.headers);
+  if (init.body != null && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const response = await appFetch(input, { ...init, headers });
+  return await response.json() as T;
+}
+
 function normalizeOptionalBaseUrl(rawValue?: string | null): string | undefined {
   const trimmedValue = rawValue?.trim();
   if (!trimmedValue) {

package/src/web/app-shell.tsx

@@ -0,0 +1,198 @@
+import { useEffect, type ReactNode, type RefObject } from "react";
+import { ActionMenu, IconButton } from "./components";
+import { SidebarTree } from "./sidebar-tree";
+import type { SidebarCollapsedState } from "./sidebar-state";
+import type { ActionMenuItem, SidebarAction, SidebarNode, WebAppRoute } from "./sidebar/types";
+
+function isSidebarShortcutEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  if (target.isContentEditable || target.closest("[contenteditable=''], [contenteditable='true']")) {
+    return true;
+  }
+  return target instanceof HTMLInputElement
+    || target instanceof HTMLTextAreaElement
+    || target instanceof HTMLSelectElement;
+}
+
+function Icon({ name }: { name: "settings" | "sidebar" | "plus" | "home" | "search" | "bolt" | "chat" | "code" | "refresh" }) {
+  const common = { "aria-hidden": true, viewBox: "0 0 24 24", className: "wapp-svg" };
+  if (name === "settings") return <svg {...common}><circle cx="12" cy="12" r="3" /><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06A1.65 1.65 0 0 0 15 19.4a1.65 1.65 0 0 0-1 .6 1.65 1.65 0 0 0-.33 1.82V22a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.6 15a1.65 1.65 0 0 0-.6-1 1.65 1.65 0 0 0-1.82-.33H2a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.6a1.65 1.65 0 0 0 1-.6 1.65 1.65 0 0 0 .33-1.82V2a2 2 0 1 1 4 0v.09A1.65 1.65 0 0 0 15 4.6a1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9c.14.33.34.64.6 1 .26.36.61.6 1 .6H22a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-2.51.4Z" /></svg>;
+  if (name === "sidebar") return <svg {...common}><rect x="4" y="5" width="16" height="14" rx="2" /><path d="M10 5v14" /></svg>;
+  if (name === "plus") return <svg {...common}><path d="M12 5v14M5 12h14" /></svg>;
+  if (name === "bolt") return <svg {...common}><path d="m13 2-8 12h7l-1 8 8-12h-7l1-8Z" /></svg>;
+  if (name === "chat") return <svg {...common}><path d="M21 15a4 4 0 0 1-4 4H8l-5 3V7a4 4 0 0 1 4-4h10a4 4 0 0 1 4 4Z" /><path d="M8 9h8M8 13h5" /></svg>;
+  if (name === "code") return <svg {...common}><path d="M8 8 4 12l4 4M16 8l4 4-4 4M14 4l-4 16" /></svg>;
+  if (name === "refresh") return <svg {...common}><path d="M21 12a9 9 0 0 1-15.5 6.3L3 16M3 21v-5h5M3 12A9 9 0 0 1 18.5 5.7L21 8M21 3v5h-5" /></svg>;
+  return <svg {...common}><path d="M4 10.5 12 4l8 6.5V20H5v-7h14" /></svg>;
+}
+
+function ActionIcon({ icon }: { icon?: ReactNode }) {
+  if (icon === "+") return <Icon name="plus" />;
+  if (icon === "↯") return <Icon name="bolt" />;
+  if (icon === "chat") return <Icon name="chat" />;
+  if (icon === "code") return <Icon name="code" />;
+  if (!icon) return <Icon name="bolt" />;
+  return <>{icon}</>;
+}
+
+export interface AppShellProps {
+  appName: string;
+  homeRoute: WebAppRoute;
+  topActions: SidebarAction[];
+  nodes: SidebarNode[];
+  route: WebAppRoute;
+  navigate: (route: WebAppRoute) => void;
+  sidebarSearchEnabled: boolean;
+  search: string;
+  onSearchChange: (search: string) => void;
+  sidebarSearchId: string;
+  sidebarSearchInputRef: RefObject<HTMLInputElement | null>;
+  sidebarOpen: boolean;
+  setSidebarOpen: (open: boolean) => void;
+  sidebarCollapsed: boolean;
+  toggleSidebarCollapsed: () => void;
+  collapsed: SidebarCollapsedState;
+  toggleCollapsed: (id: string, isCollapsed: boolean) => void;
+  searchActive: boolean;
+  effectiveVersion: string;
+  headerTitle: ReactNode;
+  headerActionLabel: string;
+  primaryHeaderActions?: ReactNode;
+  headerActions: ActionMenuItem[];
+  view: ReactNode;
+}
+
+export function AppShell({
+  appName,
+  homeRoute,
+  topActions,
+  nodes,
+  route,
+  navigate,
+  sidebarSearchEnabled,
+  search,
+  onSearchChange,
+  sidebarSearchId,
+  sidebarSearchInputRef,
+  sidebarOpen,
+  setSidebarOpen,
+  sidebarCollapsed,
+  toggleSidebarCollapsed,
+  collapsed,
+  toggleCollapsed,
+  searchActive,
+  effectiveVersion,
+  headerTitle,
+  headerActionLabel,
+  primaryHeaderActions,
+  headerActions,
+  view,
+}: AppShellProps) {
+  useEffect(() => {
+    function handleSidebarShortcut(event: KeyboardEvent) {
+      if (
+        event.key.toLowerCase() !== "b"
+        || event.altKey
+        || event.shiftKey
+        || event.ctrlKey === event.metaKey
+        || event.isComposing
+        || event.repeat
+        || isSidebarShortcutEditableTarget(event.target)
+      ) {
+        return;
+      }
+
+      event.preventDefault();
+      toggleSidebarCollapsed();
+    }
+
+    document.addEventListener("keydown", handleSidebarShortcut);
+    return () => document.removeEventListener("keydown", handleSidebarShortcut);
+  }, [toggleSidebarCollapsed]);
+
+  const topSidebarActions = topActions.slice(0, 2);
+  const sidebarToggleLabel = sidebarCollapsed ? "Show sidebar" : "Collapse sidebar";
+  const closeSidebar = () => setSidebarOpen(false);
+  const navigateFromSidebarHeader = (nextRoute: WebAppRoute) => {
+    navigate(nextRoute);
+    closeSidebar();
+  };
+  const runSidebarHeaderAction = (action: SidebarAction) => {
+    if (action.onAction) {
+      action.onAction();
+    } else if (action.route) {
+      navigate(action.route);
+    }
+    closeSidebar();
+  };
+
+  return (
+    <main className={`wapp-shell ${sidebarCollapsed ? "sidebar-collapsed" : ""} ${sidebarOpen ? "sidebar-open" : ""}`}>
+      <div
+        className="wapp-mobile-backdrop"
+        role="button"
+        tabIndex={0}
+        aria-label="Close sidebar"
+        onClick={closeSidebar}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            closeSidebar();
+          }
+        }}
+      />
+      <aside id="wapp-sidebar" className="wapp-sidebar">
+        <div className="wapp-sidebar-header">
+          <button type="button" className="wapp-brand" onClick={() => navigateFromSidebarHeader(homeRoute)}>{appName}</button>
+          <div className="wapp-sidebar-actions">
+            {topSidebarActions.map((action) => <IconButton key={action.id} className="wapp-sidebar-top-button" title={action.title} aria-label={action.title} onClick={() => runSidebarHeaderAction(action)}><ActionIcon icon={action.icon} /></IconButton>)}
+            <IconButton className="wapp-sidebar-top-button" title="Settings" aria-label="Open settings" active={route.view === "settings"} onClick={() => navigateFromSidebarHeader({ view: "settings" })}><Icon name="settings" /></IconButton>
+            <IconButton className="wapp-sidebar-top-button" title={sidebarToggleLabel} aria-label={sidebarToggleLabel} aria-expanded={!sidebarCollapsed} aria-controls="wapp-sidebar" onClick={toggleSidebarCollapsed}><Icon name="sidebar" /></IconButton>
+          </div>
+        </div>
+        <div className="wapp-sidebar-scroll">
+          {sidebarSearchEnabled ? (
+            <div className="wapp-search">
+              <label className="sr-only" htmlFor={sidebarSearchId}>Search</label>
+              <div className={`wapp-search-input-wrap${search.length > 0 ? " wapp-search-input-wrap--clearable" : ""}`}>
+                <input id={sidebarSearchId} ref={sidebarSearchInputRef} value={search} onInput={(event) => onSearchChange(event.currentTarget.value)} placeholder="Search" />
+                {search.length > 0 ? (
+                  <button
+                    type="button"
+                    className="wapp-search-clear"
+                    aria-label="Clear search"
+                    onClick={() => {
+                      onSearchChange("");
+                      sidebarSearchInputRef.current?.focus();
+                    }}
+                  >
+                    ×
+                  </button>
+                ) : null}
+              </div>
+            </div>
+          ) : null}
+          <SidebarTree nodes={nodes} route={route} navigate={(next) => { navigate(next); setSidebarOpen(false); }} collapsed={collapsed} toggleCollapsed={toggleCollapsed} searchActive={searchActive} />
+          <div className="wapp-sidebar-footer">v{effectiveVersion}<button type="button" aria-label="Reload" onClick={() => window.location.reload()}><Icon name="refresh" /></button></div>
+        </div>
+      </aside>
+      <section className="wapp-main">
+        <header className="wapp-main-header">
+          <div className="wapp-main-header-title">
+            {sidebarCollapsed ? <IconButton className="wapp-sidebar-top-button" aria-label={sidebarToggleLabel} title={sidebarToggleLabel} aria-expanded={!sidebarCollapsed} aria-controls="wapp-sidebar" onClick={toggleSidebarCollapsed}><Icon name="sidebar" /></IconButton> : <IconButton className="wapp-mobile-only wapp-sidebar-top-button" aria-label="Show sidebar" title="Show sidebar" aria-expanded={sidebarOpen} aria-controls="wapp-sidebar" onClick={() => setSidebarOpen(true)}><Icon name="sidebar" /></IconButton>}
+            <h1>{headerTitle}</h1>
+          </div>
+          {primaryHeaderActions || headerActions.length ? (
+            <div className="wapp-main-header-actions">
+              {primaryHeaderActions}
+              {headerActions.length ? <ActionMenu items={headerActions} ariaLabel={`Actions for ${headerActionLabel}`} /> : null}
+            </div>
+          ) : null}
+        </header>
+        <div className="wapp-main-content">{view}</div>
+      </section>
+    </main>
+  );
+}

package/src/web/auth-screens.tsx

@@ -0,0 +1,186 @@
+import { startAuthentication, startRegistration } from "@simplewebauthn/browser";
+import { useCallback, useEffect, useState } from "react";
+import type { DeviceVerificationDetails, PasskeyAuthStatusResponse, UserSetupDetails } from "../contracts";
+import { appJson } from "./api-client";
+import { Badge, Button, Dialog, Panel, TextField } from "./components";
+
+export function PasskeyAuthScreen({ status, refresh }: { status: PasskeyAuthStatusResponse; refresh: () => Promise<void> }) {
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+  const [username, setUsername] = useState("");
+  const description = status.bootstrapRequired
+    ? "Choose the username for the owner"
+    : status.ownerPasskeySetupRequired
+      ? "The owner passkey was removed. Set it up again to continue."
+      : "Authenticate to continue.";
+
+  async function register(endpoint: "bootstrap" | "owner-setup") {
+    setBusy(true);
+    setError(undefined);
+    try {
+      const body = endpoint === "bootstrap" ? JSON.stringify({ username }) : "{}";
+      const options = await appJson<PublicKeyCredentialCreationOptionsJSON>(`/api/passkey-auth/${endpoint}/options`, { method: "POST", body });
+      const credential = await startRegistration({ optionsJSON: options as never });
+      await appJson(`/api/passkey-auth/${endpoint}/verify`, { method: "POST", body: JSON.stringify(credential) });
+      await refresh();
+      window.location.reload();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function login() {
+    setBusy(true);
+    setError(undefined);
+    try {
+      const options = await appJson<PublicKeyCredentialRequestOptionsJSON>("/api/passkey-auth/authentication/options", { method: "POST", body: "{}" });
+      const credential = await startAuthentication({ optionsJSON: options as never });
+      await appJson("/api/passkey-auth/authentication/verify", { method: "POST", body: JSON.stringify(credential) });
+      await refresh();
+      window.location.reload();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="wapp-auth-screen">
+      <Dialog
+        className="wapp-auth-dialog"
+        title={status.bootstrapRequired ? "Create owner user" : status.ownerPasskeySetupRequired ? "Set up owner passkey" : "Passkey required"}
+        actions={status.bootstrapRequired ? (
+          <Button type="button" variant="primary" disabled={busy || !username.trim()} onClick={() => void register("bootstrap")}>Create owner</Button>
+        ) : status.ownerPasskeySetupRequired ? (
+          <Button type="button" variant="primary" disabled={busy} onClick={() => void register("owner-setup")}>Set up owner passkey</Button>
+        ) : (
+          <Button type="button" variant="primary" disabled={busy} onClick={() => void login()}>Authenticate</Button>
+        )}
+      >
+        <p>{description}</p>
+        {error ? <p className="wapp-error">{error}</p> : null}
+        {status.bootstrapRequired ? <><br /><TextField label="Username" value={username} onChange={(event) => setUsername(event.currentTarget.value)} placeholder="owner" /></> : null}
+      </Dialog>
+    </main>
+  );
+}
+
+export function UserSetupScreen({ refresh }: { refresh: () => Promise<void> }) {
+  const token = new URLSearchParams(window.location.search).get("token") ?? "";
+  const [details, setDetails] = useState<UserSetupDetails>();
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    if (!token) {
+      setError("Setup token is missing");
+      return;
+    }
+    void appJson<UserSetupDetails>(`/api/user-setup?token=${encodeURIComponent(token)}`)
+      .then(setDetails)
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+  }, [token]);
+
+  async function setup() {
+    setBusy(true);
+    setError(undefined);
+    try {
+      const options = await appJson<PublicKeyCredentialCreationOptionsJSON>("/api/user-setup/options", { method: "POST", body: JSON.stringify({ token }) });
+      const credential = await startRegistration({ optionsJSON: options as never });
+      await appJson("/api/user-setup/verify", { method: "POST", body: JSON.stringify({ token, response: credential }) });
+      window.history.replaceState(null, "", "/");
+      await refresh();
+      window.location.reload();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="wapp-auth-screen">
+      <Dialog
+        className="wapp-auth-dialog"
+        title={details?.kind === "reset" ? "Reset passkey" : "Finish user setup"}
+        actions={<Button type="button" variant="primary" disabled={busy || !details} onClick={() => void setup()}>Set up passkey</Button>}
+      >
+        <p>{details ? `Username: ${details.username}` : "Loading setup link..."}</p>
+        {details ? <p className="wapp-muted">Role: {details.role}. This link expires at {details.expiresAt}.</p> : null}
+        {error ? <p className="wapp-error">{error}</p> : null}
+      </Dialog>
+    </main>
+  );
+}
+
+export function DeviceVerificationScreen() {
+  const params = new URLSearchParams(window.location.search);
+  const initialCode = params.get("user_code") ?? "";
+  const [userCode, setUserCode] = useState(initialCode);
+  const [details, setDetails] = useState<DeviceVerificationDetails>();
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+
+  const load = useCallback(async () => {
+    if (!userCode.trim()) {
+      setDetails(undefined);
+      return;
+    }
+    setBusy(true);
+    setError(undefined);
+    try {
+      setDetails(await appJson<DeviceVerificationDetails>(`/api/auth/device/verification?user_code=${encodeURIComponent(userCode.trim())}`));
+    } catch (err) {
+      setDetails(undefined);
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }, [userCode]);
+
+  useEffect(() => void load(), [load]);
+
+  async function decide(action: "approve" | "deny") {
+    if (!details) {
+      return;
+    }
+    setBusy(true);
+    setError(undefined);
+    try {
+      setDetails(await appJson<DeviceVerificationDetails>(`/api/auth/device/${action}`, {
+        method: "POST",
+        body: JSON.stringify({ user_code: details.userCode }),
+      }));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="wapp-device-screen">
+      <Panel title="Authorize device" description="Enter the code shown by the CLI or external device.">
+        <div className="wapp-device-stack">
+          <TextField label="User code" value={userCode} onChange={(event) => setUserCode(event.currentTarget.value.toUpperCase())} placeholder="ABCD-2345" />
+          {error ? <p className="wapp-error">{error}</p> : null}
+          {details ? (
+            <div className="wapp-device-card">
+              <div><strong>Client</strong><span>{details.clientId}</span></div>
+              <div><strong>Scope</strong><span>{details.scope}</span></div>
+              <div><strong>Status</strong><Badge variant={details.status === "approved" ? "success" : details.status === "denied" ? "error" : details.status === "consumed" ? "disabled" : "warning"}>{details.status}</Badge></div>
+              <div><strong>Expires</strong><span>{details.expiresAt}</span></div>
+            </div>
+          ) : null}
+          <div className="wapp-row-actions">
+            <Button type="button" variant="ghost" disabled={busy || !details || details.status !== "pending"} onClick={() => void decide("deny")}>Deny</Button>
+            <Button type="button" variant="primary" disabled={busy || !details || details.status !== "pending"} onClick={() => void decide("approve")}>Approve</Button>
+          </div>
+        </div>
+      </Panel>
+    </main>
+  );
+}

package/src/web/components/index.tsx

@@ -30,8 +30,15 @@ export function Badge({ variant = "default", className = "", children, ...props
   return <span {...props} className={`wapp-badge wapp-badge-${variant} ${className}`}>{children}</span>;
 }
 
-export function Page({ className = "", children, ...props }: HTMLAttributes<HTMLDivElement> & { children: ReactNode }) {
-  return <div {...props} className={`wapp-page ${className}`}>{children}</div>;
+export type PageLayout = "padded" | "full";
+
+export function Page({
+  layout = "padded",
+  className = "",
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement> & { children: ReactNode; layout?: PageLayout }) {
+  return <div {...props} className={`wapp-page ${layout === "full" ? "wapp-page-full" : ""} ${className}`.trim()}>{children}</div>;
 }
 
 export function Panel({ title, description, actions, children, className = "" }: { title?: string; description?: string; actions?: ReactNode; children?: ReactNode; className?: string }) {
@@ -53,7 +60,7 @@ export function Panel({ title, description, actions, children, className = "" }:
 
 export function EmptyState({ title, description, action }: { title: string; description?: string; action?: ReactNode }) {
   return (
-    <div className="wapp-empty-state">
+    <div className="wapp-empty-state" role="status" aria-label="Empty state">
       <strong>{title}</strong>
       {description ? <span>{description}</span> : null}
       {action}

package/src/web/index.ts

@@ -4,5 +4,6 @@ export * from "./render";
 export * from "./api-client";
 export * from "./sidebar/types";
 export * from "./realtime/useRealtime";
+export { MOBILE_BREAKPOINT_PX, MOBILE_MEDIA_QUERY, MOBILE_STATE_ATTRIBUTE } from "./mobile";
 export { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 export type { ThemePreference } from "../contracts";

package/src/web/mobile-hooks.ts

@@ -0,0 +1,194 @@
+import { useEffect, useState } from "react";
+import {
+  MOBILE_MEDIA_QUERY,
+  MOBILE_STATE_ATTRIBUTE,
+  MOBILE_VIEWPORT_FINAL_SETTLE_DELAY_MS,
+  MOBILE_VIEWPORT_FIRST_SETTLE_DELAY_MS,
+} from "./mobile";
+
+export function useMobileBreakpoint(): boolean {
+  const [isMobile, setIsMobile] = useState(() => typeof window !== "undefined" && window.matchMedia(MOBILE_MEDIA_QUERY).matches);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    const query = window.matchMedia(MOBILE_MEDIA_QUERY);
+    const root = document.documentElement;
+    const sync = () => {
+      const next = query.matches;
+      setIsMobile(next);
+      root.toggleAttribute(MOBILE_STATE_ATTRIBUTE, next);
+    };
+
+    sync();
+    query.addEventListener("change", sync);
+    return () => {
+      query.removeEventListener("change", sync);
+      root.removeAttribute(MOBILE_STATE_ATTRIBUTE);
+    };
+  }, []);
+
+  return isMobile;
+}
+
+export function useMobileViewportHeight(isMobile: boolean): void {
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const root = document.documentElement;
+    const viewport = window.visualViewport;
+    const timers = new Set<number>();
+    let frame = 0;
+
+    const clearViewportHeight = () => {
+      root.style.removeProperty("--wapp-viewport-height");
+    };
+
+    const sync = () => {
+      frame = 0;
+      if (!isMobile) {
+        clearViewportHeight();
+        return;
+      }
+
+      const height = Math.round(viewport?.height ?? window.innerHeight);
+      if (height > 0) {
+        root.style.setProperty("--wapp-viewport-height", `${height}px`);
+      }
+
+      const scrollingElement = document.scrollingElement;
+      if (scrollingElement && scrollingElement.scrollTop !== 0) {
+        scrollingElement.scrollTop = 0;
+      }
+    };
+
+    const scheduleSync = () => {
+      if (frame) {
+        return;
+      }
+      frame = requestAnimationFrame(sync);
+    };
+
+    const scheduleViewportRetry = (delay: number) => {
+      const timer = window.setTimeout(() => {
+        timers.delete(timer);
+        scheduleSync();
+      }, delay);
+      timers.add(timer);
+    };
+
+    const handleViewportTransition = () => {
+      scheduleSync();
+      if (isMobile) {
+        scheduleViewportRetry(MOBILE_VIEWPORT_FIRST_SETTLE_DELAY_MS);
+        scheduleViewportRetry(MOBILE_VIEWPORT_FINAL_SETTLE_DELAY_MS);
+      }
+    };
+
+    scheduleSync();
+    viewport?.addEventListener("resize", scheduleSync);
+    viewport?.addEventListener("scroll", scheduleSync);
+    window.addEventListener("resize", scheduleSync);
+    window.addEventListener("orientationchange", handleViewportTransition);
+    document.addEventListener("focusin", handleViewportTransition);
+    document.addEventListener("focusout", handleViewportTransition);
+
+    return () => {
+      if (frame) {
+        cancelAnimationFrame(frame);
+      }
+      for (const timer of timers) {
+        clearTimeout(timer);
+      }
+      viewport?.removeEventListener("resize", scheduleSync);
+      viewport?.removeEventListener("scroll", scheduleSync);
+      window.removeEventListener("resize", scheduleSync);
+      window.removeEventListener("orientationchange", handleViewportTransition);
+      document.removeEventListener("focusin", handleViewportTransition);
+      document.removeEventListener("focusout", handleViewportTransition);
+      clearViewportHeight();
+    };
+  }, [isMobile]);
+}
+
+const SIDEBAR_SWIPE_EDGE_WIDTH = 24;
+const SIDEBAR_SWIPE_DISTANCE = 64;
+const SIDEBAR_SWIPE_VERTICAL_TOLERANCE = 48;
+
+export function useMobileSidebarSwipe(isMobile: boolean, sidebarOpen: boolean, setSidebarOpen: (open: boolean) => void): void {
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+
+    let tracking = false;
+    let startX = 0;
+    let startY = 0;
+
+    const reset = () => {
+      tracking = false;
+    };
+
+    const handleTouchStart = (event: TouchEvent) => {
+      if (sidebarOpen || !isMobile || event.touches.length !== 1) {
+        reset();
+        return;
+      }
+
+      const touch = event.touches[0];
+      if (!touch || touch.clientX > SIDEBAR_SWIPE_EDGE_WIDTH) {
+        reset();
+        return;
+      }
+
+      tracking = true;
+      startX = touch.clientX;
+      startY = touch.clientY;
+    };
+
+    const handleTouchMove = (event: TouchEvent) => {
+      if (!tracking) {
+        return;
+      }
+      if (event.touches.length !== 1) {
+        reset();
+        return;
+      }
+
+      const touch = event.touches[0];
+      if (!touch) {
+        reset();
+        return;
+      }
+
+      const deltaX = touch.clientX - startX;
+      const deltaY = Math.abs(touch.clientY - startY);
+      if (deltaX <= 0 || deltaY > SIDEBAR_SWIPE_VERTICAL_TOLERANCE || deltaY > deltaX) {
+        reset();
+        return;
+      }
+      if (deltaX < SIDEBAR_SWIPE_DISTANCE) {
+        return;
+      }
+
+      event.preventDefault();
+      setSidebarOpen(true);
+      reset();
+    };
+
+    document.addEventListener("touchstart", handleTouchStart, { passive: true });
+    document.addEventListener("touchmove", handleTouchMove, { passive: false });
+    document.addEventListener("touchend", reset);
+    document.addEventListener("touchcancel", reset);
+    return () => {
+      document.removeEventListener("touchstart", handleTouchStart);
+      document.removeEventListener("touchmove", handleTouchMove);
+      document.removeEventListener("touchend", reset);
+      document.removeEventListener("touchcancel", reset);
+    };
+  }, [isMobile, setSidebarOpen, sidebarOpen]);
+}

package/src/web/mobile.ts

@@ -0,0 +1,12 @@
+export const MOBILE_BREAKPOINT_PX = 900;
+export const MOBILE_MEDIA_QUERY = `(max-width: ${MOBILE_BREAKPOINT_PX}px)`;
+export const MOBILE_STATE_ATTRIBUTE = "data-wapp-mobile";
+
+/*
+ * Mobile Safari/WebKit and Chromium can report focus or orientation changes
+ * before visualViewport reaches its final geometry. The first retry catches
+ * the post-event layout pass; the final retry catches the end of the keyboard,
+ * browser-chrome, or rotation transition when no further event is emitted.
+ */
+export const MOBILE_VIEWPORT_FIRST_SETTLE_DELAY_MS = 120;
+export const MOBILE_VIEWPORT_FINAL_SETTLE_DELAY_MS = 320;