@vvedantb/ui 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -52,15 +52,6 @@
   "sideEffects": [
     "./src/ui/sonner.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 tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs",
-    "prepack": "node tokens/scripts/check-exports.mjs"
-  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -171,5 +162,13 @@
     "zod": {
       "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 tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs"
   }
-}
+}

package/shell/src/SessionsHoverCard.test.tsx

@@ -0,0 +1,256 @@
+// @vitest-environment happy-dom
+import { act, createRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SessionsHoverCard } from "./SessionsHoverCard";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+async function mount(node: React.ReactNode) {
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () => {
+    root!.render(node);
+  });
+}
+
+afterEach(async () => {
+  await act(async () => root?.unmount());
+  host?.remove();
+  document.body.innerHTML = "";
+  root = null;
+  host = null;
+});
+
+describe("SessionsHoverCard", () => {
+  it("renders header, body and footer slots when open", async () => {
+    await mount(
+      <SessionsHoverCard open header="Head" body="Body text" footer="Foot">
+        <button type="button">Row</button>
+      </SessionsHoverCard>,
+    );
+    const text = document.body.textContent ?? "";
+    expect(text).toContain("Row");
+    expect(text).toContain("Head");
+    expect(text).toContain("Body text");
+    expect(text).toContain("Foot");
+    expect(document.body.innerHTML).toContain("w-64");
+  });
+
+  it("does not call the body render prop or loadContent while closed", async () => {
+    const body = vi.fn(() => "x");
+    const loadContent = vi.fn(() => "y");
+    await mount(
+      <>
+        <SessionsHoverCard open={false} body={body}>
+          <button type="button">A</button>
+        </SessionsHoverCard>
+        <SessionsHoverCard open={false} loadContent={loadContent}>
+          <button type="button">B</button>
+        </SessionsHoverCard>
+      </>,
+    );
+    expect(body).not.toHaveBeenCalled();
+    expect(loadContent).not.toHaveBeenCalled();
+  });
+
+  it("calls the render prop with open true and loads content once when open", async () => {
+    const body = vi.fn((ctx: { open: boolean }) => `open=${ctx.open}`);
+    const loadContent = vi.fn(async () => "Loaded preview");
+    await mount(
+      <>
+        <SessionsHoverCard open body={body}>
+          <button type="button">A</button>
+        </SessionsHoverCard>
+        <SessionsHoverCard open loadContent={loadContent} loadingFallback="Loading">
+          <button type="button">B</button>
+        </SessionsHoverCard>
+      </>,
+    );
+    expect(body).toHaveBeenCalledWith({ open: true });
+    expect(document.body.textContent).toContain("open=true");
+    expect(loadContent).toHaveBeenCalledTimes(1);
+    expect(document.body.textContent).toContain("Loaded preview");
+  });
+
+  it("portals the content to document.body by default", async () => {
+    await mount(
+      <div id="clip" style={{ overflow: "hidden" }}>
+        <SessionsHoverCard open body="Body text">
+          <button type="button">Row</button>
+        </SessionsHoverCard>
+      </div>,
+    );
+    const content = document.querySelector("[data-radix-popper-content-wrapper]");
+    expect(content).not.toBeNull();
+    expect(document.getElementById("clip")!.contains(content)).toBe(false);
+    expect(document.body.textContent).toContain("Body text");
+  });
+
+  it("keeps the content in place with portal={false}", async () => {
+    await mount(
+      <div id="clip" style={{ overflow: "hidden" }}>
+        <SessionsHoverCard open portal={false} body="Body text">
+          <button type="button">Row</button>
+        </SessionsHoverCard>
+      </div>,
+    );
+    const content = document.querySelector("[data-radix-popper-content-wrapper]");
+    expect(document.getElementById("clip")!.contains(content)).toBe(true);
+  });
+
+  it("swaps the surface without keeping the default one", async () => {
+    await mount(
+      <>
+        <SessionsHoverCard open surface="glass" body="G" className="p-5">
+          <button type="button">A</button>
+        </SessionsHoverCard>
+      </>,
+    );
+    const card = document.querySelector("[data-state=open][data-side]") as HTMLElement;
+    expect(card.className).toContain("glass-panel-strong");
+    expect(card.className).toContain("rounded-surface");
+    expect(card.className).not.toContain("bg-overlay");
+    expect(card.className).not.toContain("rounded-lg");
+    expect(card.className).toContain("p-5");
+    expect(card.className).not.toContain("p-3");
+  });
+
+  it("uses the floating overlay surface by default", async () => {
+    await mount(
+      <SessionsHoverCard open body="B">
+        <button type="button">A</button>
+      </SessionsHoverCard>,
+    );
+    const card = document.querySelector("[data-state=open][data-side]") as HTMLElement;
+    expect(card.className).toContain("bg-overlay");
+    expect(card.className).toContain("rounded-lg");
+  });
+
+  it("forwards the ref and props to the child trigger and keeps its handlers", async () => {
+    const ref = createRef<HTMLButtonElement>();
+    const onClick = vi.fn();
+    await mount(
+      <SessionsHoverCard ref={ref as never} data-testid="row" body="B">
+        <button type="button" onClick={onClick}>
+          Row
+        </button>
+      </SessionsHoverCard>,
+    );
+    const button = document.querySelector("button") as HTMLButtonElement;
+    expect(ref.current).toBe(button);
+    expect(button.getAttribute("data-testid")).toBe("row");
+    await act(async () => button.click());
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders its own trigger element with asChild={false}", async () => {
+    await mount(
+      <SessionsHoverCard asChild={false} body="B">
+        <span>Row</span>
+      </SessionsHoverCard>,
+    );
+    const trigger = document.querySelector("[data-state]") as HTMLElement;
+    expect(trigger.tagName).toBe("A");
+    expect(trigger.textContent).toBe("Row");
+  });
+
+  describe("focus and pointer", () => {
+    function setFocusVisible(el: HTMLElement, value: boolean) {
+      const orig = el.matches.bind(el);
+      el.matches = (sel: string) => (sel === ":focus-visible" ? value : orig(sel));
+    }
+
+    it("does not open on pointer-driven focus after a context menu", async () => {
+      const onOpenChange = vi.fn();
+      await mount(
+        <SessionsHoverCard openDelay={0} header="Head" onOpenChange={onOpenChange}>
+          <button type="button">Row</button>
+        </SessionsHoverCard>,
+      );
+      const row = document.querySelector("button")!;
+      setFocusVisible(row, false);
+      await act(async () => {
+        row.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true }));
+        row.dispatchEvent(new FocusEvent("focus", { bubbles: false }));
+        row.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+      });
+      await act(async () => new Promise((r) => setTimeout(r, 20)));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+      expect(document.body.textContent).not.toContain("Head");
+    });
+
+    it("opens on keyboard focus-visible", async () => {
+      const onOpenChange = vi.fn();
+      await mount(
+        <SessionsHoverCard openDelay={0} header="Head" onOpenChange={onOpenChange}>
+          <button type="button">Row</button>
+        </SessionsHoverCard>,
+      );
+      const row = document.querySelector("button")!;
+      setFocusVisible(row, true);
+      await act(async () => {
+        row.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+      });
+      await act(async () => new Promise((r) => setTimeout(r, 20)));
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    // React derives onPointerLeave from native pointerout (with a null or outside
+    // relatedTarget). A native pointerleave event does not reach the handler.
+    function leave(el: HTMLElement) {
+      return act(async () => {
+        el.dispatchEvent(new PointerEvent("pointerout", { pointerType: "mouse", bubbles: true, relatedTarget: null }));
+      });
+    }
+
+    it("closes on pointer leave when stuck open by non-focus-visible focus", async () => {
+      const onOpenChange = vi.fn();
+      await mount(
+        <SessionsHoverCard defaultOpen header="Head" onOpenChange={onOpenChange}>
+          <button type="button">Row</button>
+        </SessionsHoverCard>,
+      );
+      const row = document.querySelector("button")!;
+      setFocusVisible(row, false);
+      row.focus();
+      await leave(row);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+      await act(async () => new Promise((r) => setTimeout(r, 20)));
+      expect(document.body.textContent).not.toContain("Head");
+    });
+
+    it("stays open on pointer leave with keyboard focus-visible", async () => {
+      const onOpenChange = vi.fn();
+      await mount(
+        <SessionsHoverCard defaultOpen header="Head" onOpenChange={onOpenChange}>
+          <button type="button">Row</button>
+        </SessionsHoverCard>,
+      );
+      const row = document.querySelector("button")!;
+      setFocusVisible(row, true);
+      row.focus();
+      await leave(row);
+      await act(async () => new Promise((r) => setTimeout(r, 20)));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+      expect(document.body.textContent).toContain("Head");
+    });
+
+    it("does not force-close on pointer leave without focus (Radix owns hover close)", async () => {
+      const onOpenChange = vi.fn();
+      await mount(
+        <SessionsHoverCard defaultOpen closeDelay={1000} header="Head" onOpenChange={onOpenChange}>
+          <button type="button">Row</button>
+        </SessionsHoverCard>,
+      );
+      const row = document.querySelector("button")!;
+      await leave(row);
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+      expect(document.body.textContent).toContain("Head");
+    });
+  });
+});

