@startsimpli/ui 0.4.114 → 0.4.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.114",
+  "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/__tests__/table-scroll.test.tsx

@@ -0,0 +1,153 @@
+/**
+ * Guards for the table's horizontal-scroll affordance (startsim-5pq7h).
+ *
+ * The defect these come from is PURELY VISUAL — "there is no sliding bar so it
+ * makes it difficult to see all the columns" — and jsdom has no layout, so
+ * NOTHING here proves a scrollbar is visible on screen. That claim is carried
+ * by browser measurement (headed Chrome + headed WebKit on macOS: 0px of
+ * scrollbar layout height before, 10px after, 0px when the table fits).
+ *
+ * What these DO guard is the two things a later edit can silently break:
+ *  - the CSS that produces the bar, including the `scrollbar-width` rule that
+ *    measurably DELETES it, and
+ *  - the "no decoration when nothing overflows" contract.
+ */
+import { render, screen } from '@testing-library/react'
+import { renderHook, act } from '@testing-library/react'
+import { useRef } from 'react'
+import { Table, TableBody, TableCell, TableRow } from '../table'
+import {
+  TABLE_SCROLL_CSS,
+  TABLE_SCROLL_STYLE_ID,
+  TABLE_SCROLLER_CLASS,
+  useScrollEdges,
+} from '../table-scroll'
+
+describe('TABLE_SCROLL_CSS', () => {
+  it('styles the webkit scrollbar, which is what gives the bar layout height', () => {
+    expect(TABLE_SCROLL_CSS).toContain(`.${TABLE_SCROLLER_CLASS}::-webkit-scrollbar`)
+    expect(TABLE_SCROLL_CSS).toMatch(/height:\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(TABLE_SCROLL_CSS).not.toMatch(/scrollbar-width/)
+    expect(TABLE_SCROLL_CSS).not.toMatch(/scrollbar-color/)
+  })
+
+  /**
+   * `overflow: auto` is what makes the bar conditional on real overflow. Under
+   * `overflow: scroll` every narrow table in the fleet would grow a dead 10px
+   * bar — a regression, not a fix.
+   */
+  it('leaves the scroller on overflow:auto so the bar is conditional on real overflow', () => {
+    expect(TABLE_SCROLL_CSS).not.toMatch(/overflow\s*:\s*scroll/)
+  })
+})
+
+describe('Table', () => {
+  const renderTable = (props: Record<string, unknown> = {}) =>
+    render(
+      <Table {...props}>
+        <TableBody>
+          <TableRow>
+            <TableCell>cell</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    )
+
+  it('marks its scroll container so the scrollbar rules can find it', () => {
+    renderTable()
+    const table = screen.getByRole('table')
+    expect(table.parentElement).toHaveClass(TABLE_SCROLLER_CLASS)
+    expect(table.parentElement).toHaveClass('overflow-auto')
+  })
+
+  it('injects the stylesheet once, however many tables are on the page', () => {
+    render(
+      <>
+        <Table />
+        <Table />
+        <Table />
+      </>
+    )
+    expect(document.querySelectorAll(`#${TABLE_SCROLL_STYLE_ID}`)).toHaveLength(1)
+    expect(document.getElementById(TABLE_SCROLL_STYLE_ID)?.textContent).toBe(
+      TABLE_SCROLL_CSS
+    )
+  })
+
+  it('sends containerClassName to the scrolling box and className to the table', () => {
+    renderTable({ containerClassName: 'max-h-96', className: 'my-table' })
+    const table = screen.getByRole('table')
+    expect(table).toHaveClass('my-table')
+    expect(table.parentElement).toHaveClass('max-h-96')
+    expect(table).not.toHaveClass('max-h-96')
+  })
+})
+
+describe('useScrollEdges', () => {
+  /** jsdom has no layout, so geometry has to be stated outright. */
+  const harness = (clientWidth: number, scrollWidth: number, scrollLeft: number) => {
+    const scroller = document.createElement('div')
+    const table = document.createElement('table')
+    scroller.appendChild(table)
+    document.body.appendChild(scroller)
+    Object.defineProperty(scroller, 'clientWidth', { value: clientWidth, configurable: true })
+    Object.defineProperty(scroller, 'scrollWidth', { value: scrollWidth, configurable: true })
+    scroller.scrollLeft = scrollLeft
+    return { scroller, table }
+  }
+
+  const run = (clientWidth: number, scrollWidth: number, scrollLeft = 0) => {
+    const { scroller, table } = harness(clientWidth, scrollWidth, scrollLeft)
+    const { result } = renderHook(() => {
+      const ref = useRef<HTMLTableElement | null>(table)
+      return useScrollEdges(ref)
+    })
+    return { edges: result.current, scroller, result }
+  }
+
+  it('reports no edge at all when the table fits — a hint under a table that fits is the same defect as a bar under one', () => {
+    expect(run(846, 846).edges).toEqual({ left: false, right: false })
+  })
+
+  it('ignores a sub-pixel overhang rather than decorating a table that visually fits', () => {
+    expect(run(846, 847).edges).toEqual({ left: false, right: false })
+  })
+
+  it('reports the right edge when columns are unreached to the right', () => {
+    expect(run(846, 1014).edges).toEqual({ left: false, right: true })
+  })
+
+  it('reports the left edge once scrolled away from the start', () => {
+    expect(run(846, 1014, 84).edges).toEqual({ left: true, right: true })
+  })
+
+  it('drops the right edge at the end of the scroll range', () => {
+    expect(run(846, 1014, 168).edges).toEqual({ left: true, right: false })
+  })
+
+  it('re-reads geometry when the scroller is scrolled', () => {
+    const { scroller, result } = run(846, 1014)
+    expect(result.current).toEqual({ left: false, right: true })
+    act(() => {
+      scroller.scrollLeft = 168
+      scroller.dispatchEvent(new Event('scroll'))
+    })
+    expect(result.current).toEqual({ left: true, right: false })
+  })
+})

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

@@ -0,0 +1,93 @@
+'use client'
+
+import { useEffect, useState, type RefObject } from 'react'
+
+/**
+ * The table's share of the scroll affordance (startsim-5pq7h).
+ *
+ * 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 {
+  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. */
+  left: boolean
+  /** There is content still unreached to the right. */
+  right: boolean
+}
+
+/**
+ * Which horizontal edges of a table's scroller still hide content.
+ *
+ * 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.
+ */
+export function useScrollEdges(
+  tableRef: RefObject<HTMLTableElement | null>
+): ScrollEdges {
+  const [edges, setEdges] = useState<ScrollEdges>({ left: false, right: false })
+
+  useEffect(() => {
+    const table = tableRef.current
+    const scroller = table?.parentElement
+    if (!table || !scroller) return
+
+    const update = () => {
+      // 1px of slack: sub-pixel column widths leave scrollWidth a hair above
+      // clientWidth on tables that visually fit, and a hint under a table that
+      // fits is the same defect as a scrollbar under one.
+      const max = scroller.scrollWidth - scroller.clientWidth
+      const next: ScrollEdges = {
+        left: max > 1 && scroller.scrollLeft > 1,
+        right: max > 1 && scroller.scrollLeft < max - 1,
+      }
+      setEdges((prev) =>
+        prev.left === next.left && prev.right === next.right ? prev : next
+      )
+    }
+
+    update()
+    scroller.addEventListener('scroll', update, { passive: true })
+
+    let observer: ResizeObserver | undefined
+    if (typeof ResizeObserver !== 'undefined') {
+      // Observe the TABLE, not just the scroller. The scroller is `w-full`, so
+      // its own box does NOT change when a column is toggled, a filter narrows
+      // the data, or a page of rows re-sizes the auto-laid-out columns — only
+      // the table's box does. Watching the scroller alone misses every one of
+      // those and leaves the hint stale.
+      observer = new ResizeObserver(update)
+      observer.observe(table)
+      observer.observe(scroller)
+    }
+    window.addEventListener('resize', update)
+
+    return () => {
+      scroller.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+      observer?.disconnect()
+    }
+  }, [tableRef])
+
+  return edges
+}

