@cueloop/client 0.1.0-alpha.67 → 0.1.0-alpha.69

package/src/components/FileContentsView.test.tsx

@@ -18,12 +18,12 @@ test("renders the loaded file contents", async () => {
   await waitForText(setup, "const answer = 42;");
 });
 
-test("shows a not-found hint when the file cannot be read", async () => {
+test("shows a centered File deleted message when the file cannot be read", async () => {
   const setup = await testRender(
     <FileContentsView path="missing.ts" loadContents={() => Promise.resolve(null)} theme={DARK} />,
     { width: 60, height: 10 },
   );
 
-  await waitForText(setup, "could not read missing.ts");
-  expect(setup.captureCharFrame()).toContain("could not read missing.ts");
+  await waitForText(setup, "File deleted");
+  expect(setup.captureCharFrame()).toContain("File deleted");
 });

package/src/components/FileContentsView.tsx

@@ -1,9 +1,15 @@
-// A Changes file tab in contents mode: a workspace file rendered read-only with line numbers.
-// Loads on mount and whenever the path changes; a null read shows a "could not read" hint.
+// A Changes/Project file tab in contents mode: a workspace file rendered read-only with line
+// numbers, for surfaces with no review session to anchor notes to (the bare-launch welcome shell).
+// Loads on mount and whenever the path changes; a null read renders a centered "File deleted".
+// Syntax highlighting comes from the native code renderable (tree-sitter), the language
+// auto-detected from the path; unknown languages simply render unstyled.
 
+import { ScrollArea } from "./ScrollArea";
 import React, { useEffect, useRef, useState } from "react";
+import type { CodeRenderable } from "@opentui/core";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
+import { filetypeForPath, syntaxStyleFor } from "./syntax-highlight";
 
 export interface FileContentsViewProps {
   path: string;
@@ -24,6 +30,9 @@ export function FileContentsView({
 }: FileContentsViewProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
   const [loaded, setLoaded] = useState<FileLoad | null>(null);
+  // The gutter mirrors the code renderable's line info, so it needs the mounted
+  // instance; a state-backed ref rebinds the target once the code renderable exists.
+  const [codeTarget, setCodeTarget] = useState<CodeRenderable | null>(null);
   const loadRef = useRef(loadContents);
   useEffect(() => {
     loadRef.current = loadContents;
@@ -53,26 +62,37 @@ export function FileContentsView({
     );
   }
   if (loaded.lines === null) {
+    // a file that no longer reads in the Changes/Project view is one the working tree deleted;
+    // the bottom pad lifts the text one row so it lines up with the footer-shortened thread empty state
     return (
-      <box style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }}>
-        <text fg={tokens.textDim}>{`could not read ${path}`}</text>
+      <box
+        style={{ flexGrow: 1, alignItems: "center", justifyContent: "center", paddingBottom: 2 }}
+      >
+        <text fg={tokens.textDim}>File deleted</text>
       </box>
     );
   }
-  const lines = loaded.lines;
+  const content = loaded.lines.join("\n");
 
   return (
-    <scrollbox style={{ flexGrow: 1 }} focused={false}>
-      <box style={{ flexDirection: "column", paddingTop: 1 }}>
-        {lines.map((line, index) => (
-          <box key={index} style={{ flexDirection: "row", paddingLeft: 1 }}>
-            <box style={{ width: 5 }}>
-              <text fg={tokens.textDim}>{String(index + 1).padStart(4)}</text>
-            </box>
-            <text fg={tokens.text}>{line.length > 0 ? line : " "}</text>
-          </box>
-        ))}
-      </box>
-    </scrollbox>
+    <ScrollArea>
+      <line-number
+        target={codeTarget ?? undefined}
+        showLineNumbers
+        fg={tokens.textDim}
+        minWidth={5}
+        paddingRight={1}
+        style={{ paddingTop: 1, paddingLeft: 1 }}
+      >
+        <code
+          ref={setCodeTarget}
+          content={content}
+          filetype={filetypeForPath(path)}
+          syntaxStyle={syntaxStyleFor(tokens)}
+          selectable={false}
+          style={{ wrapMode: "none", fg: tokens.text }}
+        />
+      </line-number>
+    </ScrollArea>
   );
 }

package/src/components/{SurfaceScrollbar.stories.tsx → OverlayScrollbar.stories.tsx}

@@ -1,10 +1,10 @@
 import React, { useRef } from "react";
 import type { ScrollBoxRenderable } from "@opentui/core";
 import { DARK } from "../theme";
-import { SurfaceScrollbar } from "./SurfaceScrollbar";
+import { OverlayScrollbar } from "./OverlayScrollbar";
 import type { Story, StoryMeta } from "./story";
 
-export const meta: StoryMeta = { title: "Chrome/SurfaceScrollbar" };
+export const meta: StoryMeta = { title: "Chrome/OverlayScrollbar" };
 
 function TallSurface(): React.ReactNode {
   const scrollRef = useRef<ScrollBoxRenderable | null>(null);
@@ -21,14 +21,13 @@ function TallSurface(): React.ReactNode {
           <text key={index} fg={DARK.textMuted}>{`row ${index + 1}`}</text>
         ))}
       </scrollbox>
-      <SurfaceScrollbar scrollbox={scrollRef} />
+      <OverlayScrollbar scrollbox={scrollRef} />
     </box>
   );
 }
 
