@vvedantb/ui 0.31.0 → 0.31.1

package/README.md

@@ -893,9 +893,11 @@ links under a separator.
 ### `Icon*` app icons
 
 Tabler-style plain app glyphs: `IconVibot`, `IconVhub`, `IconVmem`, `IconVerve`,
-`IconVelth` and `IconProjectV`. No background. Each sits on an equalised square viewBox, so all apps look the same size. `APP_ICONS[app]`
+`IconVelth`, `IconProjectV`, `IconEva` and `IconBee`. No background. Each sits on an equalised square viewBox, so all apps look the same size. `APP_ICONS[app]`
 looks one up by `AppName`.
 
+`IconEva` (a filled four-point star) and `IconBee` (an orb with eyes, stripes and antennae) are icons only. `eva` and `bee` are in `APP_NAMES`, `APP_MARKS` and `APP_ICONS`, but not in `FAMILY_APPS` or `V_PRO_APP_BENEFITS`, and `AppWordmark` and `PricingModal` do not take them.
+
 ```tsx
 import { IconVerve } from "@vvedantb/ui"
 
@@ -951,13 +953,14 @@ import { AppWordmark } from "@vvedantb/ui"
 ### `AppMark` (deprecated)
 
 Deprecated in favour of the `Icon*` components for plain marks. Tiles stay here.
-Family app icons: `app` (`projectv`, `vibot`, `vhub`, `vmem`, `verve`, `velth`),
+Family app icons: `app` (`projectv`, `vibot`, `vhub`, `vmem`, `verve`, `velth`, and the icon-only `eva` and `bee`),
 `variant`, `size`, `title`.
 
 - `variant="mark"` (default) is the plain logo in `currentColor`. It sits
   on a square viewBox. The five apps (`vibot`, `vhub`, `vmem`, `verve`, `velth`) keep one
   frame size, 629 x 629 (`APP_MARK_CROP_VIEWBOX` is the historical `173 197 629 629`), so relative
-  glyph sizes match the tiles. Each viewBox origin is centred on that glyph's `markBBox`, so no
+  glyph sizes match the tiles. `eva` and `bee` use the same 629 side, but the historical crop does not
+  include them. Each viewBox origin is centred on that glyph's `markBBox`, so no
   glyph sits off-centre in its square. `projectv` is a brand mark, so it keeps its own 687 frame,
   centred on its bbox (`PROJECTV_MARK_VIEWBOX`, `171.5 181 687 687`). `size` sets both width and
   height; a string `size` (for example `"2rem"`) is any CSS length. `APP_MARK_VIEWBOX` holds the
@@ -982,7 +985,7 @@ default) and `renderCheckout`.
 
 #### Multi-plan (0.22.0)
 
-Header: `apps` (an `AppName[]`, shown as plain `Icon*` logos at the top left; each links to the app's site in a new tab and shows its display name in a tooltip, from `FAMILY_APPS`),
+Header: `apps` (a `FamilyAppName[]`, shown as plain `Icon*` logos at the top left; each links to the app's site in a new tab and shows its display name in a tooltip, from `FAMILY_APPS`),
 `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.
@@ -997,7 +1000,7 @@ outlined "Current plan" button and does not call `renderCheckout`.
 
 `appBenefits` (`{ app, items }[]`, type `PricingPlanAppBenefit`) groups benefits per app, each under a small heading with that app's icon and display name. It renders after `benefits` and scrolls inside the card when long. Set `currentApp` on the modal to put that app's group first; the other groups keep the array order. The `featured` / `highlighted` plan uses `V_PRO_APP_BENEFITS` (the approved V Pro copy, in the order vibot, vmem, vhub, velth, verve) when it omits `appBenefits`, so apps usually pass only `currentApp`. Other plans show app benefits only when set.
 
-`FAMILY_APPS` (and `familyApp(app)`), exported from the root and `@vvedantb/ui/brand`, is the single list of app display names and sites (`vibot`, `Verve`, `Velth`, `vmem`, `vhub`, `Project V`; URLs without a trailing slash). App names live only under `src/brand/`.
+`FAMILY_APPS` (and `familyApp(app)`), exported from the root and `@vvedantb/ui/brand`, is the single list of app display names and sites (`vibot`, `Verve`, `Velth`, `vmem`, `vhub`, `Project V`; URLs without a trailing slash). Its app type is `FamilyAppName`: `AppName` without the icon-only `eva` and `bee`. App names live only under `src/brand/`.
 
 The `featured` plan's button is a solid primary button (`Button` `variant="default"`). Other plans use `secondary`.
 
