@vvedantb/ui 0.30.0 → 0.30.2

package/README.md

@@ -1196,9 +1196,10 @@ Generic pieces lifted from an app. Components that use `m` need the app's `LazyM
 
 ```tsx
 import {
-  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot,
+  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot, RollingNumber,
   MarqueeOnHover, RelativeDateTime, ImageLightbox, ImageGalleryPreview, ScreenshotPreview, VideoPreview,
-  useMediaQuery, useDocumentVisible, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  useMediaQuery, useDocumentVisible, useDocumentAppearance, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  useCountUpDisplay, parseCountable,
   convexErrorMessage, userFacingErrorMessage, useHeldResult,
 } from "@vvedantb/ui";
 ```
@@ -1206,12 +1207,16 @@ import {
 - `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`.
+- `RollingNumber` (`value`, `className`): shows an already formatted string ("1m 05s", "42%", "$1.20") and rolls each digit to its new value; other characters swap at once. Columns are keyed from the right, so "9s" → "10s" mounts only the new column. The full value stays in an `sr-only` span. For numbers that tick while the user watches; `CountPop` is for a badge that changes while the user looks elsewhere.
 - `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`).
+- Hooks: `useMediaQuery(query)`, `useDocumentVisible()`, `useDocumentAppearance()` (`"light" | "dark"` from `<html>`'s `dark` class or `data-theme`; `readDocumentAppearance` / `subscribeDocumentAppearance` are the React-free core), `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`).
+- `useCountUpDisplay(value)`: counts a number, or a label with one number ("45%", "12h", "$1.20"), from the last value to the new one over `tokenTransition.base`, keeping the prefix, suffix and decimal places. Where `RollingNumber` rolls each digit, this counts through the numbers between. The first value counts up from 0, and the same amount again does not replay. Labels it cannot count ("1h 12m", "—") show as they are, and so does every value while `PageMotionProvider` is `disabled`. `parseCountable(value)` is the parser: `{ amount, prefix, suffix, decimals }` or `null`.
 - 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`.
 
+Fixture for `RollingNumber`, `SendQueueIcon`, `PromptInputSubmit` `queued`, the `ActivityTasks` clock and `useCountUpDisplay`: `examples/motion-primitives/`.
+
 ## 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.
@@ -1497,6 +1502,7 @@ const config = {
   Outside a `StickToBottom` (for example a page outline) use `JumpRail` with `items` (`{ id, title, preview?, level? }`), a `scrollRef` or `getScrollElement`, and `targetAttribute="data-toc-id"` or `resolveTarget`. `onReveal` runs when a target is not in the DOM; `onBeforeScroll` runs just before it. `onSelect(id)` runs after a click or Enter/Space pick, once the scroll has started or `onReveal` has run, so an app can move focus to the target for keyboard users; `ChatJumpRail` accepts it too. `observeKey` re-observes when the rendered window changes. The geometry helpers (`resolveJumpRailTopPercent`, `resolveJumpRailIndexFromPointer`, `resolveJumpRailHeightStyle`, `resolveJumpRailTickWidthClass`, `resolveJumpRailTickLevelStyle`) are exported.
 - `Message`: `classes.root`, `classes.user`, `classes.assistant` (the role classes of `Message`), `classes.content` (all `MessageContent` classes), `classes.branchSelector`, `classes.branchIcon` (a class in place of the arrows' `size={14}`), and `lazyActionTooltips`: a `MessageAction` mounts its tooltip on first hover or focus (focus opens it), not with the button.
 - `PromptInput`: `classes.group` (the input group, default `overflow-hidden`), `classes.groupIdle` / `classes.groupDragOver` (added while no drag / an accepted drag is over the form), `classes.groupDefault` (added when no `containerClassName` is given), `classes.textarea`, `classes.footer`, `classes.submit`, `classes.tabItem`; `submitIcons.<send|submitted|streaming|error>`, `submitCrossfade` (cross-fade the submit icon on status change) and `menuTriggerAsChild` (`PromptInputActionMenuTrigger` becomes the Radix trigger instead of a button inside it). New `PromptInput` props: `dataDrop` (`{ type, onDrop }`: a non-file drag of that MIME type counts as a drag over the form and `onDrop` gets its string payload) and `inputGroupClassName` (same as `containerClassName`). The attachments context adds `replace(id, file)`; `accept` now matches extension patterns such as `.html` by file name; `useOptionalPromptInputController` is exported.
+- `PromptInputSubmit`: new prop `queued` (0.30.0). Set it when a send would join a queue (the agent is still working). The send icon becomes `SendQueueIcon`, an up arrow that morphs into a stack of bars while `queued` is `true`. Leave it unset to keep `submitIcons.send`. `SendQueueIcon` (`queued`, `className` default `size-4`) is exported for other send buttons. It uses `m`, so `queued` needs the app's `LazyMotion`.
 - `PromptInputSettings` (new): an overflow menu with a "Model" submenu (one radio list, or a submenu per provider). Entry: `providerLabel(provider)` (default the id), `providerIcon(provider)` (default none), `classes.trigger`.
 - `TraitsPanel` (new, with `isUltrathinkPrompt`, `applyUltrathinkPrefix`): reasoning, speed, context and thinking segments for a model picker; inside a `PromptInputProvider` it offers "Ultrathink" by editing the prompt. Entry: `classes.label`, `classes.empty`, `classes.option`, `classes.optionSelected`, `classes.optionIdle`, `classes.note`.
 - `PromptInputSpeech`, `useSpeechRecognition`, `getSpeechRecognition` (new): Web Speech API dictation; the button renders nothing without the API.
@@ -1518,7 +1524,7 @@ New dependency (installed with the package): `katex`. `streamdown` and the `@str
 
 AI surfaces that came from an app, exported from the root. Fills use `surface-secondary` (`bg-surface-secondary`, `from-surface-secondary/40`), which is the app's `--muted` under `compat-shadcn-rgb.css` and the secondary surface under `tokens.css`. They also use the shadcn colour names `bg-secondary`, `bg-popover` and `bg-card` and a few app utilities (`motion-press`, `smooth-shadow-*`, `scrollbar`, `scrollbar-none`, `text-2xs`, `text-3xs`), so they look as intended with `compat-shadcn-rgb.css` and an app that defines those utilities. They merge a caller `className` with `UiConfig.cn` when set.
 
-- `ActivityTasks` (`steps`, `isStreaming`, `name`, `startedAt`, `duration`, `layout` `folded | inline`, `onOpenFile`, `onRequestFullDetail`): an agent turn as a timeline. Tool runs fold behind one summary line, reasoning and mid-turn text render as Markdown, subtasks nest their steps, long timelines cap behind "Show N more". `OpenSubagentContext` gives subtask rows a "View" link.
+- `ActivityTasks` (`steps`, `isStreaming`, `name`, `startedAt`, `duration`, `layout` `folded | inline`, `onOpenFile`, `onRequestFullDetail`): an agent turn as a timeline. Tool runs fold behind one summary line, reasoning and mid-turn text render as Markdown, subtasks nest their steps, long timelines cap behind "Show N more". While `isStreaming` and before the first row, a header shows the time since `startedAt` as a `RollingNumber` clock. `OpenSubagentContext` gives subtask rows a "View" link.
 - The step model: `ActivityStep`, `ActivityTodoItem`, `ActivityQuestion`, `ActivityQuestionOption`, `ActivityStepOutput`, `ActivityStepEdit`, `activityStepHasRichDetail`, `activityStepConfig` (glyph and fallback label per step type), `ActivityThinkingIcon`, `useActivitySpinnerVerb`, `getRandomActivityVerb`, `useActivityElapsedSeconds`, `formatActivityElapsed`, `useStreamingDisclosure`.
 - Tool-call details show files with `FileChip` and output in a `CodeBlock` (`plain`) with its copy button, so the `CodeBlock` entry (see "App config: AI chat") styles those frames too.
 - `ActivityQuestionCard` (`questions`, `answers`): the read-only record of a multiple-choice question and its answer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",

package/src/client.ts

@@ -33,10 +33,16 @@ export { restoreModalScrollLock } from "./ui/overlay-a11y";
 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 { CountPop, countLabel, UnreadDot, CORNER_BADGE_CLASS, UnreadCornerBadge } from "./ui/count-pop";
 export { RollingNumber } from "./ui/rolling-number";
 export { ConfettiBurst } from "./ui/confetti-burst";
 export { SendQueueIcon } from "./ui/send-queue-icon";
+export { BulkActionBar } from "./ui/bulk-action-bar";
+export type { BulkActionBarProps, BulkBarAction } from "./ui/bulk-action-bar";
+export { CopyLinkMenuItem } from "./ui/copy-link-menu-item";
+export { ToggleSearch } from "./ui/toggle-search";
+export type { ToggleSearchProps, ToggleSearchVariant } from "./ui/toggle-search";
+export { MotionProvider } from "./motion/motion-provider";
 export { MarqueeOnHover } from "./ui/marquee-on-hover";
 export { RelativeDateTime } from "./ui/relative-date-time";
 export type { RelativeDateTimeProps } from "./ui/relative-date-time";

package/src/hooks/index.ts

@@ -1,5 +1,12 @@
 export { useMediaQuery } from "./use-media-query";
 export { useDocumentVisible } from "./use-document-visible";
+export {
+  readDocumentAppearance,
+  subscribeDocumentAppearance,
+  useDocumentAppearance,
+  type DocumentAppearance,
+} from "./use-document-appearance";
 export { createIdleCallback, useIdleCallback } from "./use-idle-callback";
 export { useSingleFlight } from "./use-single-flight";
 export { usePersistedScrollParent } from "./use-persisted-scroll-parent";
+export { parseCountable, useCountUpDisplay } from "./use-count-up-display";

package/src/hooks/use-count-up-display.ts

@@ -0,0 +1,80 @@
+import { animate } from "motion/react";
+import { useEffect, useRef, useState } from "react";
+import { useDisablePageMotion } from "../../app/src/page-motion/PageMotionProvider";
+import { motionEase, tokenTransition } from "../motion/presets";
+
+/** Suffixes we will count; compound durations like "1h 12m" stay static. */
+const COUNTABLE_SUFFIX = /^(?:%|h|k|m|s|ms)?$/i;
+
+/**
+ * Splits a label into the number to count and the text around it. A finite
+ * number passes through; a string needs one number with an optional prefix
+ * ("$", "~") and a suffix of `%`, `h`, `k`, `m`, `s` or `ms`. Anything else
+ * (`—`, "1h 12m", "3 of 5") is `null`.
+ */
+export function parseCountable(value: string | number): {
+  amount: number;
+  prefix: string;
+  suffix: string;
+  decimals: number;
+} | null {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return null;
+    return { amount: value, prefix: "", suffix: "", decimals: 0 };
+  }
+  const match = value.trim().match(/^(\D*?)(-?\d+(?:\.\d+)?)(\D*)$/);
+  if (!match) return null;
+  const prefix = match[1] ?? "";
+  const raw = match[2] ?? "";
+  const suffix = (match[3] ?? "").trim();
+  if (!COUNTABLE_SUFFIX.test(suffix)) return null;
+  const amount = Number(raw);
+  if (!Number.isFinite(amount)) return null;
+  const decimals = raw.includes(".") ? (raw.split(".")[1]?.length ?? 0) : 0;
+  return { amount, prefix, suffix, decimals };
+}
+
+/**
+ * Counts from the last seen number to `value` on `--motion-base`
+ * (`tokenTransition.base`), keeping the prefix, suffix and decimal places. The
+ * first value counts up from 0. The same amount again (a refetch) is a no-op,
+ * so the number does not replay on every write. Labels `parseCountable` rejects
+ * (`—`, "1h 12m") render as they are, and so does every value while
+ * `PageMotionProvider` is `disabled`.
+ */
+export function useCountUpDisplay(value: string | number): string | number {
+  const parsed = parseCountable(value);
+  const [display, setDisplay] = useState(value);
+  const lastAmount = useRef<number | null>(null);
+  const skipMotion = useDisablePageMotion();
+
+  useEffect(() => {
+    if (skipMotion) {
+      lastAmount.current = parsed?.amount ?? null;
+      setDisplay(value);
+      return;
+    }
+    if (!parsed) {
+      lastAmount.current = null;
+      setDisplay(value);
+      return;
+    }
+    if (lastAmount.current === parsed.amount) {
+      setDisplay(value);
+      return;
+    }
+    const from = lastAmount.current ?? 0;
+    lastAmount.current = parsed.amount;
+    const controls = animate(from, parsed.amount, {
+      duration: tokenTransition.base.duration,
+      ease: motionEase,
+      onUpdate: (latest) => {
+        const rounded = parsed.decimals > 0 ? latest.toFixed(parsed.decimals) : String(Math.round(latest));
+        setDisplay(`${parsed.prefix}${rounded}${parsed.suffix}`);
+      },
+    });
+    return () => controls.stop();
+  }, [parsed?.amount, parsed?.prefix, parsed?.suffix, parsed?.decimals, skipMotion, value]);
+
+  return display;
+}

