@viibestack/ui 0.1.0 → 0.6.0

package/README.md

@@ -1,18 +1,40 @@
 # @viibestack/ui
 
-Dependency-free React components -- currently a Feather/Lucide-style outline icon set (~28 icons), ported from `services/portal/frontend/src/Icons.tsx`. No runtime dependencies beyond `react` itself, so it's safe to use anywhere React runs, including apps deployed on the OpenNext Cloudflare Workers adapter (no Node-native code, nothing that needs `fs`/`stream`/native bindings).
+Dependency-free React UI kit -- a Feather/Lucide-style outline icon set (~28 icons, ported from `services/portal/frontend/src/Icons.tsx`) plus core components (Button, Card, Input, Textarea, Select, Badge, Modal, EmptyState, Spinner, Alert, Checkbox, Switch, Avatar, Tabs, and Table primitives). No runtime dependencies beyond `react`/`react-dom`, so it's safe to use anywhere React runs, including apps deployed on the OpenNext Cloudflare Workers adapter (no Node-native code, nothing that needs `fs`/`stream`/native bindings). Styled with plain Tailwind utility classes -- the consuming app needs Tailwind already set up (every app this is meant for already has it, see `scratch-scaffold.ts`).
 
 ## Usage
 
 ```tsx
-import { CheckIcon, TrashIcon, SettingsIcon } from "@viibestack/ui";
+import { CheckIcon, TrashIcon, Button, Card, Input, Modal } from "@viibestack/ui";
 
 <CheckIcon size={16} color="green" />
 <TrashIcon className="text-red-500" />
+
+<Button variant="primary" size="md" onClick={...}>Save</Button>
+<Card title="Recent activity">...</Card>
+<Input label="Email" type="email" error={errors.email} />
 ```
 
 Every icon takes the same optional props: `size` (number, default 20), `color` (default `"currentColor"`, so it follows the surrounding text color / a Tailwind `text-*` class unless overridden), and `className`.
 
+## Components
+
+- **Button** -- `variant`: `primary | secondary | outline | ghost | danger`, `size`: `sm | md | lg`, plus every native `<button>` prop.
+- **Card** -- optional `title`, wraps children in a bordered/padded container.
+- **Input** / **Textarea** / **Select** -- optional `label` and `error`, plus every native form prop. `Select` takes `options: {value, label}[]` and an optional `placeholder`.
+- **Badge** -- `variant`: `neutral | success | warning | danger | info`.
+- **Modal** -- `open`, `onClose`, optional `title`; portals to `document.body`, closes on Escape or backdrop click.
+- **EmptyState** -- `title`, optional `icon`/`description`/`action` -- the "nothing here yet" placeholder.
+- **Spinner** -- `size` (number, default 20).
+- **Alert** -- `variant`: `info | success | warning | danger`, optional `title` and `onDismiss`.
+- **Checkbox** -- optional `label`, plus every native checkbox `<input>` prop.
+- **Switch** -- controlled toggle: `checked`, `onChange(checked)`, optional `label`/`disabled`.
+- **Avatar** -- `src` (image) or `name` (renders initials as a fallback), `size` (number, default 32).
+- **Tabs** -- `items: {key, label, content}[]`; uncontrolled by default (`defaultKey`) or controlled via `activeKey`/`onChange`.
+- **Table** / **Thead** / **Tbody** / **Tr** / **Th** / **Td** -- thin styled wrappers around native table elements, wrapped in a horizontal-scroll container. For sorting/filtering/pagination, use the `data-table` package bundle (`@tanstack/react-table`) instead -- these are for simple static display only.
+
+`Button`/`Card`/etc. pick up each app's brand color automatically via the `bg-primary`/`text-primary` Tailwind utilities already wired to the `--primary` CSS variable every generated app's `globals.css` defines (see `template-patches.ts`'s `themedGlobalsCss`) -- no extra setup needed. Dark-mode styling uses Tailwind's default `dark:` variant (`prefers-color-scheme`).
+
 ## Consuming this from an app built outside this monorepo
 
 This package ships raw, untranspiled `.tsx` source (same convention as `@sideblend/shared-types`) -- no build step to keep it trivial to iterate on. Next.js does **not** transpile `node_modules` by default, so any app that installs this from npm needs one line in its `next.config.ts`:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@viibestack/ui",
-  "version": "0.1.0",
-  "description": "Dependency-free React icon set -- Feather/Lucide-style outline glyphs, no runtime dependency on any icon library.",
+  "version": "0.6.0",
+  "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",
@@ -9,15 +9,21 @@
     "src"
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "devDependencies": {
     "@types/react": "^19",
+    "@types/react-dom": "^19",
     "react": "^19",
+    "react-dom": "^19",
     "typescript": "^5"
   },
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4"
+  }
 }

