@startsimpli/ui 0.4.115 → 0.4.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.115",
+  "version": "0.4.116",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -48,8 +48,8 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "@startsimpli/api": "^0.5.58",
-    "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3"
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/auth": "^0.4.35"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -123,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/blog/MarkdownRenderer.tsx

@@ -7,6 +7,7 @@ import remarkGfm from 'remark-gfm'
 import React, { useState } from 'react'
 import { Copy, Check } from 'lucide-react'
 import { cn } from '../../utils/cn'
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance'
 
 /**
  * Themed markdown renderer for blog/article content.
@@ -31,6 +32,9 @@ function slugify(text: string): string {
 }
 
 export function MarkdownRenderer({ content, theme = 'light', className }: MarkdownRendererProps) {
+  // Wide GFM tables and long code lines both scroll sideways, and on macOS
+  // neither said so (startsim-5pq7h.1).
+  useScrollAffordance()
   const [copiedCode, setCopiedCode] = useState<string | null>(null)
 
   const copyToClipboard = async (code: string) => {
@@ -98,6 +102,9 @@ export function MarkdownRenderer({ content, theme = 'light', className }: Markdo
                     style={syntaxStyle as Record<string, React.CSSProperties>}
                     language={language}
                     PreTag="div"
+                    // Lands on the PreTag element — the box the theme puts
+                    // `overflow: auto` on, and the one that actually scrolls.
+                    className={SCROLLER_CLASS}
                     customStyle={{ margin: 0, padding: '1rem', background: 'transparent', fontSize: '0.875rem', lineHeight: '1.5' }}
                     codeTagProps={{
                       style: {
@@ -120,7 +127,7 @@ export function MarkdownRenderer({ content, theme = 'light', className }: Markdo
             )
           },
           table: ({ children, ...props }) => (
-            <div className="overflow-x-auto my-8">
+            <div className={cn('overflow-x-auto my-8', SCROLLER_CLASS)}>
               <table className="w-full border-collapse bg-card rounded-lg border border-border shadow-sm" {...props}>
                 {children}
               </table>

package/src/components/diff/DiffViewer.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react'
 import { FileText, GitBranch, Loader2, RefreshCw } from 'lucide-react'
 import { cn } from '../../lib/utils'
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance'
 
 export interface DiffSummary {
   totalFiles: number
@@ -202,7 +203,7 @@ export function DiffViewer({
             <summary className="select-none text-sm text-muted-foreground transition-colors hover:text-foreground">
               Working tree status
             </summary>
-            <pre className="mt-2 overflow-x-auto font-mono text-xs text-muted-foreground">{status}</pre>
+            <pre className={cn('mt-2 overflow-x-auto font-mono text-xs text-muted-foreground', SCROLLER_CLASS)}>{status}</pre>
           </details>
         </div>
       )}
@@ -218,7 +219,7 @@ export function DiffViewer({
               <FileText className="h-4 w-4 text-muted-foreground" aria-hidden="true" />
               <span className="font-mono text-sm text-foreground">{file.filePath}</span>
             </div>
-            <pre className="overflow-x-auto p-4 font-mono text-sm">
+            <pre className={cn('overflow-x-auto p-4 font-mono text-sm', SCROLLER_CLASS)}>
               {file.lines.map((line, index) =>
                 isMetadataLine(line) ? null : (
                   <div key={index} className={diffLineClass(line)}>

package/src/components/record-detail/RecordDetail.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react'
 import { cn } from '../../lib/utils'
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance'
 
 export type RecordFieldKind = 'text' | 'longtext' | 'url' | 'boolean' | 'json'
 
@@ -39,6 +40,9 @@ function hasValue(f: RecordField): boolean {
  * the same without duplicating the view.
  */
 export function RecordDetail({ fields, emptyMessage = 'No details.', className, showEmpty = false }: RecordDetailProps) {
+  // A json field is a code block that overflows sideways; on macOS it did so
+  // behind an invisible overlay bar (startsim-5pq7h.1).
+  useScrollAffordance()
   const visible = showEmpty ? fields : fields.filter(hasValue)
   const shorts = visible.filter((f) => f.kind !== 'longtext' && f.kind !== 'json')
   const longs = visible.filter((f) => f.kind === 'longtext')
@@ -101,7 +105,7 @@ export function RecordDetail({ fields, emptyMessage = 'No details.', className,
             {f.label}
           </h4>
           {hasValue(f) ? (
-            <pre className="overflow-x-auto rounded-md bg-muted p-3 text-xs leading-relaxed">
+            <pre className={cn('overflow-x-auto rounded-md bg-muted p-3 text-xs leading-relaxed', SCROLLER_CLASS)}>
               {f.value}
             </pre>
           ) : (

package/src/components/team/MembersTable.tsx

@@ -20,6 +20,8 @@
  */
 
 import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance'
 import { RoleSelector } from './RoleSelector'
 import {
   userDisplayName,
@@ -160,6 +162,13 @@ export function MembersTable({
   availableRoles,
   currentUserId,
 }: MembersTableProps) {
+  // The root is the element that scrolls (`overflow-x-auto`), and on macOS its
+  // bar is a zero-height overlay — the same defect the shadcn Table had
+  // (startsim-5pq7h.1). The class goes on beside `cls.root` rather than inside
+  // MEMBERS_TABLE_DEFAULTS so a consumer overriding `classNames.root` cannot
+  // drop it, and the sheet is injected here because a class name in a
+  // constants file emits no rules on its own.
+  useScrollAffordance()
   const cls = { ...MEMBERS_TABLE_DEFAULTS, ...(classNames ?? {}) }
   const withStatus = showStatus ?? members.some((m) => rowStatus(m) !== null)
   const withLastActive = showLastActive ?? members.some((m) => m.lastLoginAt !== undefined)
@@ -184,7 +193,7 @@ export function MembersTable({
   const tight = (base: string, extra: string) => `${base} ${extra}`.trim()
 
   return (
-    <div className={cls.root}>
+    <div className={cn(cls.root, SCROLLER_CLASS)}>
       <table className={cls.table}>
         <thead className={cls.thead}>
           <tr className={cls.headerRow}>

package/src/components/ui/table-scroll.ts

@@ -2,90 +2,26 @@
 
 import { useEffect, useState, type RefObject } from 'react'
 
-export const TABLE_SCROLL_STYLE_ID = 'ss-table-scroll-affordance'
-
-/** The element that actually scrolls: the wrapper `Table` puts around `<table>`. */
-export const TABLE_SCROLLER_CLASS = 'ss-table-scroller'
-/** A non-scrolling box around the scroller, so the edge hints can be pinned to it. */
-export const TABLE_SHELL_CLASS = 'ss-table-shell'
-export const TABLE_EDGE_CLASS = 'ss-table-edge'
-export const TABLE_EDGE_LEFT_CLASS = 'ss-table-edge-left'
-export const TABLE_EDGE_RIGHT_CLASS = 'ss-table-edge-right'
-
 /**
- * Wide tables scroll, but on macOS nothing says so (startsim-5pq7h).
- *
- * A reviewer reported "there is no sliding bar so it makes it difficult to see
- * all the columns". The container did scroll the whole time; macOS renders an
- * OVERLAY scrollbar that occupies no layout height and is invisible at rest, so
- * the affordance was missing, not the scrolling.
- *
- * MEASURED 2026-09-07, headed Google Chrome and headed WebKit on macOS, on a
- * 400px box holding 900px of content (`offsetHeight - clientHeight`, borders
- * subtracted):
- *
- *   no scrollbar CSS                                       0px   (overlay)
- *   scrollbar-width: thin                                  0px
- *   scrollbar-color: <thumb> <track>                       0px
- *   ::-webkit-scrollbar { height: 10px }                  10px   <-- this one
- *   ::-webkit-scrollbar + scrollbar-width/-color           0px   <-- see below
- *   ::-webkit-scrollbar, content NARROWER than the box      0px   (no regression)
- *
- * TWO RESULTS THAT ARE EASY TO UNDO BY ACCIDENT:
- *
- * 1. DO NOT ADD `scrollbar-width` OR `scrollbar-color` HERE. Every snippet on
- *    the web pairs them with the -webkit- rules "for Firefox". Measured: when
- *    the standard properties are set at the same specificity, Chromium honours
- *    them INSTEAD of the custom scrollbar and reverts the element to a
- *    zero-height overlay bar — i.e. adding them silently deletes this fix.
- *    Firefox on macOS gains nothing from them anyway (measured 0px with
- *    `scrollbar-width: thin` applied and confirmed in the computed style), so
- *    there is no Firefox branch to lose. Firefox users are served by the edge
- *    hint below instead.
- *
- * 2. The bar costs layout height ONLY while the element overflows — that is
- *    `overflow: auto`, not something this stylesheet decides — so it never
- *    appears under a table that fits. Keep the scroller on `auto`, never
- *    `scroll`, or every narrow table in the fleet grows a dead bar.
+ * The table's share of the scroll affordance (startsim-5pq7h).
  *
- * On Windows/Linux this REPLACES the ~15px classic bar with a 10px one; it does
- * not reserve a second gutter, so no platform guard is needed. Nothing here
- * animates or transitions, so `prefers-reduced-motion` has nothing to honour.
+ * The CSS and the class names moved to `lib/scroll-affordance.ts` when the same
+ * fix was applied to the package's other scrollers (startsim-5pq7h.1) — one
+ * stylesheet, one id, one string, so no two call sites can overwrite each
+ * other's rules. The measurements and the two rules that silently delete the
+ * fix are documented there. What stays here is the part that is genuinely about
+ * tables: the edge hint.
  */
-export const TABLE_SCROLL_CSS = `
-.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar {
-  height: 10px;
-  width: 10px;
-}
-.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-track {
-  background: transparent;
-}
-.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb {
-  border-radius: 9999px;
-  background-color: color-mix(in srgb, currentColor 22%, transparent);
-}
-.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb:hover {
-  background-color: color-mix(in srgb, currentColor 45%, transparent);
-}
-.${TABLE_SHELL_CLASS} {
-  position: relative;
-}
-.${TABLE_EDGE_CLASS} {
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  width: 24px;
-  pointer-events: none;
-}
-.${TABLE_EDGE_RIGHT_CLASS} {
-  right: 0;
-  background-image: linear-gradient(to left, hsl(var(--background)), hsl(var(--background) / 0));
-}
-.${TABLE_EDGE_LEFT_CLASS} {
-  left: 0;
-  background-image: linear-gradient(to right, hsl(var(--background)), hsl(var(--background) / 0));
-}
-`.trim()
+export {
+  SCROLL_AFFORDANCE_STYLE_ID as TABLE_SCROLL_STYLE_ID,
+  SCROLL_AFFORDANCE_CSS as TABLE_SCROLL_CSS,
+  TABLE_SCROLLER_CLASS,
+  TABLE_SHELL_CLASS,
+  TABLE_EDGE_CLASS,
+  TABLE_EDGE_LEFT_CLASS,
+  TABLE_EDGE_RIGHT_CLASS,
+  useScrollAffordance,
+} from '../../lib/scroll-affordance'
 
 export interface ScrollEdges {
   /** There is content scrolled off to the left. */
@@ -97,11 +33,11 @@ export interface ScrollEdges {
 /**
  * Which horizontal edges of a table's scroller still hide content.
  *
- * The persistent scrollbar above sits at the bottom of the scroller, and the
- * scroller is the FULL HEIGHT of the table — measured 3061-5698px below the
- * fold on every content view of the marketing-agents tenant at 900px tall. So a
- * reader looking at the header row never sees it, and needs a hint that travels
- * with them. This drives that hint.
+ * The persistent scrollbar sits at the bottom of the scroller, and the scroller
+ * is the FULL HEIGHT of the table — measured 3061-5698px below the fold on
+ * every content view of the marketing-agents tenant at 900px tall. So a reader
+ * looking at the header row never sees it, and needs a hint that travels with
+ * them. This drives that hint.
  *
  * Pass a ref to the `<table>`, not to the scroller: `Table` forwards its ref to
  * the table element, and the scroller is its parent.

package/src/components/ui/table.tsx

@@ -3,12 +3,7 @@
 import * as React from "react"
 
 import { cn } from "../../lib/utils"
-import { useInjectedStyle } from "../../lib/injected-style"
-import {
-  TABLE_SCROLLER_CLASS,
-  TABLE_SCROLL_CSS,
-  TABLE_SCROLL_STYLE_ID,
-} from "./table-scroll"
+import { TABLE_SCROLLER_CLASS, useScrollAffordance } from "./table-scroll"
 
 export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
   /**
@@ -23,9 +18,9 @@ export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
 const Table = React.forwardRef<HTMLTableElement, TableProps>(
   ({ className, containerClassName, ...props }, ref) => {
     // Gives the scroller a scrollbar that is actually visible while it
-    // overflows. See table-scroll.ts for the measurements — in particular why
-    // `scrollbar-width` must NOT be added alongside it.
-    useInjectedStyle(TABLE_SCROLL_STYLE_ID, TABLE_SCROLL_CSS)
+    // overflows. See lib/scroll-affordance.ts for the measurements — in
+    // particular why `scrollbar-width` must NOT be added alongside it.
+    useScrollAffordance()
 
     return (
       <div

package/src/components/workflows/ExecNodeDetails.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { cn } from '../../lib/utils';
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance';
 import { StatusBadge } from '../badge/StatusBadge';
 import { EmptyState } from '../states/EmptyState';
 import type { NodeExecView } from './types';
@@ -20,6 +21,12 @@ function JsonBlock({
   label: string;
   value: Record<string, unknown> | null | undefined;
 }) {
+  // Pretty-printed JSON runs past the right edge of a narrow inspector rail,
+  // and on macOS said so with a zero-height overlay bar (startsim-5pq7h.1).
+  // This block also caps its height, so it takes a 10px vertical gutter too —
+  // there is no CSS route to a custom bar on one axis only (measured; see
+  // lib/scroll-affordance.ts).
+  useScrollAffordance();
   const isEmpty = value == null || Object.keys(value).length === 0;
   return (
     <div className="flex min-h-0 flex-col">
@@ -29,7 +36,7 @@ function JsonBlock({
       {isEmpty ? (
         <p className="text-xs italic text-muted-foreground">No {label.toLowerCase()}.</p>
       ) : (
-        <pre className="overflow-auto rounded-md border border-border bg-muted/40 p-2 text-xs leading-relaxed">
+        <pre className={cn('overflow-auto rounded-md border border-border bg-muted/40 p-2 text-xs leading-relaxed', SCROLLER_CLASS)}>
           {JSON.stringify(value, null, 2)}
         </pre>
       )}

package/src/components/workflows/NodeInspector.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { cn } from '../../lib/utils';
+import { SCROLLER_CLASS, useScrollAffordance } from '../../lib/scroll-affordance';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '../ui/tabs';
 import { StatusBadge } from '../badge/StatusBadge';
 import { EmptyState } from '../states/EmptyState';
@@ -139,12 +140,15 @@ function SchemaField({
 }
 
 function JsonBlock({ value }: { value: Record<string, unknown> | null | undefined }) {
+  // Pretty-printed JSON runs past the right edge of a narrow inspector rail,
+  // and on macOS said so with a zero-height overlay bar (startsim-5pq7h.1).
+  useScrollAffordance();
   const isEmpty = value == null || Object.keys(value).length === 0;
   if (isEmpty) {
     return <p className="text-xs italic text-muted-foreground">No data.</p>;
   }
   return (
-    <pre className="overflow-auto rounded-md border border-border bg-muted/40 p-2 text-xs leading-relaxed">
+    <pre className={cn('overflow-auto rounded-md border border-border bg-muted/40 p-2 text-xs leading-relaxed', SCROLLER_CLASS)}>
       {JSON.stringify(value, null, 2)}
     </pre>
   );

package/src/lib/__tests__/scroll-affordance.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * Guards for the package-wide scroll affordance (startsim-5pq7h.1).
+ *
+ * The defect is PURELY VISUAL — content continues past an edge and macOS draws
+ * a zero-height overlay bar that says so to nobody — and jsdom has no layout, so
+ * NOTHING here proves a scrollbar is visible on screen. That claim is carried by
+ * browser measurement (headless Chromium with `--hide-scrollbars` REMOVED, real
+ * components rendered in examples/workflow-studio/src/app/scrollers, borders
+ * subtracted): every surface below went from 0px of scrollbar to 10px, and the
+ * negative controls stayed at 0px.
+ *
+ * What these DO guard is what a later edit can silently break:
+ *  - the two CSS properties that measurably DELETE the bar,
+ *  - the `width` declaration, whose absence measurably makes the vertical bar
+ *    WORSE (16px) rather than leaving it alone,
+ *  - the "one sheet, one id, one string" rule — two different strings under one
+ *    id overwrite each other on every mount,
+ *  - and that each surface still marks the element that actually scrolls.
+ *
+ * SEVEN of the eight changed elements are covered below. MarkdownRenderer's two
+ * — its GFM table wrapper and its fenced code block — are NOT, and cannot be
+ * under this jest config: react-markdown@10 ships ESM, `transformIgnorePatterns`
+ * does not cover node_modules here, and the suite dies with
+ * `SyntaxError: Unexpected token 'export'` before the component renders. That is
+ * why this package has no blog tests at all. Those two are carried by the browser
+ * run only, and the code-block one is the most fragile thing in this change:
+ * `className={SCROLLER_CLASS}` is handed to react-syntax-highlighter, which
+ * forwards it to its PreTag element — an upgrade could stop doing that, and
+ * nothing here would notice.
+ */
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {
+  SCROLL_AFFORDANCE_CSS,
+  SCROLL_AFFORDANCE_STYLE_ID,
+  SCROLLER_CLASS,
+  TABLE_SCROLLER_CLASS,
+} from '../scroll-affordance'
+import { DiffViewer } from '../../components/diff/DiffViewer'
+import { RecordDetail } from '../../components/record-detail/RecordDetail'
+import { MembersTable } from '../../components/team/MembersTable'
+import { ExecNodeDetails } from '../../components/workflows/ExecNodeDetails'
+import { NodeInspector } from '../../components/workflows/NodeInspector'
+import { Table, TableBody, TableCell, TableRow } from '../../components/ui/table'
+import type { MemberRow } from '../../components/team/types'
+
+describe('SCROLL_AFFORDANCE_CSS', () => {
+  it('styles the webkit scrollbar for both the table scroller and the general one', () => {
+    expect(SCROLL_AFFORDANCE_CSS).toContain(`.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar`)
+    expect(SCROLL_AFFORDANCE_CSS).toContain(`.${SCROLLER_CLASS}::-webkit-scrollbar`)
+    expect(SCROLL_AFFORDANCE_CSS).toMatch(/height:\s*10px/)
+  })
+
+  /**
+   * MEASURED 2026-09-07, headless Chromium with --hide-scrollbars removed, on a
+   * box that overflows VERTICALLY (borders subtracted):
+   *
+   *   height: 10px; width: 10px                     -> 10px vertical bar
+   *   height: 10px  (no width)                      -> 16px vertical bar
+   *   ::-webkit-scrollbar:horizontal { height:10px } ->  0px on BOTH axes
+   *
+   * Declaring any ::-webkit-scrollbar rule opts the element out of overlay
+   * scrollbars on both axes, so dropping `width` as a "we only care about
+   * horizontal" tidy-up does not leave the vertical axis alone — it makes it
+   * fatter than the platform default this replaces.
+   */
+  it('declares width alongside height, because a height-only rule leaves a 16px vertical bar', () => {
+    expect(SCROLL_AFFORDANCE_CSS).toMatch(/width:\s*10px/)
+  })
+
+  /**
+   * The finding this test exists for. MEASURED in headed Chrome on macOS:
+   *
+   *   ::-webkit-scrollbar { height: 10px }                 -> 10px of layout height
+   *   the same rule PLUS scrollbar-width / scrollbar-color ->  0px (overlay again)
+   *
+   * Chromium honours the standard properties instead of the custom scrollbar
+   * and reverts to a zero-height overlay bar. Every "cross-browser scrollbar"
+   * snippet on the web tells you to add them, and doing so here would silently
+   * undo the fix with no visible error anywhere. Firefox on macOS gains nothing
+   * from them either (measured 0px with the property confirmed applied), so
+   * there is no browser to trade away.
+   */
+  it('does NOT set scrollbar-width or scrollbar-color, which would revert Chromium to an overlay bar', () => {
+    expect(SCROLL_AFFORDANCE_CSS).not.toMatch(/scrollbar-width/)
+    expect(SCROLL_AFFORDANCE_CSS).not.toMatch(/scrollbar-color/)
+  })
+
+  /**
+   * `overflow: auto` is what makes the bar conditional on real overflow. Under
+   * `overflow: scroll` every narrow table and every short code block in the
+   * fleet would grow a dead 10px bar — a regression, not a fix.
+   */
+  it('leaves scrollers on overflow:auto so the bar is conditional on real overflow', () => {
+    expect(SCROLL_AFFORDANCE_CSS).not.toMatch(/overflow\s*:\s*scroll/)
+  })
+})
+
+describe('the surfaces that opted in', () => {
+  const diff = [
+    'diff --git a/a.ts b/a.ts',
+    'index 1111111..2222222 100644',
+    '@@ -1 +1 @@',
+    '-const a = 1',
+    '+const a = 2',
+  ].join('\n')
+
+  const member: MemberRow = {
+    id: '1',
+    userId: 'u1',
+    teamId: 't1',
+    role: 'owner',
+    joinedAt: '2026-01-04T00:00:00Z',
+    user: { id: 'u1', email: 'someone@example.com' },
+  } as MemberRow
+
+  it("marks DiffViewer's per-file block and its working-tree status block", () => {
+    const { container } = render(<DiffViewer diff={diff} status="On branch main" />)
+    const pres = container.querySelectorAll('pre')
+    expect(pres.length).toBeGreaterThan(0)
+    pres.forEach((pre) => expect(pre).toHaveClass(SCROLLER_CLASS))
+  })
+
+  it("marks RecordDetail's json block", () => {
+    const { container } = render(
+      <RecordDetail fields={[{ label: 'payload', value: '{ "a": 1 }', kind: 'json' }]} />
+    )
+    expect(container.querySelector('pre')).toHaveClass(SCROLLER_CLASS)
+  })
+
+  /**
+   * The class goes on beside `cls.root` rather than inside MEMBERS_TABLE_DEFAULTS
+   * so that a consumer passing its own `classNames.root` — which replaces the
+   * default outright — cannot silently drop the affordance.
+   */
+  it("marks MembersTable's scrolling root even when the consumer overrides its class", () => {
+    const { container } = render(
+      <MembersTable members={[member]} classNames={{ root: 'my-own-root' }} />
+    )
+    const root = container.querySelector('.my-own-root')
+    expect(root).toHaveClass(SCROLLER_CLASS)
+  })
+
+  it("marks ExecNodeDetails' json blocks", () => {
+    const { container } = render(
+      <ExecNodeDetails
+        node={{ nodeId: 'n1', status: 'success', name: 'n', inputData: { a: 1 }, outputData: { b: 2 } }}
+      />
+    )
+    const pres = container.querySelectorAll('pre')
+    expect(pres).toHaveLength(2)
+    pres.forEach((pre) => expect(pre).toHaveClass(SCROLLER_CLASS))
+  })
+
+  it("marks NodeInspector's json block, which only exists once an exec tab is open", async () => {
+    const user = userEvent.setup()
+    render(
+      <NodeInspector
+        node={{ id: 'n1', name: 'n', type: 'llm.classify', position: { x: 0, y: 0 }, parameters: {} } as never}
+        execution={{ nodeId: 'n1', status: 'success', inputData: { a: 1 } } as never}
+      />
+    )
+    await user.click(screen.getByRole('tab', { name: /input/i }))
+    const pre = document.querySelector('pre')
+    expect(pre).not.toBeNull()
+    expect(pre).toHaveClass(SCROLLER_CLASS)
+  })
+
+  it('leaves the table primitive on its own class, so the table fix is not renamed out from under it', () => {
+    render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>cell</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    )
+    expect(screen.getByRole('table').parentElement).toHaveClass(TABLE_SCROLLER_CLASS)
+  })
+
+  /**
+   * One sheet, one id, one string. `ensureInjectedStyle` REWRITES an existing
+   * sheet whose text differs, so two surfaces shipping different CSS under this
+   * id would overwrite each other on every mount, last effect wins.
+   */
+  it('injects exactly one stylesheet however many different surfaces are on the page', () => {
+    render(
+      <>
+        <Table />
+        <DiffViewer diff={diff} />
+        <RecordDetail fields={[{ label: 'p', value: '{}', kind: 'json' }]} />
+        <MembersTable members={[member]} />
+      </>
+    )
+    const sheets = document.querySelectorAll(`#${SCROLL_AFFORDANCE_STYLE_ID}`)
+    expect(sheets).toHaveLength(1)
+    expect(sheets[0].textContent).toBe(SCROLL_AFFORDANCE_CSS)
+  })
+})

package/src/lib/scroll-affordance.ts

@@ -0,0 +1,135 @@
+'use client'
+
+import { useInjectedStyle } from './injected-style'
+
+export const SCROLL_AFFORDANCE_STYLE_ID = 'ss-scroll-affordance'
+
+/**
+ * A scroller that should show a bar while it overflows.
+ *
+ * Put this on the element that ACTUALLY scrolls — the one carrying
+ * `overflow-auto` / `overflow-x-auto` — and call {@link useScrollAffordance}
+ * from the component that renders it, or the rules never reach the page.
+ */
+export const SCROLLER_CLASS = 'ss-scroller'
+
+/** The element that actually scrolls: the wrapper `Table` puts around `<table>`. */
+export const TABLE_SCROLLER_CLASS = 'ss-table-scroller'
+/** A non-scrolling box around the scroller, so the edge hints can be pinned to it. */
+export const TABLE_SHELL_CLASS = 'ss-table-shell'
+export const TABLE_EDGE_CLASS = 'ss-table-edge'
+export const TABLE_EDGE_LEFT_CLASS = 'ss-table-edge-left'
+export const TABLE_EDGE_RIGHT_CLASS = 'ss-table-edge-right'
+
+/**
+ * Content scrolls, but on macOS nothing says so (startsim-5pq7h, 5pq7h.1).
+ *
+ * A reviewer reported "there is no sliding bar so it makes it difficult to see
+ * all the columns". The container did scroll the whole time; macOS renders an
+ * OVERLAY scrollbar that occupies no layout height and is invisible at rest, so
+ * the affordance was missing, not the scrolling. The same is true of every
+ * other scroller in this package.
+ *
+ * MEASURED 2026-09-07, headed Google Chrome and headed WebKit on macOS, on a
+ * 400px box holding 900px of content (`offsetHeight - clientHeight`, borders
+ * subtracted):
+ *
+ *   no scrollbar CSS                                       0px   (overlay)
+ *   scrollbar-width: thin                                  0px
+ *   scrollbar-color: <thumb> <track>                       0px
+ *   ::-webkit-scrollbar { height: 10px }                  10px   <-- this one
+ *   ::-webkit-scrollbar + scrollbar-width/-color           0px   <-- see below
+ *   ::-webkit-scrollbar, content NARROWER than the box      0px   (no regression)
+ *
+ * THREE RESULTS THAT ARE EASY TO UNDO BY ACCIDENT:
+ *
+ * 1. DO NOT ADD `scrollbar-width` OR `scrollbar-color` HERE. Every snippet on
+ *    the web pairs them with the -webkit- rules "for Firefox". Measured: when
+ *    the standard properties are set at the same specificity, Chromium honours
+ *    them INSTEAD of the custom scrollbar and reverts the element to a
+ *    zero-height overlay bar — i.e. adding them silently deletes this fix.
+ *    Firefox on macOS gains nothing from them anyway (measured 0px with
+ *    `scrollbar-width: thin` applied and confirmed in the computed style), so
+ *    there is no Firefox branch to lose. Firefox users are served by the edge
+ *    hint below instead.
+ *
+ * 2. `width` IS LOAD-BEARING even though the defect that started this is
+ *    horizontal. Declaring any `::-webkit-scrollbar` rule opts the element out
+ *    of overlay scrollbars on BOTH axes, so a height-only rule leaves the
+ *    vertical bar at the platform default. Measured 2026-09-07 on a box that
+ *    overflows vertically, borders subtracted:
+ *
+ *      height: 10px; width: 10px   ->  10px vertical bar
+ *      height: 10px  (no width)    ->  16px vertical bar   <-- worse than before
+ *      ::-webkit-scrollbar:horizontal { height: 10px }  ->  0px on BOTH axes
+ *
+ *    The last one is the tempting "only touch the horizontal axis" spelling and
+ *    it does nothing at all in Chromium. There is no CSS route to a custom
+ *    horizontal bar that leaves the vertical axis as an overlay — so an element
+ *    given {@link SCROLLER_CLASS} that also overflows vertically gains a 10px
+ *    vertical gutter, and that has to be an acceptable trade for that surface.
+ *
+ * 3. The bar costs layout height ONLY while the element overflows — that is
+ *    `overflow: auto`, not something this stylesheet decides — so it never
+ *    appears under content that fits. Keep scrollers on `auto`, never `scroll`,
+ *    or every narrow table in the fleet grows a dead bar.
+ *
+ * On Windows/Linux this REPLACES the ~15px classic bar with a 10px one; it does
+ * not reserve a second gutter, so no platform guard is needed. Nothing here
+ * animates or transitions, so `prefers-reduced-motion` has nothing to honour.
+ *
+ * ONE stylesheet, ONE id, ONE string: `ensureInjectedStyle` rewrites the sheet
+ * when an existing id carries different text, so two call sites shipping
+ * different CSS under this id would overwrite each other on every mount. Add
+ * selectors to the lists below rather than injecting a second sheet.
+ */
+export const SCROLL_AFFORDANCE_CSS = `
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar,
+.${SCROLLER_CLASS}::-webkit-scrollbar {
+  height: 10px;
+  width: 10px;
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-track,
+.${SCROLLER_CLASS}::-webkit-scrollbar-track {
+  background: transparent;
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb,
+.${SCROLLER_CLASS}::-webkit-scrollbar-thumb {
+  border-radius: 9999px;
+  background-color: color-mix(in srgb, currentColor 22%, transparent);
+}
+.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar-thumb:hover,
+.${SCROLLER_CLASS}::-webkit-scrollbar-thumb:hover {
+  background-color: color-mix(in srgb, currentColor 45%, transparent);
+}
+.${TABLE_SHELL_CLASS} {
+  position: relative;
+}
+.${TABLE_EDGE_CLASS} {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 24px;
+  pointer-events: none;
+}
+.${TABLE_EDGE_RIGHT_CLASS} {
+  right: 0;
+  background-image: linear-gradient(to left, hsl(var(--background)), hsl(var(--background) / 0));
+}
+.${TABLE_EDGE_LEFT_CLASS} {
+  left: 0;
+  background-image: linear-gradient(to right, hsl(var(--background)), hsl(var(--background) / 0));
+}
+`.trim()
+
+/**
+ * Put {@link SCROLL_AFFORDANCE_CSS} on the page, once per document.
+ *
+ * A stylesheet rather than a Tailwind class because four of the eleven apps
+ * have no `@source` line for this package, so a class written here emits no
+ * rule over there — see `injected-style.ts`. Safe to call from every component
+ * that marks a scroller; the sheet is keyed by id.
+ */
+export function useScrollAffordance(): void {
+  useInjectedStyle(SCROLL_AFFORDANCE_STYLE_ID, SCROLL_AFFORDANCE_CSS)
+}