package/src/hooks/use-document-appearance.ts

@@ -0,0 +1,46 @@
+import { useSyncExternalStore } from "react";
+
+/** Light or dark, as the page currently draws itself. Neutral is dark-family. */
+export type DocumentAppearance = "light" | "dark";
+
+/**
+ * Reads the appearance from `<html>`: the `dark` class (Tailwind's convention,
+ * set before paint by the app's boot script) or `data-theme="dark"`.
+ *
+ * Use this rather than a theme context when code can run outside the app's
+ * theme provider (a signed-out marketing page, a canvas effect): the class is
+ * the one source every page shares.
+ */
+export function readDocumentAppearance(): DocumentAppearance {
+  const root = document.documentElement;
+  return root.classList.contains("dark") ||
+    root.getAttribute("data-theme") === "dark"
+    ? "dark"
+    : "light";
+}
+
+/** Calls `onChange` whenever `<html>`'s class or `data-theme` changes. */
+export function subscribeDocumentAppearance(onChange: () => void): () => void {
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class", "data-theme"],
+  });
+  return () => observer.disconnect();
+}
+
+function readServerAppearance(): DocumentAppearance {
+  return "light";
+}
+
+/**
+ * The page's appearance, re-rendering when it changes. Server snapshot is
+ * `"light"`, matching a page with no `dark` class.
+ */
+export function useDocumentAppearance(): DocumentAppearance {
+  return useSyncExternalStore(
+    subscribeDocumentAppearance,
+    readDocumentAppearance,
+    readServerAppearance,
+  );
+}

