@viibestack/ui 0.2.0 → 0.6.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@viibestack/ui",
-  "version": "0.2.0",
-  "description": "Dependency-free React UI kit -- icons plus core components (Button, Card, Input, Modal, etc.), styled with plain Tailwind utility classes, no runtime dependency beyond react/react-dom.",
+  "version": "0.6.1",
+  "description": "Dependency-free React UI kit -- icons, core components (Button, Card, Input, Modal, etc.), a real per-app data client (listRows/upsertRow/deleteRow/reportError), and a real per-app end-user auth client (signUp/logIn/logOut/getCurrentUser) backed by ViibeStack's own platform-managed data store.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -22,5 +22,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4"
+  }
 }

package/src/auth.ts

@@ -0,0 +1,332 @@
+// Client for the app-auth feature -- real per-app end-user sign-up/login
+// (see db/migrations/auth/012_app_end_users.sql). Framework-agnostic like
+// data.ts, and reuses the exact same resolveAppId() pattern. Unlike
+// data.ts's background sync (which fails silently -- a lost write shouldn't
+// crash the app), these are interactive flows a real person is waiting on,
+// so failures are surfaced as a real error message instead of swallowed.
+//
+// Session refresh happens automatically inside getCurrentUser() -- generated
+// app code never has to implement a refresh loop itself, the same way it
+// never has to think about resolveAppId() caching.
+
+export interface AppUser {
+  id: string;
+  email: string;
+}
+
+export type AuthActionResult = { ok: true; user: AppUser } | { ok: false; error: string };
+export type ActionResult = { ok: true } | { ok: false; error: string };
+
+let appIdPromise: Promise<string | null> | null = null;
+
+function resolveAppId(): Promise<string | null> {
+  if (!appIdPromise) {
+    appIdPromise = fetch(`${window.location.origin}/api/apps/resolve?hostname=${window.location.hostname}`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { app_id?: string } | null) => data?.app_id ?? null)
+      .catch(() => null);
+  }
+  return appIdPromise;
+}
+
+interface StoredSession {
+  jwt: string;
+  sessionId: string;
+  user: AppUser;
+}
+
+const STORAGE_KEY = "viibestack_app_auth";
+
+const ACCESS_GATE_STORAGE_KEY = "viibestack_access_gate";
+
+// Read-only peek at the current auth credential for other library modules
+// that need to authenticate a request but shouldn't own session lifecycle
+// themselves (see data.ts's listRows/upsertRow/deleteRow, which attach this
+// as a bearer token). Checks a real_accounts session first, then falls back
+// to a shared_password gate token (see verifyAccessPassword below) -- an
+// app is only ever in one auth_mode at a time, so at most one of these is
+// ever actually populated, but checking both here means data.ts doesn't
+// need to know or care which mode this app is in. Doesn't refresh an
+// about-to-expire token the way getCurrentUser() does -- callers here are
+// best-effort, fire-and-forget writes, not something worth adding a
+// network round-trip to on every call.
+export function getStoredAuthToken(): string | null {
+  return loadStoredSession()?.jwt ?? loadStoredGateToken();
+}
+
+function loadStoredSession(): StoredSession | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as StoredSession) : null;
+  } catch {
+    return null;
+  }
+}
+
+function loadStoredGateToken(): string | null {
+  try {
+    return localStorage.getItem(ACCESS_GATE_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+// shared_password apps (auth_mode = 'real_accounts' is the other, separate
+// option -- see signUp/logIn above): a single password shared by everyone
+// who should have access, checked server-side (services/portal's
+// /access-gate/verify) rather than trusting the app's own client code to
+// enforce it. Call this from the app's password-gate screen; on success the
+// token is stored and every subsequent data.ts call authenticates with it
+// automatically via getStoredAuthToken() above -- build a screen that calls
+// this once and then renders the app, same shape as a signIn() call.
+export async function verifyAccessPassword(password: string): Promise<ActionResult> {
+  const appId = await resolveAppId();
+  if (!appId) return { ok: false, error: "couldn't determine this app's id" };
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/access-gate/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password }),
+    });
+    const body = (await res.json().catch(() => ({}))) as { token?: string; error?: string };
+    if (!res.ok || !body.token) return { ok: false, error: body.error ?? "incorrect password" };
+    try {
+      localStorage.setItem(ACCESS_GATE_STORAGE_KEY, body.token);
+    } catch {
+      // best-effort -- private browsing / storage-disabled shouldn't crash the app
+    }
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "network error" };
+  }
+}
+
+// Whether this browser already has a stored gate token -- call on page load
+// (like getCurrentUser()) to decide whether to show the password screen or
+// the app itself. Doesn't verify the token is still valid server-side
+// (that happens naturally on the first real data.ts call); this is just a
+// fast, synchronous "has this device unlocked before" check.
+export function hasVerifiedAccessPassword(): boolean {
+  return loadStoredGateToken() !== null;
+}
+
+function saveStoredSession(session: StoredSession | null): void {
+  try {
+    if (session) localStorage.setItem(STORAGE_KEY, JSON.stringify(session));
+    else localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // best-effort -- private browsing / storage-disabled shouldn't crash the app
+  }
+}
+
+// Reads the JWT's own `exp` claim without verifying the signature (that's
+// services/auth's job) -- just enough to know when a proactive refresh is
+// worthwhile, same purpose as the portal frontend's own pre-expiry refresh.
+function decodeJwtExpiry(jwt: string): number | null {
+  try {
+    const payload = JSON.parse(atob(jwt.split(".")[1].replace(/-/g, "+").replace(/_/g, "/")));
+    return typeof payload.exp === "number" ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+async function callAppAuth<T>(path: string, init?: RequestInit): Promise<{ ok: true; body: T } | { ok: false; error: string }> {
+  const appId = await resolveAppId();
+  if (!appId) return { ok: false, error: "couldn't determine this app's id" };
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/app-auth${path}`, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init?.headers },
+    });
+    const body = (await res.json().catch(() => ({}))) as T & { error?: string };
+    if (!res.ok) return { ok: false, error: body.error ?? "request failed" };
+    return { ok: true, body };
+  } catch {
+    return { ok: false, error: "network error" };
+  }
+}
+
+type SessionResponse = { jwt: string; sessionId: string; user: AppUser };
+
+export async function signUp(email: string, password: string): Promise<AuthActionResult> {
+  const result = await callAppAuth<SessionResponse>("/signup", { method: "POST", body: JSON.stringify({ email, password }) });
+  if (!result.ok) return { ok: false, error: result.error };
+  saveStoredSession(result.body);
+  return { ok: true, user: result.body.user };
+}
+
+export async function logIn(email: string, password: string): Promise<AuthActionResult> {
+  const result = await callAppAuth<SessionResponse>("/login", { method: "POST", body: JSON.stringify({ email, password }) });
+  if (!result.ok) return { ok: false, error: result.error };
+  saveStoredSession(result.body);
+  return { ok: true, user: result.body.user };
+}
+
+export async function logOut(): Promise<void> {
+  const stored = loadStoredSession();
+  saveStoredSession(null);
+  if (!stored) return;
+  await callAppAuth("/logout", { method: "POST", body: JSON.stringify({ session_id: stored.sessionId }) });
+}
+
+// The one function generated app code is expected to call on every page
+// load to find out "is anyone logged in" -- returns null if there's no
+// session, or if the session has expired/been revoked server-side (in
+// which case the stale local copy is cleared automatically).
+export async function getCurrentUser(): Promise<AppUser | null> {
+  const stored = loadStoredSession();
+  if (!stored) return null;
+
+  const exp = decodeJwtExpiry(stored.jwt);
+  const needsRefresh = exp == null || exp - Math.floor(Date.now() / 1000) < 120;
+  if (!needsRefresh) return stored.user;
+
+  const result = await callAppAuth<SessionResponse>("/session/refresh", {
+    method: "POST",
+    body: JSON.stringify({ session_id: stored.sessionId }),
+  });
+  if (!result.ok) {
+    saveStoredSession(null);
+    return null;
+  }
+  saveStoredSession(result.body);
+  return result.body.user;
+}
+
+export async function requestPasswordReset(email: string): Promise<ActionResult> {
+  const result = await callAppAuth<{ ok: boolean }>("/password-reset/request", { method: "POST", body: JSON.stringify({ email }) });
+  return result.ok ? { ok: true } : { ok: false, error: result.error };
+}
+
+export async function confirmPasswordReset(token: string, newPassword: string): Promise<ActionResult> {
+  const result = await callAppAuth<{ ok: boolean }>("/password-reset/confirm", {
+    method: "POST",
+    body: JSON.stringify({ token, new_password: newPassword }),
+  });
+  return result.ok ? { ok: true } : { ok: false, error: result.error };
+}
+
+// "Sign in with Google" -- a full-page redirect (not a fetch/popup, same
+// convention as the portal's own Google login), so this hits
+// services/auth directly rather than going through the app-auth proxy
+// above. Async because it needs the resolved app_id first; render the
+// resulting URL as a plain <a href>, e.g.:
+//   const [url, setUrl] = useState<string | null>(null);
+//   useEffect(() => { googleSignInUrl().then(setUrl); }, []);
+//   {url && <a href={url}>Sign in with Google</a>}
+const AUTH_URL = "https://sideblend-auth.sideblend.workers.dev";
+
+export async function googleSignInUrl(): Promise<string | null> {
+  const appId = await resolveAppId();
+  if (!appId) return null;
+  const params = new URLSearchParams({ app_id: appId, redirect_uri: window.location.origin + window.location.pathname });
+  return `${AUTH_URL}/v1/auth/oauth/google/app-start?${params.toString()}`;
+}
+
+// Call once on page load (e.g. in a top-level useEffect) to pick up the
+// tokens Google sign-in redirects back with. Returns null on an ordinary
+// page load with nothing to consume; strips the query params either way so
+// a refresh doesn't re-process them. Store methods (signUp/logIn) already
+// call the internal save function directly -- this is the one path that
+// has to parse it back out of a URL instead.
+export function consumeGoogleRedirect(): AuthActionResult | null {
+  const params = new URLSearchParams(window.location.search);
+  const error = params.get("error");
+  const jwt = params.get("jwt");
+  const sessionId = params.get("session_id");
+  const userId = params.get("user_id");
+  const email = params.get("email");
+  if (!error && !jwt) return null; // nothing to consume -- an ordinary page load
+
+  window.history.replaceState({}, "", window.location.pathname);
+  if (error) return { ok: false, error };
+  if (!jwt || !sessionId || !userId || !email) return { ok: false, error: "incomplete sign-in response" };
+  const user = { id: userId, email };
+  saveStoredSession({ jwt, sessionId, user });
+  return { ok: true, user };
+}
+
+// Monetization (061_monetization.sql) -- only meaningful once the app
+// OWNER has turned monetization on and set a price from the portal's
+// Access tab; there's no way for generated app code to enable this itself.
+// Both functions require a signed-in end-user (call signUp/logIn first) --
+// they reuse the SAME stored session as the rest of this file.
+export interface MonetizationStatus {
+  billing_interval: "monthly" | "annual";
+  status: string; // mirrors Stripe verbatim: trialing/active/past_due/canceled/...
+  trial_end: string | null;
+  seats: number; // 1 unless the app owner set pricing_model to per-seat
+}
+
+// Redirects the browser to Stripe Checkout to start (or restart) the
+// current end-user's subscription. Resolves once the redirect has been
+// issued (ok: true) -- there's no "after checkout" callback here; check
+// getMonetizationStatus() again once the user is back (Stripe redirects to
+// this app's own URL with ?billing=success/cancelled). `seats` only matters
+// when the app owner set per-seat pricing (ignored server-side otherwise) --
+// omit it for flat-priced apps.
+export async function createMonetizationCheckout(interval: "monthly" | "annual", seats?: number): Promise<ActionResult> {
+  const stored = loadStoredSession();
+  if (!stored) return { ok: false, error: "not signed in" };
+  const appId = await resolveAppId();
+  if (!appId) return { ok: false, error: "couldn't determine this app's id" };
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/monetization/checkout`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${stored.jwt}` },
+      body: JSON.stringify({ billing_interval: interval, seats }),
+    });
+    const body = (await res.json().catch(() => ({}))) as { url?: string; error?: string };
+    if (!res.ok || !body.url) return { ok: false, error: body.error ?? "failed to start checkout" };
+    window.location.href = body.url;
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "network error" };
+  }
+}
+
+// The current end-user's own subscription/trial state -- build an
+// "Upgrade" prompt or gate a feature against this. Returns null if they
+// have no subscription (never checked out, or this app isn't monetized).
+export async function getMonetizationStatus(): Promise<MonetizationStatus | null> {
+  const stored = loadStoredSession();
+  if (!stored) return null;
+  const appId = await resolveAppId();
+  if (!appId) return null;
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/monetization/status`, {
+      headers: { Authorization: `Bearer ${stored.jwt}` },
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { subscription: MonetizationStatus | null };
+    return body.subscription;
+  } catch {
+    return null;
+  }
+}
+
+// The standard "need help with this error?" report -- distinct from the
+// automatic window.onerror/unhandledrejection capture every generated app
+// already wires up (that one posts directly to .../errors via raw fetch per
+// integrationRequirements(), no packages/ui helper involved). This one is
+// for the explicit prompt: when an error surfaces, show a small toast/banner
+// asking the end-user if they want to report it, and call this if they say
+// yes. No sign-in required -- reporter_email is optional context, not auth.
+// Server-side this always emails the app owner (072_app_error_log_workflow.sql's
+// alerted_at still dedupes a recurring message within the same hour).
+export async function reportError(message: string, details?: Record<string, unknown>, reporterEmail?: string): Promise<ActionResult> {
+  const appId = await resolveAppId();
+  if (!appId) return { ok: false, error: "couldn't determine this app's id" };
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/errors/report`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message, details, reporter_email: reporterEmail }),
+    });
+    if (!res.ok) return { ok: false, error: "failed to report" };
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "network error" };
+  }
+}

package/src/data.ts

@@ -0,0 +1,122 @@
+// Client for a 'platform_managed' app's real backend data store -- the
+// per-app JSONB mirror at platform.app_data_tables/app_data_rows, now
+// readable/writable by the app itself (see services/portal/src/index.ts's
+// GET/DELETE .../data-public/:table routes), not just a write-only sync
+// target. Framework-agnostic (plain async functions, no React) so any
+// generated or uploaded app can use it regardless of how it manages state.
+//
+// Data here is shared with anyone who has the app's URL, UNLESS the app has
+// real per-user accounts turned on (see auth.ts) -- in that case the server
+// requires a signed-in session for every call below (services/portal's
+// requireDataAccess, gated on app_registry.auth_mode = 'real_accounts'), so
+// every function here attaches the current session's token when one exists.
+// For an app with no real accounts this is just shared data, not
+// access-controlled per account -- fine for a household/team app that wants
+// everyone to see the same thing.
+
+import { getStoredAuthToken } from "./auth";
+
+function authHeaders(): Record<string, string> {
+  const token = getStoredAuthToken();
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+let appIdPromise: Promise<string | null> | null = null;
+
+function resolveAppId(): Promise<string | null> {
+  if (!appIdPromise) {
+    appIdPromise = fetch(`${window.location.origin}/api/apps/resolve?hostname=${window.location.hostname}`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { app_id?: string } | null) => data?.app_id ?? null)
+      .catch(() => null);
+  }
+  return appIdPromise;
+}
+
+export interface RowsPage<T> {
+  rows: T[];
+  nextCursor: string | null;
+}
+
+// One page of a table, server-paginated (keyset on updated_at+id, newest
+// first) -- for a table expected to grow into the thousands+ (a CRM's
+// contacts, a helpdesk's tickets), build a real "load more"/infinite-scroll
+// UI around this instead of assuming listRows() below hands back
+// everything at once.
+export async function listRowsPage<T extends { id: string }>(table: string, opts?: { limit?: number; cursor?: string }): Promise<RowsPage<T>> {
+  const appId = await resolveAppId();
+  if (!appId) return { rows: [], nextCursor: null };
+  try {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.cursor) params.set("cursor", opts.cursor);
+    const qs = params.toString();
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/data-public/${table}${qs ? `?${qs}` : ""}`, { headers: authHeaders() });
+    if (!res.ok) return { rows: [], nextCursor: null };
+    const data = (await res.json()) as { rows: T[]; next_cursor: string | null };
+    return { rows: data.rows ?? [], nextCursor: data.next_cursor ?? null };
+  } catch {
+    return { rows: [], nextCursor: null };
+  }
+}
+
+// Convenience wrapper every existing generated app already calls expecting
+// a plain array back. Auto-pages up to MAX_AUTO_PAGES so a table's growth
+// no longer silently truncates at a hard 1000-row ceiling -- but this is
+// still a "fetch it all into memory" call, not real pagination; a table
+// genuinely headed into the tens of thousands of rows should move to
+// listRowsPage() above and render incrementally instead.
+const MAX_AUTO_PAGES = 20; // 20 x 1000-row pages = 20,000 rows before this stops and returns what it has
+
+export async function listRows<T extends { id: string }>(table: string): Promise<T[]> {
+  const all: T[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_AUTO_PAGES; page++) {
+    const { rows, nextCursor } = await listRowsPage<T>(table, { limit: 1000, cursor });
+    all.push(...rows);
+    if (!nextCursor) break;
+    cursor = nextCursor;
+  }
+  return all;
+}
+
+export async function upsertRow<T extends { id: string }>(table: string, row: T): Promise<void> {
+  const appId = await resolveAppId();
+  if (!appId) return;
+  try {
+    await fetch(`${window.location.origin}/api/apps/${appId}/data/${table}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...authHeaders() },
+      body: JSON.stringify({ rows: [row] }),
+    });
+  } catch {
+    // best-effort -- a write failure shouldn't crash the app for the person using it
+  }
+}
+
+export async function deleteRow(table: string, id: string): Promise<void> {
+  const appId = await resolveAppId();
+  if (!appId) return;
+  try {
+    await fetch(`${window.location.origin}/api/apps/${appId}/data-public/${table}/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+export async function reportError(message: string, stack?: string): Promise<void> {
+  const appId = await resolveAppId();
+  if (!appId) return;
+  try {
+    await fetch(`${window.location.origin}/api/apps/${appId}/errors`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message, details: { stack, url: window.location.href } }),
+    });
+  } catch {
+    // best-effort
+  }
+}

