@vvedantb/ui 0.27.0 → 0.29.0

package/README.md

@@ -4,13 +4,16 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `SidebarUpgradeCard`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), animated nav icons from 0.11.0 (`MemoryIcon`, `BoardIcon`, ... and `NavIconBase`; `SettingsIcon` `variant` from 0.12.0), artifact viewers from 0.13.0 (`ArtifactFrame`, `ArtifactList`, `ArtifactViewer`, ...), date pickers from 0.14.0 (`Calendar`, `DatePicker`, `DateTimePicker`, `MonthPicker`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui` | The main JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `SidebarUpgradeCard`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), animated nav icons from 0.11.0 (`MemoryIcon`, `BoardIcon`, ... and `NavIconBase`; `SettingsIcon` `variant` from 0.12.0), artifact viewers from 0.13.0 (`ArtifactFrame`, `ArtifactList`, `ArtifactViewer`, ...), date pickers from 0.14.0 (`Calendar`, `DatePicker`, `DateTimePicker`, `MonthPicker`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui/client` | The root without `@vvedantb/server`, convex or Clerk, for Chrome extensions (0.28.0). Leaves out the artifact viewers, `ConvexClerkProvider`, `useStableAuth`, `createUseStableAuth`, `resetStableAuthSession` and `useEnsureUser`. See [Chrome extensions](#chrome-extensions-0280). |
+| `@vvedantb/ui/brand` | App icons (`Icon*`, `APP_ICONS`), `AppWordmark`, deprecated `AppMark`, raw SVG strings and `FAMILY_APPS`. Also in the root and `/client`. |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
 | `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `clear-input`, `motion`, `animations`, `nav-icons`, `compat-shadcn-rgb`, `border-beam` (opt-in, for `BorderBeam`), `markdown` (opt-in, for `Markdown`). CSS. `tokens.css` imports `scrollbar-thin`, `clear-input` and `motion`. |
 | `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | Same file as `tokens/css/compat-shadcn-rgb.css`. CSS. |
 | `@vvedantb/ui/tokens/tailwind-preset` | Tailwind preset (`.mjs`) for `@config "@vvedantb/ui/tokens/tailwind-preset"`. Kept as a build-tool entry: Tailwind needs a resolvable package path, and it is not a React API. |
 | `@vvedantb/ui/landing.css` | Landing page classes (`landing-wordmark-text` for `AppWordmark`, `landing-atmosphere`, `landing-grain`, `landing-pulse-dot`, ambient graph and preview animations, smooth `#top` scrolling). CSS. |
+| `@vvedantb/ui/fonts/instrument-sans.css` | Instrument Sans `@font-face` rules over packaged woff2 files, and the Clerk Inter override, for extension pages (0.28.0). Opt-in. CSS. |
 | `@vvedantb/ui/package.json` | Package metadata. |
 
 Removed in 0.4.0-rc.1: the `/cn`, `/sonner`, `/audio`, `/shell`, `/app`, `/composer` and `/tokens/native` subpaths. Import from `@vvedantb/ui`. See [`MIGRATION.md`](MIGRATION.md).
@@ -871,7 +874,7 @@ links under a separator.
 | --- | --- |
 | `brand`, `tagline` | Nodes. |
 | `socials` | `{ href, icon, label? }[]`. `icon` is a component that takes `className`. Links open in a new tab. |
-| `columns` | `{ heading, links }[]`. A link is `{ href, label, external?, image?: { src, alt } }`. |
+| `columns` | `{ heading, links }[]`. A link is `{ href, label, external?, image?: { src, alt }, app?: AppName }`. `image` is a 20px round image before the label. `app` (0.29.0) is the 14px `APP_ICONS[app]` glyph before the label, in `currentColor` and `aria-hidden`. If both are set, `app` wins. |
 | `name`, `year` | "Copyright © {year} {name}". `year` defaults to the current year. |
 | `legalLinks` | `{ href, label }[]`, open in a new tab. |
 | `variant` | `"muted"` (default, `text-muted`), `"muted-foreground"`, or `"touch"` (`text-muted-foreground`, `max-sm:hit-target` links, safe-area bottom padding). |
@@ -910,7 +913,7 @@ Shared marketing wordmark for product app names across Project V sites: the `Ico
 
 Never use `AppWordmark` for `projectv` (the type rejects it).
 
-Setup. The package does not bundle the font. `--font-sans` comes from the package tokens. Load Instrument Sans in the app, as for the rest of the UI, if it is not already loaded.
+Setup. `--font-sans` comes from the package tokens. Load Instrument Sans in the app, as for the rest of the UI, if it is not already loaded. Extension pages can import `@vvedantb/ui/fonts/instrument-sans.css` (0.28.0); web apps keep their own font loading.
 
 ```css
 @import "@vvedantb/ui/landing.css"; /* provides .landing-wordmark-text */
@@ -1209,6 +1212,55 @@ import {
 - Hooks: `useMediaQuery(query)`, `useDocumentVisible()`, `useIdleCallback(ms, fn)` (trailing debounce; `createIdleCallback` is the React-free core), `useSingleFlight(fn)` (one call at a time, latest args run next), `usePersistedScrollParent(storageKey)` (restores a container's `scrollTop` from `sessionStorage`).
 - Convex: `convexErrorMessage(error, fallback)` reads `ConvexError` data first; `userFacingErrorMessage(error, fallback)` strips the client envelope and stack. `useHeldResult(result, key)` keeps the last result while a query is skipped (`key` `null`). None of these import `convex`.
 
+## Chrome extensions (0.28.0)
+
+Extension pages (popup, side panel, options, welcome) run under the MV3 extension-page CSP, which blocks remote font stylesheets, and should not load `@vvedantb/server`. Three pieces cover them. Web apps change nothing unless they opt in.
+
+### Fonts
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@import "@vvedantb/ui/fonts/instrument-sans.css";
+@source "../node_modules/@vvedantb/ui/src/**/*.{ts,tsx}";
+```
+
+`instrument-sans.css` has four `@font-face` rules: variable weight 400-700, normal and italic, latin and latin-ext. The `url()`s are relative, so Vite and WXT copy the woff2 files into the build. The licence is `fonts/OFL.txt`. The file ends with the rule both extensions carried in `globals.css`:
+
+```css
+html,
+body {
+  font-family: var(--font-sans);
+}
+```
+
+Clerk injects an unlayered `body { font-family: Inter }`, which beats the `@layer base` rule in the tokens; this rule is unlayered too. `tokens.css` does not import the file. Once an extension imports it, it can drop its own copy of the fonts, the CSS and the override.
+
+### `@vvedantb/ui/client`
+
+```tsx
+import { AppWordmark, Button, Card, Tabs, TabsList, TabsTrigger, cn, createThemeProvider } from "@vvedantb/ui/client";
+```
+
+The root's exports, without:
+
+- the artifact viewers (`src/artifacts`: `ArtifactFrame`, `ArtifactViewer`, ...), which import `@vvedantb/server`;
+- `ConvexClerkProvider`, `useStableAuth`, `createUseStableAuth`, `resetStableAuthSession` and `useEnsureUser`, which import `convex` or `@clerk/clerk-react`.
+
+Every other name is the same binding as in the root. `src/client-exports.test.ts` keeps the two in step, and `app/tests-node/client-graph.test.mjs` checks that the entry's module graph has no `@vvedantb/server`, convex, Clerk or `node:` import. The root is unchanged.
+
+### Icons
+
+`scripts/build-brand-assets.mjs` ships in the package and writes `<out>/<app>/extension/icon-{16,32,48,128}.png` (the tile at 16, 32 and 48 px, `appExtension128Svg` at 128 px). Copy them into the extension's public folder:
+
+```sh
+out=$(mktemp -d)
+node node_modules/@vvedantb/ui/scripts/build-brand-assets.mjs --out "$out" --app vmem
+mkdir -p public/icons && cp "$out"/vmem/extension/icon-*.png public/icons/
+```
+
+PNGs need `rsvg-convert` (librsvg); without it the script writes only the SVGs and says so. It needs Node 22.18 or later. Under `node_modules` it strips the types from `src/brand/svg.ts` itself, because Node will not, and Node prints an `ExperimentalWarning` for that. `defineVExtensionConfig` in `@vvedantb/config/extension` points the manifest `icons` and `action.default_icon` at `icons/icon-{16,32,48,128}.png`.
+
 ## Slider (0.16.0, dark contrast and className props 0.16.1)
 
 shadcn's slider on `@radix-ui/react-slider` (a peer dependency), with package tokens.

package/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Instrument Sans Project Authors (https://github.com/Instrument/instrument-sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/fonts/instrument-sans.css

@@ -0,0 +1,73 @@
+/*
+ * @vvedantb/ui/fonts/instrument-sans.css: Instrument Sans for chrome-extension
+ * pages (popup, welcome). Opt-in: tokens.css does not import it, so web apps
+ * are unchanged.
+ *
+ *   @import "@vvedantb/ui/fonts/instrument-sans.css";
+ *
+ * @vvedantb/ui/tokens only names the family; MV3 extension-page CSP cannot load
+ * remote webfont stylesheets, so the files ship here. Variable weight 400-700,
+ * normal and italic, latin and latin-ext. The url()s are relative, so Vite and
+ * WXT copy the woff2 files into the build. Licence: OFL.txt in this folder.
+ *
+ * The last rule sets html and body to --font-sans (from @vvedantb/ui/tokens).
+ * It is unlayered on purpose: see the comment above it.
+ */
+@font-face {
+  font-family: "Instrument Sans";
+  font-style: italic;
+  font-weight: 400 700;
+  font-stretch: 100%;
+  font-display: swap;
+  src: url("./InstrumentSans-Italic-latin-ext.woff2") format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304,
+    U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB,
+    U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+
+@font-face {
+  font-family: "Instrument Sans";
+  font-style: italic;
+  font-weight: 400 700;
+  font-stretch: 100%;
+  font-display: swap;
+  src: url("./InstrumentSans-Italic-latin.woff2") format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
+    U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
+    U+2215, U+FEFF, U+FFFD;
+}
+
+@font-face {
+  font-family: "Instrument Sans";
+  font-style: normal;
+  font-weight: 400 700;
+  font-stretch: 100%;
+  font-display: swap;
+  src: url("./InstrumentSans-latin-ext.woff2") format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304,
+    U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB,
+    U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+
+@font-face {
+  font-family: "Instrument Sans";
+  font-style: normal;
+  font-weight: 400 700;
+  font-stretch: 100%;
+  font-display: swap;
+  src: url("./InstrumentSans-latin.woff2") format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
+    U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
+    U+2215, U+FEFF, U+FFFD;
+}
+
+/* Clerk injects unlayered `body { font-family: Inter }` which beats
+ * `@layer base` from @vvedantb/ui/tokens. Keep extension pages on Instrument Sans. */
+html,
+body {
+  font-family: var(--font-sans);
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.27.0",
+  "version": "0.29.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.",
+  "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",
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,12 @@
       "types": "./src/brand/index.ts",
       "default": "./src/brand/index.ts"
     },
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./src/client.ts"
+    },
     "./landing.css": "./src/marketing/landing.css",
+    "./fonts/instrument-sans.css": "./fonts/instrument-sans.css",
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
@@ -55,6 +60,7 @@
     "app/src",
     "tokens/src",
     "tokens/examples",
+    "fonts",
     "scripts/build-brand-assets.mjs",
     "README.md",
     "LICENSE",
@@ -63,19 +69,9 @@
   ],
   "sideEffects": [
     "./src/ui/sonner.css",
-    "./src/marketing/landing.css"
+    "./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",
@@ -165,7 +161,6 @@
     "@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",
@@ -189,7 +184,8 @@
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "zod3": "npm:zod@^3.25.76"
+    "zod3": "npm:zod@^3.25.76",
+    "@vvedantb/server": "0.10.0"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
@@ -210,5 +206,15 @@
     "@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/scripts/build-brand-assets.mjs

@@ -5,10 +5,19 @@
 // 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 { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { APP_NAMES, appAdaptiveSvg, appExtension128Svg, appMarkSvg, appTileSvg } from "../src/brand/svg.ts";
+
+// Node does not strip types from files under node_modules, so an installed copy
+// of this script strips svg.ts itself (svg.ts has no imports).
+async function loadSvg() {
+  const url = new URL("../src/brand/svg.ts", import.meta.url);
+  if (!fileURLToPath(url).split(sep).includes("node_modules")) return import(url.href);
+  const { stripTypeScriptTypes } = await import("node:module");
+  return import(`data:text/javascript,${encodeURIComponent(stripTypeScriptTypes(readFileSync(url, "utf8")))}`);
+}
+const { APP_NAMES, appAdaptiveSvg, appExtension128Svg, appMarkSvg, appTileSvg } = await loadSvg();
 
 /** Whether `rsvg-convert` can be run. */
 export function hasRsvg() {

package/src/client.ts

@@ -0,0 +1,393 @@
+// @vvedantb/ui/client: the root without `@vvedantb/server`, convex or Clerk, for
+// Chrome extensions and other pages that cannot load them. It leaves out the
+// artifact viewers (`src/artifacts`), `ConvexClerkProvider`, `useStableAuth`
+// and `useEnsureUser`; everything else matches the root. Keep it in step with
+// src/index.ts: src/client-exports.test.ts compares the two, and
+// app/tests-node/client-graph.test.mjs checks the module graph.
+export { cn } from "./utils/cn";
+export { UiConfigProvider, useUiConfig } from "./ui/ui-config";
+export type { UiConfig, UiConfigProviderProps } from "./ui/ui-config";
+export { floatingSurfaceClass } from "./ui/_menu-classes";
+export { fieldFocusClass, fieldFocusWithinClass } from "./ui/_field-classes";
+export * from "./ui/surface-classes";
+export * from "./motion/presets";
+export * from "./motion/panel-transition";
+export { ListEnter, useFirstPaintGate } from "./motion/list-enter";
+export type { ListEnterProps } from "./motion/list-enter";
+// Gesture physics and animation budget helpers (shared clock, on-screen and
+// page-visibility pausing for infinite animations).
+export { DRAG_ACTIVATION_DISTANCE_PX, projectVelocity, rubberband } from "./utils/gesture";
+export {
+  bindRuntimeAnimation,
+  ensureRuntimeVisibility,
+  observeAnimVisibility,
+  useAnimOffscreenRef,
+} from "./utils/runtimeVisibility";
+export { msUntilNextBoundary, quantizedSnapshot, subscribeQuantized } from "./utils/sharedClock";
+export { CAT_SLOT_COUNT, catColorForId, catColorForSlot, catSlotForId } from "./utils/cat-color";
+export type { CatColorClasses, CatSlot } from "./utils/cat-color";
+export { CONTROL_RADIUS_CLASS, SURFACE_RADIUS_CLASS } from "./utils/surface-radius";
+export { restoreModalScrollLock } from "./ui/overlay-a11y";
+// Generic hooks: media query, page visibility, trailing debounce,
+// single-flight async calls and a persisted scroll container.
+export * from "./hooks";
+export { ErrorBoundary } from "./ui/error-boundary";
+export type { ErrorBoundaryProps } from "./ui/error-boundary";
+export { CountPop, countLabel, UnreadDot } from "./ui/count-pop";
+export { MarqueeOnHover } from "./ui/marquee-on-hover";
+export { RelativeDateTime } from "./ui/relative-date-time";
+export type { RelativeDateTimeProps } from "./ui/relative-date-time";
+export { ImageLightbox } from "./ui/image-lightbox";
+export type { GalleryImage } from "./ui/image-lightbox";
+export { ImageGalleryPreview, ScreenshotPreview, VideoPreview } from "./ui/media-preview";
+
+export * from "./ui/avatar";
+export * from "./ui/badge";
+export * from "./ui/border-beam";
+export * from "./ui/breadcrumb";
+export * from "./ui/button";
+export * from "./ui/button-group";
+export * from "./ui/card";
+export * from "./ui/carousel";
+export * from "./ui/centered-spinner";
+export * from "./ui/checkbox";
+export * from "./ui/collapsible";
+export * from "./ui/command";
+export * from "./ui/context-menu";
+export * from "./ui/crossfade-icon";
+export * from "./ui/dialog";
+export * from "./ui/alert-dialog";
+export * from "./ui/confirm-dialog";
+export * from "./ui/dropdown-menu";
+export * from "./ui/empty-state";
+export * from "./ui/hover-card";
+export * from "./ui/input";
+export * from "./ui/label";
+export * from "./ui/labeled-slider-row";
+export * from "./ui/labeled-switch-row";
+export * from "./ui/list-row";
+export * from "./ui/loading-state";
+export * from "./ui/pagination";
+export * from "./ui/popover";
+export * from "./ui/progress";
+export * from "./ui/refresh-spin-icon";
+export {
+  Select as RadixSelect,
+  SelectContent as RadixSelectContent,
+  SelectGroup as RadixSelectGroup,
+  SelectItem as RadixSelectItem,
+  SelectLabel as RadixSelectLabel,
+  SelectScrollDownButton as RadixSelectScrollDownButton,
+  SelectScrollUpButton as RadixSelectScrollUpButton,
+  SelectSeparator as RadixSelectSeparator,
+  SelectTrigger as RadixSelectTrigger,
+  SelectValue as RadixSelectValue,
+} from "./ui/radix-select";
+export * from "./ui/search-input";
+export * from "./ui/select";
+export * from "./ui/select-field";
+export * from "./ui/separator";
+export * from "./ui/skeleton";
+export * from "./ui/slide-over-panel";
+export * from "./ui/slider";
+export * from "./ui/sonner";
+export * from "./ui/spinner";
+export * from "./ui/status-dot";
+export * from "./ui/surface";
+export * from "./ui/switch";
+export * from "./ui/table";
+export * from "./ui/tabs";
+export * from "./ui/textarea";
+export * from "./ui/toolbar-search-input";
+export * from "./ui/time-picker";
+export * from "./ui/calendar";
+export * from "./ui/date-picker";
+export * from "./ui/tooltip";
+export * from "./ui/kbd";
+export * from "./ui/sheet";
+export * from "./ui/visually-hidden";
+export * from "./ui/clearInputDissolve";
+
+// Animated nav icons. Styles: `@vvedantb/ui/tokens/css/nav-icons.css`.
+export * from "./icons";
+
+// Dual copies: the richer file uses the plain name. The deprecated `Alt` exports
+// (accordion, clear input, input group) wrap the main parts with the old markup.
+export * from "./ui/accordion";
+export {
+  AccordionAlt,
+  AccordionItemAlt,
+  AccordionTriggerAlt,
+  AccordionContentAlt,
+} from "./ui/accordion.alt";
+export * from "./ui/clear-input";
+export { ClearInputAlt } from "./ui/clear-input.alt";
+export * from "./ui/input-group";
+export {
+  InputGroupAlt,
+  InputGroupAddonAlt,
+  InputGroupButtonAlt,
+  InputGroupTextAlt,
+  InputGroupInputAlt,
+  InputGroupTextareaAlt,
+} from "./ui/input-group.alt";
+export * from "./ui/scroll-area";
+export {
+  ScrollArea as ScrollAreaAlt,
+  ScrollBar as ScrollBarAlt,
+} from "./ui/scroll-area.alt";
+
+export * from "./ai-elements/artifact";
+export * from "./ai-elements/attachments";
+export * from "./ai-elements/chain-of-thought";
+export * from "./ai-elements/code-block";
+export * from "./ai-elements/conversation";
+export * from "./ai-elements/file-chip";
+export * from "./ai-elements/image";
+export * from "./ai-elements/inline-citation";
+export * from "./ai-elements/jump-rail";
+export * from "./ai-elements/jump-rail-geometry";
+export * from "./ai-elements/chat-jump-rail";
+export * from "./ai-elements/message";
+export * from "./ai-elements/model-selector";
+export * from "./ai-elements/prompt-input";
+export * from "./ai-elements/prompt-input-settings";
+export * from "./ai-elements/prompt-input-speech";
+export * from "./ai-elements/prompt-input-traits";
+export * from "./ai-elements/queue";
+export * from "./ai-elements/reasoning";
+export * from "./ai-elements/shimmer";
+export * from "./ai-elements/sources";
+export * from "./ai-elements/speech-input";
+export * from "./ai-elements/suggestion";
+
+// 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";
+export * from "./ai-elements/activity-question";
+export * from "./ai-elements/activity-tasks";
+export * from "./ai-elements/trace";
+export * from "./ai-elements/use-streaming-disclosure";
+export * from "./ai-elements/plan";
+export * from "./ai-elements/test-results";
+export * from "./ai-elements/web-preview";
+export * from "./ai-elements/context";
+export * from "./ai-elements/model-picker";
+export * from "./ai-elements/provider-icon";
+
+// Kibo UI blocks: gantt, kanban, list, contribution graph, video player,
+// cursor, avatar stack, theme switcher. Kanban, list and gantt drag with
+// `useDragSensors`, the shared dnd-kit sensor split.
+export * from "./kibo";
+export { useDragSensors } from "./utils/useDragSensors";
+
+// Markdown renderer (Streamdown + code blocks, callouts, links, KaTeX).
+// Styles: `@vvedantb/ui/tokens/css/markdown.css`.
+export * from "./markdown";
+
+export * from "./audio";
+
+export * from "./composer";
+export { toast } from "sonner";
+
+// Shell: router-free pieces. Shell's own `cn` and `ClassValue` are not re-exported;
+// use the root `cn` (clsx + tailwind-merge).
+export { SidebarHeader } from "../shell/src/SidebarHeader";
+export type { SidebarHeaderProps } from "../shell/src/SidebarHeader";
+export { SidebarUpgradeCard } from "../shell/src/SidebarUpgradeCard";
+export type { SidebarUpgradeCardProps } from "../shell/src/SidebarUpgradeCard";
+export { PillTabs } from "../shell/src/PillTabs";
+export type { PillTabItem, PillTabsProps } from "../shell/src/PillTabs";
+export { SessionsHoverCard } from "../shell/src/SessionsHoverCard";
+export type {
+  SessionsHoverCardContext,
+  SessionsHoverCardProps,
+  SessionsHoverCardSurface,
+} from "../shell/src/SessionsHoverCard";
+
+// App shell: sidebar and main page layout. Widths come from the
+// `--app-shell-*` CSS variables that `AppShell` sets.
+export { AppShell } from "../shell/src/AppShell";
+export type {
+  AppShellContentProps,
+  AppShellMainProps,
+  AppShellProps,
+  AppShellRootProps,
+  AppShellSkipLinkProps,
+} from "../shell/src/AppShell";
+export { AppSidebar } from "../shell/src/AppSidebar";
+export type { AppSidebarProps } from "../shell/src/AppSidebar";
+// Composable sidebar parts (`Sidebar.Root`, `Sidebar.Rail`, ...) and their prop types.
+export * from "../shell/src/Sidebar";
+export { SidebarRail, RailTile, RailDivider, RailCollapseTile } from "../shell/src/SidebarRail";
+export type {
+  SidebarRailProps,
+  RailTileProps,
+  RailDividerProps,
+  RailCollapseTileProps,
+} from "../shell/src/SidebarRail";
+export { SidebarResizeHandle, useAppShellResize } from "../shell/src/SidebarResize";
+export type {
+  AppShellResize,
+  SidebarResizeHandleProps,
+  SidebarResizeOptions,
+} from "../shell/src/SidebarResize";
+export { SidebarIconTooltip } from "../shell/src/SidebarIconTooltip";
+export type { SidebarIconTooltipProps } from "../shell/src/SidebarIconTooltip";
+export { SidebarPanel } from "../shell/src/SidebarPanel";
+export type { SidebarPanelProps } from "../shell/src/SidebarPanel";
+export { SidebarAccountMenu, SidebarAccountMenuPlaceholder } from "../shell/src/SidebarAccountMenu";
+export type {
+  SidebarAccountMenuProps,
+  SidebarAccountMenuPlaceholderProps,
+} from "../shell/src/SidebarAccountMenu";
+export { SignOutDialog } from "../shell/src/SignOutDialog";
+export type { SignOutDialogProps } from "../shell/src/SignOutDialog";
+export {
+  railBadgeClass,
+  railTileClass,
+  railTileStateClass,
+  sidebarNavIconClass,
+  sidebarNavItemActionsClass,
+  sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemSubtitleClass,
+  sidebarNavItemTrailingClass,
+  sidebarNavLinkTextClass,
+  sidebarNavRowClass,
+  sidebarSectionLabelClass,
+} from "../shell/src/app-shell-classes";
+export type { SidebarNavItemClassOptions } from "../shell/src/app-shell-classes";
+
+// Marketing: landing kit, site footer and pricing dialog. Router- and Motion-free;
+// `createLandingKit` takes the app's `motion`. Styles: `@vvedantb/ui/landing.css`.
+export {
+  LandingFeatureCard,
+  LandingFooter,
+  LandingLattice,
+  LandingNavMenu,
+  LandingPageLayout,
+  LandingSection,
+  LandingSectionHeading,
+  landingItemVariants,
+} from "./marketing/landing";
+export type {
+  LandingFeature,
+  LandingFooterProps,
+  LandingLatticeProps,
+  LandingLink,
+  LandingNavMenuProps,
+  LandingPageLayoutProps,
+  LandingSectionHeadingProps,
+  LandingSectionProps,
+} from "./marketing/landing";
+export { createLandingKit } from "./marketing/createLandingKit";
+export type {
+  LandingCtaProps,
+  LandingHeroProps,
+  LandingKit,
+  LandingKitOptions,
+  LandingMotion,
+  LandingNavProps,
+  LandingRevealItemProps,
+  LandingRevealProps,
+} from "./marketing/createLandingKit";
+export {
+  landingFooterButtonClass,
+  landingFooterLinkClass,
+  landingPanelClass,
+  landingShellClass,
+} from "./marketing/marketing-classes";
+export type { PricingModalTone, SiteFooterVariant } from "./marketing/marketing-classes";
+export { SiteFooter } from "./marketing/SiteFooter";
+export type { SiteFooterLink, SiteFooterProps, SiteFooterSocial } from "./marketing/SiteFooter";
+export { PricingModal, V_PRO_APP_BENEFITS } from "./marketing/PricingModal";
+export type {
+  PricingModalLegacyProps,
+  PricingModalMultiProps,
+  PricingModalPeriod,
+  PricingModalProps,
+  PricingPlan,
+  PricingPlanAppBenefit,
+  PricingPlanBenefit,
+} from "./marketing/PricingModal";
+
+// App helpers: confirm skip, update watcher, settings chrome, theme, page title,
+// page motion, time, VITE env and error messages. Not here: `ConvexClerkProvider`,
+// `useStableAuth` and `useEnsureUser`, which import convex or Clerk.
+export {
+  bindToWindow,
+  createAltHeldStore,
+  getAltHeld,
+  useAltHeld,
+  type AltHeldBinding,
+  type AltHeldSignals,
+  type AltHeldStore,
+  type AltKeyEvent,
+} from "../app/src/confirm/useAltHeld";
+export { requestConfirm, shouldSkipConfirm } from "../app/src/confirm/confirmSkip";
+export { useRequestConfirm } from "../app/src/confirm/useRequestConfirm";
+export { ConfirmSkipHint, skipConfirmTitle } from "../app/src/confirm/ConfirmSkipHint";
+export { fetchDeployFingerprint, fingerprintFromHtml } from "../app/src/update/deployFingerprint";
+export {
+  startUpdateAvailableWatcher,
+  type UpdateAvailableWatcherOptions,
+  type UpdateToastOptions,
+} from "../app/src/update/updateWatcher";
+export { SettingsSection, type SettingsSectionConfig } from "../app/src/settings/SettingsSection";
+export { SettingsField } from "../app/src/settings/SettingsField";
+export { SettingsStack } from "../app/src/settings/SettingsStack";
+export { SettingsToggleRow } from "../app/src/settings/SettingsToggleRow";
+export { SettingsEmptyState, type SettingsEmptyStateConfig } from "../app/src/settings/SettingsEmptyState";
+export {
+  DefaultSettingsLayout,
+  SettingsPage,
+  type SettingsLayoutProps,
+  type SettingsPageProps,
+} from "../app/src/settings/SettingsPage";
+export {
+  applyThemeClass,
+  createThemeProvider,
+  getSystemTheme,
+  type ThemeAttribute,
+  type ThemeProviderKit,
+  type ThemeProviderOptions,
+  type ThemeProviderProps,
+  type ThemeState,
+} from "../app/src/theme/createThemeProvider";
+export {
+  createPageTitleContext,
+  type DocumentTitleOptions,
+  type PageTitleContextKit,
+  type PageTitleContextOptions,
+  type PageTitleValue,
+} from "../app/src/page-title/createPageTitleContext";
+export {
+  PageMotionProvider,
+  useDisablePageMotion,
+  type PageMotionConfigProps,
+  type PageMotionProviderProps,
+} from "../app/src/page-motion/PageMotionProvider";
+export { formatCompactRelativeTime, type CompactRelativeTimeOptions } from "../app/src/time/compactRelativeTime";
+export {
+  parseClientEnv,
+  VITE_ENV_NAMES,
+  type ClientEnv,
+  type ClientEnvOptions,
+  type ClientEnvSource,
+  type ClientEnvWithoutViteEnv,
+  type ViteEnvMode,
+  type ViteEnvName,
+} from "../app/src/convex/env";
+export { convexErrorMessage, userFacingErrorMessage } from "../app/src/convex/errorMessage";
+export { useHeldResult } from "../app/src/convex/useHeldResult";
+
+// Family app marks (Icon* components, deprecated 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/SiteFooter.tsx

@@ -1,4 +1,5 @@
 import type { ComponentType, ReactNode } from "react";
+import { APP_ICONS, type AppName } from "../brand";
 import { Button } from "../ui/button";
 import { Separator } from "../ui/separator";
 import { siteFooterClasses, type SiteFooterVariant } from "./marketing-classes";
@@ -10,6 +11,8 @@ export type SiteFooterLink = {
   external?: boolean;
   /** 20px round image before the label. */
   image?: { src: string; alt: string };
+  /** 14px app glyph before the label, in `currentColor` and `aria-hidden`. Wins over `image`. */
+  app?: AppName;
 };
 
 export type SiteFooterSocial = {
@@ -78,25 +81,30 @@ export function SiteFooter({
                 <div key={column.heading} className="flex-1 sm:flex-none">
                   <h4 className={c.heading}>{column.heading}</h4>
                   <div className={c.links}>
-                    {column.links.map((link) => (
-                      <a
-                        key={link.label}
-                        href={link.href}
-                        {...(link.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
-                        className={link.image ? c.imageLink : c.link}
-                      >
-                        {link.image ? (
-                          <img
-                            src={link.image.src}
-                            alt={link.image.alt}
-                            width={20}
-                            height={20}
-                            className="rounded-full object-cover w-5 h-5 md:w-5 md:h-5"
-                          />
-                        ) : null}
-                        {link.label}
-                      </a>
-                    ))}
+                    {column.links.map((link) => {
+                      const AppIcon = link.app ? APP_ICONS[link.app] : null;
+                      return (
+                        <a
+                          key={link.label}
+                          href={link.href}
+                          {...(link.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+                          className={AppIcon || link.image ? c.imageLink : c.link}
+                        >
+                          {AppIcon ? (
+                            <AppIcon size={14} />
+                          ) : link.image ? (
+                            <img
+                              src={link.image.src}
+                              alt={link.image.alt}
+                              width={20}
+                              height={20}
+                              className="rounded-full object-cover w-5 h-5 md:w-5 md:h-5"
+                            />
+                          ) : null}
+                          {link.label}
+                        </a>
+                      );
+                    })}
                   </div>
                 </div>
               ))}

package/app/README.md

@@ -1,259 +0,0 @@
-# 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/tokens/README.md

@@ -1,120 +0,0 @@
-# `@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.