package/src/index.ts

@@ -29,10 +29,16 @@ export { restoreModalScrollLock } from "./ui/overlay-a11y";
 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 { CountPop, countLabel, UnreadDot, CORNER_BADGE_CLASS, UnreadCornerBadge } from "./ui/count-pop";
 export { RollingNumber } from "./ui/rolling-number";
 export { ConfettiBurst } from "./ui/confetti-burst";
 export { SendQueueIcon } from "./ui/send-queue-icon";
+export { BulkActionBar } from "./ui/bulk-action-bar";
+export type { BulkActionBarProps, BulkBarAction } from "./ui/bulk-action-bar";
+export { CopyLinkMenuItem } from "./ui/copy-link-menu-item";
+export { ToggleSearch } from "./ui/toggle-search";
+export type { ToggleSearchProps, ToggleSearchVariant } from "./ui/toggle-search";
+export { MotionProvider } from "./motion/motion-provider";
 export { MarqueeOnHover } from "./ui/marquee-on-hover";
 export { RelativeDateTime } from "./ui/relative-date-time";
 export type { RelativeDateTimeProps } from "./ui/relative-date-time";

package/src/markdown/mermaid.ts

@@ -1,6 +1,10 @@
 import type { MermaidConfig } from "@streamdown/mermaid";
 import { useSyncExternalStore } from "react";
 import type { DiagramPlugin } from "streamdown";
