@vvedantb/ui 0.8.0 → 0.10.0

package/README.md

@@ -4,12 +4,13 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
 | `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. CSS. |
 | `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | Same file as `tokens/css/compat-shadcn-rgb.css`. CSS. |
 | `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset (`.mjs`) for `@config "@vvedantb/ui/tokens/tailwind-preset"`. Kept as a build-tool entry: Tailwind needs a resolvable package path, and it is not a React API. |
+| `@vvedantb/ui/landing.css` | Landing page classes (`landing-atmosphere`, `landing-grain`, `landing-pulse-dot`, ambient graph and preview animations, smooth `#top` scrolling). CSS. |
 | `@vvedantb/ui/package.json` | Package metadata. |
 
 Removed in 0.4.0-rc.1: the `/cn`, `/sonner`, `/audio`, `/shell`, `/app`, `/composer` and `/tokens/native` subpaths. Import from `@vvedantb/ui`. See [`MIGRATION.md`](MIGRATION.md).
@@ -792,6 +793,93 @@ Rows (hover, active, selected, drop target) use `bg-sidebar-accent` instead of `
 
 Rail tiles keep `surface-tertiary`, so in dark mode the active rail tile is a step lighter than the active row. An app that imports `tokens.css` and defines its own `--sidebar-accent` overrides the fill; it must be a full colour value there (use `compat-shadcn-rgb.css` for `R G B` channels).
 
+## Landing kit, site footer and pricing dialog (0.9.0)
+
+Marketing pieces the apps copied between each other. Each one renders the same
+DOM and class strings as the app copies it replaces. Copy, links, logos, prices
+and auth buttons come from the app; the package imports no router, no Clerk and
+no Motion.
+
+Import the stylesheet once (from CSS or TypeScript):
+
+```css
+@import "@vvedantb/ui/landing.css";
+```
+
+The components live under `src/`, which the usual `@source` line already scans.
+
+### Landing kit
+
+`createLandingKit({ motion })` takes `motion` from `motion/react` and returns
+the animated parts. Call it once at module scope.
+
+```tsx
+import { motion } from "motion/react";
+import { createLandingKit } from "@vvedantb/ui";
+
+export const { LandingReveal, LandingRevealItem, LandingHero, LandingNav, LandingCta } =
+  createLandingKit({ motion });
+```
+
+| Part | Props |
+| --- | --- |
+| `LandingReveal` | `className`, `delay` (seconds, default `0`). Staggers its children in once, when 20% is in view. |
+| `LandingRevealItem` | `className`. One revealed child (`landingItemVariants`). |
+| `LandingHero` | `eyebrow`, `title`, `description` (nodes), `actions` (the button row; it renders even when empty), `capabilities` (strings). |
+| `LandingNav` | `brand`, `homeLabel` (home link `aria-label`), `links`, `github` (`href`, `label`, `icon`), `actions`, `menu`. |
+| `LandingCta` | `title`, `description`, `action`. |
+
+Plain parts, no Motion:
+
+| Part | Props |
+| --- | --- |
+| `LandingPageLayout` | `nav`, `heroBackdrop` (before the hero, inside the atmosphere block), `hero`, `children` (sections), `footer`. Root is `#top`. |
+| `LandingSection` | `id`, `className`. |
+| `LandingSectionHeading` | `eyebrow`, `heading`, `intro`, `className`. |
+| `LandingLattice` | `className` (grid columns). Cells share 1px borders. |
+| `LandingFeatureCard` | `icon` (a component, rendered `size={18} stroke={1.5}`), `title`, `description`. |
+| `LandingNavMenu` | `links`, `github` (`href`, `icon`). Overflow menu below `md`. |
+| `LandingFooter` | `brand`, `tagline`, `links`, `actions` (after the links), `github` (`href`, `label`, `icon`). |
+
+Constants: `landingShellClass`, `landingPanelClass`, `landingItemVariants`, and
+for the footer's `actions` slot `landingFooterLinkClass` (a text link) and
+`landingFooterButtonClass` (a `Button variant="link"`).
+
+### `SiteFooter`
+
+Brand, tagline and social icon buttons; link columns; then copyright and legal
+links under a separator.
+
+| Prop | |
+| --- | --- |
+| `brand`, `tagline` | Nodes. |
+| `socials` | `{ href, icon, label? }[]`. `icon` is a component that takes `className`. Links open in a new tab. |
+| `columns` | `{ heading, links }[]`. A link is `{ href, label, external?, image?: { src, alt } }`. |
+| `name`, `year` | "Copyright © {year} {name}". `year` defaults to the current year. |
+| `legalLinks` | `{ href, label }[]`, open in a new tab. |
+| `variant` | `"muted"` (default, `text-muted`), `"muted-foreground"`, or `"touch"` (`text-muted-foreground`, `max-sm:hit-target` links, safe-area bottom padding). |
+
+### `PricingModal`
+
+One-plan upgrade dialog. Props: `open`, `onClose`, `title` (accessible, hidden),
+`description` (hidden; when set the title is an `sr-only` `DialogTitle`,
+otherwise it sits in `VisuallyHidden`), `logo` (`dark` and `light` image URLs,
+shown in that colour mode), `wordmark`, `price`, `tagline`,
+`taglineFontClassName`, `features`, `ctaLabel` (default "Get Pro"),
+`renderCheckout(button)` (wrap the button in the billing provider's checkout),
+`closeButton` (an extra compact close button, default `false`) and `tone`
+(`"muted"` default or `"muted-foreground"`).
+
+### Account menu items and rail collapse tile
+
+`SidebarAccountMenu` takes three optional props. Without them it renders as before.
+
+- `themeToggle={{ isDark, onToggle }}`: a "Light mode" / "Dark mode" item after `children`.
+- `signOut={{ onSignOut, description? }}`: a separator and a danger "Sign out" item, last. It opens `SignOutDialog`; Alt-click skips the dialog and `ConfirmSkipHint` shows while Alt is held. The menu owns the dialog state. If `onSignOut` rejects, the dialog buttons enable again.
+- `itemIconSize`: `size` of those two items' icons. Default: the icon's own size.
+
+`RailCollapseTile({ collapsed, onToggle })`: the rail tile that shows or hides the sidebar panel ("Show sidebar" with the expand icon, or "Hide sidebar").
+
 ## Toaster
 
 ```tsx
@@ -855,6 +943,6 @@ The compat file includes a fallback `glass-panel-strong` (`rgb(var(--card) / 0.9
 
 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`, `motion` and `zod` are optional peers (`peerDependenciesMeta`). Install `@clerk/clerk-react` only to use `useStableAuth`, `@tanstack/react-hotkeys` and `zod` only for the features that use them, and `motion` only to use the motion presets, `InputArea`, the 0.3 `Composer` or the AI elements and primitives that animate.
+`@clerk/clerk-react`, `convex`, `@tanstack/react-hotkeys`, `motion` and `zod` are optional peers (`peerDependenciesMeta`), so the package manager does not install or warn about them. The root still imports each of them statically from some module (`useStableAuth` and `ConvexClerkProvider` import Clerk; `ConvexClerkProvider` and `useEnsureUser` import `convex/react`; the motion presets, `ConfirmSkipHint` and others import the rest). So an app that imports `@vvedantb/ui` must have all five resolvable, even if it uses none of those exports: a bundler resolves every import before it tree-shakes. `app/tests-node/convex-esm.test.mjs` pins which root modules import `convex` and Clerk.
 
 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,259 @@
+# App helpers (`@vvedantb/ui`)
+
+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` used by the app helpers: `@clerk/clerk-react` (`useStableAuth`, `ConvexClerkProvider`), `convex` (`ConvexClerkProvider`, `useEnsureUser`), `@tanstack/react-hotkeys` and `zod` (your `z` for `parseClientEnv`). The root imports Clerk and `convex/react` statically, so they must be installed even if you do not use these helpers; see the package README.
+
+`sonner` is not a dependency. The update watcher takes the toast API as an option. The app source uses a local class join, which the root does not export (the root `cn` is the clsx and tailwind-merge one). 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";
+
+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";
+
+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";
+
+<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`. `SettingsField` `layout`: `"stacked"` (default) puts the label above the control. `"horizontal"` renders one row with the label and description on the left and the control on the right. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
+
+## useStableAuth
+
+```ts
+import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
+import { createUseStableAuth } from "@vvedantb/ui";
+
+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`.
+
+## Theme
+
+```tsx
+import { createThemeProvider } from "@vvedantb/ui";
+
+// One kit per app, at module level.
+export const { ThemeProvider, useTheme } = createThemeProvider();
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+  <App />
+</ThemeProvider>;
+
+const { theme, resolvedTheme, setTheme, isDark, toggleTheme, mounted } = useTheme();
+```
+
+`createThemeProvider` is a port of next-themes 0.4.6. An app that uses next-themes can switch without a change in behaviour: the same localStorage writes, `<html>` classes and attributes, `style.colorScheme`, `prefers-color-scheme` listener, cross-tab `storage` sync and transition blocking. Parity tests run both side by side.
+
+- Props, as in next-themes: `storageKey` (`"theme"`), `defaultTheme` (`"system"` with `enableSystem`, else `"light"`), `enableSystem` (`true`), `enableColorScheme` (`true`), `attribute` (`"data-theme"`; `"class"`, any `data-*`, or an array), `themes` (`["light", "dark"]`), `value` (theme name to written value), `forcedTheme`, `disableTransitionOnChange` (`false`) and `nonce`.
+- State: `theme`, `setTheme` (a value or a function of the current theme), `resolvedTheme`, `systemTheme`, `forcedTheme` and `themes`, as in next-themes. Added: `mounted` (after the provider's first effect), `isDark` (`mounted && resolvedTheme === "dark"`) and `toggleTheme` (from `resolvedTheme`).
+- `setTheme` is a new function each time `theme` changes and stable otherwise, as in next-themes, so effects that list it re-run at the same times.
+- next-themes reads the DOM options (`attribute`, `themes`, `value`, `enableSystem`, `enableColorScheme`, `defaultTheme`, `disableTransitionOnChange`, `nonce`) once, on the first render, and so does this port. If `enableSystem` starts `false` and later turns `true`, a stored `"system"` is written as the class `system`. `forcedTheme` follows props.
+- A nested `ThemeProvider` from the same kit renders only its children.
+- `createThemeProvider({ missingProviderMessage })`: `useTheme()` outside the provider throws that message. Without it, `useTheme()` returns an empty state with no-op setters, as next-themes does.
+- No inline script is rendered. next-themes renders one for server rendering; React does not run it in a client-rendered app. Keep a pre-paint script in `index.html` if the app has one.
+
+For an app with its own theme state (for example a theme synced from the server), two helpers:
+
+- `getSystemTheme()`: `"dark"` or `"light"` from `prefers-color-scheme`; `"light"` without `window`.
+- `applyThemeClass(theme)`: removes `light` and `dark` from `<html>`, then adds `theme`. No-op without `document`.
+
+## Page title
+
+```tsx
+import { createPageTitleContext } from "@vvedantb/ui";
+
+export const { PageTitleProvider, usePageTitle, usePageTitleSync } = createPageTitleContext({
+  missingProviderMessage: "usePageTitle must be used within a PageTitleProvider",
+});
+
+// The shell reads it:
+const { pageTitle } = usePageTitle();
+// A page publishes it while mounted:
+usePageTitleSync(title);
+```
+
+- `usePageTitle()` returns `{ pageTitle, setPageTitle, mobileActionsSlot, setMobileActionsSlot }`. `mobileActionsSlot` is an element a mobile top bar registers (pass `setMobileActionsSlot` as its `ref`) so pages can portal actions into it.
+- `usePageTitleSync(title)` sets the title while the caller is mounted and clears it on unmount. Titles that are not strings publish `""`.
+- `missingProviderMessage`: `usePageTitle()` outside the provider throws it. Without it, `usePageTitle()` returns an empty title and no-op setters.
+- `documentTitle` (off by default; without it `document.title` is never touched): `{ suffix?, separator? = " · ", fallback? }`. While a page title is set, `document.title` is `` `${pageTitle}${separator}${suffix}` `` (just the page title without a suffix). While it is empty, `fallback`, else the title at mount. The mount-time title comes back on unmount.
+
+## Page motion
+
+```tsx
+import { MotionConfig } from "motion/react";
+import { PageMotionProvider, useDisablePageMotion } from "@vvedantb/ui";
+
+<PageMotionProvider disabled={flags?.disablePageMotion === true} motionConfig={MotionConfig}>
+  <App />
+</PageMotionProvider>;
+```
+
+- Sets `html[data-page-motion]` to `"off"` or `"on"` in a layout effect (CSS can skip page and route transitions on `"off"`). The attribute stays after unmount.
+- Renders `motionConfig` with `reducedMotion` `"always"` when disabled, else `"never"`.
+- `useDisablePageMotion()`: the `disabled` value, `false` outside the provider.
+- This module does not import `motion`. Pass `MotionConfig`, or an app component that wraps it, defined at module level, for example with `LazyMotion`:
+
+```tsx
+function LazyMotionConfig({ reducedMotion, children }: PageMotionConfigProps) {
+  return (
+    <LazyMotion features={domAnimation}>
+      <MotionConfig reducedMotion={reducedMotion}>{children}</MotionConfig>
+    </LazyMotion>
+  );
+}
+```
+
+## Compact relative time
+
+```ts
+import { formatCompactRelativeTime } from "@vvedantb/ui";
+
+formatCompactRelativeTime(createdAt, { justNow: "now" }); // "now", "5m", "3h", "2d", "4mo", "1y"
+formatCompactRelativeTime(updatedAt, { calendar: true }); // "42s", ..., calendar months and years
+```
+
+Pure TypeScript, no dependencies. Options:
+
+- `now`: clock in ms, default `Date.now()`.
+- `justNow`: returned for anything under a minute old, future times included. Without it the result is whole seconds (`"42s"`), and a future time gives `"0s"` or a negative count.
+- `calendar`: `false` (default) counts elapsed time: a day is 24 hours, a month 30 days, a year 12 such months. `true` counts as `dayjs().diff(date, unit)` does: days by the local calendar across DST changes, and calendar months and years.
+
+Strings are parsed with `new Date(string)`. dayjs parses a date-only string such as `"2026-03-01"` as local midnight, `new Date` as UTC midnight; numbers, `Date` objects and ISO strings with a time give the same result either way. An invalid date gives `"NaNy"` (`"0mo"` with `calendar`).
+
+## Convex provider, VITE env and ensure-user (0.10.0)
+
+Moved from `@vvedantb/convex-client` 0.1.0 with the same names and behaviour. Its non-React helpers (`mapLoadedQuery`, `forEachLoadedQuery`, `updateAllCachedQueries`, `patchLoadedQuery`, `OptimisticStore`, `tempId`, `createMemoryOptimisticStore`) moved to `@vvedantb/server` instead, so backend packages, tests and React Native can use them without loading this package.
+
+### `ConvexClerkProvider`
+
+```tsx
+import { ConvexClerkProvider, useStableAuth } from "@vvedantb/ui";
+import { ConvexReactClient } from "convex/react";
+
+const convex = new ConvexReactClient(env.VITE_CONVEX_URL);
+
+<ClerkProvider publishableKey={env.VITE_CLERK_PUBLISHABLE_KEY}>
+  <ConvexClerkProvider client={convex} useAuth={useStableAuth}>
+    <App />
+  </ConvexClerkProvider>
+</ClerkProvider>;
+```
+
+| Props | Renders |
+| --- | --- |
+| `client` is `null` or `undefined` | `children` alone (no provider). |
+| `clerk={false}` | `<ConvexProvider client={client}>`. |
+| otherwise | `<ConvexProviderWithClerk client={client} useAuth={useAuth}>`; `useAuth` defaults to `@clerk/clerk-react`'s. |
+
+`clerk` defaults to `true`. Render it inside `ClerkProvider` unless `clerk` is `false`. Types: `ConvexClerkProviderProps`, `ConvexClerkUseAuth`.
+
+### `parseClientEnv`
+
+```ts
+import { z } from "zod";
+import { parseClientEnv } from "@vvedantb/ui";
+
+export const clientEnv = parseClientEnv(import.meta.env, { z, viteEnv: "fallback" });
+// { VITE_CONVEX_URL: string; VITE_CLERK_PUBLISHABLE_KEY: string; VITE_ENV: "development" | "staging" | "production" }
+
+export const extensionEnv = parseClientEnv(import.meta.env, {
+  z,
+  viteEnv: false,
+  extend: { VITE_CLERK_SYNC_HOST: z.string().url() },
+});
+```
+
+The schema is `z.object({ VITE_CONVEX_URL: z.string().min(1), VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1), VITE_ENV: z.enum(["development", "staging", "production"]), ...extend })`, built with your `z` (zod 3.25+ or 4; the package never imports zod at runtime). Only the schema's keys are read from `rawEnv`. Failure throws the `ZodError` from `.parse`.
+
+| `viteEnv` | `VITE_ENV` |
+| --- | --- |
+| `"strict"` (default) | Must be one of `VITE_ENV_NAMES`. |
+| `"fallback"` | Any other value, or none, becomes `"development"` before parsing. |
+| `false` | Not in the schema or the result. |
+
+Types: `ClientEnv`, `ClientEnvWithoutViteEnv`, `ClientEnvOptions`, `ClientEnvSource`, `ViteEnvMode`, `ViteEnvName`.
+
+### `useEnsureUser`
+
+```tsx
+function EnsureUser() {
+  useEnsureUser(api.users.ensureUserExists);
+  return null;
+}
+```
+
+Calls `mutation({})` every time `useConvexAuth().isAuthenticated` becomes `true` (once on mount if already signed in), and logs a rejection with `console.error`. Needs a Convex auth provider above it (`ConvexClerkProvider` with Clerk on). Pair it with `ensureUser` from `@vvedantb/server`. Type: `EnsureUserMutation`.
+
+Tests: `app/tests/convex/` ports each app's copy and runs it beside the helper (env with zod 4 and zod 3.25; provider variants; ensure-user calls over auth sequences). `app/tests-node/convex-esm.test.mjs` loads the helpers in plain Node.

package/app/src/convex/ConvexClerkProvider.tsx

@@ -0,0 +1,37 @@
+import { useAuth as useClerkAuth } from "@clerk/clerk-react";
+import { ConvexProvider, type ConvexReactClient } from "convex/react";
+import { ConvexProviderWithClerk } from "convex/react-clerk";
+import type { ComponentProps, ReactNode } from "react";
+
+/** The `useAuth` hook `ConvexProviderWithClerk` takes (Clerk's, or a wrapper such as `useStableAuth`). */
+export type ConvexClerkUseAuth = ComponentProps<typeof ConvexProviderWithClerk>["useAuth"];
+
+export type ConvexClerkProviderProps = {
+  /** No client (for example no Convex URL configured): children render without a provider. */
+  client: ConvexReactClient | null | undefined;
+  /** Default: `useAuth` from `@clerk/clerk-react`. */
+  useAuth?: ConvexClerkUseAuth;
+  /** `false` renders a plain `ConvexProvider` (no Clerk auth). Default `true`. */
+  clerk?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * The Convex provider for a Clerk app: `ConvexProviderWithClerk`, a plain
+ * `ConvexProvider` when `clerk` is `false`, or just the children when there is
+ * no client. Render it inside `ClerkProvider` unless `clerk` is `false`.
+ */
+export function ConvexClerkProvider({
+  client,
+  useAuth = useClerkAuth,
+  clerk = true,
+  children,
+}: ConvexClerkProviderProps) {
+  if (!client) return children;
+  if (!clerk) return <ConvexProvider client={client}>{children}</ConvexProvider>;
+  return (
+    <ConvexProviderWithClerk client={client} useAuth={useAuth}>
+      {children}
+    </ConvexProviderWithClerk>
+  );
+}

package/app/src/convex/env.ts

@@ -0,0 +1,76 @@
+// Type-only: the app passes its own `z`, so zod stays an optional peer and the
+// thrown ZodError comes from the app's zod version (3.25+ or 4), as today.
+import type { z } from "zod";
+
+export type ViteEnvName = "development" | "staging" | "production";
+
+export const VITE_ENV_NAMES: readonly ["development", "staging", "production"] = ["development", "staging", "production"];
+
+/** `import.meta.env`, or any record of raw env values. */
+export type ClientEnvSource = Readonly<Record<string, string | boolean | undefined>>;
+
+type BaseShape = {
+  VITE_CONVEX_URL: z.ZodType<string>;
+  VITE_CLERK_PUBLISHABLE_KEY: z.ZodType<string>;
+};
+
+type ViteEnvShape = BaseShape & { VITE_ENV: z.ZodType<ViteEnvName> };
+
+/**
+ * - `"strict"` (default): `VITE_ENV` must be one of `VITE_ENV_NAMES`.
+ * - `"fallback"`: any other value (or none) is read as `"development"`.
+ * - `false`: no `VITE_ENV` key.
+ */
+export type ViteEnvMode = "strict" | "fallback" | false;
+
+export type ClientEnvOptions<Extra extends z.ZodRawShape> = {
+  /** The app's `z` from `"zod"`. */
+  z: typeof z;
+  viteEnv?: ViteEnvMode;
+  /** Extra keys, parsed after the base keys in the same `z.object`. A key here replaces a base key. */
+  extend?: Extra;
+};
+
+/** Parsed env with `VITE_ENV`. */
+export type ClientEnv<Extra extends z.ZodRawShape = Record<never, never>> = z.output<z.ZodObject<ViteEnvShape & Extra>>;
+
+/** Parsed env without `VITE_ENV` (`viteEnv: false`). */
+export type ClientEnvWithoutViteEnv<Extra extends z.ZodRawShape = Record<never, never>> = z.output<
+  z.ZodObject<BaseShape & Extra>
+>;
+
+/**
+ * Parse VITE env with zod: `VITE_CONVEX_URL` and `VITE_CLERK_PUBLISHABLE_KEY`
+ * are `z.string().min(1)`, `VITE_ENV` is `z.enum(VITE_ENV_NAMES)`, then any
+ * `extend` keys. Only those keys are read from `rawEnv`. Throws the ZodError
+ * from `z.object(shape).parse`.
+ */
+export function parseClientEnv<Extra extends z.ZodRawShape = Record<never, never>>(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<Extra> & { viteEnv: false },
+): ClientEnvWithoutViteEnv<Extra>;
+export function parseClientEnv<Extra extends z.ZodRawShape = Record<never, never>>(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<Extra> & { viteEnv?: "strict" | "fallback" },
+): ClientEnv<Extra>;
+export function parseClientEnv(
+  rawEnv: ClientEnvSource,
+  options: ClientEnvOptions<z.ZodRawShape>,
+): z.output<z.ZodObject<z.ZodRawShape>> {
+  const zod = options.z;
+  const viteEnv = options.viteEnv ?? "strict";
+  const shape: z.ZodRawShape = {
+    VITE_CONVEX_URL: zod.string().min(1),
+    VITE_CLERK_PUBLISHABLE_KEY: zod.string().min(1),
+    ...(viteEnv === false ? {} : { VITE_ENV: zod.enum(VITE_ENV_NAMES) }),
+    ...options.extend,
+  };
+  const input: Record<string, string | boolean | undefined> = {};
+  for (const key of Object.keys(shape)) input[key] = rawEnv[key];
+  if (viteEnv === "fallback") input.VITE_ENV = viteEnvOrDevelopment(rawEnv.VITE_ENV);
+  return zod.object(shape).parse(input);
+}
+
+function viteEnvOrDevelopment(value: string | boolean | undefined): ViteEnvName {
+  return value === "production" || value === "staging" || value === "development" ? value : "development";
+}

package/app/src/convex/useEnsureUser.ts

@@ -0,0 +1,24 @@
+import { useConvexAuth, useMutation } from "convex/react";
+import type { FunctionReference } from "convex/server";
+import { useEffect } from "react";
+
+/** A public mutation that takes no args, such as `api.users.ensureUserExists`. */
+export type EnsureUserMutation = FunctionReference<"mutation", "public", Record<string, never>>;
+
+/**
+ * Call `mutation({})` each time Convex auth becomes authenticated, logging a
+ * failure with `console.error`. Needs a Convex auth provider above it
+ * (`ConvexClerkProvider` with Clerk on). Kept as an effect: it syncs the
+ * server's users row with the sign-in state, and there is no render-time
+ * alternative.
+ */
+export function useEnsureUser(mutation: EnsureUserMutation): void {
+  const { isAuthenticated } = useConvexAuth();
+  const ensureUser = useMutation(mutation);
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      ensureUser({}).catch(console.error);
+    }
+  }, [isAuthenticated, ensureUser]);
+}

package/app/src/index.ts

@@ -72,3 +72,20 @@ export {
   formatCompactRelativeTime,
   type CompactRelativeTimeOptions,
 } from "./time/compactRelativeTime.js";
+
+export {
+  ConvexClerkProvider,
+  type ConvexClerkProviderProps,
+  type ConvexClerkUseAuth,
+} from "./convex/ConvexClerkProvider.js";
+export {
+  parseClientEnv,
+  VITE_ENV_NAMES,
+  type ClientEnv,
+  type ClientEnvOptions,
+  type ClientEnvSource,
+  type ClientEnvWithoutViteEnv,
+  type ViteEnvMode,
+  type ViteEnvName,
+} from "./convex/env.js";
+export { useEnsureUser, type EnsureUserMutation } from "./convex/useEnsureUser.js";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
-  "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
+  "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -35,6 +35,7 @@
       "types": "./tokens/src/tailwind-preset.d.mts",
       "default": "./tokens/src/tailwind-preset.mjs"
     },
+    "./landing.css": "./src/marketing/landing.css",
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
@@ -50,8 +51,18 @@
     "!**/*.test.tsx"
   ],
   "sideEffects": [
-    "./src/ui/sonner.css"
+    "./src/ui/sonner.css",
+    "./src/marketing/landing.css"
   ],
+  "scripts": {
+    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
+    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs",
+    "prepack": "node tokens/scripts/check-exports.mjs"
+  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -83,6 +94,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "convex": "^1.24.0",
     "embla-carousel-react": "^8.6.0",
     "motion": ">=12.0.0",
     "nanoid": "^5.1.0",
@@ -131,6 +143,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "convex": "^1.47.0",
     "dayjs": "1.11.19",
     "embla-carousel-react": "^8.6.0",
     "happy-dom": "^18.0.0",
@@ -149,12 +162,16 @@
     "use-stick-to-bottom": "^1.1.0",
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "zod3": "npm:zod@^3.25.76"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
       "optional": true
     },
+    "convex": {
+      "optional": true
+    },
     "@tanstack/react-hotkeys": {
       "optional": true
     },
@@ -164,13 +181,5 @@
     "zod": {
       "optional": true
     }
-  },
-  "scripts": {
-    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
-    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs"
   }
-}
+}