@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/features/time-tracker/.index.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 6ba79861ed85e1a6c5f821680137cd97 -->
+Public API barrel file for the Time Tracker feature module, re-exporting all components, hooks, context utilities, and TypeScript types from their respective source files.
+
+## Key Components
+
+| Export | Source | Description |
+|---|---|---|
+| `TimeTrackerProvider` | `time-tracker-context` | Context provider for time tracker state |
+| `useTimeTracker` | `time-tracker-context` | Hook to consume time tracker context (throws if missing) |
+| `useOptionalTimeTracker` | `time-tracker-context` | Hook to consume time tracker context (returns `undefined` if missing) |
+| `TimeTrackerPanel` | `time-tracker-panel` | UI panel component for the tracker interface |
+| `TimeTrackerHeaderButton` | `time-tracker-header-button` | Header button component to open/control the tracker |
+| `useTrackerClock` | `use-tracker-clock` | Hook managing the running clock/tick logic |
+
+## Types
+
+- `TimeTrackerProviderProps`, `TimeTrackerPanelProps`, `TimeTrackerHeaderButtonProps`, `UseTrackerClockArgs` — component and hook prop shapes
+- `TimeTrackerStatus`, `TimeTrackerEntry`, `TimeTrackerData` — core tracker state types
+- `TimeTrackerTicketOption`, `TimeTrackerCustomerOption` — dropdown option types for ticket and customer selectors
+
+## Usage Example
+
+```typescript
+import {
+  TimeTrackerProvider,
+  TimeTrackerPanel,
+  TimeTrackerHeaderButton,
+  useTimeTracker,
+} from '@openframe-oss-lib/time-tracker'
+
+function App() {
+  return (
+    <TimeTrackerProvider>
+      <TimeTrackerHeaderButton />
+      <TimeTrackerPanel />
+    </TimeTrackerProvider>
+  )
+}
+
+function TrackerStatus() {
+  const tracker = useTimeTracker()
+  return <span>Status: {tracker.status}</span>
+}
+```
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/time-tracker/index.ts)

package/src/components/features/time-tracker/.time-tracker-context.md

@@ -0,0 +1,55 @@
+<!-- source-hash: de71ebaf1faea406a5249b912fbf10b9 -->
+React context module that provides time tracker state and panel visibility controls to the component tree.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `TimeTrackerProvider` | Component | Context provider wrapping the time tracker feature; accepts `TimeTrackerData` props plus optional `defaultOpen` |
+| `useTimeTracker` | Hook | Consumes context and throws if called outside a provider |
+| `useOptionalTimeTracker` | Hook | Consumes context and returns `null` if no provider is present |
+| `TimeTrackerProviderProps` | Interface | Props for the provider: `TimeTrackerData` fields, `children`, and `defaultOpen` |
+| `TimeTrackerContextValue` | Interface (internal) | Extends `TimeTrackerData` with `isOpen`, `open`, `close`, and `toggle` |
+
+## Usage Example
+
+```typescript
+// Wrap your feature tree with the provider
+import { TimeTrackerProvider, useTimeTracker } from './time-tracker-context'
+
+function App() {
+  const data: TimeTrackerData = { /* ...tracker fields */ }
+
+  return (
+    <TimeTrackerProvider {...data} defaultOpen={false}>
+      <TrackerPanel />
+    </TimeTrackerProvider>
+  )
+}
+
+// Consume in any child component
+function TrackerPanel() {
+  const { isOpen, open, close, toggle } = useTimeTracker()
+
+  return (
+    <div>
+      <button onClick={toggle}>
+        {isOpen ? 'Hide Tracker' : 'Show Tracker'}
+      </button>
+      {isOpen && <TrackerContent />}
+    </div>
+  )
+}
+
+// Safe consumption where the provider may be absent
+function MaybeTracker() {
+  const tracker = useOptionalTimeTracker()
+  if (!tracker) return null
+  return <span>{tracker.isOpen ? 'Tracking…' : 'Idle'}</span>
+}
+```
+
+## Notes
+
+- The per-second clock tick is intentionally kept in a separate `useTrackerClock` hook rather than in context, preventing global re-renders on every tick.
+- `data` spreads from the host's render, so context value identity updates only when the parent re-renders — not on timer ticks.

