@vvedantb/ui 0.19.1 → 0.22.0

package/README.md

@@ -867,14 +867,105 @@ links under a separator.
 
 ### `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"`).
+Upgrade dialog with two layouts. Without `plans` it is the single-plan dialog
+below. With `plans` (0.22.0) it is the wide multi-plan dialog.
+
+Shared props: `open`, `onClose`, `title` (accessible, hidden), `description`
+(hidden), `tone` (`"muted"` default or `"muted-foreground"`),
+`billingPeriod`, `onBillingPeriodChange`, `defaultBillingPeriod` (`"month"`
+default) and `renderCheckout`.
+
+#### Multi-plan (0.22.0)
+
+Header: `apps` (an `AppName[]`, shown as `AppMark` tiles at the top left),
+`headline` (centre), a Monthly / Annual switch and a close button (top right).
+Then one card per entry of `plans` (2 to 4 fit) and one `finePrint` line. Cards
+stack on narrow screens.
+
+A `PricingPlan` is `{ id, name, price: { month, year }, ctaLabel?, intro?,
+highlight?: { title, description }, benefits?: { label, icon?: "check" |
+AppName, muted? }[], current?, featured?, periodSuffix? }`. Prices are display
+strings and always per month (`periodSuffix` default `"/month"`; the yearly
+price is the per-month price). `ctaLabel` defaults to "Get started". `featured`
+(or `highlighted`) adds a subtle ring. A `current` plan shows a disabled,
+outlined "Current plan" button and does not call `renderCheckout`.
+
+The `featured` plan's button is a solid primary button (`Button` `variant="default"`). Other plans use `secondary`.
+
+`renderCheckout(button, plan, period)` wraps each plan's button.
+
+Each app passes its own plan names, prices and copy. The example and the screenshots use placeholder text only.
+
+```tsx
+<PricingModal
+  open={open}
+  onClose={close}
+  title="Plans"
+  apps={["vibot", "verve", "velth", "vmem", "vhub"]}
+  headline="One plan. Every V app."
+  finePrint="Cancel anytime. $120 billed yearly. Save 33%."
+  plans={[
+    { id: "free", name: "Free", price: { month: "$0", year: "$0" }, current: true },
+    {
+      id: "pro",
+      name: "V Pro",
+      price: { month: "$15", year: "$10" },
+      featured: true,
+      intro: "Everything in Free, and:",
+      highlight: { title: "Shared", description: "usage across every V app" },
+      benefits: [
+        { label: "Higher limits", icon: "vibot" },
+        { label: "Pro features", icon: "verve" },
+        { label: "Pro features", icon: "velth" },
+        { label: "More memory", icon: "vmem" },
+        { label: "More storage", icon: "vhub" },
+      ],
+    },
+  ]}
+  renderCheckout={(button, plan, period) => (
+    <CheckoutButton planId={plan.id} planPeriod={period}>{button}</CheckoutButton>
+  )}
+/>
+```
+
+In the example, V Pro costs $15/month, or $10/month billed yearly ($120/year,
+a 33% saving). The cards show the per-month price only, so the yearly total and
+the saving go in `finePrint`. Screenshots: `brand/pricing-modal/` (regenerate with
+`node scripts/build-pricing-screenshots.mjs`).
+
+#### Single plan
+
+Props: `logo` (`dark` and `light` image URLs, shown in that colour mode),
+`wordmark`, `price`, `tagline`, `taglineFontClassName`, `features`, `ctaLabel`
+(default "Get Pro"), `renderCheckout(button, period)` (wrap the button in the
+billing provider's checkout), `closeButton` (an extra compact close button,
+default `false`) and, when `description` is set, the title is an `sr-only`
+`DialogTitle`, otherwise it sits in `VisuallyHidden`.
+
+From 0.20.0, `yearly={{ pricePerMonth, total?, saveLabel? }}` adds a
+monthly/yearly toggle; `price` stays the monthly price. `renderCheckout` gets the
+selected `period` (`"month"` or `"year"`) as its second argument, for Clerk's
+`planPeriod`. Without `yearly` the DOM is unchanged.
+
+```tsx
+<PricingModal
+  price="$10"
+  yearly={{ pricePerMonth: "$8.33", total: "$100" }}
+  renderCheckout={(button, period) => (
+    <CheckoutButton planId={planId} planPeriod={period}>{button}</CheckoutButton>
+  )}
+  /* ... */
+/>
+```
+
+#### Migration
+
+Single-plan callers need no change. To move to the multi-plan layout, replace
+`logo`, `wordmark`, `price`, `tagline`, `features` and `yearly` with `plans`,
+`apps` and `headline`, and change `renderCheckout` to
+`(button, plan, period)`. Type helpers: use `PricingModalLegacyProps` or
+`PricingModalMultiProps` when you need one layout's props;
+`PricingModalProps` is their union.
 
 ### Account menu items and rail collapse tile
 

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. The attribute stays after unmount. From 0.15.0 `tokens.css` (through `tokens/css/motion.css`) ships the `"off"` rules: `.ui-page-enter`, `.ui-enter`, `.ui-enter-up` and `.ui-stagger` fade only, `animate-in` / `animate-out`, `.t-modal` and `.t-tabs-pill` stop transitioning, and view transitions stop.
+- 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)
+
+React and VITE env helpers for Convex apps. The non-React Convex helpers (`mapLoadedQuery`, `forEachLoadedQuery`, `updateAllCachedQueries`, `patchLoadedQuery`, `OptimisticStore`, `tempId`, `createMemoryOptimisticStore`) live in `@vvedantb/server`, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.19.1",
+  "version": "0.22.0",
   "license": "MIT",
   "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, artifact viewers over the @vvedantb/server artifacts core, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -40,6 +40,10 @@
       "types": "./tokens/src/tailwind-preset.d.mts",
       "default": "./tokens/src/tailwind-preset.mjs"
     },
+    "./brand": {
+      "types": "./src/brand/index.ts",
+      "default": "./src/brand/index.ts"
+    },
     "./landing.css": "./src/marketing/landing.css",
     "./package.json": "./package.json"
   },
@@ -50,6 +54,7 @@
     "app/src",
     "tokens/src",
     "tokens/examples",
