@vvedantb/ui 0.1.5 → 0.2.1

package/README.md

@@ -0,0 +1,49 @@
+# @vvedantb/ui
+
+Shared React 19 web UI. Source-exported: no build step.
+
+| Import | What it is |
+| --- | --- |
+| `@vvedantb/ui` | Primitives (Radix-based) and AI elements. |
+| `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
+| `@vvedantb/ui/shell` | Router-free `SidebarHeader` and `PillTabs`. |
+| `@vvedantb/ui/app` | Alt-click confirm skip, update watcher, settings chrome, `useStableAuth`. See `app/README.md` in the repository. |
+| `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. |
+| `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. |
+| `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | Same file as `tokens/css/compat-shadcn-rgb.css`. |
+| `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset for apps that load a JS config with `@config`. |
+| `@vvedantb/ui/tokens/native` | JS colours, radii and spacing. No CSS, no React DOM. |
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@source "../node_modules/@vvedantb/ui/src/**/*.{ts,tsx}";
+```
+
+## Colour names in components
+
+Components use `text-muted-foreground`, `primary` and `--color-*` theme variables. They no longer use `text-muted`, `*-accent` or raw `var(--muted)` reads, which clash with shadcn names. `tokens.css` still defines `--color-muted` and `--color-accent`. `pnpm --filter @vvedantb/ui check:tokens` fails if a component brings the old names back (it also runs in `build`, `test` and `verify`).
+
+## Using an existing shadcn RGB theme
+
+Use this when the app defines shadcn-style variables as space-separated channels (`--background: 244 245 246`) and reads them as `rgb(var(--background) / 0.5)`.
+
+1. Import `compat-shadcn-rgb.css` **instead of** `tokens.css`. Never import both.
+2. The app keeps `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--input`, `--ring` (each with its `-foreground` where shadcn has one) and `--radius`. The compat file does not define them. It only references them, so the app can change `--primary`, `--ring`, `--radius` or `--font-sans` at runtime.
+3. Add the `@source` line for the package sources.
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens/css/compat-shadcn-rgb.css";
+@source "../node_modules/@vvedantb/ui/src/**/*.{ts,tsx}";
+```
+
+Shared CSS that is safe without `tokens.css`: `compat-shadcn-rgb.css`, `dialog.css`, `utilities.css`, `scrollbar-thin.css` (reads `--scrollbar`, which the compat file defines), `modal.css` and `tabs.css` (both need the app motion variables listed in `tokens/README.md`), and `animations.css` (not with the Tailwind preset). `base.css` and `tabs-pills.css` read raw `--accent`, `--foreground`, `--muted`, `--segment` and `--default`; skip them unless the app defines those as full colour values.
+
+The compat file includes a fallback `glass-panel-strong` (`rgb(var(--card) / 0.95)` with a 12px blur) for toasts and dialogs. Declare your own `@utility glass-panel-strong` after the import to override it.
+
+A fixture that renders the main components against sample light and dark RGB variables is in `tokens/examples/compat-shadcn-rgb/`.
+
+`@clerk/clerk-react`, `@tanstack/react-hotkeys` and `zod` are optional peers. Install them only if you import `@vvedantb/ui/app`.
+
+Full documentation: the repository `README.md`. Upgrading from `@vvedantb/tokens`, `@vvedantb/shell` or `@vvedantb/app-kit`: `MIGRATION.md`.

package/app/README.md

@@ -0,0 +1,100 @@
+# `@vvedantb/ui/app`
+
+Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
+
+## Install
+
+```sh
+npm install @vvedantb/ui
+```
+
+## Peers
+
+Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, needed only for this subpath: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
+
+`sonner` is not a dependency. The update watcher takes the toast API as an option. This subpath uses a local class join (`cn`), not the `cn` from `@vvedantb/ui`. Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
+
+```css
+@source "../node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}";
+```
+
+## Confirm skip (Alt-click)
+
+```tsx
+import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui/app";
+
+const { request } = useRequestConfirm();
+
+<DropdownMenuItem
+  title={skipConfirmTitle("Delete")}
+  onSelect={(event) => request(() => setOpen(true), () => remove(), event)}
+>
+  Delete <ConfirmSkipHint />
+</DropdownMenuItem>
+```
+
+- `useRequestConfirm` does not subscribe to Alt. It reads `getAltHeld()` when the request happens, so the menu owner does not re-render when Alt goes down. It returns `{ request }` only.
+- `ConfirmSkipHint` stays mounted and gains a `hidden` class when Alt is not held, so an open Radix menu keeps a stable child tree.
+- The Alt store resets when the last subscriber leaves, clears on blur and tab hide, and cancels a bare Alt keydown only inside `[role='menu']` or `[data-radix-menu-content]`.
+- Also exported: `useAltHeld`, `getAltHeld`, `createAltHeldStore`, `bindToWindow`, `shouldSkipConfirm`, `requestConfirm`.
+
+## Update available watcher
+
+```ts
+import { toast } from "sonner";
+import { startUpdateAvailableWatcher } from "@vvedantb/ui/app";
+
+useEffect(
+  () =>
+    startUpdateAvailableWatcher({
+      origin: window.location.origin,
+      toast,
+      closeConvex: () => void convex.close(),
+      enabled: !import.meta.env.DEV,
+    }),
+  [],
+);
+```
+
+Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?` (default `app-update-available`), `enabled?` (default true), `reload?` (default `window.location.reload`). On a changed asset fingerprint it shows a sticky "Update available" toast. Refresh calls `closeConvex` (errors ignored), then reloads. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
+
+## Settings chrome
+
+```tsx
+import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui/app";
+
+<SettingsPage
+  title="Notifications"
+  layout={({ title, headerRight, toolbar, tabs, fillHeight, children }) => (
+    <PageContainer title={title} rightSection={headerRight} toolbar={toolbar} tabs={tabs} noScroll={fillHeight}>
+      {children}
+    </PageContainer>
+  )}
+>
+  <SettingsSection title="Email" bodyVariant="list">
+    <SettingsToggleRow title="Weekly digest" action={<Switch />} />
+  </SettingsSection>
+</SettingsPage>
+```
+
+Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow`, `SettingsEmptyState` (icon is `ComponentType<{ size?: number; className?: string }>`), `SettingsPage`. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
+
+## useStableAuth
+
+```ts
+import { useStableAuth } from "@vvedantb/ui/app"; // 2000 ms debounce, wraps Clerk useAuth
+import { createUseStableAuth } from "@vvedantb/ui/app";
+
+const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
+```
+
+After a signed-in session, a drop to signed-out reports `isLoaded: false` for the debounce window so Convex does not cascade. State is module-level. `resetStableAuthSession()` clears it and is for tests only.
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui typecheck
+pnpm --filter @vvedantb/ui test
+```
+
+Source is in `app/src` and tests in `app/tests`. Publish steps are in the root `README.md`.