package/src/composer/input-area/InputArea.tsx

@@ -1,4 +1,4 @@
-import type { ChangeEvent, ReactNode } from "react";
+import type { ChangeEvent, ReactNode, RefObject } from "react";
 import { useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { AnimatePresence, domAnimation, LazyMotion, m } from "motion/react";
@@ -22,6 +22,7 @@ import {
 import { SpeechInput } from "../../ai-elements/speech-input";
 import { chatInputContainerClass } from "../../ui/surface-classes";
 import { ComposerSlashMenu } from "./ComposerSlashMenu";
+import { InputAreaEditor } from "./InputAreaEditor";
 import { FadePresence } from "./FadePresence";
 import { InputActions, type InputActionsProps } from "./InputActions";
 import { motionFast } from "./motion";
@@ -30,6 +31,8 @@ import { useComposerCompact } from "./useComposerCompact";
 import { useComposerSlashMenu } from "./useComposerSlashMenu";
 import { useInputAreaPrediction } from "./useInputAreaPrediction";
 
+const EXPANDED_EDITOR =
+  "min-h-16 max-h-50 w-full self-stretch overflow-y-auto rounded-none px-4 pt-3.5 pb-1 text-left";
 const COMPACT_EDITOR =
   "flex min-h-9 max-h-9 min-w-0 w-auto flex-1 items-center self-center overflow-hidden whitespace-pre! rounded-none px-1 py-2 text-left leading-5";
 const COMPACT_START_ADDON =
@@ -67,8 +70,9 @@ export type InputAreaProps = {
   /** When omitted: the draft has text, or `fileCount` or `chipCount` is above 0. */
   canSubmit?: boolean;
 
-  /** Inputs to the compact pill. */
+  /** Files force the stacked card. */
   fileCount?: number;
+  /** Chips never force the stacked card. They only enable send and Backspace removal. */
   chipCount?: number;
 
   showDictate?: boolean;
@@ -86,8 +90,10 @@ export type InputAreaProps = {
   queue?: ReactNode;
   /** Attachment strip. Shown inside the input, above the text. */
   attachments?: ReactNode;
-  /** Chip row. Shown inside the input, above the text. */
+  /** Chip row. Shown inside the input, before the text (see `chipsPlacement`). */
   chips?: ReactNode;
+  /** `inline` (default): chips are non-editable atoms at the start of the same text flow, so wrapped lines start under them. `top`: chips sit in a strip above the text. */
+  chipsPlacement?: "inline" | "top";
   /** Extra rows in the plus menu after the attach row. Include your own separators. */
   plusMenuExtra?: ReactNode;
   /** Props merged onto the plus-menu dropdown content, such as `align`, `side` or `sideOffset`. Defaults: `align="start"`, `side="top"`. */
@@ -102,7 +108,7 @@ export type InputAreaProps = {
   /** Returns a continuation for the draft. Omit to turn ghost text off. */
   getPrediction?: (text: string) => Promise<string>;
   predictionEnabled?: boolean;
-  /** Classes on the ghost suggestion span. Default matches the original app composer. */
+  /** Classes for the ghost suggestion. With `chipsPlacement="top"` they sit on the overlay span. Inline mode copies their colour and opacity to the `::after` ghost text. */
   predictionTextClassName?: string;
 
   /** Wrapper around banners, queue and the input. */
@@ -142,6 +148,7 @@ export function InputArea({
   queue,
   attachments,
   chips,
+  chipsPlacement = "inline",
   plusMenuExtra,
   plusMenuContentProps,
   slashItems,
@@ -164,7 +171,10 @@ export function InputArea({
     if (!isControlled) setInternalValue(next);
     onChange?.(next);
   };
-  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const inputRef = useRef<HTMLElement>(null);
+  // Measure once after mount so a long `defaultValue` expands on first paint.
+  const [, setMeasured] = useState(false);
+  useEffect(() => setMeasured(true), []);
   const fileInputRef = useRef<HTMLInputElement>(null);
   const hasFiles = fileCount > 0;
 
@@ -176,7 +186,6 @@ export function InputArea({
   const { chromeRef, compact } = useComposerCompact({
     value: input,
     fileCount,
-    chipCount,
   });
 
   const items = slashItems ?? [];
@@ -195,13 +204,17 @@ export function InputArea({
     getPrediction,
   });
 
+  const inlineMode = chipsPlacement === "inline";
+
   const textareaClassName = cn(
     "bg-transparent! shadow-none border-none",
     "text-sm md:text-[15px] leading-5 placeholder:text-muted-foreground",
-    "smooth-typing-input field-sizing-content focus-visible:outline-hidden",
+    "smooth-typing-input focus-visible:outline-hidden",
     compact
       ? COMPACT_EDITOR
-      : "min-h-16 max-h-50 w-full self-stretch overflow-y-auto rounded-none px-4 pt-3.5 pb-1 text-left",
+      : // `py-0` clears InputGroupTextarea's default `py-3`.
+        cn(EXPANDED_EDITOR, "py-0 pt-3.5 pb-1"),
+    !inlineMode && "field-sizing-content",
   );
 
   const submitDisabled =
@@ -229,12 +242,25 @@ export function InputArea({
       const activeElement = document.activeElement;
       const isInputFocused =
         activeElement instanceof HTMLInputElement ||
-        activeElement instanceof HTMLTextAreaElement;
-      if (!isInputFocused && inputRef.current) {
-        const textarea = inputRef.current;
-        textarea.focus();
-        const length = textarea.value.length;
-        textarea.setSelectionRange(length, length);
+        activeElement instanceof HTMLTextAreaElement ||
+        (activeElement instanceof HTMLElement &&
+          activeElement.isContentEditable);
+      const editor = inputRef.current;
+      if (!isInputFocused && editor) {
+        editor.focus();
+        if (editor instanceof HTMLTextAreaElement) {
+          const length = editor.value.length;
+          editor.setSelectionRange(length, length);
+        } else {
+          const sel = window.getSelection();
+          if (sel) {
+            const range = document.createRange();
+            range.selectNodeContents(editor);
+            range.collapse(false);
+            sel.removeAllRanges();
+            sel.addRange(range);
+          }
+        }
       }
     };
     window.addEventListener("keydown", handleKeyDown);
@@ -332,6 +358,112 @@ export function InputArea({
     </div>
   );
 
+  const comboboxProps = {
+    role: slashMenu.comboboxProps.role,
+    "aria-multiline": slashMenu.comboboxProps["aria-multiline"],
+    "aria-haspopup": slashMenu.comboboxProps["aria-haspopup"],
+    "aria-autocomplete": slashMenu.comboboxProps["aria-autocomplete"],
+    "aria-expanded": slashMenu.comboboxProps["aria-expanded"],
+    "aria-controls": slashMenu.comboboxProps["aria-controls"],
+    "aria-activedescendant": slashMenu.comboboxProps["aria-activedescendant"],
+  };
+
+  /** Slash menu and ghost text keys. Returns true when handled. */
+  const handleCommonKeyDown = (
+    event: Parameters<typeof slashMenu.onKeyDown>[0],
+  ): boolean => {
+    if (slashMenu.onKeyDown(event)) return true;
+    if (prediction.suggestion) {
+      if (event.key === "Tab" && !event.shiftKey) {
+        event.preventDefault();
+        setInput(input + prediction.suggestion);
+        return true;
+      }
+      if (event.key === "Escape") {
+        event.preventDefault();
+        prediction.dismiss();
+        return true;
+      }
+    }
+    return false;
+  };
+
+  const body = (
+    <PromptInputBody>
+      <div
+        className={cn(
+          "relative min-w-0",
+          compact ? "flex-1" : "w-full self-stretch",
+        )}
+      >
+        {inlineMode ? (
+          <InputAreaEditor
+            editorRef={inputRef as RefObject<HTMLDivElement | null>}
+            value={input}
+            onValueChange={setInput}
+            placeholder={placeholder}
+            suggestion={prediction.suggestion || undefined}
+            suggestionClassName={predictionTextClassName}
+            chips={chips}
+            chipCount={chipCount}
+            onRemoveLastChip={onRemoveLastChip}
+            className={cn(textareaClassName, "relative z-10")}
+            ariaProps={comboboxProps}
+            onKeyDown={(event) => {
+              handleCommonKeyDown(event);
+            }}
+            onBlur={slashMenu.onBlur}
+          />
+        ) : (
+          <>
+            {prediction.suggestion ? (
+              <div
+                aria-hidden
+                className={cn(
+                  textareaClassName,
+                  "pointer-events-none absolute inset-0 z-0 overflow-hidden whitespace-pre-wrap wrap-break-word text-foreground",
+                )}
+              >
+                {input}
+                <span className={predictionTextClassName}>
+                  {prediction.suggestion}
+                </span>
+              </div>
+            ) : null}
+            <PromptInputTextarea
+              ref={inputRef as RefObject<HTMLTextAreaElement | null>}
+              value={input}
+              placeholder={placeholder}
+              className={cn(
+                textareaClassName,
+                "relative z-10",
+                prediction.suggestion && "caret-current text-transparent",
+              )}
+              rows={1}
+              {...comboboxProps}
+              onKeyDown={(event) => {
+                if (handleCommonKeyDown(event)) return;
+                if (
+                  event.key === "Backspace" &&
+                  event.currentTarget.selectionStart === 0 &&
+                  event.currentTarget.selectionEnd === 0 &&
+                  chipCount > 0
+                ) {
+                  event.preventDefault();
+                  onRemoveLastChip?.();
+                }
+              }}
+              onBlur={slashMenu.onBlur}
+              onChange={(e) => {
+                setInput(e.currentTarget.value);
+              }}
+            />
+          </>
+        )}
+      </div>
+    </PromptInputBody>
+  );
+
   return (
     <LazyMotion features={domAnimation}>
     <TooltipProvider>
@@ -365,7 +497,7 @@ export function InputArea({
                   "flex w-full min-w-0 [interpolate-size:allow-keywords] transition-[color,box-shadow,border-color,border-radius,height] duration-200",
                   chatInputContainerClass,
                   compact
-                    ? "h-12 flex-row flex-nowrap items-center rounded-full py-1 has-[>textarea]:h-12"
+                    ? "h-12 flex-row flex-nowrap items-center rounded-full py-1 has-[[data-slot=input-group-control]]:h-12"
                     : "h-auto flex-col items-start rounded-surface",
                   borderClassName,
                   containerClassName,
@@ -390,7 +522,7 @@ export function InputArea({
                 }
               >
                 {showFileUpload ? attachments : null}
-                {chips}
+                {inlineMode ? null : chips}
                 {compact ? (
                   <InputGroupAddon
                     align="inline-start"
@@ -399,80 +531,7 @@ export function InputArea({
                     {plusButton}
                   </InputGroupAddon>
                 ) : null}
-                <PromptInputBody>
-                  <div
-                    className={cn(
-                      "relative min-w-0",
-                      compact ? "flex-1" : "w-full self-stretch",
-                    )}
-                  >
-                    {prediction.suggestion ? (
-                      <div
-                        aria-hidden
-                        className={cn(
-                          textareaClassName,
-                          "pointer-events-none absolute inset-0 z-0 overflow-hidden whitespace-pre-wrap wrap-break-word text-foreground",
-                        )}
-                      >
-                        {input}
-                        <span className={predictionTextClassName}>
-                          {prediction.suggestion}
-                        </span>
-                      </div>
-                    ) : null}
-                    <PromptInputTextarea
-                      ref={inputRef}
-                      value={input}
-                      placeholder={placeholder}
-                      className={cn(
-                        textareaClassName,
-                        "relative z-10",
-                        prediction.suggestion &&
-                          "caret-current text-transparent",
-                      )}
-                      rows={1}
-                      role={slashMenu.comboboxProps.role}
-                      aria-multiline={slashMenu.comboboxProps["aria-multiline"]}
-                      aria-haspopup={slashMenu.comboboxProps["aria-haspopup"]}
-                      aria-autocomplete={
-                        slashMenu.comboboxProps["aria-autocomplete"]
-                      }
-                      aria-expanded={slashMenu.comboboxProps["aria-expanded"]}
-                      aria-controls={slashMenu.comboboxProps["aria-controls"]}
-                      aria-activedescendant={
-                        slashMenu.comboboxProps["aria-activedescendant"]
-                      }
-                      onKeyDown={(event) => {
-                        if (slashMenu.onKeyDown(event)) return;
-                        if (prediction.suggestion) {
-                          if (event.key === "Tab" && !event.shiftKey) {
-                            event.preventDefault();
-                            setInput(input + prediction.suggestion);
-                            return;
-                          }
-                          if (event.key === "Escape") {
-                            event.preventDefault();
-                            prediction.dismiss();
-                            return;
-                          }
-                        }
-                        if (
-                          event.key === "Backspace" &&
-                          event.currentTarget.selectionStart === 0 &&
-                          event.currentTarget.selectionEnd === 0 &&
-                          chipCount > 0
-                        ) {
-                          event.preventDefault();
-                          onRemoveLastChip?.();
-                        }
-                      }}
-                      onBlur={slashMenu.onBlur}
-                      onChange={(e) => {
-                        setInput(e.currentTarget.value);
-                      }}
-                    />
-                  </div>
-                </PromptInputBody>
+                {body}
                 {compact ? (
                   <InputGroupAddon
                     align="inline-end"

package/src/composer/input-area/InputAreaEditor.tsx

@@ -0,0 +1,268 @@
+import {
+  useLayoutEffect,
+  useRef,
+  type ClipboardEvent,
+  type FocusEventHandler,
+  type KeyboardEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { cn } from "../../utils/cn";
+
+export const CHIPS_HOST_ATTR = "data-composer-chips-inline";
+
+/** Custom property the ghost `::after` reads its colour from. */
+export const GHOST_COLOR_VAR = "--composer-ghost-color";
+
+/**
+ * Editor base class. Placeholder and ghost text use `::after`, so both follow
+ * the chips on the same line. A class cannot reach a pseudo-element, so the
+ * ghost colour comes from `--composer-ghost-color`, read off a probe span that
+ * carries `suggestionClassName`. Muted foreground is the fallback.
+ */
+export const INLINE_EDITOR_CLASS =
+  "relative block w-full cursor-text whitespace-pre-wrap wrap-break-word bg-transparent outline-hidden data-empty:after:pointer-events-none data-empty:after:select-none data-empty:after:text-muted-foreground data-empty:after:content-[attr(data-placeholder)] data-suggestion:after:pointer-events-none data-suggestion:after:select-none data-suggestion:after:text-[color:var(--composer-ghost-color,var(--color-muted-foreground))] data-suggestion:after:content-[attr(data-suggestion)]";
+
+// `contents` so each chip is an inline atom in the editor's own flow (same as
+// session-composer chip spans). A wrapping flex host becomes one box and puts
+// the text in a column beside it.
+const CHIPS_HOST_CLASS = "contents empty:hidden [&>*]:mr-1.5";
+
+/** Reads the plain text of the editor. Skips the chips host. */
+export function extractEditorText(root: HTMLElement): string {
+  let out = "";
+  const walk = (node: Node, isRoot: boolean) => {
+    node.childNodes.forEach((child, index) => {
+      if (child instanceof HTMLElement) {
+        if (child.hasAttribute(CHIPS_HOST_ATTR)) return;
+        if (child.tagName === "BR") {
+          // A trailing <br> only holds the line open.
+          if (isRoot && index === node.childNodes.length - 1) return;
+          out += "\n";
+          return;
+        }
+        if (child.tagName === "DIV" || child.tagName === "P") {
+          if (out !== "" && !out.endsWith("\n")) out += "\n";
+          walk(child, false);
+          return;
+        }
+        walk(child, false);
+        return;
+      }
+      if (child.nodeType === Node.TEXT_NODE) {
+        out += (child.textContent ?? "").replace(/\u200b/g, "");
+      }
+    });
+  };
+  walk(root, true);
+  return out;
+}
+
+function placeCaretAtEnd(el: HTMLElement) {
+  const sel = window.getSelection();
+  if (!sel) return;
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  range.collapse(false);
+  sel.removeAllRanges();
+  sel.addRange(range);
+}
+
+/** True when nothing but the chips host sits before the caret. */
+function caretAtTextStart(root: HTMLElement): boolean {
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return false;
+  const anchor = sel.anchorNode;
+  if (!anchor || !root.contains(anchor)) return false;
+  const host = root.querySelector(`[${CHIPS_HOST_ATTR}]`);
+  if (host?.contains(anchor)) return false;
+  const probe = document.createRange();
+  probe.selectNodeContents(root);
+  if (host) probe.setStartAfter(host);
+  probe.setEnd(anchor, sel.anchorOffset);
+  return probe.toString().replace(/\u200b/g, "") === "";
+}
+
+function insertPlainText(root: HTMLElement, text: string) {
+  if (document.execCommand("insertText", false, text)) return;
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0) return;
+  const range = sel.getRangeAt(0);
+  range.deleteContents();
+  const node = document.createTextNode(text);
+  range.insertNode(node);
+  range.setStartAfter(node);
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
+  root.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+export type InputAreaEditorProps = {
+  editorRef?: Ref<HTMLDivElement>;
+  value: string;
+  onValueChange: (value: string) => void;
+  placeholder?: string;
+  suggestion?: string;
+  /** Classes for the ghost text. Its colour and opacity are copied to the `::after`. */
+  suggestionClassName?: string;
+  chips?: ReactNode;
+  chipCount?: number;
+  onRemoveLastChip?: () => void;
+  className?: string;
+  /** Runs first. Call `preventDefault` to stop the built-in Enter and Backspace handling. */
+  onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
+  onBlur?: FocusEventHandler<HTMLDivElement>;
+  /** ARIA props, such as the slash menu combobox props. */
+  ariaProps?: Record<string, unknown>;
+};
+
+/**
+ * Contenteditable editor. The chips host is a non-editable inline atom at the
+ * start of the same text flow, so wrapped lines start under the chips. React
+ * owns the host only. The text nodes after it belong to the DOM and are
+ * reconciled against `value`.
+ */
+export function InputAreaEditor({
+  editorRef,
+  value,
+  onValueChange,
+  placeholder,
+  suggestion,
+  suggestionClassName,
+  chips,
+  chipCount = 0,
+  onRemoveLastChip,
+  className,
+  onKeyDown,
+  onBlur,
+  ariaProps,
+}: InputAreaEditorProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const composingRef = useRef(false);
+  const ghostProbeRef = useRef<HTMLSpanElement | null>(null);
+
+  const setRefs = (node: HTMLDivElement | null) => {
+    rootRef.current = node;
+    if (typeof editorRef === "function") editorRef(node);
+    else if (editorRef) editorRef.current = node;
+  };
+
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    if (!root || composingRef.current) return;
+    if (extractEditorText(root) === value) return;
+    Array.from(root.childNodes).forEach((child) => {
+      if (!(child instanceof HTMLElement && child.hasAttribute(CHIPS_HOST_ATTR))) {
+        root.removeChild(child);
+      }
+    });
+    if (value !== "") root.appendChild(document.createTextNode(value));
+    if (document.activeElement === root) placeCaretAtEnd(root);
+  });
+
+  // Copy the probe colour to the editor. Opacity below 1 is folded into the
+  // colour, so the `::after` needs one variable.
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const probe = ghostProbeRef.current;
+    const style = probe ? getComputedStyle(probe) : null;
+    if (!style?.color) {
+      root.style.removeProperty(GHOST_COLOR_VAR);
+      return;
+    }
+    const opacity = Number.parseFloat(style.opacity);
+    root.style.setProperty(
+      GHOST_COLOR_VAR,
+      opacity >= 0 && opacity < 1
+        ? `color-mix(in srgb, ${style.color} ${opacity * 100}%, transparent)`
+        : style.color,
+    );
+  }, [suggestion, suggestionClassName]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+    const root = event.currentTarget;
+    if (event.key === "Enter") {
+      if (composingRef.current || event.nativeEvent.isComposing) return;
+      if (event.shiftKey) return;
+      event.preventDefault();
+      const form = root.closest("form");
+      const submitButton = form?.querySelector<HTMLButtonElement>(
+        'button[type="submit"]',
+      );
+      if (submitButton?.disabled) return;
+      form?.requestSubmit();
+      return;
+    }
+    if (
+      event.key === "Backspace" &&
+      chipCount > 0 &&
+      caretAtTextStart(root)
+    ) {
+      event.preventDefault();
+      onRemoveLastChip?.();
+    }
+  };
+
+  const handlePaste = (event: ClipboardEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    const text = event.clipboardData.getData("text/plain");
+    if (text) insertPlainText(event.currentTarget, text);
+  };
+
+  return (
+    <>
+      <div
+        ref={setRefs}
+        data-slot="input-group-control"
+        contentEditable
+        suppressContentEditableWarning
+        spellCheck
+        aria-label={placeholder}
+        aria-multiline
+        {...ariaProps}
+        role="combobox"
+        data-empty={value === "" ? "" : undefined}
+        data-placeholder={placeholder}
+        data-suggestion={suggestion || undefined}
+        className={cn(INLINE_EDITOR_CLASS, className)}
+        onInput={(event) => {
+          if (composingRef.current) return;
+          onValueChange(extractEditorText(event.currentTarget));
+        }}
+        onCompositionStart={() => {
+          composingRef.current = true;
+        }}
+        onCompositionEnd={(event) => {
+          composingRef.current = false;
+          onValueChange(extractEditorText(event.currentTarget));
+        }}
+        onKeyDown={handleKeyDown}
+        onPaste={handlePaste}
+        onBlur={onBlur}
+      >
+        <span
+          contentEditable={false}
+          {...{ [CHIPS_HOST_ATTR]: "" }}
+          className={CHIPS_HOST_CLASS}
+        >
+          {chips}
+        </span>
+      </div>
+      {suggestion && suggestionClassName ? (
+        // Outside the editor, so reconciliation and the text value never see it.
+        // Zero-size, not `display: none`, so the computed colour is real.
+        <span
+          aria-hidden
+          data-composer-ghost-probe=""
+          className="pointer-events-none absolute size-0 select-none overflow-hidden text-foreground"
+        >
+          <span ref={ghostProbeRef} className={suggestionClassName} />
+        </span>
+      ) : null}
+    </>
+  );
+}

package/src/composer/input-area/composerCompact.ts

@@ -9,20 +9,18 @@ function getMeasureContext(): CanvasRenderingContext2D | null {
   return context;
 }
 
+/** Chips never force the stacked card: only files, newlines and a wrapped line do. */
 export function isComposerCompact({
   value,
   fileCount,
-  chipCount,
   exceedsPill,
 }: {
   value: string;
   fileCount: number;
-  chipCount: number;
   exceedsPill: boolean;
 }): boolean {
   if (fileCount > 0) return false;
-  if (chipCount > 0) return false;
-  if (value.trim().length === 0) return true;
+  if (value === "" || value === "\n") return true;
   if (value.includes("\n")) return false;
   return !exceedsPill;
 }

package/src/composer/input-area/useComposerCompact.ts

@@ -9,11 +9,9 @@ import {
 export function useComposerCompact({
   value,
   fileCount,
-  chipCount,
 }: {
   value: string;
   fileCount: number;
-  chipCount: number;
 }): { chromeRef: RefObject<HTMLDivElement | null>; compact: boolean } {
   "use no memo";
   const chromeRef = useRef<HTMLDivElement>(null);
@@ -26,7 +24,10 @@ export function useComposerCompact({
   const editor = editorNode instanceof HTMLElement ? editorNode : null;
   const font = editor ? getComputedStyle(editor).font : "14px sans-serif";
   if (editor && wasCompactRef.current) {
-    const inner = readEditorInnerWidth(editor);
+    const chipsWidth =
+      editor.querySelector<HTMLElement>("[data-composer-chips-inline]")
+        ?.offsetWidth ?? 0;
+    const inner = readEditorInnerWidth(editor) - chipsWidth;
     if (inner > 0) pillWidthRef.current = inner;
   }
   const exceedsPill =
@@ -37,7 +38,6 @@ export function useComposerCompact({
   const compact = isComposerCompact({
     value,
     fileCount,
-    chipCount,
     exceedsPill,
   });
   wasCompactRef.current = compact;

package/src/composer/input-area/useComposerSlashMenu.ts

@@ -30,7 +30,7 @@ export function useComposerSlashMenu({
   value: string;
   onValueChange: (value: string) => void;
   items: ComposerSlashItem[];
-  textareaRef: RefObject<HTMLTextAreaElement | null>;
+  textareaRef: RefObject<HTMLElement | null>;
   onSelect: (item: ComposerSlashItem) => void;
   /** When false the menu never opens. */
   enabled?: boolean;
@@ -122,7 +122,7 @@ export function useComposerSlashMenu({
     if (item) applyItem(item, trigger);
   };
 
-  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>): boolean => {
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>): boolean => {
     if (!showPopup) return false;
     if (visibleItems.length > 0) {
       if (event.key === "ArrowDown") {

package/app/README.md

@@ -1,100 +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`, needed only for the app helpers: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
-
-`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`. 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`.

package/tokens/README.md

@@ -1,98 +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, `*` border and `body` defaults. 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. |
-| `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-tab`, 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`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
-| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
-| `@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` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
-| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
-| `@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... */
-```
-
-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` | app `:root` |
-| `tabs.css` | `--tabs-dur`, `--tabs-ease` (app `:root`); `--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 |
-| `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`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css`. `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` |
-
-## 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.