package/src/icons.tsx

@@ -109,6 +109,14 @@ export function MenuIcon(props: IconProps = {}) {
   );
 }
 
+export function ChevronDownIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
 export function BellIcon(props: IconProps = {}) {
   return (
     <svg {...svgProps(props)}>

package/src/index.ts

@@ -1,2 +1,5 @@
 export * from "./icons";
 export * from "./components";
+export * from "./nav";
+export * from "./data";
+export * from "./auth";

package/src/nav.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+// Responsive app navigation shell -- a fixed left sidebar on desktop that
+// collapses to a hamburger-triggered slide-in drawer on mobile. Built
+// specifically to avoid three real, previously-shipped mobile-nav bugs
+// (all found and fixed on viibestack.ai's own marketing site in this same
+// session, then generalized here so every generated app gets the fix by
+// default instead of each one re-discovering it):
+//   1. A drawer positioned with a viewport-relative offset (`right: -100vw`)
+//      can end up off-screen entirely, because `vw` resolves against the
+//      layout viewport, not the visual one, and the two can differ. Fixed
+//      here by only ever mounting the drawer when open (no transform/
+//      offset math at all -- `mobileOpen && <div>...`).
+//   2. A CSS checkbox-hack accordion (hidden checkbox + label, `:checked ~`
+//      sibling selector) can register a tap as toggling the checkbox twice
+//      in one gesture on real mobile browsers, closing a group the instant
+//      it opens. Fixed by using the native `<details>/<summary>` disclosure
+//      element instead, which the browser's own tap handling manages
+//      correctly -- no custom event/state logic to get wrong.
+//   3. Flex children with `flex-shrink` (the default) let a wrapping
+//      container squeeze itself into a tall, single-column, no-line-break
+//      instead of ever collapsing to the intended stacked layout. Avoided
+//      here by never using flex-wrap for this layout at all.
+import { createPortal } from "react-dom";
+import { useEffect, useState, type ReactNode } from "react";
+import { MenuIcon, CloseIcon, ChevronDownIcon } from "./icons";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+export interface NavLinkItem {
+  href: string;
+  label: string;
+  icon?: ReactNode;
+}
+
+export interface NavGroupItem {
+  label: string;
+  icon?: ReactNode;
+  items: NavLinkItem[];
+}
+
+export type AppNavItem = NavLinkItem | NavGroupItem;
+
+function isGroup(item: AppNavItem): item is NavGroupItem {
+  return "items" in item;
+}
+
+const LINK_CLASS =
+  "flex items-center gap-2 rounded-lg px-3 py-2 text-sm font-medium text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-800";
+const LINK_ACTIVE_CLASS = "bg-primary/10 text-primary dark:bg-primary/20";
+
+export interface AppShellProps {
+  /** Logo/product name, shown in the desktop sidebar header and mobile topbar/drawer. */
+  brand: ReactNode;
+  nav: AppNavItem[];
+  /** Current path, used to highlight the active link -- compare against each item's href. */
+  activeHref?: string;
+  /**
+   * Override how a single link renders (e.g. to use Next.js's `<Link>` for
+   * client-side navigation instead of a plain `<a>`, which would trigger a
+   * full page reload). Defaults to a plain anchor tag.
+   */
+  renderLink?: (item: NavLinkItem, active: boolean) => ReactNode;
+  /** Rendered at the bottom of the sidebar/drawer -- e.g. a user menu, sign-out button. */
+  footer?: ReactNode;
+  children: ReactNode;
+}
+
+export function AppShell({ brand, nav, activeHref, renderLink, footer, children }: AppShellProps) {
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  useEffect(() => {
+    if (!mobileOpen) return;
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") setMobileOpen(false);
+    }
+    document.addEventListener("keydown", onKey);
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prevOverflow;
+    };
+  }, [mobileOpen]);
+
+  function defaultLink(item: NavLinkItem, active: boolean) {
+    return (
+      <a href={item.href} className={cx(LINK_CLASS, active && LINK_ACTIVE_CLASS)}>
+        {item.icon}
+        {item.label}
+      </a>
+    );
+  }
+  const link = renderLink ?? defaultLink;
+
+  function renderItem(item: AppNavItem, key: number, onNavigate?: () => void) {
+    if (isGroup(item)) {
+      const groupHasActive = item.items.some((sub) => sub.href === activeHref);
+      return (
+        <details key={key} open={groupHasActive} className="group">
+          <summary
+            className={cx(LINK_CLASS, "cursor-pointer list-none justify-between [&::-webkit-details-marker]:hidden")}
+          >
+            <span className="flex items-center gap-2">
+              {item.icon}
+              {item.label}
+            </span>
+            <ChevronDownIcon size={16} className="shrink-0 transition-transform group-open:rotate-180" />
+          </summary>
+          <div className="ml-3 mt-0.5 flex flex-col gap-0.5 border-l border-gray-200 pl-3 dark:border-gray-800">
+            {item.items.map((sub, i) => (
+              <div key={i} onClick={onNavigate}>
+                {link(sub, sub.href === activeHref)}
+              </div>
+            ))}
+          </div>
+        </details>
+      );
+    }
+    return (
+      <div key={key} onClick={onNavigate}>
+        {link(item, item.href === activeHref)}
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex min-h-screen bg-gray-50 dark:bg-gray-950">
+      {/* Desktop sidebar -- unchanged fixed layout, hidden below md */}
+      <aside className="hidden md:flex md:w-56 md:shrink-0 md:flex-col md:border-r md:border-gray-200 md:bg-white md:dark:border-gray-800 md:dark:bg-gray-900">
+        <div className="px-4 py-4 text-lg font-semibold text-gray-900 dark:text-gray-100">{brand}</div>
+        <nav className="flex flex-col gap-1 overflow-y-auto px-3 pb-3">
+          {nav.map((item, i) => renderItem(item, i))}
+        </nav>
+        {footer && <div className="mt-auto border-t border-gray-200 p-3 dark:border-gray-800">{footer}</div>}
+      </aside>
+
+      <div className="flex min-w-0 flex-1 flex-col">
+        {/* Mobile topbar -- hidden at md and above */}
+        <header className="flex items-center justify-between border-b border-gray-200 bg-white px-4 py-3 dark:border-gray-800 dark:bg-gray-900 md:hidden">
+          <div className="text-lg font-semibold text-gray-900 dark:text-gray-100">{brand}</div>
+          <button
+            type="button"
+            onClick={() => setMobileOpen(true)}
+            aria-label="Open menu"
+            className="rounded-lg p-2 text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-800"
+          >
+            <MenuIcon />
+          </button>
+        </header>
+
+        <main className="flex-1 overflow-auto">{children}</main>
+      </div>
+
+      {/* Mobile drawer -- only exists in the DOM while open, portaled to
+          document.body so it's never clipped by an ancestor's overflow.
+          `right: 0` with a fixed pixel width (never a vw-based offset) is
+          what keeps this from ending up off-screen -- see the file header. */}
+      {mounted &&
+        mobileOpen &&
+        createPortal(
+          <div className="fixed inset-0 z-50 md:hidden">
+            <div className="absolute inset-0 bg-black/40" onClick={() => setMobileOpen(false)} />
+            <div className="absolute inset-y-0 right-0 flex w-72 max-w-[85vw] flex-col overflow-y-auto bg-white shadow-xl dark:bg-gray-900">
+              <div className="flex items-center justify-between px-4 py-4">
+                <div className="text-lg font-semibold text-gray-900 dark:text-gray-100">{brand}</div>
+                <button
+                  type="button"
+                  onClick={() => setMobileOpen(false)}
+                  aria-label="Close menu"
+                  className="rounded-lg p-2 text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-800"
+                >
+                  <CloseIcon />
+                </button>
+              </div>
+              <nav className="flex flex-col gap-1 px-3 pb-3">
+                {nav.map((item, i) => renderItem(item, i, () => setMobileOpen(false)))}
+              </nav>
+              {footer && <div className="mt-auto border-t border-gray-200 p-3 dark:border-gray-800">{footer}</div>}
+            </div>
+          </div>,
+          document.body,
+        )}
+    </div>
+  );
+}