package/src/components/ui/table.tsx

@@ -1,19 +1,44 @@
+'use client'
+
 import * as React from "react"
 
 import { cn } from "../../lib/utils"
+import { TABLE_SCROLLER_CLASS, useScrollAffordance } from "./table-scroll"
 
-const Table = React.forwardRef<
-  HTMLTableElement,
-  React.HTMLAttributes<HTMLTableElement>
->(({ className, ...props }, ref) => (
-  <div className="relative w-full overflow-auto">
-    <table
-      ref={ref}
-      className={cn("w-full caption-bottom text-sm", className)}
-      {...props}
-    />
-  </div>
-))
+export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
+  /**
+   * Classes for the scroll container that wraps the `<table>`. This div — not
+   * the `<table>` — is the element that actually scrolls horizontally, so
+   * anything that needs to change the scrolling box (a max-height, a different
+   * overflow) belongs here rather than in `className`.
+   */
+  containerClassName?: string
+}
+
+const Table = React.forwardRef<HTMLTableElement, TableProps>(
+  ({ className, containerClassName, ...props }, ref) => {
+    // Gives the scroller a scrollbar that is actually visible while it
+    // overflows. See lib/scroll-affordance.ts for the measurements — in
+    // particular why `scrollbar-width` must NOT be added alongside it.
+    useScrollAffordance()
+
+    return (
+      <div
+        className={cn(
+          "relative w-full overflow-auto",
+          TABLE_SCROLLER_CLASS,
+          containerClassName
+        )}
+      >
+        <table
+          ref={ref}
+          className={cn("w-full caption-bottom text-sm", className)}
+          {...props}
+        />
+      </div>
+    )
+  }
+)
 Table.displayName = "Table"
 
 const TableHeader = React.forwardRef<

