@vvedantb/ui 0.26.1 → 0.28.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).
@@ -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 */
@@ -1184,8 +1187,80 @@ import { DatePicker, DateTimePicker, MonthPicker } from "@vvedantb/ui";
 - `DatePicker`: `value` "YYYY-MM-DD" or "". The trigger matches `TimePicker` and shows the date with `dateStyle: "medium"` (`locale`) or `placeholder` ("Pick a date"). `min` and `max` disable days; `clearable` adds a clear control (`onChange("")`); `name` adds a hidden input. `className` goes on the wrapper, `triggerClassName` merges onto the button (default `w-40`). A width on either sizes the field, and `w-full` on either fills the row; pill inputs can pass `triggerClassName="h-10 w-full rounded-full px-4 text-sm"`. `ariaLabel` names the trigger, followed by the shown text.
 - `DateTimePicker`: `value` "YYYY-MM-DDTHH:mm" or "". A date with no time uses `defaultTime` ("00:00"); a time with no date uses today. Only the date part of `min` and `max` applies. `triggerClassName` goes to both triggers, a width only to the date.
 - `MonthPicker`: `value` "YYYY-MM" or "", with year navigation and a month grid. `min` and `max` are "YYYY-MM".
+- `TimePicker`: `value` "HH:mm" (24h) or "". `hourCycle={12}` (0.27.0) shows "02:30 PM" and adds an AM/PM column; `value` stays 24h. Each column opens centred on the selected item.
 - `Calendar`: the styled `DayPicker` for custom layouts (every `DayPicker` prop). `parseDateValue` and `formatDateValue` convert between "YYYY-MM-DD" and a local `Date`.
 
+## Hooks, media and list motion (0.27.0)
+
+Generic pieces lifted from an app. Components that use `m` need the app's `LazyMotion`.
+
+```tsx
+import {
+  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot,
+  MarqueeOnHover, RelativeDateTime, ImageLightbox, ImageGalleryPreview, ScreenshotPreview, VideoPreview,
+  useMediaQuery, useDocumentVisible, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  convexErrorMessage, userFacingErrorMessage, useHeldResult,
+} from "@vvedantb/ui";
+```
+
+- `ErrorBoundary` (`fallback` node or `(retry) => node`, `onError`): contains a failure to its subtree; `retry` clears the error.
+- `ListEnter` (`index`, `fast`, `firstPaint`, `staggerStep`, `staggerMax`, `slide`, `as` `div | tr | li`) and `useFirstPaintGate()`: first-paint fade and 8px slide, staggered with `staggerDelay`. Pass `firstPaint={gate.current}` so recycled rows do not restagger.
+- `CountPop` (`label`, `className`, `children`): pop-in and shrink-out for a live count, re-popping on each change. `countLabel(n)` gives `null`, the number or `"99+"`. `UnreadDot` (`show`): a `bg-primary` dot on `CountPop`.
+- `MarqueeOnHover`: a single-line label that scrolls its hidden tail into view on hover (or on hover of a `group` ancestor). Import `@vvedantb/ui/tokens/css/marquee.css`; `--mq-delay` sets the dwell.
+- `RelativeDateTime` (`at`, `emptyLabel` default "—", `exactFormat` default "DD/MM/YYYY HH:mm"): "15m" / "2d" with the exact time in a tooltip.
+- `ImageLightbox` (`images`, `index` or `null`, `onIndexChange`, `onClose`): fullscreen viewer with arrow keys, buttons and swipe. `ImageGalleryPreview` (`images`): up to a 2×2 grid with a "+N" tile. `ScreenshotPreview` (`url`, `alt`) and `VideoPreview` (`url`).
+- 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/app/src/convex/errorMessage.ts

