@flamingo-stack/openframe-frontend-core 0.0.455 → 0.0.456

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

@@ -96,6 +96,8 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       isLoading = false,
       isTyping = false,
       autoScroll = true,
+      overscrollContain = true,
+      pinBottom = false,
       showAvatars = true,
       fullWidth = false,
       contentClassName,
@@ -254,6 +256,42 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       }
     }, [autoScroll, messages, dialogId, scrollToBottom, contentRef])
 
+    // ---- Passive-demo hard pin (pinBottom) ---------------------------
+    // Scripted in-page replays (the Fae/Mingo demos) have no human at the
+    // keyboard, so the newest streamed content must ALWAYS sit at the
+    // bottom. `useStickToBottom`'s smart follow only tracks while the
+    // viewer is "at bottom", which is unreliable for an assistant-only
+    // stream from a cold, non-bottom mount (the exact bug where the last
+    // reply landed below the fold). When `pinBottom` is set we snap the
+    // scroller to its full height — the SAME mechanism for BOTH demo
+    // surfaces, so Fae and Mingo behave 1:1.
+    //
+    // CRUCIAL: only re-pin when the content HEIGHT actually changed (a
+    // streamed token appended, or the conversation swapped/reset). A parent
+    // that recreates props on every render — EmbeddableChat in previewMode
+    // rebuilds its scripted state each render, churning the `messages` array
+    // identity — would otherwise fire this effect on every re-render and snap
+    // the scroller back to the bottom, trapping the visitor and blocking
+    // internal scroll (Mingo couldn't scroll while Fae, with stable memoized
+    // props, could). Skipping the pin when the height is UNCHANGED means an
+    // idle re-render leaves the scroller alone, so once the stream settles the
+    // visitor can scroll up in BOTH surfaces; a real growth (streaming) or a
+    // shrink (a new conversation) still re-pins to the fresh bottom.
+    // `useLayoutEffect` so the write lands before paint (no visible jump).
+    // Pair with `autoScroll={false}` so the library's spring doesn't fight.
+    const pinPrevHeightRef = useRef(0)
+    useLayoutEffect(() => {
+      if (!pinBottom) {
+        pinPrevHeightRef.current = 0
+        return
+      }
+      const el = scrollRef.current
+      if (!el) return
+      if (el.scrollHeight === pinPrevHeightRef.current) return
+      pinPrevHeightRef.current = el.scrollHeight
+      el.scrollTop = el.scrollHeight
+    }, [pinBottom, messages, isTyping, pendingApprovals, scrollRef])
+
     // ---- Prepend anchoring (load-older) ------------------------------
     // The library doesn't preserve user position when content grows ABOVE
     // the viewport. We do: from the pre-load geometry snapshot (taken in the
@@ -494,11 +532,16 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
         <div
           ref={setScrollRef}
           className={cn(
-            // `overscroll-contain`: reaching the top/bottom of the thread must
-            // NOT chain the wheel/touch scroll to the page behind the chat —
-            // e.g. the company-hub deck (native body scroll + sticky slide
-            // panels) would otherwise advance slides while you scroll the chat.
-            "flex h-full w-full flex-col overflow-y-auto overflow-x-hidden overscroll-contain flex-1",
+            "flex h-full w-full flex-col overflow-y-auto overflow-x-hidden flex-1",
+            // `overscroll-contain` (default ON, opt-out via `overscrollContain={false}`):
+            // reaching the top/bottom of the thread must NOT chain the wheel/
+            // touch scroll to the page behind the chat — e.g. the company-hub
+            // deck (native body scroll + sticky slide panels) would otherwise
+            // advance slides while you scroll the chat (fixed in #1501; kept as
+            // the prop default here). Passive in-page DEMO chats disable it so
+            // the surrounding page keeps scrolling normally when the pointer is
+            // over the (non-interactive) thread.
+            overscrollContain && "overscroll-contain",
             "scrollbar-thin scrollbar-track-transparent scrollbar-thumb-ods-border/30 hover:scrollbar-thumb-ods-text-secondary/30",
             className,
           )}