package/src/components/unified-table/__tests__/components/DataTableCore.scroll-affordance.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * DataTableCore's edge hints (startsim-5pq7h).
+ *
+ * The persistent scrollbar restored on the `Table` primitive sits at the bottom
+ * of the scroller, and the scroller is as tall as the whole table — measured
+ * 3061-5698px BELOW THE FOLD on every content view of the marketing-agents
+ * tenant at a 900px-tall window. A reader at the header row never sees it, so
+ * the table also fades whichever edge still hides content.
+ *
+ * jsdom has no layout, so the geometry is stated outright below. These tests
+ * guard the WIRING and the "nothing overflows -> no decoration" contract; the
+ * visual claim is carried by browser measurement, not by them.
+ */
+import { render, screen } from '@testing-library/react'
+import { DataTableCore } from '../../components/DataTableCore'
+import { ColumnConfig } from '../../types'
+import { TABLE_EDGE_CLASS, TABLE_SHELL_CLASS } from '../../../ui/table-scroll'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const data: Row[] = [
+  { id: '1', name: 'Abu Dhabi Off-Plan Mortgage Guide' },
+  { id: '2', name: 'UAE Capital Markets Fee Changes' },
+]
+
+const columns: ColumnConfig<Row>[] = [
+  { id: 'name', header: 'Name', accessorKey: 'name' },
+]
+
+/** Force the scroll container's geometry, which jsdom otherwise reports as 0/0. */
+function stubGeometry(clientWidth: number, scrollWidth: number) {
+  const original = {
+    clientWidth: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'clientWidth'),
+    scrollWidth: Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'scrollWidth'),
+  }
+  Object.defineProperty(HTMLElement.prototype, 'clientWidth', {
+    configurable: true,
+    get() {
+      return this.tagName === 'DIV' ? clientWidth : 0
+    },
+  })
+  Object.defineProperty(HTMLElement.prototype, 'scrollWidth', {
+    configurable: true,
+    get() {
+      return this.tagName === 'DIV' ? scrollWidth : 0
+    },
+  })
+  return () => {
+    if (original.clientWidth) Object.defineProperty(HTMLElement.prototype, 'clientWidth', original.clientWidth)
+    if (original.scrollWidth) Object.defineProperty(HTMLElement.prototype, 'scrollWidth', original.scrollWidth)
+  }
+}
+
+const edges = (container: HTMLElement) =>
+  container.querySelectorAll(`.${TABLE_EDGE_CLASS}`)
+
+describe('DataTableCore horizontal-scroll affordance', () => {
+  let restore: () => void = () => {}
+  afterEach(() => restore())
+
+  it('gives the table a non-scrolling shell for the hints to pin to', () => {
+    restore = stubGeometry(846, 846)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    const table = screen.getByRole('table')
+    // The shell is the OUTER box; the element that scrolls is Table's own
+    // wrapper inside it. Pinning the hints to the scroller would make them
+    // scroll away with the content.
+    expect(container.querySelector(`.${TABLE_SHELL_CLASS}`)).toBe(
+      table.parentElement?.parentElement
+    )
+  })
+
+  it('renders no edge hint at all when every column fits', () => {
+    restore = stubGeometry(846, 846)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    expect(edges(container)).toHaveLength(0)
+  })
+
+  it('fades the right edge when columns are unreached to the right', () => {
+    // /t/topic at a 1152px window: 846 visible, 1014 needed.
+    restore = stubGeometry(846, 1014)
+    const { container } = render(
+      <DataTableCore data={data} columns={columns} getRowId={(r) => r.id} />
+    )
+    const found = edges(container)
+    expect(found).toHaveLength(1)
+    expect(found[0]).toHaveClass('ss-table-edge-right')
+    // Decoration only — it must never intercept a click meant for the cell or
+    // the row-action menu underneath.
+    expect(found[0]).toHaveAttribute('aria-hidden', 'true')
+  })
+})

package/src/components/unified-table/components/DataTableCore/index.tsx

@@ -1,7 +1,14 @@
 'use client'
 