+import {
+  readDocumentAppearance,
+  subscribeDocumentAppearance,
+} from "../hooks/use-document-appearance";
 
 /**
  * Mermaid for markdown, loaded on first use. `@streamdown/mermaid` imports
@@ -102,18 +106,9 @@ function subscribe(key: string, notify: () => void): () => void {
   };
 }
 
-/** The app theme lives as a `dark` class on `<html>` (neutral is dark-family). */
+/** Mermaid's theme for the page's current appearance (neutral is dark-family). */
 function readTheme(): MermaidTheme {
-  return document.documentElement.classList.contains("dark") ? "dark" : "default";
-}
-
-function subscribeTheme(notify: () => void): () => void {
-  const observer = new MutationObserver(notify);
-  observer.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: ["class"],
-  });
-  return () => observer.disconnect();
+  return readDocumentAppearance() === "dark" ? "dark" : "default";
 }
 
 /**
@@ -145,7 +140,7 @@ export function useMermaidRender(
   code: string,
   enabled: boolean,
 ): { theme: MermaidTheme; status: Entry["status"] } {
-  const theme = useSyncExternalStore(subscribeTheme, readTheme);
+  const theme = useSyncExternalStore(subscribeDocumentAppearance, readTheme);
   const key = enabled ? cacheKey(theme, code) : "";
   const entry = useSyncExternalStore(
     (notify) => (key === "" ? () => {} : subscribe(key, notify)),

package/src/motion/motion-provider.tsx

@@ -0,0 +1,29 @@
+import { LazyMotion, MotionConfig, domMax, type FeatureBundle } from "motion/react";
+import type { ReactNode } from "react";
+
+/**
+ * The app-wide Motion setup that `m.*` components (in this package and the
+ * app) need: one lazy feature bundle under `strict`, so a stray `motion.*`
+ * import throws instead of pulling the full bundle into the entry chunk.
+ *
+ * `features` defaults to `domMax`, which includes layout animations
+ * (`layoutId` shared highlights); `domAnimation` is smaller if the app has
+ * none. Under `strict` a missing feature silently skips the animation.
+ * `reducedMotion` defaults to `"user"` (follow the OS setting); pass `"never"`
+ * to always animate.
+ */
+export function MotionProvider({
+  children,
+  features = domMax,
+  reducedMotion = "user",
+}: {
+  children: ReactNode;
+  features?: FeatureBundle;
+  reducedMotion?: "user" | "always" | "never";
+}) {
+  return (
+    <LazyMotion features={features} strict>
+      <MotionConfig reducedMotion={reducedMotion}>{children}</MotionConfig>
+    </LazyMotion>
+  );
+}