package/src/components/features/time-tracker/.time-tracker-header-button.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 33a141db20f759f37da3df0e0eb5aa99 -->
+A client-side React component that renders a time-tracking affordance in the application header, integrating a Radix UI Popover with live elapsed time display and AppLayout drawer coordination.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `TimeTrackerHeaderButton` | Component | Main header button with popover panel for time tracking |
+| `TimeTrackerHeaderButtonProps` | Interface | Props: `className` and `disabled` passthrough |
+
+**Internal dependencies:**
+
+- `useOptionalTimeTracker` — Reads tracker context; returns `null` if no `<TimeTrackerProvider>` is present (component renders nothing)
+- `useTrackerClock` — Provides live elapsed time label while a session is running
+- `useAppLayoutDrawerCoordination` — Coordinates mutual exclusion with other in-layout drawers/panels
+- `useAppLayoutDrawerContainer` — Resolves the portal target for the backdrop overlay
+
+## Behavior Notes
+
+- **No provider → no render:** If `TimeTrackerContext` is absent, the component returns `null`
+- **Live clock:** While tracking, the elapsed time renders inline in the `HeaderButton` trigger
+- **Visual states:** Icon color shifts to `ods-accent` (tracking) or `ods-text-secondary` (paused)
+- **Backdrop scoping:** Inside `AppLayout`, the dim overlay is portaled into the main-content container so header and sidebar remain interactive; outside `AppLayout` it falls back to a full-viewport overlay
+- **Drawer coordination:** Registers a stable `AppLayoutDrawerHandle` so opening the time tracker closes other panels and vice versa
+
+## Usage Example
+
+```typescript
+// Wrap your app with TimeTrackerProvider, then drop the button into your header
+import { TimeTrackerProvider } from './time-tracker-context'
+import { TimeTrackerHeaderButton } from './time-tracker-header-button'
+
+function AppHeader() {
+  return (
+    <TimeTrackerProvider>
+      <header>
+        <TimeTrackerHeaderButton />
+      </header>
+    </TimeTrackerProvider>
+  )
+}
+
+// Outside a provider, the component renders nothing — safe to include unconditionally
+function MinimalHeader() {
+  return (
+    <header>
+      <TimeTrackerHeaderButton disabled={false} />
+    </header>
+  )
+}
+```

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