-// The mirrored bar: content three times the viewport puts a thumb a third as tall at the top.
-export const ThumbAtTop: Story = {
+// At rest the overlay bar is hidden; the thumb only appears while the surface is scrolling.
+export const AtRest: Story = {
   render: () => <TallSurface />,
-  expectedColors: [DARK.textDim],
   size: { width: 24, height: 8 },
 };

package/src/components/{SurfaceScrollbar.test.tsx → OverlayScrollbar.test.tsx}

@@ -6,16 +6,28 @@
 
 import { describe, expect, test } from "bun:test";
 import { testRender } from "@opentui/react/test-utils";
+import { ScrollBoxRenderable, type Renderable } from "@opentui/core";
 import React from "react";
-import { DiffSheet } from "./DiffSheet";
+import { DiffContentView } from "./DiffContentView";
 import { diffRows, marksByRows } from "../view-diff";
 import { allowEventLoopUpdates } from "../test-support";
 import { fixtureDiffSession } from "./story-fixtures";
 import { DARK } from "../theme";
-import { thumbGeometry } from "./SurfaceScrollbar";
+import { thumbGeometry } from "./OverlayScrollbar";
 
 const noop = (): void => {};
 
+function findById(node: Renderable, id: string): Renderable | undefined {
+  if (node.id === id) return node;
+  for (const child of node.getChildren()) {
+    const found = findById(child, id);
+
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
 function hex(color: { toInts(): [number, number, number, number] }): string {
   const [red, green, blue] = color.toInts();
 
@@ -69,7 +81,7 @@ describe("the diff sheet's scrollbar", () => {
     });
     const width = 60;
     const setup = await testRender(
-      <DiffSheet
+      <DiffContentView
         rows={rows}
         session={session}
         marks={marksByRows(session.annotations, rows)}
@@ -85,17 +97,33 @@ describe("the diff sheet's scrollbar", () => {
 
     allowEventLoopUpdates();
     await setup.waitForVisualIdle();
+    // the overlay bar hides at rest; a scroll reveals the thumb
+    const scroller = findById(setup.renderer.root, "diff-scroll");
+
+    if (!(scroller instanceof ScrollBoxRenderable))
+      throw new Error("diff-scroll is not a scrollbox");
+    const countThumbRows = (): number =>
+      setup.captureSpans().lines.filter((line) => {
+        let column = 0;
+
+        for (const span of line.spans) {
+          column += span.text.length;
+          if (column >= width) return span.bg !== undefined && hex(span.bg) === DARK.textDim;
+        }
+
+        return false;
+      }).length;
+
+    // the overlay bar reveals on a scroll and hides after an idle delay; alternate the offset to
+    // re-trigger the reveal until the thumb is captured, so a slow CI settle never races the hide
+    let thumbRows = 0;
+
+    for (let attempt = 0; attempt < 20 && thumbRows === 0; attempt++) {
+      scroller.scrollTo(attempt % 2 === 0 ? 4 : 5);
+      await setup.waitForVisualIdle();
+      thumbRows = countThumbRows();
+    }
     const frame = setup.captureCharFrame().split("\n");
-    const thumbRows = setup.captureSpans().lines.filter((line) => {
-      let column = 0;
-
-      for (const span of line.spans) {
-        column += span.text.length;
-        if (column >= width) return span.bg !== undefined && hex(span.bg) === DARK.textDim;
-      }
-
-      return false;
-    }).length;
 
     // Assert - the thumb occupies the last column at the top (scroll offset 0), and the dot sits
     // to its left in the rail, so the order reads content, dots, scrollbar

package/src/components/{SurfaceScrollbar.tsx → OverlayScrollbar.tsx}

@@ -1,29 +1,29 @@
 /**
  * A one-cell vertical scrollbar that mirrors a scrollbox's scroll state, so the bar can sit
  * where the layout wants it (the panel's rightmost column, past the discussion dots) instead
- * of inside the scrollbox's own viewport row. Reads the scroll position each frame, draws the
- * thumb, and a click or drag on the track scrolls the box.
+ * of inside the scrollbox's own viewport row. It is an overlay: the thumb appears while the
+ * surface is scrolling and hides once scrolling has been idle, so a resting surface shows none.
  */
 
-import React, { useRef, type RefObject } from "react";
+import React, { useEffect, useRef, useState, type RefObject } from "react";
 import type { BoxRenderable, ScrollBoxRenderable } from "@opentui/core";
 import type { Theme } from "../theme";
 import { useFrameMeasure } from "../use-frame-measure";
 import { useComponentTheme } from "./theme-context";
 
+const HIDE_DELAY_MS = 1500;
+
 interface ScrollState {
   top: number;
   height: number;
   viewport: number;
 }
 
-/** The thumb's row and height for a viewport of `track` rows over the scroll state. */
 export interface ThumbGeometry {
   row: number;
   height: number;
 }
 
-/** Where the thumb sits: proportional to the scroll offset, never shorter than one row, or null when nothing scrolls. */
 export function thumbGeometry(state: ScrollState, track: number): ThumbGeometry | null {
   if (track <= 0 || state.height <= state.viewport || state.viewport <= 0) return null;
   const height = Math.max(1, Math.round((state.viewport / state.height) * track));
@@ -33,14 +33,19 @@ export function thumbGeometry(state: ScrollState, track: number): ThumbGeometry
   return { row: Math.min(track - height, Math.max(0, row)), height };
 }
 
-export interface SurfaceScrollbarProps {
+export interface OverlayScrollbarProps {
   scrollbox: RefObject<ScrollBoxRenderable | null>;
   theme?: Theme;
 }
 
-export function SurfaceScrollbar({ scrollbox, theme }: SurfaceScrollbarProps): React.ReactNode {
+export function OverlayScrollbar({ scrollbox, theme }: OverlayScrollbarProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
   const trackRef = useRef<BoxRenderable | null>(null);
+  const [visible, setVisible] = useState(false);
+  const draggingRef = useRef(false);
+  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const prevTopRef = useRef<number | null>(null);
+
   const state = useFrameMeasure<ScrollState>(
     () => ({
       top: scrollbox.current?.scrollTop ?? 0,
@@ -56,25 +61,56 @@ export function SurfaceScrollbar({ scrollbox, theme }: SurfaceScrollbarProps): R
     (left, right) => left === right,
     0,
   );
-  const thumb = thumbGeometry(state, track);
 
-  // a row on the track maps to the scroll offset that puts the thumb's top there
+  const reveal = (): void => {
+    setVisible(true);
+    if (hideTimerRef.current) clearTimeout(hideTimerRef.current);
+    hideTimerRef.current = setTimeout(() => {
+      if (!draggingRef.current) setVisible(false);
+    }, HIDE_DELAY_MS);
+  };
+
+  // reveal on real scroll movement, never on first mount, then hide once idle
+  useEffect(() => {
+    if (prevTopRef.current !== null && state.top !== prevTopRef.current) reveal();
+    prevTopRef.current = state.top;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state.top]);
+
+  useEffect(
+    () => () => {
+      if (hideTimerRef.current) clearTimeout(hideTimerRef.current);
+    },
+    [],
+  );
+
+  const geometry = thumbGeometry(state, track);
+  const thumb = visible ? geometry : null;
+
   const scrollToTrackRow = (screenY: number): void => {
     const box = scrollbox.current;
 
-    if (!box || !thumb) return;
-    const row = screenY - (trackRef.current?.y ?? 0) - Math.floor(thumb.height / 2);
-    const ratio = Math.min(1, Math.max(0, row / Math.max(1, track - thumb.height)));
+    if (!box || !geometry) return;
+    const row = screenY - (trackRef.current?.y ?? 0) - Math.floor(geometry.height / 2);
+    const ratio = Math.min(1, Math.max(0, row / Math.max(1, track - geometry.height)));
 
     box.scrollTo(Math.round(ratio * (state.height - state.viewport)));
+    reveal();
   };
 
   return (
     <box
       ref={trackRef}
       style={{ width: 1, flexShrink: 0, flexDirection: "column" }}
-      onMouseDown={(event) => scrollToTrackRow(event.y)}
+      onMouseDown={(event) => {
+        draggingRef.current = true;
+        scrollToTrackRow(event.y);
+      }}
       onMouseDrag={(event) => scrollToTrackRow(event.y)}
+      onMouseUp={() => {
+        draggingRef.current = false;
+        reveal();
+      }}
     >
       {thumb ? (
         <box

package/src/components/ProjectTreeView.tsx

@@ -2,6 +2,7 @@
 // Folders start collapsed and expand on click; a file click opens it as a tab. The caller keys this
 // on the session id so switching sessions remounts it and never shows the previous repository's paths.
 
+import { ScrollArea } from "./ScrollArea";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
@@ -60,7 +61,7 @@ export function ProjectTreeView({
   }
 
   return (
-    <scrollbox style={{ flexGrow: 1 }} focused={false}>
+    <ScrollArea>
       <Tree
         nodes={nodes}
         expandedIds={expandedIds}
@@ -77,6 +78,6 @@ export function ProjectTreeView({
         }
         theme={theme}
       />
-    </scrollbox>
+    </ScrollArea>
   );
 }

package/src/components/{PrototypeSheet.stories.tsx → PrototypeContentView.stories.tsx}

@@ -1,16 +1,15 @@
 import React from "react";
 import { DARK } from "../theme";
 import type { Story, StoryMeta } from "./story";
-import { PrototypeSheet } from "./PrototypeSheet";
+import { PrototypeContentView } from "./PrototypeContentView";
 
-export const meta: StoryMeta = { title: "Surfaces/PrototypeSheet" };
+export const meta: StoryMeta = { title: "Surfaces/PrototypeContentView" };
 
-// The story renderer reports no kitty graphics, so the sheet shows its fallback.
+// The story renderer reports no kitty graphics, so the view shows its fallback.
 export const Unsupported: Story = {
   render: () => (
-    <PrototypeSheet
+    <PrototypeContentView
       prototypePath="/tmp/example.html"
-      quickActions={[]}
       canComment={true}
       onCommentElement={() => {}}
     />

package/src/components/{PrototypeSheet.tsx → PrototypeContentView.tsx}

@@ -1,8 +1,9 @@
 /**
  * Prototype review surface: renders the HTML screenshot into a reserved cell
  * region via the kitty graphics protocol, and turns a click into a DOM-element
- * selection, so the shared marker actions bar and compose card annotate an
- * element rather than a text span. The image is painted directly (not through
+ * selection that opens the shared compose card - the same edit primitive plan
+ * and diff use - so a note anchors to an element rather than a text span. The
+ * image is painted directly (not through
  * OpenTUI's ImageRenderable, which does not display in every terminal): the
  * region's cells are never repainted, and the picture is re-placed after each
  * frame so it survives OpenTUI's own draws.
@@ -13,11 +14,9 @@ import type { BoxRenderable } from "@opentui/core";
 import * as v from "valibot";
 import { useKeyboard, useRenderer } from "@opentui/react";
 import type { Theme } from "../theme";
-import { quickActionBody, type QuickAction } from "../config";
 import { useComponentTheme } from "./theme-context";
-import { FRAME_BORDER_STYLE } from "./primitives/frame";
-import { MarkerPopover } from "./MarkerPopover";
-import { AnnotationCard } from "./AnnotationCard";
+import { Composer, DiscussionCard } from "./AnnotationCards";
+import { annotationPaletteFor } from "../annotation-palette";
 import {
   cssBoxToCell,
   imageCellToCss,
@@ -34,9 +33,8 @@ import {
   type CellRegion,
 } from "../kitty-image";
 
-export interface PrototypeSheetProps {
+export interface PrototypeContentViewProps {
   prototypePath: string;
-  quickActions: QuickAction[];
   canComment: boolean;
   onCommentElement: (element: PrototypeElement, body: string) => void;
   /** Signals when the inline compose owns the keyboard, so the app suppresses
@@ -50,7 +48,7 @@ export interface PrototypeSheetProps {
 
 type SheetStatus = "loading" | "ready" | "unsupported" | "error";
 
-const POPOVER_ROWS = 3;
+const OVERLAY_ROWS = 3;
 /** Compose-card width, so the floating composer reads like the plan/diff one
  *  instead of shrinking to its content. */
 const COMPOSE_COLS = 46;
@@ -123,16 +121,33 @@ function captureConfig(region: CellRegion, renderer: CaptureRenderer) {
   };
 }
 
-function PrototypeSheetImpl({
+/**
+ * The terminal's scheme, read from its reading-text color: a dark terminal
+ * carries light text, a light terminal dark text. Passed to the renderer as
+ * prefers-color-scheme so a theme-aware mockup emerges into the right surface.
+ */
+function terminalColorScheme(textColor: string): "dark" | "light" {
+  const hex = textColor.replace("#", "");
+
+  if (hex.length < 6) return "dark";
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+
+  return luminance > 0.5 ? "dark" : "light";
+}
+
+function PrototypeContentViewImpl({
   prototypePath,
-  quickActions,
   canComment,
   onCommentElement,
   onComposingChange,
   hidden = false,
   theme,
-}: PrototypeSheetProps): React.ReactNode {
+}: PrototypeContentViewProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
+  const palette = annotationPaletteFor(tokens);
   const renderer = useRenderer();
   const regionRef = useRef<BoxRenderable | null>(null);
   const browserRef = useRef<PrototypeRenderer | null>(null);
@@ -156,9 +171,7 @@ function PrototypeSheetImpl({
     top: number;
     regionColumns: number;
   } | null>(null);
-  const [actionsOpen, setActionsOpen] = useState(false);
   const [composing, setComposing] = useState(false);
-  const [draftText, setDraftText] = useState("");
 
   const setPng = (png: Uint8Array): void => {
     pngRef.current = png;
@@ -247,6 +260,7 @@ function PrototypeSheetImpl({
           filePath: prototypePath,
           viewport: capture.viewport,
           deviceScaleFactor: capture.deviceScaleFactor,
+          colorScheme: terminalColorScheme(tokens.text),
         });
 
         // the sheet may have unmounted while Chromium was launching; close the
@@ -279,9 +293,7 @@ function PrototypeSheetImpl({
   const clearSelection = (): void => {
     setSelected(null);
     setOverlayCell(null);
-    setActionsOpen(false);
     setComposing(false);
-    setDraftText("");
   };
 
   // While the compose textarea owns the keyboard, the global keymap is
@@ -315,11 +327,17 @@ function PrototypeSheetImpl({
       setSelected(element);
       setOverlayCell({
         left: Math.max(0, cell.column - geometry.x),
-        top: Math.max(0, topRaw < POPOVER_ROWS ? topRaw + 1 : topRaw - POPOVER_ROWS),
+        top: Math.max(0, topRaw < OVERLAY_ROWS ? topRaw + 1 : topRaw - OVERLAY_ROWS),
         regionColumns: geometry.width,
       });
-      setActionsOpen(false);
-      setComposing(false);
+      // selecting an element opens the compose card directly, the same edit
+      // primitive plan and diff use - there is no intermediate marker toolbar
+      if (canComment) {
+        onComposingChange?.(true);
+        setComposing(true);
+      } else {
+        setComposing(false);
+      }
     })().catch((error) => {
       setErrorMessage(error instanceof Error ? error.message : String(error));
       setStatus("error");
@@ -346,8 +364,8 @@ function PrototypeSheetImpl({
     clearSelection();
   };
 
-  // the overlay carries an opaque fill so the popover and compose card read as
-  // solid cards over the image, matching the plan surface
+  // the overlay carries an opaque fill so the compose card reads as a solid
+  // card over the image, matching the plan surface
   const overlayStyle = {
     position: "absolute" as const,
     left: overlayCell?.left ?? 0,
@@ -370,9 +388,6 @@ function PrototypeSheetImpl({
       style={{
         flexGrow: 1,
         flexDirection: "column",
-        border: true,
-        borderStyle: FRAME_BORDER_STYLE,
-        borderColor: tokens.text,
       }}
     >
       <box
@@ -389,40 +404,25 @@ function PrototypeSheetImpl({
           <text fg={tokens.textDim}>{statusLine(status, errorMessage)}</text>
         </box>
       ) : null}
-      {selected && !composing ? (
-        <box style={overlayStyle}>
-          <MarkerPopover
-            view={actionsOpen ? "actions" : "toolbar"}
-            actions={quickActions}
-            actionIndex={0}
-            canCut={false}
-            onComment={() => {
-              if (!canComment) return;
-              onComposingChange?.(true);
-              setComposing(true);
-            }}
-            onCut={() => undefined}
-            onOpenActions={() => setActionsOpen(true)}
-            onClose={clearSelection}
-            onPickAction={(index) => commit(quickActionBody(quickActions[index]!))}
-            onBack={() => setActionsOpen(false)}
-            theme={theme}
-          />
-        </box>
-      ) : null}
       {selected && composing ? (
         <box style={composeStyle}>
-          <AnnotationCard
-            kind="comment"
-            quote={selected.quote}
-            draft={{
-              text: draftText,
-              onInput: setDraftText,
-              onSave: () => commit(draftText),
-              onSubmit: () => commit(draftText),
-              onCancel: clearSelection,
-            }}
-            theme={theme}
+          <DiscussionCard
+            tokens={tokens}
+            segments={[
+              {
+                color: palette.cardEdge,
+                node: (
+                  <Composer
+                    seed=""
+                    glyph="●"
+                    tokens={tokens}
+                    onSave={commit}
+                    onReady={() => undefined}
+                    onInput={() => undefined}
+                  />
+                ),
+              },
+            ]}
           />
         </box>
       ) : null}
@@ -432,10 +432,10 @@ function PrototypeSheetImpl({
 
 /**
  * Memoized so an unrelated App re-render (status ticks, a rail-width drag) does
- * not re-render the sheet; the parent passes a stable onCommentElement so the
+ * not re-render the view; the parent passes a stable onCommentElement so the
  * shallow prop compare holds.
  */
-export const PrototypeSheet = React.memo(PrototypeSheetImpl);
+export const PrototypeContentView = React.memo(PrototypeContentViewImpl);
 
 function statusLine(status: SheetStatus, errorMessage: string): string {
   if (status === "loading") return "rendering prototype…";

package/src/components/ScrollArea.stories.tsx

@@ -0,0 +1,20 @@
+import React from "react";
+import { DARK } from "../theme";
+import { ScrollArea } from "./ScrollArea";
+import type { Story, StoryMeta } from "./story";
+
+export const meta: StoryMeta = { title: "Chrome/ScrollArea" };
+
+// Taller-than-viewport content; the overlay bar stays hidden until the surface scrolls.
+export const AtRest: Story = {
+  render: () => (
+    <box style={{ width: 24, height: 8, backgroundColor: DARK.background }}>
+      <ScrollArea>
+        {Array.from({ length: 24 }, (_unused, index) => (
+          <text key={index} fg={DARK.textMuted}>{`row ${index + 1}`}</text>
+        ))}
+      </ScrollArea>
+    </box>
+  ),
+  size: { width: 24, height: 8 },
+};

package/src/components/ScrollArea.tsx

@@ -0,0 +1,44 @@
+/**
+ * A scrollbox whose bar follows the global rule: no always-on scrollbar. The built-in bar is
+ * hidden and an OverlayScrollbar rides the rightmost column, appearing only while scrolling.
+ * Pass scrollRef to keep scrollTo / scrollChildIntoView on the underlying ScrollBox.
+ */
+
+import React, { useRef, type ReactNode, type RefObject } from "react";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import type { Theme } from "../theme";
+import { OverlayScrollbar } from "./OverlayScrollbar";
+
+export interface ScrollAreaProps {
+  children: ReactNode;
+  focused?: boolean;
+  theme?: Theme;
+  scrollRef?: RefObject<ScrollBoxRenderable | null>;
+}
+
+export function ScrollArea({
+  children,
+  focused = false,
+  theme,
+  scrollRef,
+}: ScrollAreaProps): React.ReactNode {
+  const innerRef = useRef<ScrollBoxRenderable | null>(null);
+  const attach = (node: ScrollBoxRenderable | null): void => {
+    innerRef.current = node;
+    if (scrollRef) scrollRef.current = node;
+  };
+
+  return (
+    <box style={{ flexGrow: 1, flexDirection: "row" }}>
+      <scrollbox
+        ref={attach}
+        style={{ flexGrow: 1 }}
+        focused={focused}
+        verticalScrollbarOptions={{ visible: false }}
+      >
+        {children}
+      </scrollbox>
+      <OverlayScrollbar scrollbox={innerRef} theme={theme} />
+    </box>
+  );
+}