package/app/src/auth/useStableAuth.ts

@@ -0,0 +1,69 @@
+import { useAuth } from "@clerk/clerk-react";
+import { useEffect, useState } from "react";
+
+/** The two Clerk `useAuth` fields the hook reads. */
+export type ClerkAuthSlice = {
+  isLoaded: boolean;
+  isSignedIn: boolean | undefined;
+};
+
+export type StableAuthOptions = {
+  /** How long a sign-in loss reads as "still loading". Default 2000 ms. */
+  debounceMs?: number;
+};
+
+// Tracks sign-in during this session to detect stale deploy auth loss.
+let wasEverSignedIn = false;
+
+/**
+ * Test-only. Clears the module-level "was ever signed in" flag so one test
+ * cannot leak state into the next. Do not call from app code.
+ */
+export function resetStableAuthSession(): void {
+  wasEverSignedIn = false;
+}
+
+/**
+ * Build a `useAuth` wrapper that debounces a brief signed-in to signed-out
+ * flicker (for example after a deploy) by reporting `isLoaded: false` for
+ * `debounceMs`, so Convex does not cascade on a transient auth loss.
+ */
+export function createUseStableAuth<T extends ClerkAuthSlice>(
+  useAuthHook: () => T,
+  options: StableAuthOptions = {},
+): () => T {
+  const debounceMs = options.debounceMs ?? 2000;
+
+  return function useStableAuth(): T {
+    const auth = useAuthHook();
+    const [overrideLoading, setOverrideLoading] = useState(false);
+
+    useEffect(() => {
+      if (auth.isSignedIn) {
+        wasEverSignedIn = true;
+        setOverrideLoading(false);
+        return;
+      }
+
+      if (wasEverSignedIn && auth.isLoaded && !auth.isSignedIn) {
+        setOverrideLoading(true);
+        const timer = setTimeout(() => {
+          wasEverSignedIn = false;
+          setOverrideLoading(false);
+        }, debounceMs);
+        return () => clearTimeout(timer);
+      }
+
+      setOverrideLoading(false);
+    }, [auth.isLoaded, auth.isSignedIn]);
+
+    if (overrideLoading) {
+      return { ...auth, isLoaded: false };
+    }
+    return auth;
+  };
+}
+
+/** `useAuth` from `@clerk/clerk-react` with the 2000 ms debounce. */
+export const useStableAuth: () => ReturnType<typeof useAuth> =
+  createUseStableAuth(useAuth);