@@ -1308,7 +1311,13 @@ import { SonnerToaster, toast } from "@vvedantb/ui";
 />;
 ```
 
-With no new props and no `UiConfig.SonnerToaster` entry the toaster looks as it did in 0.2.1. An entry sets app defaults for any prop (see "App config: AI chat" below). Caller props merge with the package defaults instead of replacing them:
+With no new props and no `UiConfig.SonnerToaster` entry the toaster looks as it did in 0.2.1, except for three changes from 0.31.1:
+
+- Toasts sit at the top right (`position="top-right"`). Sonner's own default is bottom-right. Pass `position`, or set `UiConfig.SonnerToaster.position`, to move them.
+- The text column grows (`content`: `flex min-w-0 grow flex-col`). `unstyled` drops sonner's own grow, so without it the action button left a gap at the right edge. Apps no longer need to set `classes.content` for this.
+- The action and cancel buttons are 28px tall (`h-7 shrink-0 rounded-control px-2.5 text-xs`), up from 24px. The action button presses with `motion-press active:scale-[0.96]` (`motion-press` is an app utility) and hovers with `hover:bg-primary/90`. `classes.actionButton` replaces the string, and `toastOptions.classNames.actionButton` appends to it.
+
+A `UiConfig.SonnerToaster` entry sets app defaults for any prop (see "App config: AI chat" below). Caller props merge with the package defaults instead of replacing them:
 
 - `toastOptions.classNames`: per key, the package classes come first and the caller classes follow, so callers can override utilities. Other `toastOptions` fields (such as `duration`) take the caller value.
 - `icons`: merged per key. With `toastIcons="filled24"` the caller overrides single icons and keeps the rest.
@@ -1330,7 +1339,9 @@ Opt-in props (all default to the current look):
 
 With `closeButtonStyle="hoverChip"`, hover changes the text colour, and sonner may still change the background. The border stays `border-border` (pinned with `hover:border-border!` over sonner's dark hover border), so the ring does not brighten in dark mode.
 
-Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/`.
+Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/` (`update.html` shows the update toast).
+
+For the "Update available" toast, call `showUpdateAvailableToast({ toast, closeConvex })` or let `startUpdateAvailableWatcher` call it. See `app/README.md`.
 
 ## App config
 

package/app/README.md

@@ -0,0 +1,269 @@
+# 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 calls `showUpdateAvailableToast` once. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
+
+`showUpdateAvailableToast({ toast, closeConvex?, toastId?, reload? })` (from 0.31.1) shows the toast on its own, for an app with its own update signal:
+
+```ts
+import { showUpdateAvailableToast, toast } from "@vvedantb/ui";
+
+showUpdateAvailableToast({ toast, closeConvex: () => void convex.close() });
+```
+
+It shows a sticky "Update available" toast, "Refresh to load the latest version.", with a Refresh action. Refresh calls `closeConvex` (errors ignored), then reloads. The same `toastId` replaces an open toast instead of adding a second one. Mount `SonnerToaster`: from 0.31.1 its default `content` class grows the text column, so Refresh sits at the right edge without app classes.
+
+## 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/app/src/index.ts

@@ -17,7 +17,9 @@ export {
   fingerprintFromHtml,
 } from "./update/deployFingerprint.js";
 export {
+  showUpdateAvailableToast,
   startUpdateAvailableWatcher,
+  type ShowUpdateAvailableToastOptions,
   type UpdateAvailableWatcherOptions,
   type UpdateToastOptions,
 } from "./update/updateWatcher.js";

package/app/src/update/updateWatcher.ts

@@ -16,6 +16,7 @@ export type UpdateAvailableWatcherOptions = {
   closeConvex?: () => void;
   /** Poll interval in ms. Default 60000. */
   pollMs?: number;
+  /** Default `app-update-available`. */
   toastId?: string;
   /** Pass `!import.meta.env.DEV`. When false, nothing starts. Default true. */
   enabled?: boolean;
@@ -23,13 +24,47 @@ export type UpdateAvailableWatcherOptions = {
   reload?: () => void;
 };
 
+export type ShowUpdateAvailableToastOptions = Pick<
+  UpdateAvailableWatcherOptions,
+  "toast" | "closeConvex" | "toastId" | "reload"
+>;
+
 const DEFAULT_POLL_MS = 60_000;
 const DEFAULT_TOAST_ID = "app-update-available";
 
+/**
+ * Show the sticky "Update available" toast with a Refresh action. Refresh
+ * calls `closeConvex` (errors ignored), then reloads. The same `toastId`
+ * replaces an open toast instead of stacking a second one.
+ */
+export function showUpdateAvailableToast({
+  toast,
+  closeConvex,
+  toastId = DEFAULT_TOAST_ID,
+  reload = () => window.location.reload(),
+}: ShowUpdateAvailableToastOptions): void {
+  toast.message("Update available", {
+    id: toastId,
+    description: "Refresh to load the latest version.",
+    duration: Number.POSITIVE_INFINITY,
+    action: {
+      label: "Refresh",
+      onClick: () => {
+        try {
+          closeConvex?.();
+        } catch {
+          // socket may already be closed during teardown
+        }
+        reload();
+      },
+    },
+  });
+}
+
 /**
  * Poll the live index HTML for a new Vite asset fingerprint (and re-check when
- * the tab becomes visible). Shows a sticky "Update available" toast with a
- * Refresh action when a newer deploy is serving. Returns a stop function.
+ * the tab becomes visible). Calls `showUpdateAvailableToast` once when a newer
+ * deploy is serving. Returns a stop function.
  */
 export function startUpdateAvailableWatcher(
   options: UpdateAvailableWatcherOptions,
@@ -39,9 +74,9 @@ export function startUpdateAvailableWatcher(
     toast,
     closeConvex,
     pollMs = DEFAULT_POLL_MS,
-    toastId = DEFAULT_TOAST_ID,
+    toastId,
     enabled = true,
-    reload = () => window.location.reload(),
+    reload,
   } = options;
   if (!enabled) return () => {};
 
@@ -52,22 +87,7 @@ export function startUpdateAvailableWatcher(
   const showToast = (): void => {
     if (shown) return;
     shown = true;
-    toast.message("Update available", {
-      id: toastId,
-      description: "Refresh to load the latest version.",
-      duration: Number.POSITIVE_INFINITY,
-      action: {
-        label: "Refresh",
-        onClick: () => {
-          try {
-            closeConvex?.();
-          } catch {
-            // socket may already be closed during teardown
-          }
-          reload();
-        },
-      },
-    });
+    showUpdateAvailableToast({ toast, closeConvex, toastId, reload });
   };
 
   const check = async (): Promise<void> => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main 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), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",
@@ -72,6 +72,17 @@
     "./src/marketing/landing.css",
     "./fonts/instrument-sans.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",
@@ -161,6 +172,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",
@@ -184,8 +196,7 @@
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "zod3": "npm:zod@^3.25.76",
-    "@vvedantb/server": "0.10.0"
+    "zod3": "npm:zod@^3.25.76"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
@@ -206,15 +217,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",
-    "brand:assets": "node scripts/build-brand-assets.mjs",
-    "brand:sheet": "node scripts/build-brand-sheet.mjs"
   }
-}
+}

package/src/brand/AppIcons.tsx

@@ -72,3 +72,5 @@ export const IconVmem = APP_ICONS.vmem;
 export const IconVerve = APP_ICONS.verve;
 export const IconVelth = APP_ICONS.velth;
 export const IconProjectV = APP_ICONS.projectv;
+export const IconEva = APP_ICONS.eva;
+export const IconBee = APP_ICONS.bee;

package/src/brand/AppWordmark.tsx

@@ -3,8 +3,8 @@ import { cn } from "../utils/cn";
 import { APP_ICONS } from "./AppIcons";
 import type { AppName } from "./svg";
 
-/** The five product apps. `projectv` keeps its Michroma wordmark and never uses `AppWordmark`. */
-export type ProductAppName = Exclude<AppName, "projectv">;
+/** The five product apps. `projectv` keeps its Michroma wordmark and never uses `AppWordmark`. `eva` and `bee` are icons only. */
+export type ProductAppName = Exclude<AppName, "projectv" | "eva" | "bee">;
 
 export type AppWordmarkProps = Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel" | "aria-label" | "title" | "id"> & {
   /** Which product app's name to show. The label is always the lowercase app id. */

package/src/brand/familyApps.ts

@@ -1,7 +1,10 @@
 import type { AppName } from "./svg";
 
+/** Apps in the Project V family. `eva` and `bee` have marks and icons but are not family apps. */
+export type FamilyAppName = Exclude<AppName, "eva" | "bee">;
+
 export type FamilyApp = {
-  app: AppName;
+  app: FamilyAppName;
   /** Display name. */
   name: string;
   /** Home page of the app. */
@@ -19,6 +22,6 @@ export const FAMILY_APPS: readonly FamilyApp[] = [
 ];
 
 /** Entry of `FAMILY_APPS` for an app. */
-export function familyApp(app: AppName): FamilyApp {
+export function familyApp(app: FamilyAppName): FamilyApp {
   return FAMILY_APPS.find((entry) => entry.app === app)!;
 }

package/src/brand/index.ts

@@ -25,6 +25,6 @@ export {
 } from "./svg";
 export type { AppMarkVariant, AppName, MarkShape } from "./svg";
 export { FAMILY_APPS, familyApp } from "./familyApps";
-export type { FamilyApp } from "./familyApps";
+export type { FamilyApp, FamilyAppName } from "./familyApps";
 export { V_PRO_APP_BENEFITS } from "./vProAppBenefits";
 export type { PricingPlanAppBenefit } from "./vProAppBenefits";

package/src/brand/svg.ts

@@ -1,7 +1,8 @@
 // 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;
+/** Every mark. `eva` and `bee` are marks and icons only: they are not family apps, so `FAMILY_APPS` leaves them out. */
+export const APP_NAMES = ["projectv", "vibot", "vhub", "vmem", "verve", "velth", "eva", "bee"] as const;
 
 export type AppName = (typeof APP_NAMES)[number];
 
@@ -36,7 +37,9 @@ export function markLinecap(app: AppName): "butt" | "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.
+ * `vibot`, `vhub`, `vmem` and `projectv` are traced from the approved 1024px renders. `eva` (option A,
+ * a filled four-point star) and `bee` (option D, an orb with eyes, stripes and antennae) are the final
+ * vectors from their design sheet, as drawn there.
  */
 export const APP_MARKS: Record<AppName, MarkShape> = {
   projectv: {
@@ -77,6 +80,22 @@ export const APP_MARKS: Record<AppName, MarkShape> = {
       "M512 732.3C644.2 652.1 734.3 471.9 724.3 301.6C604.1 371.7 524 552 512 732.3Z",
     ],
   },
+  eva: {
+    kind: "fill",
+    paths: ["M242.9 512Q485.1 485.1 512 278.8Q538.9 485.1 781 512Q538.9 538.9 512 745.1Q485.1 538.9 242.9 512Z"],
+  },
+  bee: {
+    kind: "stroke",
+    paths: [
+      "M304 530.7A208.1 208.1 0 1 1 720.1 530.7A208.1 208.1 0 1 1 304 530.7",
+      "M447.5 414.2L447.5 445.4",
+      "M576.5 414.2L576.5 445.4",
+      "M306.3 561.9L717.7 561.9",
+      "M344 653.4L680 653.4",
+      "M468.3 341.4Q455.8 291.4 420.5 260.2",
+      "M555.7 341.4Q568.2 291.4 603.5 260.2",
+    ],
+  },
 };
 
 type Point = [number, number];
@@ -180,6 +199,7 @@ export function markBBox(app: AppName): Box {
  * (x 186 to 789, y 259.96 to 761.7) at side max(width, height) x 1.04 (about 4% padding), rounded outward.
  * All five use this side, so glyph scale stays equal. Only the size is shared: each app has its own origin in
  * `APP_MARK_VIEWBOX`. `projectv` is left out so its wide brand mark does not shrink the app glyphs.
+ * Historical: this union covers those five only. `eva` and `bee` reuse the 629 side but are not part of it.
  */
 export const APP_MARK_CROP_VIEWBOX = "173 197 629 629";
 
@@ -190,9 +210,9 @@ export const APP_MARK_CROP_VIEWBOX = "173 197 629 629";
 export const PROJECTV_MARK_VIEWBOX = "171.5 181 687 687";
 
 /**
- * Plain-mark viewBox per app. Always square. The five apps keep one 629 side (equal scale), and each origin is
- * `markBBox(app)` centre minus 314.5 on both axes, so every glyph sits centred in its own frame. `projectv` uses
- * its 687 frame, centre minus 343.5. Hardcoded; checked against `markBBox` in tests.
+ * Plain-mark viewBox per app. Always square. Every mark except `projectv` keeps one 629 side (equal scale), and each
+ * origin is `markBBox(app)` centre minus 314.5 on both axes, so every glyph sits centred in its own frame. `projectv`
+ * uses its 687 frame, centre minus 343.5. Hardcoded; checked against `markBBox` in tests.
  */
 export const APP_MARK_VIEWBOX: Record<AppName, string> = {
   projectv: PROJECTV_MARK_VIEWBOX,
@@ -201,6 +221,8 @@ export const APP_MARK_VIEWBOX: Record<AppName, string> = {
   vmem: "197.24772201231343 196.33100022273135 629 629",
   verve: "197.5 210.9 629 629",
   velth: "197.5 202.45 629 629",
+  eva: "197.45 197.45 629 629",
+  bee: "197.55 187.2807619340906 629 629",
 };
 
 /**
@@ -215,6 +237,8 @@ export const APP_MARK_VIEWBOX_START: Record<AppName, string> = {
   vmem: "255.5301217210191 196.33100022273135 629 629",
   verve: "260.4 210.9 629 629",
   velth: "273.9433593555699 202.45 629 629",
+  eva: "242.9 197.45 629 629",
+  bee: "278.94999999999993 187.2807619340906 629 629",
 };
 
 /** Width over height of a mark's viewBox. Always about 1, because the viewBoxes are square. Kept for API stability; do not use it for sizing. */

package/src/brand/vProAppBenefits.ts

@@ -2,7 +2,7 @@ import type { AppName } from "./svg";
 
 /** Benefits for one app, shown under that app's icon and name. */
 export type PricingPlanAppBenefit = {
-  app: Exclude<AppName, "projectv">;
+  app: Exclude<AppName, "projectv" | "eva" | "bee">;
   items: readonly string[];
 };
 

package/src/client.ts

@@ -342,7 +342,9 @@ export { useRequestConfirm } from "../app/src/confirm/useRequestConfirm";
 export { ConfirmSkipHint, skipConfirmTitle } from "../app/src/confirm/ConfirmSkipHint";
 export { fetchDeployFingerprint, fingerprintFromHtml } from "../app/src/update/deployFingerprint";
 export {
+  showUpdateAvailableToast,
   startUpdateAvailableWatcher,
+  type ShowUpdateAvailableToastOptions,
   type UpdateAvailableWatcherOptions,
   type UpdateToastOptions,
 } from "../app/src/update/updateWatcher";

package/src/marketing/PricingModal.tsx

@@ -1,6 +1,6 @@
 import { useRef, useState, type ReactElement, type ReactNode } from "react";
 import { IconCheck, IconX } from "@tabler/icons-react";
-import { APP_ICONS, IconProjectV, V_PRO_APP_BENEFITS, familyApp, type AppIconProps, type AppName, type PricingPlanAppBenefit } from "../brand";
+import { APP_ICONS, IconProjectV, V_PRO_APP_BENEFITS, familyApp, type AppIconProps, type AppName, type FamilyAppName, type PricingPlanAppBenefit, type ProductAppName } from "../brand";
 import { Button } from "../ui/button";
 import { Dialog, DialogContent, DialogDescription, DialogTitle } from "../ui/dialog";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../ui/tooltip";
@@ -101,10 +101,10 @@ export type PricingModalMultiProps = {
   description?: string;
   /** Cards, left to right. Sized for 1 to 4. */
   plans: readonly PricingPlan[];
-  /** App marks at the top left. */
-  apps?: readonly AppName[];
+  /** App marks at the top left. Family apps only: each links to its `FAMILY_APPS` site. */
+  apps?: readonly FamilyAppName[];
   /** App the dialog is shown in. Its `appBenefits` group comes first. */
-  currentApp?: Exclude<AppName, "projectv">;
+  currentApp?: ProductAppName;
   /** Centred headline, for example "One plan. Every V app." */
   headline?: ReactNode;
   /** Small print under the cards. */

package/src/ui/__snapshots__/sonner-dom.test.tsx.snap

@@ -2,4 +2,4 @@
 
 exports[`SonnerToaster DOM > renders the toaster and a toast 1`] = `"<section aria-label="Notifications alt+T" tabindex="-1" aria-live="polite" aria-relevant="additions text" aria-atomic="false" data-react-aria-top-layer="true"></section>"`;
 
-exports[`SonnerToaster DOM > renders the toaster and a toast 2`] = `"<section aria-label="Notifications alt+T" tabindex="-1" aria-live="polite" aria-relevant="additions text" aria-atomic="false" data-react-aria-top-layer="true"><ol dir="ltr" tabindex="-1" class="toaster group !font-sans" data-sonner-toaster="true" data-sonner-theme="light" data-y-position="top" data-x-position="right" style="--front-toast-height: 0px; --width: 356px; --gap: 12px; --offset-top: 24px; --offset-right: 24px; --offset-bottom: 24px; --offset-left: 24px; --mobile-offset-top: 16px; --mobile-offset-right: 16px; --mobile-offset-bottom: 16px; --mobile-offset-left: 16px;"><li tabindex="0" class="group toast glass-panel-strong flex w-full items-center gap-3 rounded-lg px-4 py-3 text-sm text-foreground smooth-shadow-ring-md" data-sonner-toast="" data-styled="false" data-mounted="true" data-promise="false" data-swiped="false" data-removed="false" data-visible="true" data-y-position="top" data-x-position="right" data-index="0" data-front="true" data-swiping="false" data-dismissible="true" data-swipe-out="false" data-expanded="false" style="--index: 0; --toasts-before: 0; --z-index: 1; --offset: 0px; --initial-height: 0px;"><div data-content="" class=""><div data-title="" class="font-medium leading-snug">Saved</div><div data-description="" class="text-[13px] leading-snug text-muted-foreground">All changes stored</div></div></li></ol></section>"`;
+exports[`SonnerToaster DOM > renders the toaster and a toast 2`] = `"<section aria-label="Notifications alt+T" tabindex="-1" aria-live="polite" aria-relevant="additions text" aria-atomic="false" data-react-aria-top-layer="true"><ol dir="ltr" tabindex="-1" class="toaster group !font-sans" data-sonner-toaster="true" data-sonner-theme="light" data-y-position="top" data-x-position="right" style="--front-toast-height: 0px; --width: 356px; --gap: 12px; --offset-top: 24px; --offset-right: 24px; --offset-bottom: 24px; --offset-left: 24px; --mobile-offset-top: 16px; --mobile-offset-right: 16px; --mobile-offset-bottom: 16px; --mobile-offset-left: 16px;"><li tabindex="0" class="group toast glass-panel-strong flex w-full items-center gap-3 rounded-lg px-4 py-3 text-sm text-foreground smooth-shadow-ring-md" data-sonner-toast="" data-styled="false" data-mounted="true" data-promise="false" data-swiped="false" data-removed="false" data-visible="true" data-y-position="top" data-x-position="right" data-index="0" data-front="true" data-swiping="false" data-dismissible="true" data-swipe-out="false" data-expanded="false" style="--index: 0; --toasts-before: 0; --z-index: 1; --offset: 0px; --initial-height: 0px;"><div data-content="" class="flex min-w-0 grow flex-col"><div data-title="" class="font-medium leading-snug">Saved</div><div data-description="" class="text-[13px] leading-snug text-muted-foreground">All changes stored</div></div></li></ol></section>"`;

package/src/ui/sonner.tsx

@@ -14,6 +14,9 @@ import "./sonner.css";
 // neutral. Callers should pass `theme` so sonner's internal `data-theme`
 // attribute matches the active app theme.
 //
+// Position: `top-right` by default (sonner's own default is `bottom-right`), as
+// apps mount it. A `position` prop or `UiConfig.SonnerToaster.position` wins.
+//
 // Stacking: `expand={false}` keeps toasts collapsed (offset + scale). Hovering
 // the stack expands them. `sonner.css` hides back-toast content while collapsed
 // because `unstyled` disables sonner's built-in `data-styled` stack rules.
@@ -83,13 +86,31 @@ const hoverChipCloseButtonClassName =
 const defaultCloseButtonClassName =
   "rounded-lg bg-default px-2.5 py-1 text-xs font-medium text-foreground transition-colors hover:bg-default/78";
 
+// Action and cancel buttons: 28px tall (`h-7`), 10px side padding, 12px text,
+// `rounded-control` (10px), the classes apps already set through `classes`.
+// Measured on the toaster fixture's Refresh button: 28px tall, up from 24px with the 0.31.0
+// `px-2.5 py-1 rounded-lg` (16px radius) string. `shrink-0` keeps the button
+// from squeezing when the text column grows. `motion-press` is an app utility
+// (not in `tokens.css`), as in `BulkActionBar`.
+const defaultActionButtonClassName =
+  "h-7 shrink-0 rounded-control bg-primary px-2.5 text-xs font-medium text-primary-foreground motion-press active:scale-[0.96] hover:bg-primary/90";
+
+const defaultCancelButtonClassName =
+  "h-7 shrink-0 rounded-control bg-surface-secondary px-2.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-surface-tertiary";
+
+const defaultToasterPosition = "top-right" satisfies ToasterProps["position"];
+
 const toastRadiusClasses = {
   lg: "rounded-lg",
   surface: "rounded-surface",
   control: "rounded-field",
 } as const;
 
-/** Default `classNames`, with the opt-in variants applied. No options gives the 0.2.1 defaults. */
+/**
+ * Default `classNames`, with the opt-in variants applied. No options gives the
+ * 0.2.1 defaults, plus `content` and the 28px `actionButton` and `cancelButton`
+ * (from 0.31.1).
+ */
 function createToasterClassNames({
   toastRadius = "lg",
   density = "default",
@@ -111,14 +132,15 @@ function createToasterClassNames({
   const descriptionSize = compact ? "text-xs" : "text-[13px]";
   return {
     toast: `group toast glass-panel-strong flex w-full items-center ${compact ? "gap-2" : "gap-3"} ${radius} ${compact ? "px-3 py-2 text-xs" : "px-4 py-3 text-sm"} text-foreground smooth-shadow-ring-md${hideStackedContent ? ` ${hideStackedContentClassName}` : ""}`,
+    // `unstyled` drops sonner's `[data-content]` grow, so the text column grows
+    // here and the action and cancel buttons sit at the right edge.
+    content: "flex min-w-0 grow flex-col",
     title: titleLeading === "5" ? "font-medium leading-5" : "font-medium leading-snug",
     description: descriptionMuted
       ? `${descriptionSize} leading-snug text-muted-foreground!`
       : `${descriptionSize} leading-snug text-muted-foreground`,
-    actionButton:
-      "rounded-lg bg-primary px-2.5 py-1 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90",
-    cancelButton:
-      "rounded-lg bg-surface-secondary px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-surface-tertiary",
+    actionButton: defaultActionButtonClassName,
+    cancelButton: defaultCancelButtonClassName,
     closeButton:
       closeButtonStyle === "hoverChip"
         ? hoverChipCloseButtonClassName
@@ -192,6 +214,9 @@ function withConfigDefaults<T extends object>(defaults: Partial<T> | undefined,
 function SonnerToaster(props: ToasterProps & SonnerToasterOptions) {
   const {
     classes,
+    // Defaulted here, not by spreading after a literal, so `position={undefined}`
+    // still gets top-right rather than sonner's bottom-right.
+    position = defaultToasterPosition,
     toastRadius,
     density,
     toastIcons = "default",
@@ -223,6 +248,7 @@ function SonnerToaster(props: ToasterProps & SonnerToasterOptions) {
       visibleToasts={4}
       gap={12}
       {...rest}
+      position={position}
       closeButton={closeButton ?? (closeButtonStyle === "hoverChip" ? true : undefined)}
       className={
         toasterClassName && className

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.

package/tokens/examples/toaster/Fixture.tsx

@@ -44,6 +44,7 @@ export function Fixture() {
           <Button onClick={fire}>Show toast</Button>
         </div>
       </main>
+      {/* No `position`: the package default, top-right. */}
       <SonnerToaster
         theme={dark ? "dark" : "light"}
         toastRadius={compact ? "control" : "surface"}

package/tokens/examples/toaster/README.md

@@ -1,11 +1,12 @@
 # toaster fixture
 
-Renders `SonnerToaster` with every opt-in prop on (`toastRadius="surface"`, `toastIcons="filled24"`, `closeButtonStyle="hoverChip"`, `sonnerVars`, `descriptionMuted`). It fires one sample toast with a title and a description on load. The toast stays open. Use "Show toast" to fire another.
+Renders `SonnerToaster` with every opt-in prop on (`toastRadius="surface"`, `toastIcons="filled24"`, `closeButtonStyle="hoverChip"`, `sonnerVars`, `descriptionMuted`). It passes no `position`, so toasts show at the top right, the package default from 0.31.1. It fires one sample toast with a title and a description on load. The toast stays open. Use "Show toast" to fire another.
 
 | Page | Stylesheet |
 | --- | --- |
 | `/tokens.html` | `tokens.css` plus `utilities.css` (`styles-tokens.css`) |
 | `/compat.html` | `compat-shadcn-rgb.css` plus `utilities.css`, with sample `R G B` variables (`styles-compat.css`) |
+| `/update.html` | `tokens.css` plus `utilities.css` (`styles-tokens.css`). Fires the update toast from `showUpdateAvailableToast` on load, at the top right: title, description and a Refresh action that reloads the page. The Refresh button uses the package default (28px tall, `rounded-control`). "Show update toast" fires it again. |
 
 Each stylesheet declares `glass-panel-strong` (tokens page only) and `smooth-shadow-ring-md`. The app owns those toast classes. The compat page also defines `--success` and `--warning` and maps them to `--color-success` and `--color-warning`.
 
@@ -15,4 +16,4 @@ Run it from this folder (it is not a workspace member, and React resolves from t
 pnpm install --ignore-workspace && pnpm dev
 ```
 