-import { ReactNode, useState, useCallback } from 'react'
+import { ReactNode, useState, useCallback, useRef } from 'react'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../../ui/table'
+import {
+  useScrollEdges,
+  TABLE_SHELL_CLASS,
+  TABLE_EDGE_CLASS,
+  TABLE_EDGE_LEFT_CLASS,
+  TABLE_EDGE_RIGHT_CLASS,
+} from '../../../ui/table-scroll'
 import { Checkbox } from '../../../ui/checkbox'
 import { Button } from '../../../ui/button'
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger } from '../../../ui/dropdown-menu'
@@ -91,6 +98,14 @@ export function DataTableCore<TData>({
   // State for tracking if a column is being dragged (to disable sorting during drag)
   const [isDraggingColumn, setIsDraggingColumn] = useState(false)
 
+  // The scrollbar restored in `Table` sits at the bottom of the scroller, and
+  // the scroller is as tall as the whole table — thousands of pixels below the
+  // fold on a full page of rows. These flags drive a fade at whichever edge
+  // still hides content, so the reader is told at the header row, not only at
+  // the very bottom of the page (startsim-5pq7h).
+  const tableRef = useRef<HTMLTableElement>(null)
+  const scrollEdges = useScrollEdges(tableRef)
+
   // Drag handlers
   const handleDragStart = useCallback((_: DragStart) => {
     setIsDraggingColumn(true)
@@ -334,8 +349,13 @@ export function DataTableCore<TData>({
   return (
     // overflow-x-auto: a wide table scrolls horizontally inside its own border
     // instead of overflowing the page to the right (startsim column-overflow).
-    <div className={cn('rounded-md border border-border overflow-x-auto', className)}>
-      <Table>
+    // NOTE: this div is not the element that ends up scrolling — `Table`'s own
+    // `overflow-auto` wrapper inside it is, because that wrapper is `w-full`
+    // and so never makes this one overflow. That is why the scrollbar styling
+    // and the ref below both target the inner wrapper. This div stays as the
+    // non-scrolling shell the edge hints are pinned to.
+    <div className={cn('rounded-md border border-border overflow-x-auto', TABLE_SHELL_CLASS, className)}>
+      <Table ref={tableRef}>
         {renderColumnHeaders()}
 
         <TableBody>
@@ -474,6 +494,17 @@ export function DataTableCore<TData>({
           )}
         </TableBody>
       </Table>
+
+      {/* Edge hints. Rendered only while that side actually hides something, so
+          a table that fits gets no decoration at all. `pointer-events: none`
+          keeps the rightmost column's cells and the row-action menu clickable
+          underneath. */}
+      {scrollEdges.left && (
+        <div aria-hidden="true" className={cn(TABLE_EDGE_CLASS, TABLE_EDGE_LEFT_CLASS)} />
+      )}
+      {scrollEdges.right && (
+        <div aria-hidden="true" className={cn(TABLE_EDGE_CLASS, TABLE_EDGE_RIGHT_CLASS)} />
+      )}
     </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/injected-style.ts

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+
+/**
+ * Append a stylesheet to <head> exactly once per document, keyed by `id`.
+ *
+ * WHY THIS EXISTS instead of a .css file or Tailwind classes (startsim-5pq7h):
+ *
+ *  - @startsimpli/ui ships SOURCE (`main: ./src/index.ts`), and each consuming
+ *    app decides for itself whether Tailwind scans it. Four of the eleven apps
+ *    — crochet, recipe, workflows and raise — have no
+ *    `@source ".../@startsimpli/ui/src/**"` line in their globals.css, so a
+ *    Tailwind class written in this package emits no rule at all over there.
+ *  - The subpath CSS exports (`./gantt/styles`, `./workflows/styles`) only take
+ *    effect once the app adds an `@import`, which is a change in eleven repos.
+ *  - Pseudo-element rules (`::-webkit-scrollbar`) cannot be expressed as an
+ *    inline `style` prop.
+ *
+ * Injecting from the component is the only delivery that reaches every place
+ * the component actually renders.
+ */
+export function ensureInjectedStyle(id: string, css: string): void {
+  if (typeof document === 'undefined') return
+
+  const existing = document.getElementById(id)
+  if (existing) {
+    if (existing.textContent !== css) existing.textContent = css
+    return
+  }
+
+  const el = document.createElement('style')
+  el.id = id
+  el.textContent = css
+  document.head.appendChild(el)
+}
+
+/** React wrapper for {@link ensureInjectedStyle}. Safe to call from every instance. */
+export function useInjectedStyle(id: string, css: string): void {
+  useEffect(() => {
+    ensureInjectedStyle(id, css)
+  }, [id, 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)
+}