package/app/src/cn.ts

@@ -0,0 +1,6 @@
+type ClassPart = string | false | null | undefined;
+
+/** Minimal class join. Drops falsy parts; does not merge conflicting Tailwind classes. */
+export function cn(...parts: ClassPart[]): string {
+  return parts.filter(Boolean).join(" ");
+}

package/app/src/confirm/ConfirmSkipHint.tsx

@@ -0,0 +1,35 @@
+import { formatForDisplay, type Hotkey } from "@tanstack/react-hotkeys";
+import { cn } from "../cn.js";
+import { z } from "zod";
+import { useAltHeld } from "./useAltHeld.js";
+
+// `Hotkey` covers combinations, not a bare modifier, so the literal is parsed
+// in rather than asserted. `formatForDisplay` renders it as ⌥ / Alt.
+const ALT_HOTKEY = z.custom<Hotkey>().parse("Alt");
+
+/** Platform-native "⌥-click skips confirmation" / "Alt-click skips confirmation". */
+export function skipConfirmTitle(actionTitle?: string): string {
+  const skip = `${formatForDisplay(ALT_HOTKEY)}-click skips confirmation`;
+  return actionTitle ? `${actionTitle} · ${skip}` : skip;
+}
+
+/**
+ * Visible only while Alt is held. Stays mounted (hidden) otherwise so an open
+ * Radix menu item keeps a stable child tree. Sits after the action label so every
+ * confirmable control shows that this click will skip the dialog.
+ */
+export function ConfirmSkipHint({ className }: { className?: string }) {
+  const altHeld = useAltHeld();
+  return (
+    <kbd
+      className={cn(
+        "ml-auto shrink-0 rounded bg-surface-secondary px-1 py-0.5 font-mono text-[10px] text-muted-foreground",
+        !altHeld && "hidden",
+        className,
+      )}
+      aria-hidden
+    >
+      {formatForDisplay(ALT_HOTKEY)}
+    </kbd>
+  );
+}

package/app/src/confirm/confirmSkip.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether this activation should skip the confirmation dialog.
+ *
+ * `event.altKey` covers the click itself. `altHeld` covers Radix `onSelect`
+ * (and keyboard activation) which do not carry the modifier.
+ */
+export function shouldSkipConfirm(
+  altHeld: boolean,
+  event?: { altKey?: boolean } | null,
+): boolean {
+  return altHeld || event?.altKey === true;
+}
+
+/** Open the dialog, or run the action immediately when Alt is held. */
+export function requestConfirm(
+  altHeld: boolean,
+  open: () => void,
+  confirm: () => void,
+  event?: { altKey?: boolean } | null,
+): void {
+  if (shouldSkipConfirm(altHeld, event)) {
+    confirm();
+    return;
+  }
+  open();
+}

package/app/src/confirm/useAltHeld.ts