package/src/components/chat/embeddable-chat.tsx

@@ -2264,7 +2264,19 @@ function EmbeddableChatInner({
                     <ChatMessageList
                       messages={messages}
                       isTyping={chatLoading}
-                      autoScroll={true}
+                      // Real drawer: the library's smart follow. Passive in-page
+                      // demo (previewMode): deterministic hard pin instead — a
+                      // scripted assistant-only stream from a cold mount never
+                      // satisfies the library's "at bottom" gate, so the reply
+                      // landed below the fold. `pinBottom` snaps to bottom on
+                      // every frame; identical mechanism to the Fae demo box, so
+                      // both surfaces behave 1:1.
+                      autoScroll={!previewMode}
+                      pinBottom={previewMode}
+                      // Passive in-page demos (previewMode) let the surrounding
+                      // page scroll over the thread; the real drawer keeps
+                      // containment (deck slide-scroll fix).
+                      overscrollContain={!previewMode}
                       assistantType="mingo"
                       assistantIcon={mingoAssistantIcon}
                       renderEntityCard={renderEntityCard}
@@ -2272,11 +2284,27 @@ function EmbeddableChatInner({
                       renderContextItem={renderContextItem}
                       renderMention={renderMention}
                       NavLinkAnchor={NavLinkAnchorViaRuntime}
-                      // Hide the message-list scrollbar for the Mingo panel
+                      // Real Mingo drawer: hide the message-list scrollbar
                       // (scroll stays functional). Scoped here via `className`
                       // instead of `ChatMessageList` itself, so other list
                       // consumers (host chat, tickets) keep their thin bar.
-                      className="flex-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+                      //
+                      // `previewMode` (the passive in-page demo) instead:
+                      //  • KEEP the default thin scrollbar — the "elevator" —
+                      //    so the Mingo demo's scroll controls match the Fae
+                      //    demo box (which renders the default ChatMessageList
+                      //    scrollbar) 1:1.
+                      //  • Re-enable pointer events on the scroller: previewMode
+                      //    puts `pointer-events-none` on the whole panel (line
+                      //    ~1981) so the demo doesn't trap clicks, but that also
+                      //    killed wheel/touch scroll on the thread (the Mingo
+                      //    embed couldn't scroll while the Fae box could). Only
+                      //    the scroller re-enables; composer + chrome stay inert.
+                      className={
+                        previewMode
+                          ? 'flex-1 pointer-events-auto'
+                          : 'flex-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden'
+                      }
                       // No inner `px`/`pb`: the panel wrapper already pads with
                       // `p-[var(--spacing-system-m)]`. The default content class
                       // adds `px-[var(--spacing-system-m)]` + `pb-…xs`, which

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

@@ -207,6 +207,7 @@ export function GuideWelcome({
           chips={chipItems}
           rows={4}
           pauseOnHover
+          dragScroll
           fade={['left', 'right']}
           fadeSize={{ left: 32 }}
           fadeColor="var(--color-bg)"

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

@@ -339,6 +339,7 @@ export function MingoWelcome({
               }))}
               rows={4}
               pauseOnHover
+              dragScroll
               fade={['left', 'right']}
               fadeSize={{ left: 32 }}
               fadeColor="var(--color-bg)"

package/src/components/chat/quick-action-wall.tsx

@@ -71,6 +71,10 @@ export interface QuickActionWallProps {
   /** Marquee on/off (auto-off when content fits / reduced motion / loading). */
   animate?: boolean
   pauseOnHover?: boolean
+  /** Opt-in manual drag + wheel scroll (forwarded to {@link MarqueeWall}) — the
+   *  auto-marquee pauses while the user drags/wheels and resumes from there.
+   *  Enabled on the embeddable-chat quick-action walls. */
+  dragScroll?: boolean
   fade?: MarqueeWallFadeEdge | ReadonlyArray<MarqueeWallFadeEdge>
   /** Color behind the wall — the fades blend into it. */
   fadeColor?: string
@@ -139,6 +143,7 @@ export function QuickActionWall({
   speed,
   animate = true,
   pauseOnHover,
+  dragScroll = false,
   fade,
   fadeColor,
   fadeSize,
@@ -206,6 +211,7 @@ export function QuickActionWall({
             speed={speed}
             animate={animate && !loading}
             pauseOnHover={pauseOnHover}
+            dragScroll={dragScroll}
             copyGap={gap}
             contentClassName={cn('flex items-center', contentClassName)}
             contentStyle={{ gap }}
@@ -229,6 +235,7 @@ export function QuickActionWall({
       // Skeleton walls stay put — the marquee starts when real chips land.
       animate={animate && !loading}
       pauseOnHover={pauseOnHover}
+      dragScroll={dragScroll}
       fade={fade}
       fadeColor={fadeColor}
       fadeSize={fadeSize}

package/src/components/chat/types/component.types.ts

@@ -222,6 +222,23 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
   typingMessage?: string
   smoothScroll?: boolean
   autoScroll?: boolean
+  /** `overscroll-behavior: contain` on the scroller (default true) — stops
+   *  wheel/touch scroll from chaining to the page at the thread's edges (the
+   *  deck / drawer need this). Passive in-page demo chats set `false` so the
+   *  page keeps scrolling normally over the non-interactive thread. */
+  overscrollContain?: boolean
+  /** Deterministic stick-to-bottom for PASSIVE scripted replays (the in-page
+   *  Fae/Mingo demos). Whenever the scroll HEIGHT changes — a streamed token
+   *  grows the thread, or a new conversation replaces it — the scroller is
+   *  hard-snapped to its full height, so the newest streamed line is always
+   *  visible even though no human is at the keyboard. Unlike `autoScroll` (the
+   *  library's smart follow, which only tracks while the viewer is "at bottom"
+   *  and is unreliable for an assistant-only stream from a cold, non-bottom
+   *  mount), this pins on real growth without that gate. A same-height idle
+   *  re-render does NOT re-pin, so once the stream settles the viewer can freely
+   *  scroll up. Pair with `autoScroll={false}` so the library's spring doesn't
+   *  run in parallel. */
+  pinBottom?: boolean
   showAvatars?: boolean
   /** Same `fullWidth` semantics as `ChatHeaderProps.fullWidth` — drops
    *  the inner content wrapper's `max-w-ods-content-narrow` so messages

package/src/components/features/cards-strip.tsx

@@ -45,6 +45,7 @@ import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { cn } from '../../utils/cn';
 import { NEAR_VIEWPORT_ROOT_MARGIN } from '../../hooks/use-near-viewport';
 import { useMarqueeEngine } from '../../hooks/ui/use-marquee-engine';
+import { useResetOnPageHidden } from '../../hooks/ui/use-reset-on-page-hidden';
 import { useSuppressCloneFocus } from '../../hooks/ui/use-suppress-clone-focus';
 import { Button } from '../ui/button';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
@@ -424,6 +425,20 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
     const current = activeKeyRef.current;
     if (current !== null) deactivate(current);
   }, [deactivate]);
+  // Unconditional hover-clear (any pointer type) — the self-heal for a MISSED
+  // `pointerleave`. A leave can be swallowed by a tab blur, an interrupted
+  // pointer (pointercancel), or an overlay mounting under the cursor, leaving
+  // `inside` stuck true so the marquee freezes FOREVER ("gets stuck every once
+  // in a while"). Reset it on pointercancel + whenever the tab hides / the
+  // window loses focus; the next real hover re-arms it. Can only un-stick.
+  const clearHover = useCallback(() => {
+    hoverPointerRef.current.inside = false;
+    const current = activeKeyRef.current;
+    if (current !== null) deactivate(current);
+  }, [deactivate]);
+  // Shared SSOT self-heal: un-stick the hover flag whenever the tab hides / the
+  // window loses focus (a `pointerleave`/`pointercancel` can be swallowed).
+  useResetOnPageHidden(clearHover);
   /** Re-sync hover only when the track actually moved under the pointer.
    *  KNOWN HOT-PATH COST (intentional): while the marquee runs with the
    *  pointer parked over strip whitespace (no card → not paused), scrollLeft
@@ -654,6 +669,7 @@ export function CardsStrip<T = unknown>(props: CardsStripProps<T>): React.ReactE
           onPointerEnter={onHoverPointerEnter}
           onPointerMove={onHoverPointerMove}
           onPointerLeave={onHoverPointerLeave}
+          onPointerCancel={clearHover}
           onScroll={onSeamWarp}
         >
           <div ref={trackRef} data-copies={copies} className="flex w-max items-stretch gap-4">

package/src/components/ui/marquee-wall.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import { cn } from '../../utils/cn'
 import { useMarqueeEngine } from '../../hooks/ui/use-marquee-engine'
 import { useMediaQuery } from '../../hooks/ui/use-media-query'
+import { useResetOnPageHidden } from '../../hooks/ui/use-reset-on-page-hidden'
 import { useSuppressCloneFocus } from '../../hooks/ui/use-suppress-clone-focus'
 import { NEAR_VIEWPORT_ROOT_MARGIN } from '../../hooks/use-near-viewport'
 
@@ -153,6 +154,13 @@ export interface MarqueeWallProps {
    *  must never move under a pointing cursor (required for interactive chip
    *  walls). Default true. */
   pauseOnHover?: boolean
+  /** Opt-in MANUAL scroll: pointer-drag + horizontal wheel move the wall along
+   *  its axis (transform-based — no inner scroller is created, so it stays
+   *  deck-safe). The auto-marquee pauses during the interaction and briefly
+   *  after, then resumes drifting from wherever the user left it. Off by
+   *  default (decorative walls stay auto-only); enabled on the embeddable-chat
+   *  quick-action walls so users can browse the actions by hand. */
+  dragScroll?: boolean
   /** Edge fade(s) — the "there's more" affordance. ONE spelling of the
    *  clip-and-fade across every wall surface. */
   fade?: MarqueeWallFadeEdge | ReadonlyArray<MarqueeWallFadeEdge>
@@ -295,6 +303,7 @@ export function MarqueeWall({
   speed = 40,
   animate = true,
   pauseOnHover = true,
+  dragScroll = false,
   fade,
   fadeColor = 'var(--color-bg)',
   fadeSize,
@@ -386,6 +395,9 @@ export function MarqueeWall({
 
   // ---- pause-reason set ------------------------------------------------------
   const pointerInsideRef = React.useRef(false)
+  const clearPointerInside = React.useCallback(() => {
+    pointerInsideRef.current = false
+  }, [])
   const onPointerEnter = React.useCallback((e: React.PointerEvent) => {
     if (e.pointerType === 'touch') return
     pointerInsideRef.current = true
@@ -394,6 +406,21 @@ export function MarqueeWall({
     if (e.pointerType === 'touch') return
     pointerInsideRef.current = false
   }, [])
+  // Stale-flag self-heal (shared SSOT): if a `pointerleave` is MISSED (tab blur,
+  // overlay under the cursor, interrupted pointer), `inside` stays stuck true and
+  // the wall freezes forever — so un-stick it whenever the tab hides / the window
+  // loses focus. The next real pointer/enter re-arms it.
+  useResetOnPageHidden(clearPointerInside)
+
+  // ---- manual drag / wheel scroll (opt-in via `dragScroll`) ------------------
+  // Transform-based (no inner scroller → deck-safe): drag/wheel move the
+  // engine's float position directly; `draggingRef` + a short suppress window
+  // pause the auto-marquee during and just after the interaction so it resumes
+  // drifting from where the user left it. Refs declared here (before the engine)
+  // so `isPaused` can read them; the handlers (which need the engine's `wrap`)
+  // are defined after the engine call.
+  const draggingRef = React.useRef(false)
+  const dragSuppressUntilRef = React.useRef(0)
 
   // ---- transform driver ------------------------------------------------------
   const applyTransform = React.useCallback(
@@ -414,6 +441,26 @@ export function MarqueeWall({
     },
     [axis, reverse, trackId],
   )
+  // Sync-aware position writer — THE single entry point for every position
+  // update (the engine's rAF apply AND the manual drag/wheel handlers). With a
+  // `sync` controller it publishes to the shared position and drives every peer
+  // wall's transform; without one it just writes our own. Routing drag/wheel
+  // through here (instead of raw `applyTransform`) keeps a wall that is both
+  // `sync`-ed and `dragScroll`-ed in lockstep with its peers — a direct
+  // `applyTransform` would move only this wall and leave `sync.position` + peers
+  // stale. Members' own `apply` stays the raw `applyTransform` (no re-publish),
+  // so the `forEach` fan-out can't recurse.
+  const applyPos = React.useCallback(
+    (pos: number) => {
+      if (sync) {
+        sync.position = pos
+        sync.members.forEach(m => m.apply(pos))
+      } else {
+        applyTransform(pos)
+      }
+    },
+    [sync, applyTransform],
+  )
   // Clear any residual offset only when the marquee turns off STRUCTURALLY
   // (content shrank so it fits, reduced-motion flipped) — the static wall must
   // sit at its natural origin. A mere run-gate pause (`animate` false) does NOT
@@ -457,18 +504,16 @@ export function MarqueeWall({
     }
   }, [sync, applyTransform])
 
-  const { posRef } = useMarqueeEngine({
+  const { posRef, wrap } = useMarqueeEngine({
     active: marqueeActive && nearViewport && isDriver,
     speed,
-    isPaused: () =>
-      (pauseOnHover && pointerInsideRef.current) || document.visibilityState === 'hidden',
+    isPaused: now =>
+      (pauseOnHover && pointerInsideRef.current) ||
+      draggingRef.current ||
+      now < dragSuppressUntilRef.current ||
+      document.visibilityState === 'hidden',
     getWrapSize: () => wrapSizeRef.current,
-    apply: sync
-      ? pos => {
-          sync.position = pos
-          sync.members.forEach(m => m.apply(pos))
-        }
-      : applyTransform,
+    apply: applyPos,
     // Synced pairs: a re-elected driver resumes from the pair's live position
     // (engine seeds from readBack on activation) instead of restarting at 0.
     readBack: sync ? () => sync.position : undefined,
@@ -490,17 +535,122 @@ export function MarqueeWall({
     }
   }, [marqueeMounted, reverse, posRef])
 
+  // ---- manual drag / wheel handlers (only wired when `dragScroll`) -----------
+  const DRAG_RESUME_MS = 1200
+  const dragStartRef = React.useRef({ coord: 0, pos: 0 })
+  const dragMovedRef = React.useRef(false)
+  const suppressClickRef = React.useRef(false)
+
+  const onDragPointerDown = React.useCallback((e: React.PointerEvent) => {
+    if (!marqueeMounted) return
+    draggingRef.current = true
+    dragMovedRef.current = false
+    // Clear any click-suppress left armed by a prior drag that ended WITHOUT a
+    // synthetic click on this container (pointercancel, or the pointer released
+    // off the wall) — otherwise `onDragClickCapture` would swallow this fresh
+    // tap's action. A new press is unambiguously a new intent.
+    suppressClickRef.current = false
+    dragStartRef.current = { coord: axis === 'y' ? e.clientY : e.clientX, pos: posRef.current }
+    try { containerRef.current?.setPointerCapture(e.pointerId) } catch { /* capture is best-effort */ }
+  }, [marqueeMounted, axis, posRef])
+
+  const onDragPointerMove = React.useCallback((e: React.PointerEvent) => {
+    if (!draggingRef.current) return
+    const delta = (axis === 'y' ? e.clientY : e.clientX) - dragStartRef.current.coord
+    if (Math.abs(delta) > 3) dragMovedRef.current = true
+    // Track follows the pointer. `applyPos` maps pos→translate as `-pos`
+    // (forward) / `pos-wrap` (reverse), so a rightward/downward drag (delta > 0)
+    // must DECREASE pos on a forward wall and INCREASE it on a reverse one.
+    // Via `applyPos` (not raw `applyTransform`) so synced peer walls follow.
+    posRef.current = wrap(dragStartRef.current.pos + (reverse ? delta : -delta))
+    applyPos(posRef.current)
+    dragSuppressUntilRef.current = performance.now() + DRAG_RESUME_MS
+  }, [axis, reverse, wrap, posRef, applyPos])
+
+  const onDragPointerUp = React.useCallback((e: React.PointerEvent) => {
+    if (!draggingRef.current) return
+    draggingRef.current = false
+    // A real drag ends over a chip → swallow the synthetic click so the drag
+    // doesn't fire the chip's action.
+    if (dragMovedRef.current) suppressClickRef.current = true
+    dragSuppressUntilRef.current = performance.now() + DRAG_RESUME_MS
+    try { containerRef.current?.releasePointerCapture(e.pointerId) } catch { /* best-effort */ }
+  }, [])
+
+  const onDragClickCapture = React.useCallback((e: React.MouseEvent) => {
+    if (suppressClickRef.current) {
+      suppressClickRef.current = false
+      e.preventDefault()
+      e.stopPropagation()
+    }
+  }, [])
+
+  // Along-axis wheel → move the wall. Wired as a NATIVE non-passive listener
+  // (not React's `onWheel`, which React attaches passively so `preventDefault`
+  // is a no-op): once WE consume an along-axis wheel we must `preventDefault` to
+  // suppress the browser's horizontal history-swipe (two-finger trackpad) on an
+  // x-wall. An x-wall ignores vertical page-scroll wheels (and vice-versa) so the
+  // surrounding page still scrolls normally.
+  React.useEffect(() => {
+    const el = containerRef.current
+    if (!el || !dragScroll || !marqueeMounted) return
+    const onWheel = (e: WheelEvent) => {
+      // Only claim the DOMINANT-axis wheel (per axis), so a cross-axis wheel
+      // still scrolls the page: an x-wall ignores vertical wheels, a y-wall
+      // ignores horizontal ones.
+      const primary =
+        axis === 'y'
+          ? Math.abs(e.deltaY) >= Math.abs(e.deltaX)
+            ? e.deltaY
+            : 0
+          : Math.abs(e.deltaX) >= Math.abs(e.deltaY)
+            ? e.deltaX
+            : 0
+      if (primary === 0) return
+      e.preventDefault()
+      // Via `applyPos` (not raw `applyTransform`) so synced peer walls follow.
+      posRef.current = wrap(posRef.current + (reverse ? -primary : primary))
+      applyPos(posRef.current)
+      dragSuppressUntilRef.current = performance.now() + DRAG_RESUME_MS
+    }
+    el.addEventListener('wheel', onWheel, { passive: false })
+    return () => el.removeEventListener('wheel', onWheel)
+  }, [dragScroll, marqueeMounted, axis, reverse, wrap, posRef, applyPos])
+
   // ---- render ----------------------------------------------------------------
   const renderContent = (isClone: boolean) =>
     typeof children === 'function' ? children({ isClone }) : children
 
+  // Reduced-motion static fallback: when the marquee does NOT mount (chiefly
+  // prefers-reduced-motion) but the content OVERFLOWS, the drag/transform path
+  // is inert — so on a `dragScroll` wall fall back to NATIVE
+  // overflow scroll along the axis. Otherwise the overflowing chips would be
+  // clipped by `overflow-hidden` with no way to reach them (a11y regression vs
+  // the old wrapping row). The visible thin scrollbar (global `*` rule) is the
+  // right affordance for reduced-motion users. No engine needed — the browser
+  // scrolls the single static track.
+  const staticScrollable = dragScroll && overflows && !marqueeMounted
+
   return (
     <div
       ref={containerRef}
-      className={cn('relative overflow-hidden', className)}
+      className={cn(
+        'relative',
+        staticScrollable ? (axis === 'y' ? 'overflow-y-auto' : 'overflow-x-auto') : 'overflow-hidden',
+        dragScroll && marqueeMounted && 'cursor-grab active:cursor-grabbing select-none',
+        className,
+      )}
+      // x-walls let vertical page-scroll pass (`pan-y`) and own horizontal
+      // drags; y-walls the reverse. Only when drag is actually live.
+      style={dragScroll && marqueeMounted ? { touchAction: axis === 'y' ? 'pan-x' : 'pan-y' } : undefined}
       data-marquee-track={trackId}
       onPointerEnter={onPointerEnter}
       onPointerLeave={onPointerLeave}
+      onPointerDown={dragScroll ? onDragPointerDown : undefined}
+      onPointerMove={dragScroll ? onDragPointerMove : undefined}
+      onPointerUp={dragScroll ? onDragPointerUp : undefined}
+      onPointerCancel={dragScroll ? onDragPointerUp : undefined}
+      onClickCapture={dragScroll ? onDragClickCapture : undefined}
     >
       <div
         ref={trackRef}

package/src/hooks/ui/index.ts

@@ -12,6 +12,7 @@ export * from './use-media-query'
 export * from './use-memoized-callback'
 export * from './use-notification-permission'
 export * from './use-onboarding-state'
+export * from './use-reset-on-page-hidden'
 export * from './use-search'
 export * from './use-suppress-clone-focus'
 export * from './use-table-pagination'

package/src/hooks/ui/use-reset-on-page-hidden.ts

@@ -0,0 +1,32 @@
+import { useEffect } from 'react'
+
+/**
+ * Runs `reset` whenever the tab is hidden or the window loses focus — exactly the
+ * moments a `pointerleave` / `pointercancel` can be SWALLOWED (tab blur, an
+ * overlay mounting under the cursor, an interrupted pointer), which otherwise
+ * leaves a hover/"inside" flag stuck `true` and freezes a marquee FOREVER. The
+ * next real pointer/hover re-arms the flag.
+ *
+ * SSOT self-heal for every marquee surface (MarqueeWall, CardsStrip) so the
+ * blur + `visibilitychange` wiring lives in one place. `reset` almost always
+ * only UN-sticks state. The one edge: on `blur` WITHOUT the tab hiding (a second
+ * window focused beside this one), clearing the hover-pause can let the marquee
+ * resume under a still-stationary cursor in the now-unfocused window — it
+ * re-pauses on the next `pointermove`/`pointerenter`. We keep the `blur` reset
+ * anyway because it's the only signal that catches a tab-blur that swallows the
+ * `pointerleave` without a `visibilitychange`. Pass a STABLE `reset` (memoize
+ * with `useCallback`) — the listeners re-attach whenever its identity changes.
+ */
+export function useResetOnPageHidden(reset: () => void): void {
+  useEffect(() => {
+    const onVisibility = () => {
+      if (document.visibilityState === 'hidden') reset()
+    }
+    window.addEventListener('blur', reset)
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      window.removeEventListener('blur', reset)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [reset])
+}

package/src/hooks/use-near-viewport.ts

@@ -29,19 +29,39 @@
 
 import { useEffect, useRef, useState, useCallback } from 'react';
 
-// Per-rootMargin IO map. Multiple call sites with different margins each
-// get their own singleton observer.
+// Per-(rootMargin, threshold) IO map. Multiple call sites with different
+// margins/thresholds each get their own singleton observer.
 const observers = new Map<string, IntersectionObserver>();
 const subscribers = new WeakMap<Element, () => void>();
 
-function getObserverFor(rootMargin: string): IntersectionObserver {
-  const existing = observers.get(rootMargin);
+// Slack for the explicit ratio check: an element sized to exactly meet the
+// threshold can report a ratio a hair under it (sub-pixel / float rounding), so
+// accept `ratio >= threshold - EPSILON`. With `threshold: 0` this is a no-op
+// (ratio is always ≥ 0 > -EPSILON) — the `isIntersecting` check alone gates.
+const THRESHOLD_EPSILON = 0.01;
+
+/** Stable map key for an observer config. */
+function observerKey(rootMargin: string, threshold: number): string {
+  return `${rootMargin}|${threshold}`;
+}
+
+function getObserverFor(rootMargin: string, threshold: number): IntersectionObserver {
+  const key = observerKey(rootMargin, threshold);
+  const existing = observers.get(key);
   if (existing) return existing;
 
   const io = new IntersectionObserver(
     (entries) => {
       entries.forEach((entry) => {
+        // Enforce the threshold EXPLICITLY. `isIntersecting` is spec-defined as
+        // `intersectionRatio > 0` (any overlap), so the initial `observe()`
+        // firing can report `true` at, say, 20% visible even with
+        // `threshold: 0.5` — which would prematurely pass the gate. Require both
+        // an intersection AND the ratio to actually meet the threshold (minus a
+        // small epsilon for the float rounding where the ratio lands a hair
+        // under the exact value).
         if (!entry.isIntersecting) return;
+        if (entry.intersectionRatio < threshold - THRESHOLD_EPSILON) return;
         // Race-safe: re-read the callback at fire time. A late IO firing
         // after cleanup must not invoke a stale callback.
         const cb = subscribers.get(entry.target);
@@ -52,9 +72,9 @@ function getObserverFor(rootMargin: string): IntersectionObserver {
         }
       });
     },
-    { rootMargin }
+    { rootMargin, threshold }
   );
-  observers.set(rootMargin, io);
+  observers.set(key, io);
   return io;
 }
 
@@ -78,12 +98,16 @@ export interface UseNearViewportResult<T extends Element = HTMLElement> {
  *                   '500px' = element starts mounting 500px before scroll-in.
  *                   '1000px' = a full viewport's worth of lookahead.
  *                   '0px' = strict on-screen detection.
+ * @param threshold  Fraction of the element that must be visible before firing
+ *                   (0 = any pixel — the default; 0.5 = at least half on-screen).
  */
 export function useNearViewport<T extends Element = HTMLElement>(
-  rootMargin: string = NEAR_VIEWPORT_ROOT_MARGIN
+  rootMargin: string = NEAR_VIEWPORT_ROOT_MARGIN,
+  threshold: number = 0
 ): UseNearViewportResult<T> {
   const [isNear, setIsNear] = useState(false);
   const elRef = useRef<T | null>(null);
+  const key = observerKey(rootMargin, threshold);
 
   // Subscribe/unsubscribe on element change.
   const ref = useCallback(
@@ -96,7 +120,7 @@ export function useNearViewport<T extends Element = HTMLElement>(
         const stillOurs = subscribers.get(prev);
         if (stillOurs) {
           subscribers.delete(prev);
-          observers.get(rootMargin)?.unobserve(prev);
+          observers.get(key)?.unobserve(prev);
         }
       }
 
@@ -105,9 +129,9 @@ export function useNearViewport<T extends Element = HTMLElement>(
 
       const cb = () => setIsNear(true);
       subscribers.set(node, cb);
-      getObserverFor(rootMargin).observe(node);
+      getObserverFor(rootMargin, threshold).observe(node);
     },
-    [rootMargin]
+    [key, rootMargin, threshold]
   );
 
   // Unsubscribe on unmount. Identity check guards the StrictMode race.
@@ -117,10 +141,10 @@ export function useNearViewport<T extends Element = HTMLElement>(
       if (!el) return;
       if (subscribers.get(el)) {
         subscribers.delete(el);
-        observers.get(rootMargin)?.unobserve(el);
+        observers.get(key)?.unobserve(el);
       }
     };
-  }, [rootMargin]);
+  }, [key]);
 
   return { ref, isNear };
 }