package/src/motion/panel-transition.tsx

@@ -36,3 +36,42 @@ export function PanelTransition({
     </ViewTransition>
   );
 }
+
+export interface ViewTransitionSuspenseProps {
+  fallback: ReactNode;
+  children: ReactNode;
+  /** View transition class on the content as it arrives. Default `vt-enter`. */
+  enter?: string;
+  /** View transition class on the fallback as it leaves. Default `vt-exit`. */
+  exit?: string;
+}
+
+/**
+ * `<Suspense>` whose fallback fades out as the content comes in, through React
+ * `<ViewTransition>`. Suspense reveals commit on retry lanes, which React
+ * animates even outside `startTransition`. Needs a React build that exports
+ * `ViewTransition`; the app supplies the `::view-transition-old(.vt-exit)` and
+ * `::view-transition-new(.vt-enter)` CSS. Routers that commit route changes
+ * synchronously (through `useSyncExternalStore`) do not animate here; use the
+ * router's own view transition for pages.
+ */
+export function ViewTransitionSuspense({
+  fallback,
+  children,
+  enter = "vt-enter",
+  exit = "vt-exit",
+}: ViewTransitionSuspenseProps) {
+  return (
+    <React.Suspense
+      fallback={
+        <ViewTransition default="none" exit={exit}>
+          {fallback}
+        </ViewTransition>
+      }
+    >
+      <ViewTransition default="none" enter={enter}>
+        {children}
+      </ViewTransition>
+    </React.Suspense>
+  );
+}

package/src/ui/bulk-action-bar.tsx