@@ -0,0 +1,128 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Whether Alt (Option on macOS) is held right now.
+ *
+ * Subscribes to the window so every confirmable control can restyle when the
+ * modifier goes down, and so Alt+click still works when the activating event
+ * is a Radix `onSelect` that does not carry `altKey`.
+ *
+ * Cleared on blur / visibility hide so a missed keyup after alt-tab cannot
+ * leave the app stuck in skip-confirm mode.
+ */
+
+/** The only two fields the store reads off a keyboard event. */
+export type AltKeyEvent = { key: string; altKey: boolean };
+
+/** What the binding feeds the store. `clear` is any event that can swallow a keyup. */
+export type AltHeldSignals = {
+  keyDown: (event: AltKeyEvent) => void;
+  keyUp: (event: AltKeyEvent) => void;
+  clear: () => void;
+};
+
+/** Wires the signals to a real event source and returns the unbind. */
+export type AltHeldBinding = (signals: AltHeldSignals) => () => void;
+
+export type AltHeldStore = {
+  subscribe: (onStoreChange: () => void) => () => void;
+  getSnapshot: () => boolean;
+};
+
+/**
+ * The binding is injected so the state machine can be driven without a DOM.
+ * Listeners attach lazily and, crucially, the held flag resets when the last
+ * subscriber leaves: with nothing bound, a keyup can no longer be observed, so
+ * a flag left at `true` would survive into the next mount and silently skip the
+ * confirmation dialog on a plain click.
+ */
+export function createAltHeldStore(bind: AltHeldBinding): AltHeldStore {
+  let altHeld = false;
+  let unbind: (() => void) | null = null;
+  const listeners = new Set<() => void>();
+
+  function setHeld(next: boolean): void {
+    if (altHeld === next) return;
+    altHeld = next;
+    for (const listener of listeners) listener();
+  }
+
+  const signals: AltHeldSignals = {
+    keyDown: (event) => {
+      if (event.key === "Alt" || event.altKey) setHeld(true);
+    },
+    keyUp: (event) => {
+      // A keyup for some other key still reports altKey while Alt is down, so
+      // only a released Alt — or a keyup without the modifier — clears.
+      if (event.key === "Alt" || !event.altKey) setHeld(false);
+    },
+    clear: () => setHeld(false),
+  };
+
+  return {
+    subscribe: (onStoreChange) => {
+      if (unbind === null) unbind = bind(signals);
+      listeners.add(onStoreChange);
+      return () => {
+        listeners.delete(onStoreChange);
+        if (listeners.size > 0) return;
+        unbind?.();
+        unbind = null;
+        // Nothing is listening for the keyup any more; start the next mount
+        // from a known-unheld state rather than a stale `true`.
+        altHeld = false;
+      };
+    },
+    getSnapshot: () => altHeld,
+  };
+}
+
+function isInOpenMenu(target: EventTarget | null): boolean {
+  return (
+    target instanceof Element &&
+    target.closest("[role='menu'], [data-radix-menu-content]") !== null
+  );
+}
+
+/** Default binding: window key events plus blur and tab-hide clears. */
+export const bindToWindow: AltHeldBinding = (signals) => {
+  if (typeof window === "undefined") return () => {};
+  const onKeyDown = (event: KeyboardEvent): void => {
+    // A bare Alt press can steal focus to the browser menu bar and dismiss an
+    // open Radix menu. Cancel it only when it lands inside one.
+    if (event.key === "Alt" && isInOpenMenu(event.target)) {
+      event.preventDefault();
+    }
+    signals.keyDown(event);
+  };
+  const onKeyUp = (event: KeyboardEvent): void => signals.keyUp(event);
+  const onBlur = (): void => signals.clear();
+  const onVisibilityChange = (): void => {
+    if (document.hidden) signals.clear();
+  };
+  window.addEventListener("keydown", onKeyDown);
+  window.addEventListener("keyup", onKeyUp);
+  window.addEventListener("blur", onBlur);
+  document.addEventListener("visibilitychange", onVisibilityChange);
+  return () => {
+    window.removeEventListener("keydown", onKeyDown);
+    window.removeEventListener("keyup", onKeyUp);
+    window.removeEventListener("blur", onBlur);
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+  };
+};
+
+const altHeldStore = createAltHeldStore(bindToWindow);
+
+/** Current value without subscribing. Safe to read inside event handlers. */
+export function getAltHeld(): boolean {
+  return altHeldStore.getSnapshot();
+}
+
+export function useAltHeld(): boolean {
+  return useSyncExternalStore(
+    altHeldStore.subscribe,
+    altHeldStore.getSnapshot,
+    () => false,
+  );
+}