+    "scripts/build-brand-assets.mjs",
     "README.md",
     "LICENSE",
     "!**/*.test.ts",
@@ -59,6 +64,17 @@
     "./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 tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.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",
+    "brand:assets": "node scripts/build-brand-assets.mjs",
+    "brand:sheet": "node scripts/build-brand-sheet.mjs",
+    "prepack": "node tokens/scripts/check-exports.mjs"
+  },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -148,6 +164,7 @@
     "@tanstack/react-hotkeys": "^0.13.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
+    "@vvedantb/server": "workspace:*",
     "ai": "^5.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -171,8 +188,7 @@
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "zod3": "npm:zod@^3.25.76",
-    "@vvedantb/server": "0.8.1"
+    "zod3": "npm:zod@^3.25.76"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
@@ -193,13 +209,5 @@
     "@vvedantb/server": {
       "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 tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.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"
   }
-}
+}

package/scripts/build-brand-assets.mjs

@@ -0,0 +1,126 @@
+// Writes the favicon, PWA, extension and Android icon sets for the family apps.
+//
+//   node scripts/build-brand-assets.mjs --out <dir> [--app <name>] [--no-png] [--dry-run]
+//
+// SVGs are always written. PNGs and favicon.ico need `rsvg-convert`; without it they are skipped
+// with a message. Layout: <dir>/<app>/{mark,icon,favicon,icon-light}.svg, PNGs, extension/, android/.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { APP_NAMES, appAdaptiveSvg, appExtension128Svg, appMarkSvg, appTileSvg } from "../src/brand/svg.ts";
+
+/** Whether `rsvg-convert` can be run. */
+export function hasRsvg() {
+  return spawnSync("rsvg-convert", ["--version"], { stdio: "ignore" }).status === 0;
+}
+
+/** Renders `svg` to a square PNG buffer of `px` pixels. */
+export function renderPng(svg, px) {
+  const result = spawnSync("rsvg-convert", ["-w", String(px), "-h", String(px), "-f", "png"], { input: svg, maxBuffer: 64 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`rsvg-convert failed: ${String(result.stderr)}`);
+  return result.stdout;
+}
+
+/** An ICO file that embeds each PNG (sizes in pixels, same order). */
+export function icoFromPngs(pngs, sizes) {
+  const header = Buffer.alloc(6 + 16 * pngs.length);
+  header.writeUInt16LE(1, 2);
+  header.writeUInt16LE(pngs.length, 4);
+  let offset = header.length;
+  pngs.forEach((png, i) => {
+    const at = 6 + 16 * i;
+    header.writeUInt8(sizes[i] % 256, at);
+    header.writeUInt8(sizes[i] % 256, at + 1);
+    header.writeUInt16LE(1, at + 4);
+    header.writeUInt16LE(32, at + 6);
+    header.writeUInt32LE(png.length, at + 8);
+    header.writeUInt32LE(offset, at + 12);
+    offset += png.length;
+  });
+  return Buffer.concat([header, ...pngs]);
+}
+
+/** SVG files for one app, as `[relative path, content]`. */
+export function svgFiles(app) {
+  const tile = appTileSvg(app);
+  return [
+    ["mark.svg", appMarkSvg(app)],
+    ["icon.svg", tile],
+    ["favicon.svg", tile],
+    ["icon-light.svg", appTileSvg(app, "light")],
+    ["android/adaptive-foreground.svg", appAdaptiveSvg(app, "#fff")],
+  ];
+}
+
+/** PNG files for one app, as `[relative path, svg source, pixels]`. */
+export function pngSpecs(app) {
+  const tile = appTileSvg(app);
+  const square = appTileSvg(app, "dark", 0);
+  return [
+    ["favicon-16.png", tile, 16],
+    ["favicon-32.png", tile, 32],
+    ["apple-touch-icon.png", square, 180],
+    ["icon-192.png", tile, 192],
+    ["icon-512.png", tile, 512],
+    ["icon-1024.png", tile, 1024],
+    ["icon-light.png", appTileSvg(app, "light"), 512],
+    ["maskable-512.png", square, 512],
+    ["extension/icon-16.png", tile, 16],
+    ["extension/icon-32.png", tile, 32],
+    ["extension/icon-48.png", tile, 48],
+    ["extension/icon-128.png", appExtension128Svg(app), 128],
+    ["android/adaptive-foreground-432.png", appAdaptiveSvg(app, "#fff"), 432],
+    ["android/adaptive-monochrome-432.png", appAdaptiveSvg(app, "#000"), 432],
+  ];
+}
+
+/** Writes (or, with `dryRun`, lists) the set for each app. Returns the relative file paths per app and any skip notes. */
+export function buildBrandAssets({ out, apps = APP_NAMES, png = true, dryRun = false }) {
+  const written = [];
+  const notes = [];
+  const withPng = png && hasRsvg();
+  if (png && !withPng) notes.push("rsvg-convert not found: PNGs and favicon.ico skipped (SVGs written).");
+  const put = (file, data) => {
+    written.push(file);
+    if (dryRun) return;
+    mkdirSync(dirname(join(out, file)), { recursive: true });
+    writeFileSync(join(out, file), data);
+  };
+  for (const app of apps) {
+    for (const [name, svg] of svgFiles(app)) put(join(app, name), svg);
+    if (!withPng) continue;
+    for (const [name, svg, px] of pngSpecs(app)) put(join(app, name), dryRun ? "" : renderPng(svg, px));
+    const sizes = [16, 32, 48];
+    const tile = appTileSvg(app);
+    put(join(app, "favicon.ico"), dryRun ? "" : icoFromPngs(sizes.map((px) => renderPng(tile, px)), sizes));
+  }
+  return { written, notes };
+}
+
+function parseArgs(argv) {
+  const args = { out: "", app: "", png: true, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--out") args.out = argv[++i] ?? "";
+    else if (arg === "--app") args.app = argv[++i] ?? "";
+    else if (arg === "--no-png") args.png = false;
+    else if (arg === "--dry-run") args.dryRun = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!args.out) throw new Error("--out <dir> is required");
+  if (args.app && !APP_NAMES.includes(args.app)) throw new Error(`--app must be one of ${APP_NAMES.join(", ")}`);
+  return args;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const { written, notes } = buildBrandAssets({ out: args.out, apps: args.app ? [args.app] : APP_NAMES, png: args.png, dryRun: args.dryRun });
+    for (const file of written) console.log(`${args.dryRun ? "would write" : "wrote"} ${join(args.out, file)}`);
+    for (const note of notes) console.warn(note);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}

package/src/brand/AppMark.tsx

@@ -0,0 +1,55 @@
+import { useId, type SVGProps } from "react";
+import { APP_MARKS, MARK_VIEWBOX, TILE_RADIUS, markLinecap, markStrokeWidth, type AppMarkVariant, type AppName } from "./svg";
+
+export type AppMarkProps = Omit<SVGProps<SVGSVGElement>, "children" | "height" | "width" | "viewBox"> & {
+  /** Which family app's mark to draw. */
+  app: AppName;
+  /** `"mark"` (default): glyph in `currentColor`. `"tile"`: white glyph on a black rounded tile. `"tile-light"`: black glyph on a white tile. */
+  variant?: AppMarkVariant;
+  /** Width and height. Default 24. */
+  size?: number | string;
+  /** Accessible name. Without it the mark is `aria-hidden`. */
+  title?: string;
+};
+
+const TILE_TONES = {
+  tile: { bg: "#000", fg: "#fff" },
+  "tile-light": { bg: "#fff", fg: "#000" },
+} as const;
+
+/** One of the six family app marks on the 1024 grid. */
+export function AppMark({ app, variant = "mark", size = 24, title, ...rest }: AppMarkProps) {
+  const titleId = useId();
+  const { kind, paths } = APP_MARKS[app];
+  const tone = variant === "mark" ? undefined : TILE_TONES[variant];
+  const color = tone?.fg ?? "currentColor";
+  const glyphProps =
+    kind === "fill"
+      ? { fill: color }
+      : { fill: "none", stroke: color, strokeWidth: markStrokeWidth(app), strokeLinecap: markLinecap(app), strokeLinejoin: "round" };
+  const glyph = (
+    <g {...(glyphProps as SVGProps<SVGGElement>)} data-glyph={app}>
+      {paths.map((d) => (
+        <path key={d} d={d} />
+      ))}
+    </g>
+  );
+  return (
+    <svg
+      {...rest}
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox={MARK_VIEWBOX}
+      data-app={app}
+      data-variant={variant}
+      role={title ? "img" : undefined}
+      aria-hidden={title ? undefined : true}
+      aria-labelledby={title ? titleId : undefined}
+    >
+      {title ? <title id={titleId}>{title}</title> : null}
+      {tone ? <rect width={1024} height={1024} rx={TILE_RADIUS} fill={tone.bg} /> : null}
+      {glyph}
+    </svg>
+  );
+}

package/src/brand/index.ts

@@ -0,0 +1,16 @@
+export { AppMark } from "./AppMark";
+export type { AppMarkProps } from "./AppMark";
+export {
+  APP_MARKS,
+  APP_MARK_SVG,
+  APP_NAMES,
+  APP_TILE_LIGHT_SVG,
+  APP_TILE_SVG,
+  appAdaptiveSvg,
+  appExtension128Svg,
+  appMarkSvg,
+  appTileSvg,
+  markLinecap,
+  markStrokeWidth,
+} from "./svg";
+export type { AppMarkVariant, AppName, MarkShape } from "./svg";

package/src/brand/svg.ts

@@ -0,0 +1,119 @@
+// Geometry and raw SVG strings for the family app marks. No imports, so the
+// asset script can load this file directly with Node.
+
+export const APP_NAMES = ["projectv", "vibot", "vhub", "vmem", "verve", "velth"] as const;
+
+export type AppName = (typeof APP_NAMES)[number];
+
+/** `mark`: glyph only, follows `currentColor`. `tile`: white glyph on a black tile. `tile-light`: black glyph on a white tile. */
+export type AppMarkVariant = "mark" | "tile" | "tile-light";
+
+export const MARK_VIEWBOX = "0 0 1024 1024";
+export const MARK_STROKE_WIDTH = 50;
+export const TILE_RADIUS = 224;
+
+export type MarkShape = {
+  /** Filled shapes (no stroke) versus lines (50 wide, round caps by default). */
+  kind: "fill" | "stroke";
+  /** Path data on the 1024 grid. */
+  paths: readonly string[];
+  /** Stroke width override on the 1024 grid. Defaults to `MARK_STROKE_WIDTH`. */
+  strokeWidth?: number;
+  /** Line cap override. Defaults to `"round"`. */
+  linecap?: "butt" | "round";
+};
+
+/** Stroke width of a mark on the 1024 grid. */
+export function markStrokeWidth(app: AppName): number {
+  return APP_MARKS[app].strokeWidth ?? MARK_STROKE_WIDTH;
+}
+
+/** Line cap of a mark. */
+export function markLinecap(app: AppName): "butt" | "round" {
+  return APP_MARKS[app].linecap ?? "round";
+}
+
+/**
+ * Glyphs sized by one rule: longest side = 512 * min(1.2, aspect^0.25), centred halfway between
+ * the bounding-box centre and the centre of mass. `verve` and `velth` are the final vectors.
+ * The others are traced from the approved 1024px renders.
+ */
+export const APP_MARKS: Record<AppName, MarkShape> = {
+  projectv: {
+    kind: "fill",
+    paths: ["M172 398L260 397L418 558L580 377L858 378L824 415L604 415L452 598L466 611L622 433L808 433L773 471L658 471L491 671L442 672Z"],
+  },
+  vibot: {
+    kind: "fill",
+    paths: [
+      "M295 314L396 314L396 574C520 540 620 440 655 314L711 314C680 470 560 590 396 627L390 627L390 651L396 651C560 610 700 480 734 314L789 314C740 540 560 712 295 712Z",
+    ],
+  },
+  vhub: {
+    kind: "stroke",
+    paths: ["M211 512L743 512", "M415 512C500 512 540 363 743 363", "M415 512C500 512 540 661 743 661"],
+  },
+  vmem: {
+    kind: "stroke",
+    strokeWidth: 58,
+    linecap: "butt",
+    paths: [
+      "M693.2 379.5A227.25 227.25 0 0 1 581.0 732.7",
+      "M442.5 732.7A227.25 227.25 0 0 1 330.9 378.7",
+      "M397.3 319.9A227.25 227.25 0 0 1 627.1 320.4",
+    ],
+  },
+  verve: {
+    kind: "stroke",
+    paths: [
+      "M285.4 344.1Q428.6 344.1 512 552.6Q595.4 344.1 738.6 344.1",
+      "M285.4 344.1L285.4 579.8Q428.6 579.8 512 706.7Q595.4 579.8 738.6 579.8L738.6 344.1",
+    ],
+  },
+  velth: {
+    kind: "stroke",
+    paths: [
+      "M512 732.3C379.8 652.1 289.7 471.9 299.7 301.6C419.9 371.7 500 552 512 732.3Z",
+      "M512 732.3C644.2 652.1 734.3 471.9 724.3 301.6C604.1 371.7 524 552 512 732.3Z",
+    ],
+  },
+};
+
+const NS = 'xmlns="http://www.w3.org/2000/svg"';
+
+/** Attributes that paint the glyph in `color`. */
+export function markPaintAttrs(app: AppName, color: string): string {
+  return APP_MARKS[app].kind === "fill" ? `fill="${color}"` : `fill="none" stroke="${color}" stroke-width="${markStrokeWidth(app)}" stroke-linecap="${markLinecap(app)}" stroke-linejoin="round"`;
+}
+
+function pathElements(app: AppName): string {
+  return APP_MARKS[app].paths.map((d) => `<path d="${d}"/>`).join("");
+}
+
+/** Glyph only, painted with `color` (default `currentColor`). */
+export function appMarkSvg(app: AppName, color = "currentColor"): string {
+  return `<svg ${NS} viewBox="${MARK_VIEWBOX}" ${markPaintAttrs(app, color)}>${pathElements(app)}</svg>\n`;
+}
+
+/** Tile with a glyph. `radius` 0 gives a full-bleed square (apple-touch, maskable). */
+export function appTileSvg(app: AppName, tone: "dark" | "light" = "dark", radius = TILE_RADIUS): string {
+  const [bg, fg] = tone === "dark" ? ["#000", "#fff"] : ["#fff", "#000"];
+  const rx = radius > 0 ? ` rx="${radius}"` : "";
+  return `<svg ${NS} viewBox="${MARK_VIEWBOX}"><rect width="1024" height="1024"${rx} fill="${bg}"/><g ${markPaintAttrs(app, fg)}>${pathElements(app)}</g></svg>\n`;
+}
+
+/** Android adaptive-icon layer: 432 canvas, glyph scaled into the 288 inner square. */
+export function appAdaptiveSvg(app: AppName, color: string): string {
+  const scale = 288 / 1024;
+  return `<svg ${NS} viewBox="0 0 432 432"><g transform="translate(216 216) scale(${scale}) translate(-512 -512)" ${markPaintAttrs(app, color)}>${pathElements(app)}</g></svg>\n`;
+}
+
+/** Chrome extension 128px icon: 96px tile plus 16px transparent padding. */
+export function appExtension128Svg(app: AppName): string {
+  const inner = appTileSvg(app).replace(`<svg ${NS} viewBox="${MARK_VIEWBOX}">`, `<svg ${NS} x="16" y="16" width="96" height="96" viewBox="${MARK_VIEWBOX}">`);
+  return `<svg ${NS} viewBox="0 0 128 128">${inner.trim()}</svg>\n`;
+}
+
+export const APP_MARK_SVG = Object.fromEntries(APP_NAMES.map((app) => [app, appMarkSvg(app)])) as Record<AppName, string>;
+export const APP_TILE_SVG = Object.fromEntries(APP_NAMES.map((app) => [app, appTileSvg(app)])) as Record<AppName, string>;
+export const APP_TILE_LIGHT_SVG = Object.fromEntries(APP_NAMES.map((app) => [app, appTileSvg(app, "light")])) as Record<AppName, string>;

package/src/index.ts

@@ -143,7 +143,7 @@ export * from "./ai-elements/sources";
 export * from "./ai-elements/speech-input";
 export * from "./ai-elements/suggestion";
 
-// Agent activity and run surfaces (moved from eva): the activity timeline and
+// Agent activity and run surfaces (moved from an app): the activity timeline and
 // its step model, Trace lines, plan, test results, web preview, context usage
 // and the model picker.
 export * from "./ai-elements/activity-shared";
@@ -289,11 +289,21 @@ export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-
 export { SiteFooter } from "./marketing/SiteFooter";
 export type { SiteFooterLink, SiteFooterProps, SiteFooterSocial } from "./marketing/SiteFooter";
 export { PricingModal } from "./marketing/PricingModal";
-export type { PricingModalProps } from "./marketing/PricingModal";
+export type {
+  PricingModalLegacyProps,
+  PricingModalMultiProps,
+  PricingModalPeriod,
+  PricingModalProps,
+  PricingPlan,
+  PricingPlanBenefit,
+} from "./marketing/PricingModal";
 
 // App helpers: confirm skip, update watcher, settings chrome, stable auth, Convex provider, VITE env and ensure-user.
 export * from "../app/src/index";
 
+// Family app marks (AppMark and raw SVG strings for favicons).
+export * from "./brand";
+
 // Native tokens (JS values that match tokens.css).
 export { tokens } from "../tokens/src/native";
 export type { Tokens } from "../tokens/src/native";

package/src/marketing/PricingModal.tsx

@@ -1,11 +1,17 @@
-import type { ReactElement, ReactNode } from "react";
+import { useRef, useState, type ReactElement, type ReactNode } from "react";
 import { IconCheck, IconX } from "@tabler/icons-react";
+import { AppMark } from "../brand/AppMark";
+import type { AppName } from "../brand/svg";
 import { Button } from "../ui/button";
 import { Dialog, DialogContent, DialogDescription, DialogTitle } from "../ui/dialog";
 import { VisuallyHidden } from "../ui/visually-hidden";
-import { pricingModalClasses, type PricingModalTone } from "./marketing-classes";
+import { pricingModalClasses, pricingMultiClasses, type PricingModalTone } from "./marketing-classes";
 
-export type PricingModalProps = {
+export type PricingModalPeriod = "month" | "year";
+
+export type PricingModalLegacyProps = {
+  /** Absent in the single-plan layout. Set `plans` for the multi-plan layout. */
+  plans?: undefined;
   open: boolean;
   /** Called when the dialog asks to close and by the `closeButton`. */
   onClose: () => void;
@@ -19,6 +25,21 @@ export type PricingModalProps = {
   wordmark: string;
   /** For example "$9". */
   price: string;
+  /** Adds a monthly/yearly toggle. Without it the modal is monthly only and `price` is the only price. */
+  yearly?: {
+    /** Yearly price per month, for example "$8.33". */
+    pricePerMonth: string;
+    /** Yearly total shown in the note, for example "$100". */
+    total?: string;
+    /** Badge on the yearly option. Default "Save 2 months". */
+    saveLabel?: string;
+  };
+  /** Selected period, when the parent controls it. Needs `yearly`. */
+  billingPeriod?: PricingModalPeriod;
+  /** Called with the period the user picks. */
+  onBillingPeriodChange?: (period: PricingModalPeriod) => void;
+  /** Initial period when `billingPeriod` is not set. Default `"month"`. */
+  defaultBillingPeriod?: PricingModalPeriod;
   tagline: ReactNode;
   /** Extra font class on the tagline, placed after `max-w-[28ch]`. */
   taglineFontClassName?: string;
@@ -26,16 +47,75 @@ export type PricingModalProps = {
   features: readonly string[];
   /** Label of the full-width checkout button. Default "Get Pro". */
   ctaLabel?: string;
-  /** Wraps the checkout button, for example in the billing provider's checkout and signed-in gates. */
-  renderCheckout: (button: ReactElement) => ReactNode;
+  /** Wraps the checkout button, for example in the billing provider's checkout and signed-in gates. `period` is the selected period, for `planPeriod`; it is always `"month"` without `yearly`. */
+  renderCheckout: (button: ReactElement, period: PricingModalPeriod) => ReactNode;
   /** Second, compact close button in the top-right corner. Default `false`. */
   closeButton?: boolean;
   /** Secondary text colour class. Default `"muted"`. */
   tone?: PricingModalTone;
 };
 
-/** Single-plan upgrade dialog: brand header with price and tagline, checkout button and feature list. */
-export function PricingModal({
+export type PricingPlanBenefit = {
+  label: ReactNode;
+  /** `"check"` (default) or an app mark. */
+  icon?: "check" | AppName;
+  /** Dimmed row. */
+  muted?: boolean;
+};
+
+export type PricingPlan = {
+  id: string;
+  name: string;
+  /** Display strings per month, for example `{ month: "$10", year: "$8" }`. The yearly price is still per month. */
+  price: { month: string; year: string };
+  /** Default "Get started". */
+  ctaLabel?: string;
+  /** Line above the highlight, for example "Everything in Free, and:". */
+  intro?: ReactNode;
+  /** Large title with small text under it. */
+  highlight?: { title: string; description: string };
+  benefits?: readonly PricingPlanBenefit[];
+  /** The plan the user is on: the button reads "Current plan" and is disabled. */
+  current?: boolean;
+  /** Subtle ring on the card. `highlighted` is an alias. */
+  featured?: boolean;
+  highlighted?: boolean;
+  /** Text after the price. Default "/month". */
+  periodSuffix?: string;
+};
+
+export type PricingModalMultiProps = {
+  open: boolean;
+  onClose: () => void;
+  /** Accessible dialog title. Not visible. */
+  title: string;
+  /** Accessible description. Not visible. */
+  description?: string;
+  /** Cards, left to right. Sized for 1 to 4. */
+  plans: readonly PricingPlan[];
+  /** App marks at the top left. */
+  apps?: readonly AppName[];
+  /** Centred headline, for example "One plan. Every V app." */
+  headline?: ReactNode;
+  /** Small print under the cards. */
+  finePrint?: ReactNode;
+  billingPeriod?: PricingModalPeriod;
+  onBillingPeriodChange?: (period: PricingModalPeriod) => void;
+  /** Default `"month"`. */
+  defaultBillingPeriod?: PricingModalPeriod;
+  /** Wraps each plan's button, for example in the billing provider's checkout. Not called for the `current` plan. */
+  renderCheckout: (button: ReactElement, plan: PricingPlan, period: PricingModalPeriod) => ReactNode;
+  tone?: PricingModalTone;
+};
+
+export type PricingModalProps = PricingModalLegacyProps | PricingModalMultiProps;
+
+/** Upgrade dialog. With `plans`: wide multi-plan layout. Without: the single-plan layout. */
+export function PricingModal(props: PricingModalProps) {
+  return props.plans ? <PricingModalMulti {...props} /> : <PricingModalSingle {...props} />;
+}
+
+function PricingModalSingle({
   open,
   onClose,
   title,
@@ -43,6 +123,10 @@ export function PricingModal({
   logo,
   wordmark,
   price,
+  yearly,
+  billingPeriod,
+  onBillingPeriodChange,
+  defaultBillingPeriod = "month",
   tagline,
   taglineFontClassName,
   features,
@@ -50,8 +134,14 @@ export function PricingModal({
   renderCheckout,
   closeButton = false,
   tone = "muted",
-}: PricingModalProps) {
+}: PricingModalLegacyProps) {
   const c = pricingModalClasses[tone];
+  const [localPeriod, setLocalPeriod] = useState<PricingModalPeriod>(defaultBillingPeriod);
+  const period: PricingModalPeriod = yearly ? (billingPeriod ?? localPeriod) : "month";
+  const selectPeriod = (next: PricingModalPeriod) => {
+    setLocalPeriod(next);
+    onBillingPeriodChange?.(next);
+  };
   const taglineClass = ["mt-4 max-w-[28ch]", taglineFontClassName, c.tagline].filter(Boolean).join(" ");
   return (
     <Dialog open={open} onOpenChange={(next) => !next && onClose()}>
@@ -87,9 +177,27 @@ export function PricingModal({
             </span>
           </div>
 
-          <div className="mt-8 flex items-end gap-2">
+          {yearly ? (
+            <div role="group" aria-label="Billing period" className="mt-8 inline-flex rounded-lg bg-surface-tertiary p-0.5">
+              {(["month", "year"] as const).map((value) => (
+                <button
+                  key={value}
+                  type="button"
+                  aria-pressed={period === value}
+                  onClick={() => selectPeriod(value)}
+                  className={`rounded-md px-3 py-1 text-xs font-medium transition-colors duration-100 ${
+                    period === value ? "bg-segment text-segment-foreground" : "text-muted-foreground hover:text-foreground"
+                  }`}
+                >
+                  {value === "month" ? "Monthly" : `Yearly · ${yearly.saveLabel ?? "Save 2 months"}`}
+                </button>
+              ))}
+            </div>
+          ) : null}
+
+          <div className={yearly ? "mt-5 flex items-end gap-2" : "mt-8 flex items-end gap-2"}>
             <span className="text-5xl font-medium tabular-nums leading-none tracking-tight text-foreground">
-              {price}
+              {yearly && period === "year" ? yearly.pricePerMonth : price}
             </span>
             <span className={c.period}>/ month</span>
           </div>
@@ -102,9 +210,14 @@ export function PricingModal({
             <Button size="lg" className="h-11 w-full rounded-xl">
               {ctaLabel}
             </Button>,
+            period,
           )}
 
-          <p className={c.note}>Cancel anytime. Billed monthly.</p>
+          <p className={c.note}>
+            {period === "year"
+              ? `Cancel anytime. ${yearly?.total ? `${yearly.total} billed yearly.` : "Billed yearly."}`
+              : "Cancel anytime. Billed monthly."}
+          </p>
 
           <div className="mt-8">
             <p className={c.featuresHeading}>What you get</p>
@@ -124,3 +237,163 @@ export function PricingModal({
     </Dialog>
   );
 }
+
+const multiWidth = {
+  1: "sm:max-w-md",
+  2: "sm:max-w-3xl",
+  3: "sm:max-w-5xl",
+  4: "sm:max-w-6xl",
+} as const;
+
+const multiColumns = {
+  1: "",
+  2: "sm:grid-cols-2",
+  3: "md:grid-cols-3",
+  4: "sm:grid-cols-2 lg:grid-cols-4",
+} as const;
+
+function PricingModalMulti({
+  open,
+  onClose,
+  title,
+  description,
+  plans,
+  apps,
+  headline,
+  finePrint,
+  billingPeriod,
+  onBillingPeriodChange,
+  defaultBillingPeriod = "month",
+  renderCheckout,
+  tone = "muted",
+}: PricingModalMultiProps) {
+  const c = pricingMultiClasses[tone];
+  const [localPeriod, setLocalPeriod] = useState<PricingModalPeriod>(defaultBillingPeriod);
+  const period = billingPeriod ?? localPeriod;
+  const selectPeriod = (next: PricingModalPeriod) => {
+    setLocalPeriod(next);
+    onBillingPeriodChange?.(next);
+  };
+  const contentRef = useRef<HTMLDivElement>(null);
+  const count = Math.min(Math.max(plans.length, 1), 4) as 1 | 2 | 3 | 4;
+  return (
+    <Dialog open={open} onOpenChange={(next) => !next && onClose()}>
+      <DialogContent
+        ref={contentRef}
+        hideCloseButton
+        // Focus the dialog, not the first segment button, so no ring shows on open.
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          contentRef.current?.focus();
+        }}
+        className={`max-h-[calc(100dvh-2rem)] gap-0 overflow-y-auto p-0 font-sans sm:w-[calc(100vw-2rem)] ${multiWidth[count]}`}
+      >
+        <DialogTitle className="sr-only">{title}</DialogTitle>
+        {description ? <DialogDescription className="sr-only">{description}</DialogDescription> : null}
+
+        <div className="grid grid-cols-[1fr_auto] items-center gap-x-4 gap-y-3 px-4 pb-4 pt-5 sm:grid-cols-[1fr_auto_1fr] sm:px-6">
+          <div className="flex items-center gap-2 text-foreground" data-testid="pricing-apps">
+            {apps?.map((app) => <AppMark key={app} app={app} variant="tile" size={24} className="rounded-md" />)}
+          </div>
+          <div className="flex items-center justify-end gap-2 sm:order-last">
+            <div role="group" aria-label="Billing period" className="inline-flex rounded-full bg-surface-tertiary p-0.5">
+              {(["month", "year"] as const).map((value) => (
+                <button
+                  key={value}
+                  type="button"
+                  aria-pressed={period === value}
+                  onClick={() => selectPeriod(value)}
+                  className={`rounded-full px-3 py-1 text-xs font-medium transition-colors duration-150 motion-reduce:transition-none ${
+                    period === value ? "bg-segment text-segment-foreground" : `${c.switchIdle} hover:text-foreground`
+                  }`}
+                >
+                  {value === "month" ? "Monthly" : "Annual"}
+                </button>
+              ))}
+            </div>
+            <button
+              type="button"
+              onClick={onClose}
+              className="flex size-8 items-center justify-center rounded-full text-muted-foreground transition-[background-color,transform] duration-100 ease-out hover:bg-surface-tertiary hover:text-foreground active:scale-[0.96] motion-reduce:transition-none"
+            >
+              <IconX className="size-4" />
+              <span className="sr-only">Close</span>
+            </button>
+          </div>
+          {headline ? (
+            <p className="col-span-2 text-balance text-center text-xl font-medium tracking-tight text-foreground sm:order-none sm:col-span-1 sm:text-2xl">
+              {headline}
+            </p>
+          ) : (
+            <span className="hidden sm:block" />
+          )}
+        </div>
+
+        <div className={`grid grid-cols-1 gap-3 px-4 sm:px-6 ${multiColumns[count]}`}>
+          {plans.map((plan) => {
+            const emphasised = plan.featured ?? plan.highlighted;
+            const button = (
+              <Button
+                size="lg"
+                variant={plan.current ? "outline" : emphasised ? "default" : "secondary"}
+                disabled={plan.current}
+                className="h-12 w-full rounded-full"
+              >
+                {plan.current ? "Current plan" : (plan.ctaLabel ?? "Get started")}
+              </Button>
+            );
+            return (
+              <section
+                key={plan.id}
+                data-plan={plan.id}
+                aria-label={plan.name}
+                className={`flex flex-col rounded-3xl bg-surface-secondary p-5 ${
+                  emphasised ? "ring-1 ring-foreground/25" : "ring-1 ring-separator"
+                }`}
+              >
+                <h3 className="text-base text-foreground">{plan.name}</h3>
+                <p className="mt-4 flex items-baseline gap-1">
+                  <span className="text-5xl font-medium tabular-nums leading-none tracking-tight text-foreground">
+                    {plan.price[period]}
+                  </span>
+                  <span className={c.suffix}>{plan.periodSuffix ?? "/month"}</span>
+                </p>
+                <div className="mt-5">{plan.current ? button : renderCheckout(button, plan, period)}</div>
+                {plan.intro ? <p className={`mt-6 text-sm ${c.suffix}`}>{plan.intro}</p> : null}
+                {plan.highlight ? (
+                  <div className="mt-3">
+                    <p className="text-2xl font-medium leading-tight text-foreground">{plan.highlight.title}</p>
+                    <p className="text-sm text-foreground">{plan.highlight.description}</p>
+                  </div>
+                ) : null}
+                {plan.benefits?.length ? (
+                  <ul className="mt-5 space-y-2.5 border-t border-separator pt-4">
+                    {plan.benefits.map((benefit, index) => (
+                      <li
+                        key={index}
+                        className={`flex items-start gap-2.5 text-sm leading-snug ${
+                          benefit.muted ? c.suffix : "text-foreground"
+                        }`}
+                      >
+                        <span className="mt-0.5 flex size-4 shrink-0 items-center justify-center">
+                          {benefit.icon && benefit.icon !== "check" ? (
+                            <AppMark app={benefit.icon} size={16} />
+                          ) : (
+                            <IconCheck className="size-4" strokeWidth={2} />
+                          )}
+                        </span>
+                        <span>{benefit.label}</span>
+                      </li>
+                    ))}
+                  </ul>
+                ) : null}
+              </section>
+            );
+          })}
+        </div>
+
+        {finePrint ? <p className={`px-4 pb-5 pt-4 text-xs sm:px-6 ${c.suffix}`}>{finePrint}</p> : <div className="pb-4" />}
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/marketing/marketing-classes.ts

@@ -113,3 +113,15 @@ export const pricingModalClasses = {
 } as const;
 
 export type PricingModalTone = keyof typeof pricingModalClasses;
+
+/** Multi-plan `PricingModal` secondary text classes for the two tones. */
+export const pricingMultiClasses = {
+  muted: {
+    suffix: "text-muted", // check-tokens-allow: text-muted
+    switchIdle: "text-muted", // check-tokens-allow: text-muted
+  },
+  "muted-foreground": {
+    suffix: "text-muted-foreground",
+    switchIdle: "text-muted-foreground",
+  },
+} as const;

package/tokens/README.md

@@ -0,0 +1,120 @@
+# `@vvedantb/ui/tokens`
+
+Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and Tailwind preset are subpaths of `@vvedantb/ui`; the native JS tokens are named exports of the root (`tokens`, `Tokens`). Source-exported: no build step. Paths in the `File` column are relative to `packages/ui/tokens/`.
+
+## Exports
+
+| Export | File | What it is |
+| --- | --- | --- |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. From 0.16.3 `--field-radius` (`rounded-field`) is `min(var(--radius), 0.625rem)`, the same cap as `rounded-control` (was `1.25rem`). 0.7.2 adds `--sidebar-accent` / `sidebar-accent` (sidebar nav row fill: light `var(--surface-tertiary)`, dark `oklch(22.64% 0 0)`). In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. From 0.15.0 it imports `clear-input.css`, `scrollbar-thin.css` and `motion.css`, sets the `--modal-*` and `--tabs-*` motion variables on `:root`, and defines `.glass-panel-strong` (`var(--overlay)`) and `.sidebar-section-label`. |
+| `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
+| `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
+| `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
+| `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
+| `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tabs` container (0.15.0), `.t-tab` with its press scale, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
+| `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target` and `@utility reveal-on-hover`. `rounded-surface` moved to `tokens.css` in 0.7.1. |
+| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). Imported by `tokens.css` from 0.15.0. |
+| `@vvedantb/ui/tokens/css/clear-input.css` | `src/css/clear-input.css` | `ClearInput` layers (`.t-clear*`) and the `--clear-*` / `--glow-*` timings. Imported by `tokens.css`. From 0.15.1 the layers clip in `.t-clear-clip`, so `.t-clear` keeps the focus ring, and the placeholder layer only shows during `.is-clearing`. |
+| `@vvedantb/ui/tokens/css/motion.css` | `src/css/motion.css` | `.ui-page-enter`, `.ui-enter`, `.ui-enter-up`, `.ui-stagger`, their keyframes and reduced-motion rules, and the `html[data-page-motion="off"]` overrides for `PageMotionProvider`. Imported by `tokens.css`. |
+| `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
+| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` (both `min(var(--radius), 0.625rem)` from 0.16.3), the same three radius utilities as `tokens.css` and `.glass-panel-strong` (solid `--popover` from 0.15.0). Import it **or** `tokens.css`, never both. |
+| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + modal + tabs + tabs-pills + utilities + animations + nav-icons, for new CSS-first apps (`tokens.css` brings scrollbar-thin). |
+| `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
+
+Every file was extracted because the same rule (same at-rule context, selector and body) sits in 3 or more of the five apps. The measured duplication is in `verify/ANALYSIS.md`, and the proof that each app compiles to the same CSS after migrating is in `verify/RESULTS.md`. Blocks that only 2 apps share, or that drift in a way that would change an app's CSS, stay in the apps; `verify/ANALYSIS.md` lists them.
+
+## Use
+
+CSS-first app (no `tailwind.config`):
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@import "@vvedantb/ui/tokens/css/animations.css";
+@import "@vvedantb/ui/tokens/css/base.css";
+/* ...app @layer base rules... */
+@import "@vvedantb/ui/tokens/css/modal.css";
+@import "@vvedantb/ui/tokens/css/tabs.css";
+/* ...app @layer components rules... */
+/* no --modal-* / --tabs-* needed: tokens.css sets them */
+```
+
+App with a JS config (`@config "../tailwind.config.ts"`):
+
+```ts
+import { tokensPreset } from "@vvedantb/ui/tokens/tailwind-preset";
+
+export default {
+  presets: [tokensPreset()],
+  // or tokensPreset({ color: (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)` })
+  content: ["./src/**/*.{ts,tsx}"],
+  theme: { extend: { /* app-only colours, fonts, animations */ } },
+  plugins: [tailwindcssAnimate],
+};
+```
+
+The preset holds `darkMode: "class"`, the shared colour map (`border`, `surface.*`, `danger.*`, `field.*`, shadcn aliases `primary`/`secondary`/`destructive`/`card`/`popover`/`input` ...), `borderRadius` lg/md/sm/field, `boxShadow` soft/panel/insetSoft, `ease-smooth`, `screens` xs to 2xl in px, and the aurora / fade-in-up / indeterminate / accordion keyframes. It does not hold plugins, `content`, fonts, `accent`/`muted`/`ring`/`sidebar` (they differ per app) or accordion timings.
+
+Do not import `css/animations.css` in an app that uses the preset: the preset already defines the same keyframes and animations.
+
+### Where to put the imports
+
+Tailwind inlines an `@import` where it sits, even in the middle of a file (it must be at top level, not inside an `@layer` block). Put each import where the app's own copy of the rules was. Within one layer, later rules win at equal specificity, so moving shared rules above or below app rules can flip the result for elements matched by both. `examples/migration.md` gives the exact position for each app, and `pnpm --filter @vvedantb/ui verify` checks it.
+
+### Variables each file needs
+
+| File | Needs | Provided by |
+| --- | --- | --- |
+| `base.css` | `--accent`, `--foreground` | tokens.css or the app theme |
+| `dialog.css` | none | |
+| `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | tokens.css (0.15.0), or app `:root` with the compat file |
+| `tabs.css` | `--tabs-dur`, `--tabs-ease` (tokens.css, or app `:root` with the compat file); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
+| `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
+| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
+| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
+| `clear-input.css`, `motion.css` | none (own `:root` defaults) | |
+| `animations.css` | none | |
+| `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
+
+### Using an existing shadcn RGB theme
+
+See the package `README.md`. With the compat file, `base.css`, `scrollbar-thin.css`, `clear-input.css`, `motion.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css` (`modal.css` and `tabs.css` then need the `--modal-*` / `--tabs-*` values on the app `:root`). `base.css` reads `--accent` and `--foreground` and `tabs-pills.css` reads `--muted`, `--segment` and `--default`. Those are not channel-compatible, so skip `tabs-pills.css` and `index.css` (which includes `base.css`) unless the app defines those variables as full colours.
+
+### Parameters
+
+Where apps share a rule but drifted in one value, the value is a custom property whose fallback is the most common value. Set it on `:root` to keep a different value.
+
+| File | Property | Default | Set by |
+| --- | --- | --- | --- |
+| `base.css` | `--tokens-control-transition-property` | `background-color, border-color, color, box-shadow, transform, opacity` | app-c: `background-color, color, transform, opacity` |
+| `base.css` | `--tokens-control-transition-duration` | `240ms` | app-c: `100ms` |
+
+From 0.15.0 the files that moved out of the apps take `:root` variables too. Every rule is in a Tailwind layer, so an app rule for the same selector (unlayered, or later in the same layer) also wins.
+
+| File | Property | Default |
+| --- | --- | --- |
+| `tokens.css` | `--modal-open-dur`, `--modal-close-dur` | `180ms`, `120ms` |
+| `tokens.css` | `--modal-scale`, `--modal-scale-close` | `0.96`, `0.96` |
+| `tokens.css` | `--modal-ease`, `--tabs-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `tokens.css` | `--tabs-dur` | `200ms` |
+| `tokens.css` | `--sidebar-section-label-mix`, `--sidebar-section-label-hover-mix` | `55%`, `80%` (share of `--muted`) |
+| `scrollbar-thin.css` | `--scrollbar-thin-rest`, `--scrollbar-thin-hover` | `40%`, `80%` (share of `--scrollbar`) |
+| `clear-input.css` | `--clear-dur`, `--clear-out-dur`, `--clear-in-dur` | `1000ms`, `400ms`, `400ms` |
+| `clear-input.css` | `--clear-out-fly`, `--clear-in-fly` | `12px`, `12px` |
+| `clear-input.css` | `--clear-out-ease`, `--clear-in-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `clear-input.css` | `--glow-delay`, `--glow-peak-at`, `--glow-opacity`, `--glow-spread` | `50ms`, `0.15`, `0.85`, `1.5` |
+| `motion.css` | `--ui-enter-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` |
+| `motion.css` | `--ui-page-enter-dur`, `--ui-enter-dur`, `--ui-enter-up-dur` | `160ms`, `200ms`, `220ms` |
+| `motion.css` | `--ui-stagger-step` | `40ms` (children 1 to 8) |
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui build     # export targets exist + tsc (primitives, shell, app)
+pnpm --filter @vvedantb/ui test      # vitest (app helpers) + offline node --test: exports, CSS structure, Tailwind compile, preset
+pnpm --filter @vvedantb/ui analyze   # rule-level duplication across the app clones -> verify/ANALYSIS.tables.md
+pnpm --filter @vvedantb/ui verify    # before/after compile of every app -> verify/RESULTS.md, examples/migration.md
+```
+
+`analyze` and `verify` need the app clones (`APPS_DIR`, default `/workspace/cvx`; name or symlink the clones `app-a` to `app-e` inside it) and network access the first time: they install Tailwind 4.3.3, the plugins, postcss and jiti into a scratch directory (`VERIFY_DIR`, default `/workspace/pk-tokens-verify`, outside the repo). The migration for each app is data in `verify/migrations/<app>.json`. Each removed block must equal the shared file's block with the same context and selector, or the run fails.