@flamingo-stack/openframe-frontend-core 0.0.458-snapshot.20260721084902 → 0.0.458

package/src/components/chat/chat-ticket-list.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react'
 import { cn } from '../../utils/cn'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
+import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { ChatTicketItem, type ChatTicketItemData } from './entity-cards/chat-ticket-item'
 
 export interface ChatTicketListProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -46,7 +47,12 @@ const ChatTicketList = React.forwardRef<HTMLDivElement, ChatTicketListProps>(
             !fadeBottom && "border-b rounded-b-md",
           )}
         >
-          <div ref={scrollRef} className="overflow-y-auto overscroll-contain h-full" onScroll={updateFade}>
+          <OverlayScrollArea
+            viewportRef={scrollRef}
+            className="h-full"
+            contentClassName="overscroll-contain"
+            onScroll={updateFade}
+          >
             {tickets.map((ticket) => (
               <ChatTicketItem
                 key={ticket.id}
@@ -54,7 +60,7 @@ const ChatTicketList = React.forwardRef<HTMLDivElement, ChatTicketListProps>(
                 onClick={onTicketClick}
               />
             ))}
-          </div>
+          </OverlayScrollArea>
 
           {/* Scroll-fade overlays — tinted with the page background so edge
               tickets fade into the surface behind the list in BOTH themes

package/src/components/chat/guide-welcome.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import { cn } from '../../utils/cn'
 import { MingoIcon } from '../icons'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
+import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { Skeleton } from '../ui/skeleton'
 import { QuickActionWall } from './quick-action-wall'
 import { EntityIcon } from '../icon-display'
@@ -141,10 +142,11 @@ export function GuideWelcome({
       {/* Greeting + slash-command list share one scroll region; `relative` so
           the edge fades can overlay it. */}
       <div className="relative flex flex-1 min-h-0 flex-col">
-        <div
-          ref={scrollRef}
+        <OverlayScrollArea
+          viewportRef={scrollRef}
           onScroll={updateScrollFade}
-          className="flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-y-auto overscroll-contain"
+          className="flex-1 min-h-0"
+          contentClassName="flex min-h-full flex-col gap-[var(--spacing-system-m)] overscroll-contain"
         >
           {/* Greeting grows to fill (`flex-1`) so the slash-command list stays
               anchored below it — but its content is anchored at the TOP of the
@@ -187,7 +189,7 @@ export function GuideWelcome({
           </div>
 
           {children}
-        </div>
+        </OverlayScrollArea>
 
         {/* Edge scroll-fades — visible only when content is hidden beyond them. */}
         <ScrollFadeOverlay edge="top" visible={fadeTop} className="h-12" />

package/src/components/chat/mingo-chat-history.tsx

@@ -5,6 +5,7 @@ import { cn } from '../../utils/cn'
 import { ActionsMenuDropdown, type ActionsMenuItem } from '../ui/actions-menu'
 import { Button } from '../ui/button'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
+import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { Ellipsis01Icon, SearchXmarkIcon } from '../icons-v2-generated'
 import { ChatListEmptyState } from './chat-list-empty-state'
 import type { DialogItem } from './types/component.types'
@@ -338,10 +339,11 @@ export function MingoChatHistory({
       {/* Scroll region — the search INPUT now lives in the panel header
           (Figma 116:51217), so the list is just the grouped rows + fades. */}
       <div className="relative flex flex-1 min-h-0 flex-col">
-        <div
-          ref={scrollRef}
+        <OverlayScrollArea
+          viewportRef={scrollRef}
           onScroll={updateFade}
-          className="flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-y-auto overscroll-contain"
+          className="flex-1 min-h-0"
+          contentClassName="flex flex-col gap-[var(--spacing-system-m)] overscroll-contain"
         >
           {noSearchResults ? (
             // No search matches — same centred glyph + title + caption layout as
@@ -374,7 +376,7 @@ export function MingoChatHistory({
             ))
           )}
           {hasMore ? <div ref={sentinelRef} className="h-px shrink-0" /> : null}
-        </div>
+        </OverlayScrollArea>
 
         {/* Scroll-fade — only while content is hidden in that direction. */}
         <ScrollFadeOverlay edge="top" visible={fadeTop} color="var(--color-bg-card)" className="h-12" />

package/src/components/chat/mingo-welcome.tsx

@@ -8,6 +8,7 @@ import { QuickActionChipButton } from './quick-action-chip'
 import { QuickActionWall } from './quick-action-wall'
 import { Button } from '../ui/button'
 import { ScrollFadeOverlay, useScrollFade } from '../ui/scroll-fade'
+import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon'
 import {
   CompassIcon,
@@ -239,10 +240,11 @@ export function MingoWelcome({
           input. The wrapper is `relative` so the scroll-fade gradients can
           overlay the top/bottom edges. */}
       <div className="relative flex flex-1 min-h-0 flex-col">
-      <div
-        ref={scrollRef}
+      <OverlayScrollArea
+        viewportRef={scrollRef}
         onScroll={updateScrollFade}
-        className="flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-y-auto overscroll-contain"
+        className="flex-1 min-h-0"
+        contentClassName="flex min-h-full flex-col gap-[var(--spacing-system-m)] overscroll-contain"
       >
         {/* Greeting — grows to fill (`flex-1`) so it centres vertically,
             keeping the grid anchored at the bottom of the scroll area. Default
@@ -261,7 +263,7 @@ export function MingoWelcome({
           <p className="text-h4 text-ods-text-secondary">{subtitle}</p>
         </div>
       </div>
-      </div>
+      </OverlayScrollArea>
 
       {/* Edge scroll-fades — visible only when content is hidden beyond them.
           Fade into the panel's dark `ods-bg` surface (the default color), matching

package/src/components/features/notifications/notification-drawer.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useEffect, useRef } from 'react'
+import { OverlayScrollArea } from '../../ui/overlay-scroll-area'
 import { BellOffIcon } from '../../icons-v2-generated/interface/bell-off-icon'
 import { ClockHistoryIcon, ArrowRightUpIcon } from '../../icons-v2-generated'
 import { useAppLayoutDrawerContainer } from '../../navigation/app-layout-context'
@@ -189,9 +190,12 @@ function DrawerScrollList({
 
   const isEmpty = unreadNotifications.length === 0
   return (
-    <div
-      ref={scrollRef}
-      className="flex flex-1 flex-col gap-[var(--spacing-system-xs)] overflow-y-auto px-[var(--spacing-system-m)]"
+    <OverlayScrollArea
+      viewportRef={scrollRef}
+      // Horizontal padding lives on the host: OverlayScrollbars zeroes viewport
+      // padding, so `px-*` on `contentClassName` would be silently dropped.
+      className="flex-1 min-h-0 px-[var(--spacing-system-m)]"
+      contentClassName="flex flex-col gap-[var(--spacing-system-xs)]"
     >
       {isEmpty && !isLoadingMore ? (
         <EmptyState />
@@ -214,7 +218,7 @@ function DrawerScrollList({
           {loadMore && hasMore && <div ref={sentinelRef} className="h-1" aria-hidden="true" />}
         </>
       )}
-    </div>
+    </OverlayScrollArea>
   )
 }
 

package/src/components/features/time-tracker/time-tracker-panel.tsx

@@ -21,6 +21,7 @@ import {
   XmarkIcon,
 } from '../../icons-v2-generated'
 import { useTrackerClock } from './use-tracker-clock'
+import { OverlayScrollArea } from '../../ui/overlay-scroll-area'
 import type { TimeTrackerData, TimeTrackerEntry, TimeTrackerStatus } from './types'
 
 interface CustomerAutocompleteOption extends AutocompleteOption {
@@ -149,11 +150,18 @@ export function TimeTrackerPanel({
   const visibleEntries = lastEntries.slice(0, 3)
 
   return (
-    <div
+    <OverlayScrollArea
       className={cn(
-        'relative flex max-h-[calc(100vh-6rem)] w-full flex-col gap-[var(--spacing-system-l)] overflow-y-auto rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-m)]',
+        // Padding lives on the host, NOT `contentClassName`: OverlayScrollbars
+        // forces `padding: 0` on the viewport, so padding on the scroller is
+        // silently dropped (see OverlayScrollArea docs).
+        'max-h-[calc(100vh-6rem)] w-full rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-m)]',
         className,
       )}
+      // No `relative` here so the absolute close button anchors to the padded
+      // host (OverlayScrollArea's host is always relative) and keeps its inset
+      // from the card edge instead of from the padding box.
+      contentClassName="flex flex-col gap-[var(--spacing-system-l)]"
     >
       <Button
         variant="transparent"
@@ -314,7 +322,7 @@ export function TimeTrackerPanel({
       <Button variant="outline" fullWidth onClick={onClose} className="md:hidden">
         Close
       </Button>
-    </div>
+    </OverlayScrollArea>
   )
 }
 

package/src/components/layout/page-container.tsx

@@ -4,6 +4,7 @@ import React from 'react'
 import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
 import { PageActions, type PageActionButton } from '../ui/page-actions'
+import { OverlayScrollArea } from '../ui/overlay-scroll-area'
 import { BackButton } from './back-button'
 
 // Legacy interface for backward compatibility (layout version)
@@ -393,7 +394,7 @@ function renderAdvancedPageContainer({
 
     switch (variant) {
       case 'detail':
-        return cn('flex-1 overflow-auto', mobilePadding, contentClassName)
+        return cn('flex-1 min-h-0', mobilePadding, contentClassName)
       case 'list':
         return cn('flex flex-col gap-4 md:gap-6', mobilePadding, contentClassName)
       case 'form':
@@ -407,10 +408,21 @@ function renderAdvancedPageContainer({
   return (
     <div className={getContainerClasses()}>
       {renderHeader()}
-      
-      <div className={getContentClasses()}>
-        {children}
-      </div>
+
+      {variant === 'detail' ? (
+        // The only scrolling variant — standardized overlay scrollbar.
+        // `contentClassName` is forwarded to BOTH layers: padding stays effective
+        // on the host, while layout (`flex flex-col gap-*`) reaches the scroller,
+        // the direct parent of the children (OverlayScrollbars zeroes viewport
+        // padding, so padding on the scroller alone would be dropped).
+        <OverlayScrollArea className={getContentClasses()} contentClassName={contentClassName}>
+          {children}
+        </OverlayScrollArea>
+      ) : (
+        <div className={getContentClasses()}>
+          {children}
+        </div>
+      )}
     </div>
   )
 }

package/src/components/ui/drawer.tsx

@@ -7,6 +7,7 @@ import { X } from "lucide-react"
 
 import { cn } from "../../utils/cn"
 import { useHeaderHeight } from "../../hooks/ui/use-header-height"
+import { OverlayScrollArea } from "./overlay-scroll-area"
 
 /** Unified overlay backdrop — dimmed, no blur. Single source of truth for
  *  every full-screen backdrop (Drawer, AppLayoutDrawer, MobileBurgerMenu,
@@ -530,12 +531,16 @@ DrawerDescription.displayName = "DrawerDescription"
 
 const DrawerBody = ({
   className,
+  children,
   ...props
 }: React.HTMLAttributes<HTMLDivElement>) => (
-  <div
-    className={cn("flex flex-1 flex-col gap-4 overflow-y-auto", className)}
+  <OverlayScrollArea
+    className={cn("flex-1 min-h-0", className)}
+    contentClassName="flex flex-col gap-4"
     {...props}
-  />
+  >
+    {children}
+  </OverlayScrollArea>
 )
 DrawerBody.displayName = "DrawerBody"
 

package/src/components/ui/index.ts

@@ -177,3 +177,4 @@ export * from './simple-markdown-renderer'
 export { RichMarkdownRenderer, type RichMarkdownRendererProps } from './rich-markdown-renderer'
 export * from './filter-pill-row'
 
+export * from './overlay-scroll-area'

package/src/components/ui/modal-v2.tsx

@@ -5,6 +5,7 @@ import { useEffect, useState } from "react"
 import { usePreventScroll } from "@react-aria/overlays"
 import { XmarkIcon } from "../icons-v2-generated"
 import { cn } from "../../utils/cn"
+import { OverlayScrollArea } from "./overlay-scroll-area"
 
 // Duration of the open/close animation in ms — keep in sync with the
 // `duration-200` utilities applied to the backdrop and panel below.
@@ -131,9 +132,18 @@ Modal.displayName = "ModalV2"
 
 const ModalContent = React.forwardRef<HTMLDivElement, ModalContentProps>(
   ({ children, className }, ref) => (
-    <div ref={ref} className={cn("flex-1 min-h-0 overflow-y-auto", className)}>
+    // `className` goes to BOTH layers on purpose: historically it styled the
+    // single scrolling div that directly parented the children, so it may carry
+    // layout (`flex flex-col gap-*` — must reach the scroller/`contentClassName`,
+    // the direct parent of the children) OR padding (must stay on the host, since
+    // OverlayScrollbars zeroes viewport padding). Each class lands where it works.
+    <OverlayScrollArea
+      viewportRef={ref}
+      className={cn("flex-1 min-h-0", className)}
+      contentClassName={className}
+    >
       {children}
-    </div>
+    </OverlayScrollArea>
   )
 )
 ModalContent.displayName = "ModalV2Content"

package/src/components/ui/modal.tsx

@@ -4,6 +4,7 @@ import * as React from "react"
 import { useEffect } from "react"
 import { usePreventScroll } from "@react-aria/overlays"
 import { cn } from "../../utils/cn"
+import { OverlayScrollArea } from "./overlay-scroll-area"
 
 interface ModalProps {
   isOpen: boolean
@@ -82,9 +83,15 @@ Modal.displayName = "Modal"
 /** @deprecated Use ModalV2Content from './modal-v2' instead. */
 const ModalContent = React.forwardRef<HTMLDivElement, ModalContentProps>(
   ({ children, className }, ref) => (
-    <div ref={ref} className={cn("overflow-y-auto min-h-0 flex-1", className)}>
+    // See ModalV2Content: `className` may carry layout (must reach the scroller)
+    // or padding (must stay on the host), so it goes to both layers.
+    <OverlayScrollArea
+      viewportRef={ref}
+      className={cn("min-h-0 flex-1", className)}
+      contentClassName={className}
+    >
       {children}
-    </div>
+    </OverlayScrollArea>
   )
 )
 ModalContent.displayName = "ModalContent"

package/src/components/ui/overlay-scroll-area.tsx

@@ -0,0 +1,219 @@
+'use client'
+
+import * as React from 'react'
+import { OverlayScrollbars, type PartialOptions } from 'overlayscrollbars'
+import { cn } from '../../utils/cn'
+
+// =============================================================================
+// Standardized macOS-like overlay scrollbars on every platform.
+//
+// OverlayScrollbars hides the native scrollbar and draws a styleable overlay
+// one on top while keeping NATIVE scrolling (wheel, touchpad momentum,
+// keyboard, drag-the-thumb). With `autoHide` the bar shows only while
+// scrolling and fades out when idle — the macOS behavior, now identical on
+// Windows/Linux and for mouse users.
+//
+// Touch devices keep the native scrollbars: mobile bars are already overlay
+// and auto-hiding, so the custom layer is initialized only on fine-pointer
+// devices (desktop / tablet with a mouse).
+// =============================================================================
+
+/** Overlay scrollbars are desktop-only; touch keeps native scrolling. */
+const FINE_POINTER_QUERY = '(hover: hover) and (pointer: fine)'
+
+/**
+ * `matchMedia` for the fine-pointer query, or `null` where it doesn't exist —
+ * jsdom (every consumer's component tests) and non-browser render paths. The
+ * whole overlay layer is progressive enhancement, so "can't detect" degrades
+ * to the native scrollbar instead of throwing.
+ */
+const matchFinePointer = (): MediaQueryList | null =>
+  typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+    ? window.matchMedia(FINE_POINTER_QUERY)
+    : null
+
+/** True once mounted on a device with a mouse/trackpad-grade pointer. */
+export function useFinePointer(): boolean {
+  const [fine, setFine] = React.useState(false)
+  React.useEffect(() => {
+    const mq = matchFinePointer()
+    if (!mq) return
+    setFine(mq.matches)
+    const onChange = (e: MediaQueryListEvent) => setFine(e.matches)
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [])
+  return fine
+}
+
+/** Shared ODS defaults: thin grey thumb, transparent track, show on scroll. */
+const ODS_SCROLLBAR_OPTIONS: PartialOptions = {
+  scrollbars: {
+    theme: 'os-theme-ods',
+    autoHide: 'scroll',
+    autoHideDelay: 800,
+    // Keep the bar visible until the first scroll so keyboard/AT users still
+    // get the affordance on freshly opened views.
+    autoHideSuspend: true,
+  },
+}
+
+const setRef = <T,>(ref: React.Ref<T> | undefined, value: T | null) => {
+  if (!ref) return
+  if (typeof ref === 'function') ref(value)
+  else (ref as React.MutableRefObject<T | null>).current = value
+}
+
+export interface OverlayScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Sizing/box classes of the scroll container (`flex-1 min-h-0`, `max-h-…`,
+   *  borders, background) — AND paddings. Do NOT include `overflow-*` here.
+   *
+   *  PADDING BELONGS HERE, NOT ON `contentClassName`: OverlayScrollbars owns
+   *  the viewport's box and writes `padding: 0` inline on it, so a padding
+   *  class on the viewport is silently dropped (measured — this is why the
+   *  wrapper components keep passing their consumer `className` to the host). */
+  className?: string
+  /** Layout classes for the scrolling element itself (`flex flex-col gap-…`).
+   *  Children are its direct children, so `gap`/`flex` applies exactly as it
+   *  did on the old single `overflow-auto` div. Paddings do NOT work here —
+   *  see `className`. */
+  contentClassName?: string
+  /** Receives the actual scrolling element — use for scrollTop/scrollHeight
+   *  logic and as IntersectionObserver root. Set from the first commit, valid
+   *  on both the overlay and the native fallback path. */
+  viewportRef?: React.Ref<HTMLDivElement>
+  /** Extra OverlayScrollbars options merged over the ODS defaults. */
+  options?: PartialOptions
+  children?: React.ReactNode
+}
+
+/**
+ * Replacement for an `overflow-auto` scroll container with the standardized
+ * ODS overlay scrollbar. Split the old scroller's classes: sizing goes to
+ * `className`, content layout to `contentClassName`. The inner scroller div
+ * is stable across pointer modes — refs and `onScroll` (via the standard
+ * HTML props) keep working like on the plain div it replaces.
+ *
+ * On touch devices (no fine pointer) the overlay layer is never initialized
+ * and the inner div scrolls with its native (already overlay) scrollbar.
+ */
+export function OverlayScrollArea({
+  className,
+  contentClassName,
+  viewportRef,
+  options,
+  children,
+  ...props
+}: OverlayScrollAreaProps) {
+  const hostRef = React.useRef<HTMLDivElement>(null)
+  const scrollerRef = React.useRef<HTMLDivElement>(null)
+
+  // Serialize to keep the effect dep stable for inline `options` objects.
+  const optionsJson = JSON.stringify(options ?? null)
+
+  // Layout effect so the viewport is upgraded before consumers' own layout
+  // effects (scroll-fade hooks, observers) measure it.
+  React.useLayoutEffect(() => {
+    const host = hostRef.current
+    const viewport = scrollerRef.current
+    if (!host || !viewport) return
+    const extra = (JSON.parse(optionsJson) ?? {}) as PartialOptions
+    const mq = matchFinePointer()
+    if (!mq) return
+    let instance: ReturnType<typeof OverlayScrollbars> | null = null
+
+    const sync = () => {
+      if (mq.matches && !instance) {
+        // Our own div is passed as the viewport: children stay inside it and
+        // it remains the scrolling element; the library only suppresses its
+        // native scrollbar and appends the overlay handles to the host.
+        instance = OverlayScrollbars(
+          { target: host, elements: { viewport } },
+          // `scrollbars` merges one level deep: a caller overriding a single
+          // key (e.g. `autoHide`) must not drop the ODS theme and the other
+          // defaults with it.
+          {
+            ...ODS_SCROLLBAR_OPTIONS,
+            ...extra,
+            scrollbars: { ...ODS_SCROLLBAR_OPTIONS.scrollbars, ...extra.scrollbars },
+          },
+        )
+      } else if (!mq.matches && instance) {
+        instance.destroy()
+        instance = null
+      }
+    }
+
+    sync()
+    mq.addEventListener('change', sync)
+    return () => {
+      mq.removeEventListener('change', sync)
+      instance?.destroy()
+    }
+  }, [optionsJson])
+
+  return (
+    <div ref={hostRef} className={cn('relative', className)}>
+      <div
+        ref={(el) => {
+          scrollerRef.current = el
+          setRef(viewportRef, el)
+        }}
+        className={cn('h-full w-full overflow-auto', contentClassName)}
+        {...props}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export interface GlobalOverlayScrollbarsProps {
+  /** Extra OverlayScrollbars options merged over the ODS defaults. */
+  options?: PartialOptions
+}
+
+/**
+ * Applies the same overlay scrollbar to the PAGE scroller (`<body>`).
+ * Render once near the app root (client side). No-op on touch devices.
+ *
+ * ONLY mount this on APP-SHELL pages whose body barely scrolls — the real
+ * scrolling happens in inner `OverlayScrollArea` containers (openframe-frontend,
+ * openframe-chat). Do NOT mount it on long scroll-driven documents: the thumb is
+ * repositioned from JS on every scroll frame, so on a page whose main thread is
+ * already busy with reveal-on-scroll sections, tickers and marquees the scroll
+ * visibly stutters. Measured on multi-platform-hub; raising the update debounce
+ * (`update.debounce.mutation`/`resize`) did NOT help, which rules out the
+ * observer re-measurement and points at the per-frame cost itself — i.e. it is
+ * inherent to any JS-drawn scrollbar, not to this library. Such pages keep the
+ * native page scrollbar, styled by the ODS `scrollbar-width`/`scrollbar-color`
+ * globals; their inner containers can still use `OverlayScrollArea`.
+ */
+export function GlobalOverlayScrollbars({ options }: GlobalOverlayScrollbarsProps = {}) {
+  const fine = useFinePointer()
+  // Serialize to keep the effect dep stable for inline `options` objects.
+  const optionsJson = JSON.stringify(options ?? null)
+
+  React.useEffect(() => {
+    if (!fine) return
+    const extra = (JSON.parse(optionsJson) ?? {}) as PartialOptions
+    // Required by OverlayScrollbars for body initialization — suppresses the
+    // native scrollbars on both scroll roots before the overlay takes over.
+    document.documentElement.setAttribute('data-overlayscrollbars-initialize', '')
+    document.body.setAttribute('data-overlayscrollbars-initialize', '')
+    const instance = OverlayScrollbars(document.body, {
+      ...ODS_SCROLLBAR_OPTIONS,
+      ...extra,
+      // Same one-level-deep merge as OverlayScrollArea: a caller overriding a
+      // single key must not drop the ODS theme (or a tuning preset's siblings).
+      scrollbars: { ...ODS_SCROLLBAR_OPTIONS.scrollbars, ...extra.scrollbars },
+    })
+    return () => {
+      instance.destroy()
+      document.documentElement.removeAttribute('data-overlayscrollbars-initialize')
+      document.body.removeAttribute('data-overlayscrollbars-initialize')
+    }
+  }, [fine, optionsJson])
+
+  return null
+}

package/src/stories/OverlayScrollArea.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { OverlayScrollArea } from '../components/ui/overlay-scroll-area'
+
+// POC: standardized macOS-like overlay scrollbar (OverlayScrollbars) — the
+// bar appears while scrolling / hovering and fades out when idle, on every
+// platform. Native scrolling (wheel, touchpad momentum, thumb drag) is kept.
+
+const meta: Meta<typeof OverlayScrollArea> = {
+  title: 'UI/OverlayScrollArea',
+  component: OverlayScrollArea,
+  parameters: { layout: 'centered' },
+}
+
+export default meta
+type Story = StoryObj<typeof OverlayScrollArea>
+
+const rows = (count: number) =>
+  Array.from({ length: count }, (_, i) => (
+    <div key={i} className="border-b border-ods-border px-[var(--spacing-system-m)] py-[var(--spacing-system-s)] text-ods-text-primary">
+      Row {i + 1} — scrollable content
+    </div>
+  ))
+
+export const Vertical: Story = {
+  render: () => (
+    <OverlayScrollArea className="h-72 w-96 rounded-lg border border-ods-border bg-ods-card">
+      {rows(40)}
+    </OverlayScrollArea>
+  ),
+}
+
+export const Horizontal: Story = {
+  render: () => (
+    <OverlayScrollArea className="h-24 w-96 rounded-lg border border-ods-border bg-ods-card">
+      <div className="flex w-max gap-[var(--spacing-system-s)] p-[var(--spacing-system-m)]">
+        {Array.from({ length: 30 }, (_, i) => (
+          <div key={i} className="flex h-12 w-28 shrink-0 items-center justify-center rounded-md bg-ods-bg text-ods-text-secondary">
+            Chip {i + 1}
+          </div>
+        ))}
+      </div>
+    </OverlayScrollArea>
+  ),
+}
+
+export const Both: Story = {
+  render: () => (
+    <OverlayScrollArea className="h-72 w-96 rounded-lg border border-ods-border bg-ods-card">
+      <div className="w-[800px]">{rows(40)}</div>
+    </OverlayScrollArea>
+  ),
+}

package/src/styles/index.css

@@ -10,6 +10,8 @@
 /* Vendor/library style overrides */
 @import "./vendor-react-easy-crop.css";
 @import "./vendor-react-scroll.css";
+@import "./vendor-overlayscrollbars.css";
+@import "./overlay-scrollbars-theme.css";
 
 @tailwind base;
 @tailwind components;

package/src/styles/overlay-scrollbars-theme.css

@@ -0,0 +1,19 @@
+/* ODS theme for OverlayScrollbars (see components/ui/overlay-scroll-area.tsx).
+   Thin grey draggable thumb on a transparent track — matches the global
+   elevator scrollbar styling, but with macOS-like auto-hide on all platforms. */
+.os-theme-ods {
+  --os-size: 8px;
+  --os-padding-perpendicular: 2px;
+  --os-padding-axis: 2px;
+  --os-track-bg: transparent;
+  --os-track-bg-hover: transparent;
+  --os-track-bg-active: transparent;
+  --os-handle-bg: var(--ods-system-greys-grey);
+  --os-handle-bg-hover: var(--ods-system-greys-grey-hover);
+  --os-handle-bg-active: var(--ods-system-greys-grey-action);
+  --os-handle-border-radius: 4px;
+  --os-handle-perpendicular-size: 100%;
+  --os-handle-perpendicular-size-hover: 100%;
+  --os-handle-perpendicular-size-active: 100%;
+  --os-handle-min-size: 33px;
+}