package/src/auth.ts

@@ -0,0 +1,304 @@
+// 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;
+}
+
+// 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).
+export async function createMonetizationCheckout(interval: "monthly" | "annual"): 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 }),
+    });
+    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;
+  }
+}

package/src/components.tsx

@@ -0,0 +1,460 @@
+"use client";
+
+// Core UI building blocks -- Button, Card, Input, Textarea, Select, Badge,
+// Modal, EmptyState, Spinner, Alert, Checkbox, Switch, Avatar, Tabs, and
+// Table primitives. Styled with plain Tailwind utility classes
+// (the consuming app already has Tailwind v4, see scratch-scaffold.ts) --
+// no runtime dependency beyond react/react-dom. Brand color (bg-primary/
+// text-primary/border-primary) comes from the --primary CSS custom
+// property every generated app's globals.css already defines (see
+// template-patches.ts's themedGlobalsCss) via Tailwind's @theme inline
+// block -- these components pick that up automatically, no extra wiring.
+// dark: variants use Tailwind's default prefers-color-scheme strategy.
+
+import { createPortal } from "react-dom";
+import { useEffect, useRef, useState } from "react";
+import type { ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes, TableHTMLAttributes, ThHTMLAttributes, TdHTMLAttributes } from "react";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+// ── Button ──────────────────────────────────────────────────────────────────
+
+export type ButtonVariant = "primary" | "secondary" | "outline" | "ghost" | "danger";
+export type ButtonSize = "sm" | "md" | "lg";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+const BUTTON_VARIANTS: Record<ButtonVariant, string> = {
+  primary: "bg-primary text-white hover:brightness-90 disabled:opacity-50",
+  secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-100 dark:hover:bg-gray-700 disabled:opacity-50",
+  outline: "border border-gray-300 text-gray-900 hover:bg-gray-50 dark:border-gray-700 dark:text-gray-100 dark:hover:bg-gray-900 disabled:opacity-50",
+  ghost: "text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-800 disabled:opacity-50",
+  danger: "bg-red-600 text-white hover:bg-red-700 disabled:opacity-50",
+};
+
+const BUTTON_SIZES: Record<ButtonSize, string> = {
+  sm: "text-sm px-3 py-1.5 rounded-md",
+  md: "text-sm px-4 py-2 rounded-lg",
+  lg: "text-base px-5 py-2.5 rounded-lg",
+};
+
+export function Button({ variant = "primary", size = "md", className, ...rest }: ButtonProps) {
+  return (
+    <button
+      className={cx(
+        "inline-flex items-center justify-center gap-2 font-medium transition-colors disabled:cursor-not-allowed",
+        BUTTON_VARIANTS[variant],
+        BUTTON_SIZES[size],
+        className,
+      )}
+      {...rest}
+    />
+  );
+}
+
+// ── Card ────────────────────────────────────────────────────────────────────
+
+export interface CardProps {
+  title?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function Card({ title, children, className }: CardProps) {
+  return (
+    <div className={cx("rounded-xl border border-gray-200 bg-white p-5 dark:border-gray-800 dark:bg-gray-900", className)}>
+      {title && <div className="mb-3 text-base font-semibold text-gray-900 dark:text-gray-100">{title}</div>}
+      {children}
+    </div>
+  );
+}
+
+// ── Field label wrapper (shared by Input/Textarea/Select) ──────────────────
+
+function FieldWrapper({ label, error, children }: { label?: ReactNode; error?: ReactNode; children: ReactNode }) {
+  if (!label && !error) return <>{children}</>;
+  return (
+    <label className="flex flex-col gap-1.5">
+      {label && <span className="text-sm font-medium text-gray-700 dark:text-gray-300">{label}</span>}
+      {children}
+      {error && <span className="text-sm text-red-600 dark:text-red-400">{error}</span>}
+    </label>
+  );
+}
+
+const FIELD_CLASS =
+  "w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 outline-none " +
+  "focus:border-primary focus:ring-1 focus:ring-primary dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100 " +
+  "disabled:cursor-not-allowed disabled:opacity-50";
+
+// ── Input ───────────────────────────────────────────────────────────────────
+
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  label?: ReactNode;
+  error?: ReactNode;
+}
+
+export function Input({ label, error, className, ...rest }: InputProps) {
+  return (
+    <FieldWrapper label={label} error={error}>
+      <input className={cx(FIELD_CLASS, Boolean(error) && "border-red-400 focus:border-red-500 focus:ring-red-500", className)} {...rest} />
+    </FieldWrapper>
+  );
+}
+
+// ── Textarea ────────────────────────────────────────────────────────────────
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: ReactNode;
+  error?: ReactNode;
+}
+
+export function Textarea({ label, error, className, ...rest }: TextareaProps) {
+  return (
+    <FieldWrapper label={label} error={error}>
+      <textarea className={cx(FIELD_CLASS, "resize-y", Boolean(error) && "border-red-400 focus:border-red-500 focus:ring-red-500", className)} {...rest} />
+    </FieldWrapper>
+  );
+}
+
+// ── Select ──────────────────────────────────────────────────────────────────
+
+export interface SelectOption { value: string; label: string }
+
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "children"> {
+  label?: ReactNode;
+  error?: ReactNode;
+  options: SelectOption[];
+  placeholder?: string;
+}
+
+export function Select({ label, error, options, placeholder, className, ...rest }: SelectProps) {
+  return (
+    <FieldWrapper label={label} error={error}>
+      <select className={cx(FIELD_CLASS, Boolean(error) && "border-red-400 focus:border-red-500 focus:ring-red-500", className)} {...rest}>
+        {placeholder && <option value="">{placeholder}</option>}
+        {options.map((o) => (
+          <option key={o.value} value={o.value}>{o.label}</option>
+        ))}
+      </select>
+    </FieldWrapper>
+  );
+}
+
+// ── Badge ───────────────────────────────────────────────────────────────────
+
+export type BadgeVariant = "neutral" | "success" | "warning" | "danger" | "info";
+
+const BADGE_VARIANTS: Record<BadgeVariant, string> = {
+  neutral: "bg-gray-100 text-gray-700 dark:bg-gray-800 dark:text-gray-300",
+  success: "bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-400",
+  warning: "bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-400",
+  danger: "bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-400",
+  info: "bg-blue-100 text-blue-700 dark:bg-blue-900/40 dark:text-blue-400",
+};
+
+export interface BadgeProps {
+  variant?: BadgeVariant;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function Badge({ variant = "neutral", children, className }: BadgeProps) {
+  return (
+    <span className={cx("inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium", BADGE_VARIANTS[variant], className)}>
+      {children}
+    </span>
+  );
+}
+
+// ── Spinner ─────────────────────────────────────────────────────────────────
+
+export interface SpinnerProps {
+  size?: number;
+  className?: string;
+}
+
+export function Spinner({ size = 20, className }: SpinnerProps) {
+  return (
+    <svg
+      className={cx("animate-spin text-current", className)}
+      style={{ width: size, height: size }}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-label="Loading"
+    >
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v4a4 4 0 00-4 4H4z" />
+    </svg>
+  );
+}
+
+// ── EmptyState ──────────────────────────────────────────────────────────────
+
+export interface EmptyStateProps {
+  icon?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  action?: ReactNode;
+  className?: string;
+}
+
+export function EmptyState({ icon, title, description, action, className }: EmptyStateProps) {
+  return (
+    <div className={cx("flex flex-col items-center justify-center gap-2 rounded-xl border border-dashed border-gray-300 p-10 text-center dark:border-gray-700", className)}>
+      {icon && <div className="text-gray-400 dark:text-gray-600">{icon}</div>}
+      <div className="text-sm font-medium text-gray-900 dark:text-gray-100">{title}</div>
+      {description && <div className="text-sm text-gray-500 dark:text-gray-400">{description}</div>}
+      {action && <div className="mt-2">{action}</div>}
+    </div>
+  );
+}
+
+// ── Modal ───────────────────────────────────────────────────────────────────
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  title?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}
+
+// Portal to document.body so the modal escapes any parent's overflow/
+// stacking context -- mounted-check guards the createPortal call during
+// Next.js's SSR pass, where `document` doesn't exist yet.
+export function Modal({ open, onClose, title, children, className }: ModalProps) {
+  const [mounted, setMounted] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => setMounted(true), []);
+
+  useEffect(() => {
+    if (!open) return;
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") onClose();
+    }
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  if (!mounted || !open) return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4" onClick={(e) => { if (e.target === e.currentTarget) onClose(); }}>
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        className={cx("w-full max-w-md rounded-xl bg-white p-6 shadow-xl dark:bg-gray-900", className)}
+      >
+        {title && <div className="mb-4 text-lg font-semibold text-gray-900 dark:text-gray-100">{title}</div>}
+        {children}
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
+// ── Alert ───────────────────────────────────────────────────────────────────
+
+export type AlertVariant = "info" | "success" | "warning" | "danger";
+
+const ALERT_VARIANTS: Record<AlertVariant, string> = {
+  info: "bg-blue-50 text-blue-800 border-blue-200 dark:bg-blue-900/20 dark:text-blue-300 dark:border-blue-900",
+  success: "bg-green-50 text-green-800 border-green-200 dark:bg-green-900/20 dark:text-green-300 dark:border-green-900",
+  warning: "bg-amber-50 text-amber-800 border-amber-200 dark:bg-amber-900/20 dark:text-amber-300 dark:border-amber-900",
+  danger: "bg-red-50 text-red-800 border-red-200 dark:bg-red-900/20 dark:text-red-300 dark:border-red-900",
+};
+
+export interface AlertProps {
+  variant?: AlertVariant;
+  title?: ReactNode;
+  children?: ReactNode;
+  onDismiss?: () => void;
+  className?: string;
+}
+
+export function Alert({ variant = "info", title, children, onDismiss, className }: AlertProps) {
+  return (
+    <div className={cx("flex items-start justify-between gap-3 rounded-lg border p-3.5 text-sm", ALERT_VARIANTS[variant], className)}>
+      <div>
+        {title && <div className="font-medium">{title}</div>}
+        {children && <div className={title ? "mt-0.5" : undefined}>{children}</div>}
+      </div>
+      {onDismiss && (
+        <button type="button" onClick={onDismiss} aria-label="Dismiss" className="shrink-0 opacity-60 hover:opacity-100">
+          ✕
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ── Checkbox ────────────────────────────────────────────────────────────────
+
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+  label?: ReactNode;
+}
+
+export function Checkbox({ label, className, ...rest }: CheckboxProps) {
+  return (
+    <label className="inline-flex items-center gap-2 text-sm text-gray-900 dark:text-gray-100">
+      <input type="checkbox" className={cx("h-4 w-4 rounded border-gray-300 accent-primary dark:border-gray-700", className)} {...rest} />
+      {label}
+    </label>
+  );
+}
+
+// ── Switch ──────────────────────────────────────────────────────────────────
+
+export interface SwitchProps {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label?: ReactNode;
+  disabled?: boolean;
+  className?: string;
+}
+
+export function Switch({ checked, onChange, label, disabled, className }: SwitchProps) {
+  return (
+    <label className={cx("inline-flex items-center gap-2 text-sm text-gray-900 dark:text-gray-100", disabled && "opacity-50")}>
+      <button
+        type="button"
+        role="switch"
+        aria-checked={checked}
+        disabled={disabled}
+        onClick={() => onChange(!checked)}
+        className={cx(
+          "relative h-5 w-9 shrink-0 rounded-full transition-colors disabled:cursor-not-allowed",
+          checked ? "bg-primary" : "bg-gray-300 dark:bg-gray-700",
+          className,
+        )}
+      >
+        <span className={cx("absolute left-0.5 top-0.5 h-4 w-4 rounded-full bg-white transition-transform", checked && "translate-x-4")} />
+      </button>
+      {label}
+    </label>
+  );
+}
+
+// ── Avatar ──────────────────────────────────────────────────────────────────
+
+export interface AvatarProps {
+  src?: string;
+  name?: string;
+  size?: number;
+  className?: string;
+}
+
+function initialsFor(name: string): string {
+  const parts = name.trim().split(/\s+/);
+  return ((parts[0]?.[0] ?? "") + (parts.length > 1 ? parts[parts.length - 1][0] : "")).toUpperCase();
+}
+
+export function Avatar({ src, name, size = 32, className }: AvatarProps) {
+  const style = { width: size, height: size, fontSize: size * 0.4 };
+  if (src) {
+    // eslint-disable-next-line @next/next/no-img-element -- a generic package can't depend on next/image
+    return <img src={src} alt={name ?? ""} style={style} className={cx("rounded-full object-cover", className)} />;
+  }
+  return (
+    <div
+      style={style}
+      className={cx("flex items-center justify-center rounded-full bg-primary font-medium text-white", className)}
+      aria-label={name}
+    >
+      {name ? initialsFor(name) : ""}
+    </div>
+  );
+}
+
+// ── Tabs ────────────────────────────────────────────────────────────────────
+
+export interface TabItem {
+  key: string;
+  label: ReactNode;
+  content: ReactNode;
+}
+
+export interface TabsProps {
+  items: TabItem[];
+  defaultKey?: string;
+  activeKey?: string;
+  onChange?: (key: string) => void;
+  className?: string;
+}
+
+// Uncontrolled by default (defaultKey / internal state) -- pass activeKey +
+// onChange together to control it externally instead.
+export function Tabs({ items, defaultKey, activeKey, onChange, className }: TabsProps) {
+  const [internalKey, setInternalKey] = useState(defaultKey ?? items[0]?.key);
+  const key = activeKey ?? internalKey;
+  const active = items.find((i) => i.key === key) ?? items[0];
+
+  function select(k: string) {
+    if (activeKey === undefined) setInternalKey(k);
+    onChange?.(k);
+  }
+
+  return (
+    <div className={className}>
+      <div className="flex gap-1 border-b border-gray-200 dark:border-gray-800">
+        {items.map((item) => (
+          <button
+            key={item.key}
+            type="button"
+            onClick={() => select(item.key)}
+            className={cx(
+              "border-b-2 px-3 py-2 text-sm font-medium transition-colors",
+              item.key === key
+                ? "border-primary text-primary"
+                : "border-transparent text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100",
+            )}
+          >
+            {item.label}
+          </button>
+        ))}
+      </div>
+      <div className="pt-4">{active?.content}</div>
+    </div>
+  );
+}
+
+// ── Table primitives ─────────────────────────────────────────────────────────
+// Thin styled wrappers around native table elements -- for simple, fully
+// client-rendered data. For sorting/filtering/pagination, request the
+// "data-table" package bundle (@tanstack/react-table) instead.
+
+export function Table({ className, ...rest }: TableHTMLAttributes<HTMLTableElement>) {
+  return (
+    <div className="overflow-x-auto rounded-lg border border-gray-200 dark:border-gray-800">
+      <table className={cx("w-full text-left text-sm", className)} {...rest} />
+    </div>
+  );
+}
+
+export function Thead(props: HTMLAttributes<HTMLTableSectionElement>) {
+  return <thead className="bg-gray-50 dark:bg-gray-900" {...props} />;
+}
+
+export function Tbody(props: HTMLAttributes<HTMLTableSectionElement>) {
+  return <tbody className="divide-y divide-gray-200 dark:divide-gray-800" {...props} />;
+}
+
+export function Tr(props: HTMLAttributes<HTMLTableRowElement>) {
+  return <tr {...props} />;
+}
+
+export function Th({ className, ...rest }: ThHTMLAttributes<HTMLTableCellElement>) {
+  return <th className={cx("px-4 py-2.5 font-medium text-gray-500 dark:text-gray-400", className)} {...rest} />;
+}
+
+export function Td({ className, ...rest }: TdHTMLAttributes<HTMLTableCellElement>) {
+  return <td className={cx("px-4 py-2.5 text-gray-900 dark:text-gray-100", className)} {...rest} />;
+}

package/src/data.ts

@@ -0,0 +1,88 @@
+// 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 async function listRows<T extends { id: string }>(table: string): Promise<T[]> {
+  const appId = await resolveAppId();
+  if (!appId) return [];
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/data-public/${table}`, { headers: authHeaders() });
+    if (!res.ok) return [];
+    const data = (await res.json()) as { rows: T[] };
+    return data.rows ?? [];
+  } catch {
+    return [];
+  }
+}
+
+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 +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>
+  );
+}