@@ -0,0 +1,58 @@
+<!-- source-hash: f9c7f4b630216f5355a492cdd085052d -->
+A floating time-tracking panel component that renders a real-time timer, ticket/customer assignment fields, notes input, and a recent-entries list for MSP technicians to log billable time.
+
+## Key Components
+
+### `TimeTrackerPanel` (main export)
+The primary panel component consuming all `TimeTrackerData` props plus `onClose` and optional `className`. Handles:
+- **Timer controls** – start, pause, resume, and finish/save actions driven by `status` (`ready | tracking | paused`)
+- **Live clock** – formatted elapsed time via the `useTrackerClock` hook
+- **Ticket & customer selection** – searchable `Autocomplete` fields with server-side filtering support
+- **Notes textarea** – optional when a ticket is selected; required otherwise
+- **Validation** – inline field errors shown only after a submit attempt, reset when status returns to `ready`
+- **Last entries list** – up to 3 recent `TimeTrackerEntry` rows; empty state shown when none exist
+- **Footer actions** – Manual Entry button and a `SplitButton` to open "My Time"
+
+### `StatusTag` (internal)
+Renders a styled `Tag` reflecting current tracker status: `tracking` (success + animated loader), `paused` (warning + pause icon), or `ready` (grey).
+
+### `LastEntryRow` (internal)
+Displays a single time entry row with duration, date, title, and optional description.
+
+## Usage Example
+
+```typescript
+import { TimeTrackerPanel } from '@openframe/ui'
+
+<TimeTrackerPanel
+  status="ready"
+  runningSince={null}
+  accumulatedMs={0}
+  ticketOptions={[{ id: 'T-1', label: 'Ticket #1' }]}
+  selectedTicketId={null}
+  onSelectedTicketChange={(id) => setTicket(id)}
+  onTicketSearch={(q) => fetchTickets(q)}
+  ticketsLoading={false}
+  customerOptions={[{ id: 'C-1', label: 'Acme Corp', imageUrl: '/acme.png' }]}
+  selectedCustomerId={null}
+  onSelectedCustomerChange={(id) => setCustomer(id)}
+  onCustomerSearch={(q) => fetchCustomers(q)}
+  customersLoading={false}
+  customerLocked={false}
+  notes=""
+  onNotesChange={setNotes}
+  lastEntries={[]}
+  onStart={startTimer}
+  onPause={pauseTimer}
+  onResume={resumeTimer}
+  onCancel={cancelTimer}
+  onSubmit={submitEntry}
+  isStarting={false}
+  isSubmitting={false}
+  onClose={() => setOpen(false)}
+/>
+```
+
+## Source
+
+[`time-tracker-panel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/time-tracker-panel.tsx)

package/src/components/features/time-tracker/.types.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 3997f1f6adad59896ed8ceba4767a157 -->
+Defines the complete TypeScript contract for the OpenFrame time tracker UI component, including status states, option shapes, entry records, and the full host-provided data interface.
+
+## Key Components
+
+| Export | Kind | Description |
+|---|---|---|
+| `TimeTrackerStatus` | Type | Union of tracker states: `'ready'`, `'tracking'`, `'paused'` |
+| `TimeTrackerTicketOption` | Interface | `id` + `label` pair for ticket autocomplete options |
+| `TimeTrackerCustomerOption` | Interface | `id` + `label` + optional `imageUrl` for customer autocomplete |
+| `TimeTrackerEntry` | Interface | A previous session record with pre-formatted `durationLabel` and `dateLabel` |
+| `TimeTrackerData` | Interface | The complete prop contract fed by the host into the UI component |
+
+### `TimeTrackerData` Notable Fields
+
+- **`status` / `runningSince` / `accumulatedMs`** — Drives the live timer; UI ticks locally from `runningSince`, backend stays source of truth
+- **`ticketOptions` / `selectedTicketId` / `onTicketSearch`** — Ticket autocomplete wiring (host handles search)
+- **`customerOptions` / `onSelectedCustomerChange`** — Optional customer panel; rendered only when `onSelectedCustomerChange` is provided
+- **`customerLocked`** — Prevents customer edits when derived from the selected ticket
+- **`lastEntries`** — Up to three recent sessions displayed in the panel
+- **`isStarting` / `isSubmitting`** — Loading guards for async host actions
+
+## Usage Example
+
+```typescript
+const data: TimeTrackerData = {
+  status: 'ready',
+  accumulatedMs: 0,
+  ticketOptions: [{ id: 'TKT-42', label: '#42 – Replace firewall' }],
+  selectedTicketId: null,
+  onSelectedTicketChange: (id) => dispatch(selectTicket(id)),
+  onTicketSearch: (query) => dispatch(searchTickets(query)),
+  customerOptions: [{ id: 'cust-1', label: 'Acme Corp', imageUrl: 'https://cdn.example.com/acme.png' }],
+  selectedCustomerId: null,
+  onSelectedCustomerChange: (id) => dispatch(selectCustomer(id)),
+  notes: '',
+  onNotesChange: (value) => dispatch(setNotes(value)),
+  lastEntries: [
+    { id: 'e1', durationLabel: '00:08:17', dateLabel: '07/12/25', title: 'Network audit' },
+  ],
+  onStart: () => dispatch(startTimer()),
+  onPause: () => dispatch(pauseTimer()),
+  onResume: () => dispatch(resumeTimer()),
+  onCancel: () => dispatch(cancelTimer()),
+  onSubmit: () => dispatch(submitTimer()),
+};
+```
+
+## Source
+
+[`types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/types.ts)