-Open the printed URL plus `/tokens.html` or `/compat.html`. Add `?variant=compact` for the compact density with `toastRadius="control"`. Add `?theme=dark` for dark mode (combine with `&`), or use "Toggle theme". Hover the toast to see the close chip. `Fixture.tsx` is not part of the package typecheck.
+Open the printed URL plus `/tokens.html`, `/compat.html` or `/update.html`. Add `?variant=compact` for the compact density with `toastRadius="control"`. Add `?theme=dark` for dark mode (combine with `&`), or use "Toggle theme". `?variant=compact` applies to the first two pages only. Hover the toast to see the close chip. `Fixture.tsx` and `UpdateToastFixture.tsx` are not part of the package typecheck.

package/tokens/examples/toaster/UpdateToastFixture.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { showUpdateAvailableToast } from "../../../app/src/update/updateWatcher";
+import { Button } from "../../../src/ui/button";
+import { SonnerToaster } from "../../../src/ui/sonner";
+
+function initialDark(): boolean {
+  return new URLSearchParams(window.location.search).get("theme") === "dark";
+}
+
+// The toast `startUpdateAvailableWatcher` shows. Refresh reloads this page,
+// which fires the toast again.
+function fireUpdateToast() {
+  showUpdateAvailableToast({ toast });
+}
+
+/** The update toast with its Refresh action, for screenshots. */
+export function UpdateToastFixture() {
+  const [dark, setDark] = useState(initialDark);
+
+  // Sonner portals toasts onto `document.body`, so `.dark` must live on `<html>`.
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", dark);
+    return () => {
+      document.documentElement.classList.remove("dark");
+    };
+  }, [dark]);
+
+  useEffect(() => {
+    const id = window.setTimeout(fireUpdateToast, 150);
+    return () => window.clearTimeout(id);
+  }, []);
+
+  return (
+    <>
+      <main className="min-h-screen bg-background p-8 text-foreground">
+        <div className="flex gap-3">
+          <Button onClick={() => setDark((d) => !d)}>Toggle theme</Button>
+          <Button onClick={fireUpdateToast}>Show update toast</Button>
+        </div>
+      </main>
+      {/* No `position`: the package default, top-right, as Eva mounts it. */}
+      <SonnerToaster
+        theme={dark ? "dark" : "light"}
+        toastRadius="surface"
+        toastIcons="filled24"
+        closeButtonStyle="hoverChip"
+        sonnerVars
+        descriptionMuted
+      />
+    </>
+  );
+}

package/tokens/examples/toaster/main-update.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { UpdateToastFixture } from "./UpdateToastFixture";
+import "./styles-tokens.css";
+
+createRoot(document.getElementById("root")!).render(<UpdateToastFixture />);

package/tokens/examples/toaster/update.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Update toast fixture</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main-update.tsx"></script>
+  </body>
+</html>

package/tokens/examples/toaster/vite.config.ts

@@ -7,6 +7,6 @@ export default defineConfig({
   plugins: [tailwindcss()],
   esbuild: { jsx: "automatic" },
   resolve: { dedupe: ["react", "react-dom"] },
-  build: { rollupOptions: { input: ["tokens.html", "compat.html"] } },
+  build: { rollupOptions: { input: ["tokens.html", "compat.html", "update.html"] } },
   server: { fs: { allow: ["../../.."] } },
 });