@@ -0,0 +1,62 @@
+/**
+ * The message to show the user for a failed Convex call.
+ *
+ * Production Convex redacts plain `Error` messages to "Server Error", so
+ * `error.message` alone leaves the user with a request id and no reason. Only
+ * `ConvexError` data crosses the wire intact — read that first. Matched by
+ * `name` rather than `instanceof`, so this module does not import `convex`.
+ */
+export function convexErrorMessage(error: unknown, fallback: string): string {
+  if (
+    error instanceof Error &&
+    error.name === "ConvexError" &&
+    "data" in error &&
+    typeof error.data === "string"
+  ) {
+    return error.data;
+  }
+  return error instanceof Error ? error.message : fallback;
+}
+
+const UNCAUGHT = "Uncaught Error:";
+const PLAIN = "Error:";
+
+/**
+ * The same failure, stripped of everything the Convex client wraps around it.
+ *
+ * A client-side rejection reads
+ * `[CONVEX M(teams:create)] [Request ID: abc] Server Error\nUncaught Error: Team
+ * name is required\n    at handler (../convex/teams.ts:107:12)`. Shown verbatim
+ * in a form's error slot that is a stack trace with the sentence buried in the
+ * middle, so take the text the handler actually threw: after the last
+ * `Uncaught Error:` / `Error:`, up to the newline or the stack frame.
+ *
+ * `error` is deliberately not `unknown` — callers catch `unknown` and narrow at
+ * the boundary with `err instanceof Error ? err : null`.
+ */
+export function userFacingErrorMessage(
+  error: Error | string | null | undefined,
+  fallback: string,
+): string {
+  const raw = typeof error === "string" ? error : (error?.message ?? "");
+
+  let start = 0;
+  const uncaught = raw.lastIndexOf(UNCAUGHT);
+  if (uncaught !== -1) {
+    start = uncaught + UNCAUGHT.length;
+  } else {
+    const plain = raw.lastIndexOf(PLAIN);
+    if (plain !== -1) start = plain + PLAIN.length;
+  }
+
+  let text = raw.slice(start);
+  const newline = text.indexOf("\n");
+  if (newline !== -1) text = text.slice(0, newline);
+  const frame = text.indexOf(" at ");
+  if (frame !== -1) text = text.slice(0, frame);
+  text = text.trim();
+
+  // Nothing survived the strip, or the whole thing was the client's envelope.
+  if (text.length === 0 || text.startsWith("[CONVEX")) return fallback;
+  return text;
+}

package/app/src/convex/useHeldResult.ts

@@ -0,0 +1,26 @@
+import { useState } from "react";
+
+/**
+ * Keeps the last loaded `result` while a query is skipped, instead of
+ * flipping to `undefined`. Pair it with any `useQuery`:
+ *
+ *   const result = useQuery(api.x.get, args);
+ *   const shown = useHeldResult(result, args === "skip" ? null : JSON.stringify(args));
+ *
+ * `key` names what the result is for, and `null` means skipped. While skipped
+ * the last result stays (so a hidden pane that pauses its subscription does
+ * not flash a spinner when shown again). A new non-null key loads as
+ * `undefined` rather than showing the previous key's data; pass a stable key
+ * on purpose to keep the last result across argument changes.
+ */
+export function useHeldResult<T>(result: T | undefined, key: string | null): T | undefined {
+  // State, not a ref: reading a ref during render makes the React Compiler
+  // skip the file. Adjusting state during render is the supported way to
+  // remember a previous value.
+  const [held, setHeld] = useState({ key, value: result });
+  if (result !== undefined && (result !== held.value || key !== held.key)) {
+    setHeld({ key, value: result });
+  }
+  if (result !== undefined) return result;
+  return key === null || key === held.key ? held.value : undefined;
+}

package/app/src/index.ts

@@ -22,11 +22,17 @@ export {
   type UpdateToastOptions,
 } from "./update/updateWatcher.js";
 
-export { SettingsSection } from "./settings/SettingsSection.js";
+export {
+  SettingsSection,
+  type SettingsSectionConfig,
+} from "./settings/SettingsSection.js";
 export { SettingsField } from "./settings/SettingsField.js";
 export { SettingsStack } from "./settings/SettingsStack.js";
 export { SettingsToggleRow } from "./settings/SettingsToggleRow.js";