@@ -0,0 +1,229 @@
+import { m, AnimatePresence } from "motion/react";
+import { ConfirmSkipHint, skipConfirmTitle } from "../../app/src/confirm/ConfirmSkipHint";
+import { tokenTransition } from "../motion/presets";
+import { CountPop } from "./count-pop";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "./dropdown-menu";
+import { Separator } from "./separator";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
+import { IconDots, IconX } from "@tabler/icons-react";
+import type { ComponentType } from "react";
+
+/**
+ * One control in the bar. The bar is deliberately dumb: each action carries the
+ * handler it should run, so confirm dialogs, Alt-to-skip and any per-surface
+ * bookkeeping stay with the caller that owns that state.
+ */
+export interface BulkBarAction {
+  key: string;
+  /** Full label used in the More menu and for accessibility. */
+  label: string;
+  /** Shorter label shown inline in the bar (defaults to `label`). */
+  shortLabel?: string;
+  icon: ComponentType<{ size: number; className?: string }>;
+  destructive?: boolean;
+  /** Shows the Alt-to-skip hint; the caller still owns the skip itself. */
+  showSkipHint?: boolean;
+  onClick: () => void;
+}
+
+export interface BulkActionBarProps {
+  isSelecting: boolean;
+  selectedCount: number;
+  totalCount: number;
+  onExitSelect: () => void;
+  onSelectAll: () => void;
+  onClearSelection: () => void;
+  primaryActions: ReadonlyArray<BulkBarAction>;
+  moreActions?: ReadonlyArray<BulkBarAction>;
+  destructiveAction?: BulkBarAction;
+  /** Motion key for the presence animation, e.g. "quick-tasks-bulk-bar". */
+  barKey: string;
+}
+
+/**
+ * A single labelled button inside the action bar. The label collapses to
+ * icon-only below the `sm` breakpoint (HeroUI "responsive labels" pattern).
+ */
+function BarButton({
+  action,
+  disabled,
+}: {
+  action: BulkBarAction;
+  disabled: boolean;
+}) {
+  const Icon = action.icon;
+  return (
+    <button
+      type="button"
+      aria-label={action.label}
+      title={
+        action.showSkipHint ? skipConfirmTitle(action.label) : action.label
+      }
+      onClick={action.onClick}
+      disabled={disabled}
+      // `motion-press`, not `transition-colors`: the destructive Delete takes
+      // this same branch, so the highest-consequence control in the bar was the
+      // one with no acknowledgement at all before its confirm dialog appeared.
+      className={`motion-press inline-flex h-9 shrink-0 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium active:scale-[0.96] disabled:pointer-events-none disabled:opacity-30 ${
+        action.destructive
+          ? "text-destructive hover:bg-destructive/10 hover:text-destructive"
+          : "text-muted-foreground hover:bg-surface-secondary hover:text-foreground"
+      }`}
+    >
+      <Icon size={17} />
+      <span className="hidden sm:inline">
+        {action.shortLabel ?? action.label}
+      </span>
+      {action.showSkipHint ? <ConfirmSkipHint /> : null}
+    </button>
+  );
+}
+
+/**
+ * The floating selection bar for any list with bulk actions. Render it inside
+ * a `relative` list container: it sits absolute at the bottom. It owns the shell only: presence
+ * motion, the count, select-all/clear, the primary buttons, the More menu and
+ * the destructive slot on the right. Behaviour arrives as `onClick` per action.
+ */
+export function BulkActionBar({
+  isSelecting,
+  selectedCount,
+  totalCount,
+  onExitSelect,
+  onSelectAll,
+  onClearSelection,
+  primaryActions,
+  moreActions,
+  destructiveAction,
+  barKey,
+}: BulkActionBarProps) {
+  const hasSelection = selectedCount > 0;
+  const allSelected = totalCount > 0 && selectedCount >= totalCount;
+
+  return (
+    <AnimatePresence initial={false}>
+      {isSelecting && (
+        <m.div
+          key={barKey}
+          className="absolute inset-x-0 bottom-3 z-20 flex justify-center px-4 pb-[env(safe-area-inset-bottom)]"
+          initial={{ opacity: 0, y: 20 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: 20 }}
+          transition={tokenTransition.fast}
+        >
+          <TooltipProvider>
+            <div className="flex max-w-[calc(100vw-2rem)] items-center gap-1 overflow-x-auto rounded-surface bg-popover/95 px-2.5 py-2 backdrop-blur-md smooth-shadow-ring-lg scrollbar-none">
+              {/* Prefix: selection count */}
+              <div className="flex shrink-0 items-center gap-2 pl-1 pr-0.5">
+                <CountPop
+                  label={String(selectedCount)}
+                  className="rounded-md bg-surface-secondary px-2 py-0.5 text-xs font-semibold text-foreground tabular-nums"
+                />
+                <span className="hidden text-sm font-medium text-muted-foreground sm:inline">
+                  selected
+                </span>
+              </div>
+
+              {/* Reaching the whole list is the one action a selection bar can
+                  offer that the rows cannot: shift-clicking to the end of a
+                  long list is the alternative. */}
+              {totalCount > 0 && (
+                <button
+                  type="button"
+                  onClick={allSelected ? onClearSelection : onSelectAll}
+                  className="motion-press inline-flex h-9 shrink-0 items-center rounded-lg px-2 text-sm font-medium text-muted-foreground hover:bg-surface-secondary hover:text-foreground active:scale-[0.96]"
+                >
+                  {allSelected ? "Clear" : `Select all (${totalCount})`}
+                </button>
+              )}
+
+              <Separator
+                orientation="vertical"
+                className="mx-1.5 h-5 shrink-0 bg-border"
+              />
+
+              {/* Content: primary actions + More dropdown */}
+              {primaryActions.map((action) => (
+                <BarButton
+                  key={action.key}
+                  action={action}
+                  disabled={!hasSelection}
+                />
+              ))}
+
+              {moreActions && moreActions.length > 0 && (
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <button
+                      type="button"
+                      aria-label="More actions"
+                      disabled={!hasSelection}
+                      className="inline-flex size-9 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-surface-secondary hover:text-foreground disabled:pointer-events-none disabled:opacity-30 data-[state=open]:bg-surface-secondary data-[state=open]:text-foreground"
+                    >
+                      <IconDots size={17} />
+                    </button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="center" side="top" sideOffset={8}>
+                    {moreActions.map((action) => {
+                      const Icon = action.icon;
+                      return (
+                        <DropdownMenuItem
+                          key={action.key}
+                          disabled={!hasSelection}
+                          onClick={action.onClick}
+                        >
+                          <Icon size={16} />
+                          {action.label}
+                        </DropdownMenuItem>
+                      );
+                    })}
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              )}
+
+              {destructiveAction && (
+                <>
+                  <Separator
+                    orientation="vertical"
+                    className="mx-1.5 h-5 shrink-0 bg-border"
+                  />
+                  <BarButton
+                    action={destructiveAction}
+                    disabled={!hasSelection}
+                  />
+                </>
+              )}
+
+              <Separator
+                orientation="vertical"
+                className="mx-1.5 h-5 shrink-0 bg-border"
+              />
+
+              {/* Suffix: dismiss selection */}
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <button
+                    type="button"
+                    aria-label="Cancel selection"
+                    className="inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-surface-secondary hover:text-foreground"
+                    onClick={onExitSelect}
+                  >
+                    <IconX size={17} />
+                  </button>
+                </TooltipTrigger>
+                <TooltipContent side="top" className="text-xs" sideOffset={8}>
+                  Cancel selection
+                </TooltipContent>
+              </Tooltip>
+            </div>
+          </TooltipProvider>
+        </m.div>
+      )}
+    </AnimatePresence>
+  );
+}