package/app/src/confirm/useRequestConfirm.ts

@@ -0,0 +1,25 @@
+import { requestConfirm } from "./confirmSkip.js";
+import { getAltHeld } from "./useAltHeld.js";
+
+type ConfirmEvent = { altKey?: boolean } | null;
+
+function request(
+  open: () => void,
+  confirm: () => void,
+  event?: ConfirmEvent,
+): void {
+  requestConfirm(getAltHeld(), open, confirm, event);
+}
+
+const api = { request } as const;
+
+/**
+ * Confirm helper for menu owners. It must not subscribe to Alt: a re-render of
+ * the owner when Alt goes down remounts the open Radix menu and closes it.
+ * `ConfirmSkipHint` is the only subscriber and lives inside the open menu.
+ * The Alt state is read when the request happens. The returned object is
+ * stable and holds no React state, so it is safe to call anywhere.
+ */
+export function useRequestConfirm() {
+  return api;
+}

package/app/src/index.ts

@@ -0,0 +1,43 @@
+export {
+  bindToWindow,
+  createAltHeldStore,
+  getAltHeld,
+  useAltHeld,
+  type AltHeldBinding,
+  type AltHeldSignals,
+  type AltHeldStore,
+  type AltKeyEvent,
+} from "./confirm/useAltHeld.js";
+export { requestConfirm, shouldSkipConfirm } from "./confirm/confirmSkip.js";
+export { useRequestConfirm } from "./confirm/useRequestConfirm.js";
+export { ConfirmSkipHint, skipConfirmTitle } from "./confirm/ConfirmSkipHint.js";
+
+export {
+  fetchDeployFingerprint,
+  fingerprintFromHtml,
+} from "./update/deployFingerprint.js";
+export {
+  startUpdateAvailableWatcher,
+  type UpdateAvailableWatcherOptions,
+  type UpdateToastOptions,
+} from "./update/updateWatcher.js";
+
+export { SettingsSection } from "./settings/SettingsSection.js";
+export { SettingsField } from "./settings/SettingsField.js";
+export { SettingsStack } from "./settings/SettingsStack.js";
+export { SettingsToggleRow } from "./settings/SettingsToggleRow.js";
+export { SettingsEmptyState } from "./settings/SettingsEmptyState.js";
+export {
+  DefaultSettingsLayout,
+  SettingsPage,
+  type SettingsLayoutProps,
+  type SettingsPageProps,
+} from "./settings/SettingsPage.js";
+
+export {
+  createUseStableAuth,
+  resetStableAuthSession,
+  useStableAuth,
+  type ClerkAuthSlice,
+  type StableAuthOptions,
+} from "./auth/useStableAuth.js";

package/app/src/settings/SettingsEmptyState.tsx