-export { SettingsEmptyState } from "./settings/SettingsEmptyState.js";
+export {
+  SettingsEmptyState,
+  type SettingsEmptyStateConfig,
+} from "./settings/SettingsEmptyState.js";
 export {
   DefaultSettingsLayout,
   SettingsPage,
@@ -89,3 +95,5 @@ export {
   type ViteEnvName,
 } from "./convex/env.js";
 export { useEnsureUser, type EnsureUserMutation } from "./convex/useEnsureUser.js";
+export { convexErrorMessage, userFacingErrorMessage } from "./convex/errorMessage.js";
+export { useHeldResult } from "./convex/useHeldResult.js";

package/app/src/settings/SettingsEmptyState.tsx

@@ -1,4 +1,15 @@
 import type { ComponentType, ReactNode } from "react";
+import { useUiConfig } from "../../../src/ui/ui-config";
+
+const ICON_CLASS = "mb-5 text-muted-foreground opacity-50";
+
+/** `UiConfig.SettingsEmptyState`: replaces the built-in classes of a part. */
+export interface SettingsEmptyStateConfig {
+  classes?: {
+    /** The icon above the title (colour, opacity, spacing). */
+    icon?: string;
+  };
+}
 
 interface SettingsEmptyStateProps {
   /** Tabler icon component, rendered muted above the copy. */
@@ -23,9 +34,11 @@ export function SettingsEmptyState({
   description,
   action,
 }: SettingsEmptyStateProps) {
+  const iconClass =
+    useUiConfig("SettingsEmptyState")?.classes?.icon ?? ICON_CLASS;
   return (
     <div className="flex flex-col items-center justify-center px-4 py-16 text-center">
-      <Icon size={28} className="mb-5 text-muted-foreground opacity-50" />
+      <Icon size={28} className={iconClass} />
       <h4 className="text-sm font-medium text-foreground">{title}</h4>
       {description ? (
         <p className="mt-2 max-w-sm text-xs leading-relaxed text-muted-foreground">

package/app/src/settings/SettingsSection.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 
-import { cn } from "../cn.js";
+import { useCn, useUiConfig } from "../../../src/ui/ui-config";
 
 type SettingsSectionBodyVariant = "form" | "list" | "compact";
 
@@ -10,6 +10,23 @@ const BODY_VARIANT_CLASS: Record<SettingsSectionBodyVariant, string> = {
   compact: "px-4 py-3",
 };
 
+const CARD_CLASS =
+  "rounded-lg bg-surface-card [&_input]:bg-field-background [&_textarea]:bg-field-background [&_[data-slot=select-trigger]]:bg-field-background [&_[role=combobox]]:border-border [&_[role=combobox]]:bg-field-background";
+const FOOTER_CLASS =
+  "flex items-center justify-end gap-2 rounded-b-lg bg-surface-secondary px-4 py-3";
+
+/** `UiConfig.SettingsSection`: replaces the built-in classes of a part. */
+export interface SettingsSectionConfig {
+  classes?: {
+    /** The card behind the body and footer (tone, radius, nested field fills). */
+    card?: string;
+    /** The bottom bar that holds `footer`. */
+    footer?: string;
+    /** Body padding per `bodyVariant`. */
+    body?: Partial<Record<SettingsSectionBodyVariant, string>>;
+  };
+}
+
 interface SettingsSectionProps {
   /** Section heading. Kept short — the description carries the detail. */
   title: ReactNode;
@@ -49,6 +66,9 @@ export function SettingsSection({
   bodyClassName,
   className,
 }: SettingsSectionProps) {
+  const config = useUiConfig("SettingsSection");
+  const cn = useCn();
+  const classes = config?.classes;
   const hasBody = children != null;
   const hasCard = hasBody || footer != null;
 
@@ -71,17 +91,22 @@ export function SettingsSection({
       {hasCard ? (
         <div
           className={cn(
-            "rounded-lg bg-surface-card [&_input]:bg-field-background [&_textarea]:bg-field-background [&_[data-slot=select-trigger]]:bg-field-background [&_[role=combobox]]:border-border [&_[role=combobox]]:bg-field-background",
+            classes?.card ?? CARD_CLASS,
             bodyVariant === "list" && "overflow-hidden",
           )}
         >
           {hasBody ? (
-            <div className={cn(BODY_VARIANT_CLASS[bodyVariant], bodyClassName)}>
+            <div
+              className={cn(
+                classes?.body?.[bodyVariant] ?? BODY_VARIANT_CLASS[bodyVariant],
+                bodyClassName,
+              )}
+            >
               {children}
             </div>
           ) : null}
           {footer ? (
-            <div className="flex items-center justify-end gap-2 rounded-b-lg bg-surface-secondary px-4 py-3">
+            <div className={classes?.footer ?? FOOTER_CLASS}>
               {footer}
             </div>
           ) : null}

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.26.1",
+  "version": "0.28.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"
@@ -34,6 +34,7 @@
     "./tokens/css/compat-shadcn-rgb.css": "./tokens/src/css/compat-shadcn-rgb.css",
     "./tokens/css/border-beam.css": "./tokens/src/css/border-beam.css",
     "./tokens/css/markdown.css": "./tokens/src/css/markdown.css",
+    "./tokens/css/marquee.css": "./tokens/src/css/marquee.css",
     "./tokens/compat/shadcn-rgb.css": "./tokens/src/css/compat-shadcn-rgb.css",
     "./tokens/css/*.css": "./tokens/src/css/*.css",
     "./tokens/tailwind-preset": {
@@ -44,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",
@@ -54,6 +60,7 @@
     "app/src",
     "tokens/src",
     "tokens/examples",
+    "fonts",
     "scripts/build-brand-assets.mjs",
     "README.md",
     "LICENSE",
@@ -62,7 +69,8 @@
   ],
   "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",

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() {