package/src/ui/clearInputDissolve.ts

@@ -1,5 +1,7 @@
 /** transitions.dev input clear with dissolve — see 13-input-clear-dissolve.md */
 
+import { readDocumentAppearance } from "../hooks/use-document-appearance";
+
 // Times come back in ms. CSS minifiers rewrite `1000ms` as `1s`, so a value
 // in seconds is converted rather than read as 1.
 export function readCssNumber(
@@ -53,13 +55,6 @@ export function readCssEase(root: HTMLElement, name: string): (t: number) => num
   };
 }
 
-function isDarkTheme(root: HTMLElement): boolean {
-  return (
-    root.classList.contains("dark") ||
-    root.getAttribute("data-theme") === "dark"
-  );
-}
-
 function measureCanvas(): CanvasRenderingContext2D | null {
   const canvas = document.createElement("canvas");
   return canvas.getContext("2d");
@@ -93,7 +88,7 @@ function buildGlowBackground(
     return "";
   }
   canvas.font = getComputedStyle(input).font;
-  const dark = isDarkTheme(root);
+  const dark = readDocumentAppearance() === "dark";
   const rgb = dark ? "255,255,255" : "0,0,0";
   const width = wrap.clientWidth || 280;
   const padLeft = parseFloat(getComputedStyle(input).paddingLeft) || 12;

package/src/ui/copy-link-menu-item.tsx

@@ -0,0 +1,29 @@
+import { IconLink } from "@tabler/icons-react";
+import { DropdownMenuItem } from "./dropdown-menu";
+
+/**
+ * A "Copy link" item for a More menu: copies the current page URL. Pass `path`
+ * when the current URL is not the link to share (a per-user route that shows
+ * different content to each person, say); it resolves against the origin.
+ */
+export function CopyLinkMenuItem({
+  iconSize = 14,
+  path,
+  label = "Copy link",
+}: {
+  iconSize?: number;
+  path?: string;
+  label?: string;
+}) {
+  return (
+    <DropdownMenuItem
+      onClick={() => {
+        const href = path ? new URL(path, window.location.origin).href : window.location.href;
+        void navigator.clipboard.writeText(href);
+      }}
+    >
+      <IconLink size={iconSize} />
+      {label}
+    </DropdownMenuItem>
+  );
+}

package/src/ui/count-pop.tsx

@@ -65,3 +65,21 @@ export function UnreadDot({ show, className }: { show: boolean; className?: stri
     </CountPop>
   );
 }
+
+/**
+ * Shape and placement of a count badge hung off a tile's bottom-right corner.
+ * Put the tile in a `relative` box; add one tone class (e.g. a live colour).
+ */
+export const CORNER_BADGE_CLASS =
+  "absolute -bottom-0.5 -right-0.5 flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] font-semibold leading-none";
+
+/** An unread count on a tile's corner: `CountPop` in the primary tone, "99+" above 99. */
+export function UnreadCornerBadge({ count, className }: { count: number | undefined; className?: string }) {
+  const cn = useCn();
+  return (
+    <CountPop
+      label={countLabel(count)}
+      className={cn(CORNER_BADGE_CLASS, "bg-primary text-primary-foreground", className)}
+    />
+  );
+}

package/src/ui/toggle-search.tsx

@@ -0,0 +1,138 @@
+import { useState, type KeyboardEventHandler } from "react";
+import { IconSearch } from "@tabler/icons-react";
+import { Button } from "./button";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { SearchInput } from "./search-input";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
+
+// "compact" is the always-visible logs/toolbar field. "large" is the icon
+// button + popover, which keeps a crowded toolbar short.
+export type ToggleSearchVariant = "compact" | "large";
+
+export interface ToggleSearchProps {
+  value: string;
+  onChange: (value: string | null) => void;
+  placeholder?: string;
+  visible?: boolean;
+  variant?: ToggleSearchVariant;
+}
+
+function SearchField({
+  value,
+  onChange,
+  placeholder,
+  className,
+  onKeyDown,
+  autoFocus,
+}: {
+  value: string;
+  onChange: (value: string | null) => void;
+  placeholder: string;
+  className?: string;
+  onKeyDown?: KeyboardEventHandler<HTMLInputElement>;
+  autoFocus?: boolean;
+}) {
+  return (
+    <SearchInput
+      value={value}
+      onChange={(next) => onChange(next.length > 0 ? next : null)}
+      onClear={() => onChange(null)}
+      placeholder={placeholder}
+      className={className}
+      inputClassName="h-8"
+      autoFocus={autoFocus}
+      onKeyDown={onKeyDown}
+    />
+  );
+}
+
+/**
+ * Toolbar search. Compact stays an inline field; large collapses to an icon
+ * that opens a popover — a primary dot on the button means a query is applied.
+ * `large` uses a `Tooltip`, so render it under the app's `TooltipProvider`.
+ */
+export function ToggleSearch({
+  value,
+  onChange,
+  placeholder = "Search...",
+  visible = true,
+  variant = "compact",
+}: ToggleSearchProps) {
+  const [open, setOpen] = useState(false);
+  const hasQuery = value.trim().length > 0;
+
+  if (!visible) return null;
+
+  if (variant === "compact") {
+    return (
+      <SearchField
+        value={value}
+        onChange={onChange}
+        placeholder={placeholder}
+        // `max-sm:min-w-0` + `sm:shrink-0`: on a phone the field yields to its
+        // toolbar siblings instead of forcing the row (and the page) to overflow.
+        className="w-36 max-w-none max-sm:min-w-0 sm:w-44 sm:shrink-0"
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            onChange(null);
+          }
+        }}
+      />
+    );
+  }
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <PopoverTrigger asChild>
+            <Button
+              size="icon-sm"
+              variant="secondary"
+              aria-label={hasQuery ? "Search, filter applied" : "Search"}
+              aria-pressed={open}
+              className="relative motion-press hover:scale-[1.01] active:scale-[0.96]"
+            >
+              <IconSearch size={16} />
+              {hasQuery ? (
+                <span
+                  aria-hidden
+                  className="pointer-events-none absolute -top-0.5 -right-0.5 z-10 size-2 rounded-full bg-primary ring-2 ring-background"
+                />
+              ) : null}
+            </Button>
+          </PopoverTrigger>
+        </TooltipTrigger>
+        <TooltipContent>Search</TooltipContent>
+      </Tooltip>
+      <PopoverContent
+        align="end"
+        className="w-72 p-2"
+        onOpenAutoFocus={(event) => {
+          // Radix types this as a plain `Event`, so the content element has to
+          // be narrowed before it can be searched for the field.
+          const content = event.currentTarget;
+          if (!(content instanceof HTMLElement)) return;
+          const input = content.querySelector("input");
+          if (input instanceof HTMLInputElement) {
+            event.preventDefault();
+            input.focus();
+          }
+        }}
+      >
+        <SearchField
+          value={value}
+          onChange={onChange}
+          placeholder={placeholder}
+          className="w-full max-w-none"
+          autoFocus
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              setOpen(false);
+            }
+          }}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}