@@ -0,0 +1,38 @@
+import type { ComponentType, ReactNode } from "react";
+
+interface SettingsEmptyStateProps {
+  /** Tabler icon component, rendered muted above the copy. */
+  icon: ComponentType<{ size?: number; className?: string }>;
+  title: string;
+  /** One line on what to do about it. */
+  description?: string;
+  /** Primary call to action, e.g. the same button as the section header. */
+  action?: ReactNode;
+}
+
+/**
+ * The "nothing here yet" state for a settings section body.
+ *
+ * Sits inside a SettingsSection rather than floating on the canvas, so an empty
+ * list still reads as part of the card it belongs to.
+ * Shared across apps.
+ */
+export function SettingsEmptyState({
+  icon: Icon,
+  title,
+  description,
+  action,
+}: SettingsEmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center justify-center px-4 py-16 text-center">
+      <Icon size={28} className="mb-5 text-muted-foreground opacity-50" />
+      <h4 className="text-sm font-medium text-foreground">{title}</h4>
+      {description ? (
+        <p className="mt-2 max-w-sm text-xs leading-relaxed text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
+      {action ? <div className="mt-6">{action}</div> : null}
+    </div>
+  );
+}

package/app/src/settings/SettingsField.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+
+interface SettingsFieldProps {
+  /** Field name, shown above the control. */
+  label: ReactNode;
+  /** Help text shown under the control. */
+  description?: ReactNode;
+  /** `id` of the control, so clicking the label focuses it. */
+  htmlFor?: string;
+  children: ReactNode;
+}
+
+/**
+ * One labelled control inside a SettingsSection body.
+ *
+ * Every settings form repeats the same label / control / help-text stack, so it
+ * lives here rather than being re-spaced per field. Stack several inside a
+ * section body with `grid gap-5`. Shared across apps.
+ */
+export function SettingsField({
+  label,
+  description,
+  htmlFor,
+  children,
+}: SettingsFieldProps) {
+  return (
+    <div>
+      <label
+        htmlFor={htmlFor}
+        className="mb-2 block text-sm font-medium text-foreground"
+      >
+        {label}
+      </label>
+      {children}
+      {description ? (
+        <p className="mt-1.5 text-pretty text-xs leading-relaxed text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/app/src/settings/SettingsPage.tsx

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react";
+import { cn } from "../cn.js";
+import { SettingsStack } from "./SettingsStack.js";
+
+export type SettingsLayoutProps = {
+  title: string;
+  headerRight?: ReactNode;
+  toolbar?: ReactNode;
+  tabs?: ReactNode;
+  fillHeight?: boolean;
+  children: ReactNode;
+};
+
+export interface SettingsPageProps {
+  title: string;
+  /** Sparse primary action(s) in the title row (e.g. Add, Delete). */
+  headerRight?: ReactNode;
+  /** Filters / search / segmented controls. Sits under the title. */
+  toolbar?: ReactNode;
+  /** Route tabs. Sit under the title (and under toolbar if both exist). */
+  tabs?: ReactNode;
+  /**
+   * Wrap children in the standard settings section stack. Set false when the
+   * child already owns its own vertical rhythm.
+   */
+  stack?: boolean;
+  /** Fill the remaining shell height instead of scrolling the page. */
+  fillHeight?: boolean;
+  /**
+   * Page chrome supplied by the app (for example its own page container).
+   * Receives the stacked children. Defaults to a plain `div` layout.
+   */
+  layout?: (props: SettingsLayoutProps) => ReactNode;
+  children: ReactNode;
+}
+
+/** Plain fallback layout: heading, optional slots, then the body. */
+export function DefaultSettingsLayout({
+  title,
+  headerRight,
+  toolbar,
+  tabs,
+  fillHeight = false,
+  children,
+}: SettingsLayoutProps) {
+  return (
+    <div
+      className={cn(
+        "mx-auto flex w-full max-w-3xl flex-col gap-4 px-4 py-6",
+        fillHeight && "h-full min-h-0",
+      )}
+    >
+      <div className="flex items-center justify-between gap-4">
+        <h1 className="text-balance text-lg font-semibold text-foreground">
+          {title}
+        </h1>
+        {headerRight ? <div className="shrink-0">{headerRight}</div> : null}
+      </div>
+      {toolbar ? <div>{toolbar}</div> : null}
+      {tabs ? <div>{tabs}</div> : null}
+      <div className={cn(fillHeight ? "min-h-0 flex-1" : null)}>{children}</div>
+    </div>
+  );
+}
+
+/**
+ * Shared chrome for settings: title row, optional toolbar / tabs, then a
+ * consistent section stack. Apps pass `layout` to wrap their own page
+ * container; this package does not import one.
+ */
+export function SettingsPage({
+  title,
+  headerRight,
+  toolbar,
+  tabs,
+  stack = true,
+  fillHeight = false,
+  layout,
+  children,
+}: SettingsPageProps) {
+  const body = stack ? <SettingsStack>{children}</SettingsStack> : children;
+  const render = layout ?? DefaultSettingsLayout;
+  return (
+    <>
+      {render({ title, headerRight, toolbar, tabs, fillHeight, children: body })}
+    </>
+  );
+}