package/src/components/features/time-tracker/.use-tracker-clock.md

@@ -0,0 +1,32 @@
+<!-- source-hash: 348c9778f1a385757c49446a815eb860 -->
+Display-only React hook that ticks a `HH:MM:SS` clock once per second while time tracking is active, and shows a static elapsed time otherwise.
+
+## Key Components
+
+- **`useTrackerClock`** — Main hook. Returns a formatted `HH:MM:SS` string derived from `accumulatedMs` plus live elapsed time since `runningSince`. The interval runs only when `status === 'tracking'`; it clears automatically on pause/stop or unmount.
+- **`formatElapsed`** — Internal utility. Converts a total millisecond value to a zero-padded `HH:MM:SS` string, clamping negative values to `0`.
+- **`UseTrackerClockArgs`** — Input interface describing the tracker state needed to drive the clock.
+
+## Usage Example
+
+```typescript
+import { useTrackerClock } from './use-tracker-clock'
+
+function TimerDisplay({ entry }) {
+  const elapsed = useTrackerClock({
+    status: entry.status,           // 'tracking' | 'paused' | 'stopped'
+    runningSince: entry.startedAt,  // epoch ms when current segment began
+    accumulatedMs: entry.totalMs,   // ms logged before current segment
+  })
+
+  return <span>{elapsed}</span> // e.g. "01:23:45"
+}
+```
+
+## Notes
+
+- `runningSince` is only meaningful when `status === 'tracking'`; passing it in other states has no effect.
+- The interval resets whenever `status` or `runningSince` changes, preventing drift when a session is paused and resumed.
+- `accumulatedMs` defaults to `0`, so the hook works for brand-new sessions with no prior logged time.
+
+**Source:** [`use-tracker-clock.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-tracker-clock.ts)

package/src/components/features/use-walkthrough-video.ts

@@ -0,0 +1,70 @@
+"use client";
+
+/**
+ * useWalkthroughVideo — client read hook for the per-platform walkthrough video.
+ *
+ * SSOT for fetching + shaping the widget's data on the CLIENT (any embedder
+ * reuses it). The public endpoint returns the RAW body `{ walkthroughVideo }`
+ * (no {success,data} wrapper). The video's `captionsUrl` is a RELATIVE
+ * `/api/captions/...` path; pass `transformCaptionsUrl` to route it through a
+ * proxy (embedders) — omit it for same-origin hosts.
+ *
+ * SSR hosts (the hub) resolve the video server-side and pass it to the widget
+ * directly; they don't need this hook. It exists for client-only embedders.
+ */
+
+import { useQuery } from '@tanstack/react-query';
+import type { WalkthroughVideoData } from './floating-walkthrough-video';
+
+export interface UseWalkthroughVideoOptions {
+  /** Absolute or proxied URL of the public GET route. */
+  endpoint: string;
+  /** SSR/initial seed to avoid a loading flash. */
+  initialData?: WalkthroughVideoData | null;
+  enabled?: boolean;
+  /** Rewrite the RELATIVE captionsUrl (e.g. prefix a `/content` proxy base). */
+  transformCaptionsUrl?: (relativeUrl: string) => string;
+}
+
+export interface UseWalkthroughVideoResult {
+  video: WalkthroughVideoData | null;
+  isLoading: boolean;
+}
+
+export function useWalkthroughVideo(opts: UseWalkthroughVideoOptions): UseWalkthroughVideoResult {
+  const { endpoint, initialData, enabled = true, transformCaptionsUrl } = opts;
+
+  const query = useQuery<WalkthroughVideoData | null>({
+    queryKey: ['walkthrough-video', endpoint],
+    enabled,
+    initialData: initialData ?? undefined,
+    // `null` is a legitimate cached VALUE to React Query, so an embedder
+    // passing `initialData={null}` to mean "no seed" got status:'success' and
+    // no fetch for the whole staleTime window. Treat null as absent.
+    staleTime: 5 * 60 * 1000,
+    // Returns the RAW video, cached under the endpoint key. A real HTTP
+    // failure THROWS so React Query retries and surfaces isError, instead of
+    // caching a fake "no video" for the whole stale window. The hub route
+    // answers "no walkthrough for this platform" as 200 + null, not 404; the
+    // 404 arm is kept for embedders whose proxy 404s a missing resource.
+    queryFn: async () => {
+      const res = await fetch(endpoint);
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`Walkthrough video request failed (${res.status})`);
+      const body = (await res.json()) as { walkthroughVideo: WalkthroughVideoData | null };
+      return body?.walkthroughVideo ?? null;
+    },
+    // Per-observer transform — NEVER mutate the cached data. `select` also runs
+    // over `initialData`, so the SSR seed is rewritten too. Keeping the proxy
+    // rewrite here (not in queryFn) means a second consumer of the same
+    // endpoint can't inherit this observer's proxied captionsUrl from the cache.
+    select: (video) => {
+      if (video?.captionsUrl && transformCaptionsUrl && video.captionsUrl.startsWith('/')) {
+        return { ...video, captionsUrl: transformCaptionsUrl(video.captionsUrl) };
+      }
+      return video;
+    },
+  });
+
+  return { video: query.data ?? null, isLoading: query.isLoading };
+}

package/src/components/features/video-bites-strip.tsx

@@ -25,12 +25,11 @@
  * starts only on hover (`<Video playOnHover>` — sound at 50%, muted fallback).
  */
 
-import React, { useMemo, useRef, useState, useEffect } from 'react';
+import React, { useMemo, useState } from 'react';
 import { cn } from '../../utils/cn';
-import { Video } from './video';
 import { useVideoWarmup } from './use-video-warmup';
-import { toMuxPreviewUrl } from './mux-origins';
-import { NEAR_VIEWPORT_ROOT_MARGIN } from '../../hooks/use-near-viewport';
+import { VideoHoverPreviewSurface } from './video-hover-preview';
+import { CardHitLayer } from './card-hit-layer';
 import { detectAspectRatio, RATIO_TO_CSS_ASPECT, ratioToCategory } from './video-ratio-tabs';
 import type { VideoTeaserWithRatio } from './video-ratio-tabs';
 import {
@@ -38,12 +37,9 @@ import {
   sortBitesByCreatedAtDesc,
   type VideoBiteStripProfile,
 } from './video-bites-shared';
-import Image from '../../embed-shims/next-image';
 import { CardsStrip, STRIP_CELL_MAX_WIDTH } from './cards-strip';
-import { useCoverImageFallback } from '../chat/entity-cards/use-cover-image-fallback';
 import { UserDisplay } from '../user-display';
 import { Chevron02RightIcon } from '../icons-v2-generated/arrows/chevron-02-right-icon';
-import { VideoPlayBadge } from './video-center-badge';
 
 // NOTE: the title constant / profile adapter / sort comparator live in the
 // server-safe leaf `video-bites-shared.ts` (its own published subpath). The
@@ -229,16 +225,9 @@ export function VideoBiteCard({
   const cssAspect = RATIO_TO_CSS_ASPECT[ratioToCategory(detectAspectRatio(bite.aspect_ratio))];
   const targetHref = bite.href ?? sectionHref;
   const hasTarget = !!(targetHref || bite.onNavigate || onBiteNavigate);
-  // Strip keys and navigation stay on the RAW bite.url — only playback gets
-  // the rendition-capped preview URL below, so keys are stable regardless of
-  // the cap and original + clone share one HTTP cache entry per URL.
+  // Strip keys and navigation stay on the RAW bite.url — the surface applies
+  // the rendition cap internally, so keys are stable regardless of the cap.
   const key = cardKey ?? `${bite.url}__${index}`;
-  // Rendition-capped playback URL for this ~234px preview card: public Mux
-  // HLS manifests get `?max_resolution=720p` (the only Safari-side cap —
-  // native HLS ignores hls.js's player-size capping); everything else passes
-  // through unchanged. Used by BOTH the first-frame facade and the hover
-  // player so the two layers share the manifest fetch.
-  const previewUrl = toMuxPreviewUrl(bite.url);
 
   // Hover activation: controlled by the strip (activeKey) or self-managed
   // when rendered standalone (admin editor).
@@ -248,42 +237,6 @@ export function VideoBiteCard({
   const activate = () => (controlled ? onActivate?.(key) : setSelfActive(true));
   const deactivate = () => (controlled ? onDeactivate?.(key) : setSelfActive(false));
 
-  // Player mount: controlled (strip's shared-by-index gate) or an internal
-  // TWO-WAY near-viewport observer (standalone). Two-way — NOT the fire-once
-  // `useNearViewport` — so players unmount again >500px away and live
-  // MuxPlayer instances stay bounded.
-  const gateControlled = playerMounted !== undefined;
-  const rootElRef = useRef<HTMLDivElement | null>(null);
-  const [isNear, setIsNear] = useState(false);
-  useEffect(() => {
-    if (gateControlled) return;
-    const el = rootElRef.current;
-    if (!el || typeof IntersectionObserver === 'undefined') return;
-    const io = new IntersectionObserver(
-      entries => setIsNear(entries[0]?.isIntersecting ?? false),
-      { rootMargin: NEAR_VIEWPORT_ROOT_MARGIN },
-    );
-    io.observe(el);
-    return () => io.disconnect();
-  }, [gateControlled]);
-  const showMedia = gateControlled ? playerMounted : isNear;
-
-  // Player mounts at NEAR-VIEWPORT (not on first hover) so hover playback is
-  // INSTANT for any card the user can reach — mounting on activation made
-  // freshly-scrolled cards stall for seconds while MuxPlayer initialized and
-  // buffered. Always-mounted players are visually safe now that every bite
-  // carries a poster: the player renders with a transparent media background
-  // over the card's poster layer, so a not-yet-decoded player never shows as
-  // a black rectangle (the original wrap-seam flash came from POSTERLESS
-  // mounted players, not from mounting itself).
-  const showPlayer = showMedia;
-
-  // Poster resolution — THE shared entity-card cover fallback chain
-  // (use-cover-image-fallback): the bite's real thumbnail_url, dropped on
-  // load error. When it resolves to null (no thumbnail yet, or it failed)
-  // the media zone falls back to the first-frame <video> facade below.
-  const { src: posterSrc, onError: onPosterError } = useCoverImageFallback(bite.thumbnail_url);
-
   const navigate = () => {
     if (bite.onNavigate) bite.onNavigate();
     else onBiteNavigate?.(bite, index);
@@ -362,9 +315,22 @@ export function VideoBiteCard({
     isActive ? 'opacity-100' : 'opacity-0 group-hover/card:opacity-100 group-focus-within/card:opacity-100',
     // Non-interactive while invisible so it never swallows clicks on the
     // resting card / player controls.
-    isActive ? 'pointer-events-auto' : 'pointer-events-none group-hover/card:pointer-events-auto group-focus-within/card:pointer-events-auto',
+    isActive ? 'pointer-events-auto' : 'pointer-events-none',
   );
 
+  // Full-card click target (above the visual overlay (z-[5] vs its auto), below the surface's own z-10 children (play badge, unmute button) which must stay clickable). Mirrors
+  // the walkthrough card: a hit layer owns the click, the overlay owns the look.
+  // ALWAYS interactive. The old overlay was hover-gated because it was a
+  // visible panel that would otherwise swallow clicks while invisible; a
+  // contentless hit layer has no such problem, and gating it meant the media
+  // element received the pointer instead — so a resting card showed `cursor:
+  // auto` over the play glyph even though the glyph accented on hover.
+  // Touch keeps the deliberate two-tap model (tap 1 previews, tap 2 opens), so
+  // the layer stays inert until the card is active — making it unconditionally
+  // clickable meant a phone tap navigated instantly and bites could no longer
+  // be previewed on mobile. Mouse/keyboard get it immediately.
+  const hitLayerClass = cn('z-[5]', isTouch && !isActive ? 'pointer-events-none' : 'pointer-events-auto');
+
   const media = (
     <div
       className="relative w-full"
@@ -372,96 +338,33 @@ export function VideoBiteCard({
       // same as the old single-box layout). Editor mode: width-driven.
       style={{ aspectRatio: cssAspect, ...(height !== undefined ? { height, maxWidth: STRIP_CELL_MAX_WIDTH } : {}) }}
     >
-      {showMedia ? (
-        // Clones: `inert` (not just the wrapper's aria-hidden) — the player's
-        // shadow-DOM center control is otherwise still tab-reachable inside a
-        // hidden subtree (axe aria-hidden-focus). Hover preview on clones
-        // keeps working: playback is driven imperatively from the CARD's own
-        // pointer handlers, never from focus/clicks on the player chrome.
-        <div className="absolute inset-0" inert={isClone || undefined}>
-          {/* Poster layer. Preferred: the bite's REAL thumbnail (generated at
-              Vizard-ingestion time by vizard-persistence-utils via Shotstack
-              capture — the provider sends no cover), resolved through the
-              shared cover fallback chain. Fallback when it's absent or fails
-              to load: the <Video> component's `firstFrameOnly` facade paints
-              the `#t=0.1` frame. Either way the box is never a black
-              rectangle, and original + clone paint the IDENTICAL image so the
-              marquee's wrap seam stays pixel-invisible. */}
-          {posterSrc ? (
-            <Image
-              src={posterSrc}
-              alt=""
-              fill
-              // Bite cards are portrait 9:16 at ~234px wide (Figma: 416px tall).
-              // Without `sizes`, `fill` makes the Supabase-optimizing <Image>
-              // assume a full-viewport width and request a ~2500px render for a
-              // 234px slot. Pin it to the card width so the render endpoint
-              // returns a ~2x-retina image instead of the near-full-res poster.
-              sizes="234px"
-              unoptimized
-              onError={onPosterError}
-              className="object-cover"
-            />
-          ) : (
-            <Video kind="file" url={previewUrl} firstFrameOnly layout="fill" />
-          )}
-
-          {/* Play affordance for every non-playing state (resting poster,
-              facade, mounted-but-paused): <VideoPlayBadge> — a pixel replica
-              of MuxPlayer's pre-play center button (media-chrome's own PAUSED
-              center control is a different, smaller bare glyph, so the
-              mounted player runs chromeless and the replica keeps all states
-              identical to the mux button). Hidden while playing. */}
-          {!isActive && <VideoPlayBadge className="absolute inset-0 z-10 m-auto" />}
-          {showPlayer && (
-            // `--media-background-color: transparent` (inherited into
-            // media-chrome) — the freshly-mounted player must not blank the
-            // facade behind it with its default black fill while it loads.
-            <div
-              className="absolute inset-0"
-              style={{ '--media-background-color': 'transparent' } as React.CSSProperties}
-            >
-              {/* CONTROLLED hover playback keyed to CARD hover (`isActive`): the
-                  detail overlay is part of the card, so moving the pointer onto
-                  it keeps playing. Sound at 50% (pre-activation: muted start +
-                  live unmute on the user's first gesture); CHROMELESS — the
-                  card's mux-replica badge above is the play affordance for
-                  every non-playing state.
-
-                  INVARIANTS (do not regress):
-                  - No explicit `preload` — the SSOT default ('metadata',
-                    'none' under Save-Data) buffers manifest + ~1 segment on
-                    mount, which is exactly what makes hover start instant.
-                  - The poster <Image> layer above stays mounted UNDER this
-                    player permanently, and play() is imperative — never gated
-                    on poster load — so there is no black flash and no
-                    loading state between hover and first frame. */}
-              <Video
-                kind="file"
-                url={previewUrl}
-                poster={bite.thumbnail_url}
-                playWhenHovered={isActive}
-                chromeless
-                layout="fill"
-              />
-            </div>
-          )}
-        </div>
-      ) : (
-        // Aspect-matched placeholder until the card nears the viewport (CLS-free).
-        <div className="absolute inset-0 bg-ods-card" />
-      )}
+      {/* THE shared hover-preview media zone (poster → facade → badge →
+          controlled hover playback + near-viewport mount gate). The bite strip
+          keeps the internal unmute badge (no overlaying activation button). */}
+      <VideoHoverPreviewSurface
+        url={bite.url}
+        posterUrl={bite.thumbnail_url}
+        active={isActive}
+        playerMounted={playerMounted}
+        isClone={isClone}
+      />
 
-      {hasTarget && !isClone && !titleEditable ? (
-        targetHref ? (
-          <a href={targetHref} aria-label={`Open ${bite.title || 'source content'}`} className={overlayClass}>
-            {overlayContent}
-          </a>
-        ) : (
-          <button type="button" onClick={navigate} aria-label={`Open ${bite.title || 'source content'}`} className={cn(overlayClass, 'text-left w-full')}>
-            {overlayContent}
-          </button>
-        )
+      {hasTarget && !titleEditable ? (
+        // CONTENTLESS full-bleed hit layer + a purely visual overlay — the same
+        // grammar the walkthrough card uses. Previously the anchor/button WAS
+        // the bottom strip, so the card centre (where the play glyph sits) was
+        // not clickable and showed no pointer cursor even though the glyph
+        // accented on hover. One interactive element, no a11y duplication.
+        <>
+          <CardHitLayer
+            label={`Open ${bite.title || 'source content'}`}
+            href={targetHref || undefined}
+            onClick={targetHref ? undefined : navigate}
+            className={hitLayerClass}
+            decorative={isClone}
+          />
+          <div className={cn(overlayClass, 'pointer-events-none')}>{overlayContent}</div>
+        </>
       ) : (
         <div className={overlayClass}>{overlayContent}</div>
       )}
@@ -470,10 +373,7 @@ export function VideoBiteCard({
 
   return (
     <div
-      ref={node => {
-        rootElRef.current = node;
-        return rootRef?.(node);
-      }}
+      ref={node => rootRef?.(node)}
       aria-hidden={isClone || undefined}
       // Hit-test marker for the strip engine's pointer-tracked hover re-sync
       // (cards move under a stationary pointer — see cards-strip.tsx). The

package/src/components/features/video-center-badge.tsx

@@ -49,7 +49,16 @@ export interface VideoPlayBadgeProps {
 export function VideoPlayBadge({ size = 'md', className }: VideoPlayBadgeProps): React.ReactElement {
   return (
     <div
-      className={cn('pointer-events-none flex items-center justify-center text-ods-text-primary transition-colors', className)}
+      className={cn(
+        'pointer-events-none flex items-center justify-center text-ods-text-primary transition-colors',
+        // Accent on card hover. These glyphs are pointer-events-none by design,
+        // so they can never resolve their own :hover — they key off the host
+        // card's `group/card` marker. Living HERE (not at each call site) is
+        // what makes bites, the walkthrough card and every future surface
+        // behave identically from one definition.
+        'group-hover/card:text-ods-accent',
+        className,
+      )}
       style={{ filter: GLYPH_SHADOW }}
     >
       <PlayFilledIcon size={SIZES[size]} color="currentColor" />
@@ -70,7 +79,7 @@ export function VideoUnmuteGlyph({ size = 'md', className }: VideoUnmuteGlyphPro
     <VolumeOffFilledIcon
       size={SIZES[size]}
       color="currentColor"
-      className={className}
+      className={cn('transition-colors group-hover/card:text-ods-accent', className)}
       style={{ filter: GLYPH_SHADOW }}
     />
   )