@djangocfg/ui-tools 2.1.431 → 2.1.433

package/src/tools/media/Gallery/components/lightbox/GalleryLightbox.tsx

@@ -12,6 +12,14 @@ import { GalleryMedia } from '../media'
 import { GalleryThumbnails } from '../thumbnails'
 import type { GalleryLightboxProps } from '../../types'
 
+// Liquid-glass control — token-driven (--card / --foreground), so it stays
+// legible on BOTH the light scrim and the dark vibrancy backdrop. Foreground
+// icon color flips with the theme; hover wash adapts via the foreground token.
+const GLASS_BTN =
+  'glass-liquid text-foreground/80 transition-colors ' +
+  'hover:text-foreground hover:bg-[color-mix(in_oklab,var(--foreground)_12%,transparent)] ' +
+  'focus:outline-none focus-visible:ring-2 focus-visible:ring-ring'
+
 /**
  * GalleryLightbox - Fullscreen image viewer with zoom and navigation
  *
@@ -241,11 +249,16 @@ export const GalleryLightbox = memo(function GalleryLightbox({
       ref={dialogRef}
       className={cn(
         'fixed inset-0 z-50',
-        'backdrop-blur-sm',
+        // Theme-aware Quick-Look scrim: a LIGHT neutral wash in light mode so
+        // the lightbox feels native (Quick Look matches system appearance),
+        // a deep vibrancy floor in dark mode. blur+saturate in both so the
+        // page behind bleeds through softly and the image floats.
+        'backdrop-blur-2xl backdrop-saturate-150',
+        '[background-color:color-mix(in_oklab,var(--background)_72%,transparent)]',
+        'dark:[background-color:color-mix(in_oklab,#000_82%,transparent)]',
         'animate-in fade-in-0 duration-200',
         'focus:outline-none'
       )}
-      style={{ backgroundColor: 'rgba(0, 0, 0, 0.85)' }}
       role="dialog"
       aria-modal="true"
       aria-label={title || labels.lightbox}
@@ -258,22 +271,28 @@ export const GalleryLightbox = memo(function GalleryLightbox({
       >
         {/* Header */}
         <div className="absolute top-0 left-0 right-0 z-10 flex items-center justify-between p-4">
-          {/* Title & Counter */}
-          <div className="text-white">
-            {title && <div className="font-medium">{title}</div>}
-            {hasMultiple && (
-              <div className="text-sm text-white/70" aria-live="polite">
-                {currentIndex + 1} / {images.length}
-              </div>
-            )}
-          </div>
+          {/* Title & Counter — liquid-glass pill so it reads on both the light
+              and dark scrim (glass-liquid is token-driven, foreground text
+              flips with the theme). */}
+          {(title || hasMultiple) ? (
+            <div className="glass-liquid rounded-2xl px-3 py-1.5 text-foreground">
+              {title && <div className="font-medium">{title}</div>}
+              {hasMultiple && (
+                <div className="text-sm text-foreground/70" aria-live="polite">
+                  {currentIndex + 1} / {images.length}
+                </div>
+              )}
+            </div>
+          ) : (
+            <span aria-hidden />
+          )}
 
           {/* Actions */}
           <div className="flex items-center gap-2">
             {enableZoom && !isVideo && (
               <button
                 type="button"
-                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-white"
+                className={cn(GLASS_BTN, 'p-2 rounded-full')}
                 onClick={handleToggleZoom}
                 aria-label={isZoomed ? labels.zoomOut : labels.zoomIn}
               >
@@ -288,7 +307,7 @@ export const GalleryLightbox = memo(function GalleryLightbox({
             {enableDownload && (
               <button
                 type="button"
-                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-white"
+                className={cn(GLASS_BTN, 'p-2 rounded-full')}
                 onClick={handleDownload}
                 aria-label={labels.download}
               >
@@ -299,7 +318,7 @@ export const GalleryLightbox = memo(function GalleryLightbox({
             {enableShare && (
               <button
                 type="button"
-                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-white"
+                className={cn(GLASS_BTN, 'p-2 rounded-full')}
                 onClick={handleShare}
                 aria-label={labels.share}
               >
@@ -309,7 +328,7 @@ export const GalleryLightbox = memo(function GalleryLightbox({
 
             <button
               type="button"
-              className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-white"
+              className={cn(GLASS_BTN, 'p-2 rounded-full')}
               onClick={onClose}
               aria-label={labels.close}
             >
@@ -360,11 +379,10 @@ export const GalleryLightbox = memo(function GalleryLightbox({
             <button
               type="button"
               className={cn(
+                GLASS_BTN,
                 'absolute left-4 top-1/2 -translate-y-1/2 z-10',
                 'w-12 h-12 rounded-full',
-                'bg-white/10 hover:bg-white/20 text-white',
-                'flex items-center justify-center transition-colors',
-                'focus:outline-none focus-visible:ring-2 focus-visible:ring-white'
+                'flex items-center justify-center'
               )}
               onClick={goToPrev}
               aria-label={labels.previous}
@@ -375,11 +393,10 @@ export const GalleryLightbox = memo(function GalleryLightbox({
             <button
               type="button"
               className={cn(
+                GLASS_BTN,
                 'absolute right-4 top-1/2 -translate-y-1/2 z-10',
                 'w-12 h-12 rounded-full',
-                'bg-white/10 hover:bg-white/20 text-white',
-                'flex items-center justify-center transition-colors',
-                'focus:outline-none focus-visible:ring-2 focus-visible:ring-white'
+                'flex items-center justify-center'
               )}
               onClick={goToNext}
               aria-label={labels.next}
@@ -391,7 +408,7 @@ export const GalleryLightbox = memo(function GalleryLightbox({
 
         {/* Thumbnails */}
         {showThumbnails && hasMultiple && !isZoomed && (
-          <div className="absolute bottom-0 left-0 right-0 p-4 bg-gradient-to-t from-black/50 to-transparent">
+          <div className="absolute bottom-0 left-0 right-0 p-4 bg-gradient-to-t from-white/40 dark:from-black/50 to-transparent">
             <GalleryThumbnails
               images={images}
               currentIndex={currentIndex}

package/src/tools/media/ImageViewer/README.md

@@ -139,6 +139,15 @@ Click the expand button to open in a fullscreen dialog. Gallery navigation works
 </Dialog>
 ```
 
+## Used as the chat attachment lightbox
+
+The [Chat tool](../../chat/README.md) uses `LazyImageViewer` as the **default**
+lightbox for image attachments. When a host wires no `onAttachmentOpen` /
+`onClick`, clicking an image attachment opens this viewer in a dialog
+(`inDialog`), seeded with all of that message's image attachments so prev/next
+gallery navigation works across them, opened at the clicked `initialIndex`. See
+`chat/messages/Attachments.tsx` (`ImageLightboxProvider`).
+
 ## Styling
 
 The component fills its container. Wrap in a sized element:

package/src/tools/media/ImageViewer/components/ImageViewer.tsx

@@ -3,14 +3,21 @@
 /**
  * ImageViewer - Image viewer with zoom, pan, rotate, flip, gallery navigation
  *
- * Features:
- * - Zoom with mouse wheel and presets
- * - Pan with drag
- * - Rotate 90°
- * - Flip horizontal/vertical
- * - Fullscreen dialog
- * - Keyboard shortcuts (+/-, 0, r, ←/→ for gallery)
- * - Gallery mode: pass images[] with multiple items
+ * Two presentations share one engine (react-zoom-pan-pinch):
+ * - Embedded (default): checkerboard canvas + editing toolbar (zoom presets,
+ *   rotate, flip, expand-to-fullscreen).
+ * - Lightbox (`lightbox` / `inDialog`): macOS Quick-Look-grade fullscreen —
+ *   clean dark backdrop, idle-fading floating chrome, no rotate/flip slab.
+ *
+ * Gesture model (macOS-native):
+ * - Trackpad pinch arrives as wheel events with `ctrlKey=true`; the library's
+ *   `smooth` path maps `|deltaY|` to the zoom magnitude so scale tracks the
+ *   gesture 1:1. We raise `smoothStep` (see WHEEL_SMOOTH_STEP) so a real pinch
+ *   reaches a meaningful zoom in one motion.
+ * - Zoom is anchored to the FOCAL POINT (cursor / pinch midpoint) — the point
+ *   under the fingers stays put — handled natively by the library.
+ * - Pan by drag when zoomed; double-click/tap toggles fit ↔ zoom toward the
+ *   point; keyboard +/-/0 and arrows (pan when zoomed, gallery nav at fit).
  */
 
 import { useEffect, useState, useRef, useCallback, useMemo } from 'react';
@@ -26,8 +33,16 @@ import { useHotkey } from '@djangocfg/ui-core/hooks';
 
 import { ImageToolbar } from './ImageToolbar';
 import { ImageInfo } from './ImageInfo';
-import { useImageTransform, useImageLoading } from '../hooks';
-import { KEYBOARD_PAN_STEP } from '../utils';
+import { LightboxChrome } from './LightboxChrome';
+import { useImageTransform, useImageLoading, useIdleChrome } from '../hooks';
+import {
+  KEYBOARD_PAN_STEP,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  WHEEL_SMOOTH_STEP,
+  PINCH_STEP,
+  DOUBLE_CLICK_STEP,
+} from '../utils';
 import type { ImageViewerProps } from '../types';
 
 // =============================================================================
@@ -38,10 +53,15 @@ export function ImageViewer({
   images,
   initialIndex = 0,
   inDialog = false,
+  lightbox = false,
+  onRequestClose,
   autoFocus = false,
 }: ImageViewerProps) {
   const t = useAppT();
 
+  // `lightbox` implies the in-dialog presentation.
+  const isLightbox = lightbox || inDialog;
+
   const [currentIndex, setCurrentIndex] = useState(() =>
     Math.max(0, Math.min(initialIndex, images.length - 1))
   );
@@ -61,12 +81,17 @@ export function ImageViewer({
   const containerRef = useRef<HTMLDivElement>(null);
   const controlsRef = useRef<ReactZoomPanPinchRef | null>(null);
 
+  // Idle-fading chrome (lightbox only). Pointer movement over the canvas keeps
+  // the controls visible; resting for CHROME_IDLE_MS fades them out.
+  const { active: chromeActive, onActivity, setPinned } = useIdleChrome(isLightbox);
+
   const labels = useMemo(() => ({
     noImage: t('tools.image.noImage'),
     failedToLoad: t('tools.image.failedToLoad'),
     loading: t('ui.form.loading'),
     prev: t('tools.gallery.previous'),
     next: t('tools.gallery.next'),
+    close: t('tools.gallery.close'),
   }), [t]);
 
   const {
@@ -114,14 +139,21 @@ export function ImageViewer({
 
   const handleExpand = useCallback(() => setDialogOpen(true), []);
 
+  // Reset zoom/pan to fit whenever the gallery image changes — a fresh image
+  // should never inherit the previous one's pan offset.
+  const goTo = useCallback((next: number) => {
+    setCurrentIndex(next);
+    controlsRef.current?.resetTransform();
+  }, []);
+
   const prev = useCallback(() =>
-    setCurrentIndex((i) => (i - 1 + images.length) % images.length),
-    [images.length]
+    goTo((currentIndex - 1 + images.length) % images.length),
+    [goTo, currentIndex, images.length]
   );
 
   const next = useCallback(() =>
-    setCurrentIndex((i) => (i + 1) % images.length),
-    [images.length]
+    goTo((currentIndex + 1) % images.length),
+    [goTo, currentIndex, images.length]
   );
 
   // Pan the image by a fixed offset (arrow keys)
@@ -154,7 +186,11 @@ export function ImageViewer({
         case '-': case '_': e.preventDefault(); controls.zoomOut(); break;
         case '0': e.preventDefault(); controls.resetTransform(); break;
         case 'r': case 'R':
-          if (!e.metaKey && !e.ctrlKey) { e.preventDefault(); rotate(); }
+          // Rotate is an editing affordance — embedded mode only.
+          if (!isLightbox && !e.metaKey && !e.ctrlKey) { e.preventDefault(); rotate(); }
+          break;
+        case 'Escape':
+          if (isLightbox && onRequestClose) { e.preventDefault(); onRequestClose(); }
           break;
         // Arrow keys pan only when zoomed in. While at fit scale they
         // fall through to gallery navigation (handled by useHotkey).
@@ -166,7 +202,7 @@ export function ImageViewer({
     };
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [rotate, panBy]);
+  }, [rotate, panBy, isLightbox, onRequestClose]);
 
   // Keyboard: gallery navigation (global, only while not zoomed in so it
   // never competes with arrow-key panning)
@@ -215,20 +251,33 @@ export function ImageViewer({
       tabIndex={0}
       role="img"
       aria-label={current.file.name}
+      onMouseMove={isLightbox ? onActivity : undefined}
       className={cn(
         'flex-1 h-full relative overflow-hidden outline-none',
         'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset',
-        'bg-[length:16px_16px]',
-        '[background-color:color-mix(in_oklab,var(--muted)_20%,transparent)]',
-        '[background-image:linear-gradient(45deg,color-mix(in_oklab,var(--muted)_40%,transparent)_25%,transparent_25%),linear-gradient(-45deg,color-mix(in_oklab,var(--muted)_40%,transparent)_25%,transparent_25%),linear-gradient(45deg,transparent_75%,color-mix(in_oklab,var(--muted)_40%,transparent)_75%),linear-gradient(-45deg,transparent_75%,color-mix(in_oklab,var(--muted)_40%,transparent)_75%)]',
-        '[background-position:0_0,0_8px,8px_-8px,-8px_0px]'
+        isLightbox
+          // Lightbox: a deep, slightly translucent vibrancy backdrop. The
+          // saturate+blur is the macOS Quick Look recipe — the page behind
+          // the dialog's scrim bleeds through softly so the image floats.
+          ? cn(
+              '[background-color:color-mix(in_oklab,#000_82%,transparent)]',
+              'backdrop-blur-2xl backdrop-saturate-150',
+            )
+          // Embedded: the classic transparency checkerboard.
+          : cn(
+              'bg-[length:16px_16px]',
+              '[background-color:color-mix(in_oklab,var(--muted)_20%,transparent)]',
+              '[background-image:linear-gradient(45deg,color-mix(in_oklab,var(--muted)_40%,transparent)_25%,transparent_25%),linear-gradient(-45deg,color-mix(in_oklab,var(--muted)_40%,transparent)_25%,transparent_25%),linear-gradient(45deg,transparent_75%,color-mix(in_oklab,var(--muted)_40%,transparent)_75%),linear-gradient(-45deg,transparent_75%,color-mix(in_oklab,var(--muted)_40%,transparent)_75%)]',
+              '[background-position:0_0,0_8px,8px_-8px,-8px_0px]',
+            ),
       )}
     >
-      {src && <ImageInfo src={src} />}
+      {/* Dimensions badge — embedded only (lightbox keeps chrome minimal). */}
+      {!isLightbox && src && <ImageInfo src={src} />}
 
       {useProgressiveLoading && !isFullyLoaded && (
         <div className="absolute top-3 left-3 z-10 px-2 py-1 bg-black/60 backdrop-blur-sm border border-white/10 rounded text-[10px] text-white/80 font-mono flex items-center gap-1.5">
-          <div className="w-2 h-2 bg-blue-400 rounded-full animate-pulse" />
+          <div className="w-2 h-2 bg-primary rounded-full animate-pulse" />
           {labels.loading}
         </div>
       )}
@@ -243,29 +292,38 @@ export function ImageViewer({
 
       <TransformWrapper
         initialScale={1}
-        minScale={0.1}
-        maxScale={8}
+        minScale={MIN_ZOOM}
+        maxScale={MAX_ZOOM}
         centerOnInit
         centerZoomedOut
+        // `smooth` (default) makes the wheel/trackpad zoom magnitude scale with
+        // `|deltaY|`, i.e. 1:1 with the gesture. The raised `smoothStep` gives
+        // a macOS trackpad pinch real reach in a single motion (the library's
+        // 0.001 default felt dead). Focal-point anchoring is handled natively.
+        smooth
+        wheel={{ smoothStep: WHEEL_SMOOTH_STEP }}
+        pinch={{ step: PINCH_STEP }}
+        doubleClick={{ mode: 'toggle', step: DOUBLE_CLICK_STEP }}
+        panning={{ velocityDisabled: false }}
         onTransformed={(ref, state) => {
           controlsRef.current = ref;
           // Avoid a re-render on every pan frame — only when zoom changes
           setScale((prev) => (prev === state.scale ? prev : state.scale));
         }}
         onInit={(ref) => { controlsRef.current = ref; }}
-        wheel={{ step: 0.1 }}
-        doubleClick={{ mode: 'toggle', step: 2 }}
-        panning={{ velocityDisabled: false }}
       >
-        <ImageToolbar
-          scale={scale}
-          transform={transform}
-          onRotate={rotate}
-          onFlipH={flipH}
-          onFlipV={flipV}
-          onZoomPreset={handleZoomPreset}
-          onExpand={!inDialog ? handleExpand : undefined}
-        />
+        {/* Embedded editing toolbar (rotate/flip/expand) — not in the lightbox. */}
+        {!isLightbox && (
+          <ImageToolbar
+            scale={scale}
+            transform={transform}
+            onRotate={rotate}
+            onFlipH={flipH}
+            onFlipV={flipV}
+            onZoomPreset={handleZoomPreset}
+            onExpand={!inDialog ? handleExpand : undefined}
+          />
+        )}
 
         <TransformComponent
           wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
@@ -294,7 +352,12 @@ export function ImageViewer({
               <img
                 src={src}
                 alt={current.file.name}
-                className="max-w-full max-h-full object-contain select-none"
+                className={cn(
+                  'max-w-full max-h-full object-contain select-none',
+                  // A soft drop shadow lifts the image off the dark lightbox
+                  // backdrop (Preview / Photos do the same).
+                  isLightbox && 'drop-shadow-[0_8px_40px_rgba(0,0,0,0.55)]',
+                )}
                 style={{
                   transform: transformStyle,
                   transition: 'transform 0.15s ease-out, opacity 0.3s ease-out',
@@ -310,52 +373,75 @@ export function ImageViewer({
         </TransformComponent>
       </TransformWrapper>
 
-      {/* Gallery navigation */}
-      {hasMultiple && (
-        <>
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <button
-                type="button"
-                onClick={prev}
-                aria-label={labels.prev}
-                className="absolute left-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
-              >
-                <ChevronLeft className="h-5 w-5" />
-              </button>
-            </TooltipTrigger>
-            <TooltipContent side="right">{labels.prev}</TooltipContent>
-          </Tooltip>
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <button
-                type="button"
-                onClick={next}
-                aria-label={labels.next}
-                className="absolute right-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
-              >
-                <ChevronRight className="h-5 w-5" />
-              </button>
-            </TooltipTrigger>
-            <TooltipContent side="left">{labels.next}</TooltipContent>
-          </Tooltip>
-          <div className="absolute top-3 left-1/2 -translate-x-1/2 z-10 bg-black/60 backdrop-blur-sm border border-white/10 text-white/80 text-xs font-mono px-2 py-0.5 rounded-full pointer-events-none">
-            {currentIndex + 1} / {images.length}
-          </div>
-        </>
+      {/* Lightbox: restrained macOS-grade chrome that idle-fades. */}
+      {isLightbox ? (
+        <LightboxChrome
+          active={chromeActive}
+          index={currentIndex + 1}
+          total={images.length}
+          scale={scale}
+          fileName={current.file.name}
+          onPrev={prev}
+          onNext={next}
+          onClose={() => onRequestClose?.()}
+          onPinChange={setPinned}
+          labels={{ prev: labels.prev, next: labels.next, close: labels.close }}
+        />
+      ) : (
+        hasMultiple && (
+          // Embedded gallery nav (checkerboard canvas).
+          <>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={prev}
+                  aria-label={labels.prev}
+                  className="absolute left-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
+                >
+                  <ChevronLeft className="h-5 w-5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="right">{labels.prev}</TooltipContent>
+            </Tooltip>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={next}
+                  aria-label={labels.next}
+                  className="absolute right-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
+                >
+                  <ChevronRight className="h-5 w-5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent side="left">{labels.next}</TooltipContent>
+            </Tooltip>
+            <div className="absolute top-3 left-1/2 -translate-x-1/2 z-10 bg-black/60 backdrop-blur-sm border border-white/10 text-white/80 text-xs font-mono px-2 py-0.5 rounded-full pointer-events-none">
+              {currentIndex + 1} / {images.length}
+            </div>
+          </>
+        )
       )}
 
-      {/* Fullscreen dialog */}
-      {!inDialog && (
+      {/* Embedded expand-to-fullscreen dialog (uses the lightbox presentation). */}
+      {!inDialog && !lightbox && (
         <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
-          <DialogContent className="max-w-[95vw] max-h-[95vh] w-[95vw] h-[95vh] p-0 overflow-hidden [&>button]:hidden flex flex-col">
+          <DialogContent
+            fullscreen
+            closeButton={false}
+            className="border-0 bg-transparent p-0 shadow-none"
+          >
             <DialogTitle className="sr-only">{current.file.name}</DialogTitle>
-            <div className="flex items-center justify-between px-4 py-2 border-b shrink-0">
-              <span className="text-sm font-medium truncate">{current.file.name}</span>
-            </div>
-            <div className="flex-1 min-h-0">
-              <ImageViewer images={images} initialIndex={currentIndex} inDialog />
-            </div>
+            {dialogOpen && (
+              <ImageViewer
+                images={images}
+                initialIndex={currentIndex}
+                lightbox
+                autoFocus
+                onRequestClose={() => setDialogOpen(false)}
+              />
+            )}
           </DialogContent>
         </Dialog>
       )}

package/src/tools/media/ImageViewer/components/LightboxChrome.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+/**
+ * LightboxChrome - Restrained, macOS-grade floating controls for the
+ * fullscreen image lightbox.
+ *
+ * Design intent (Apple HIG / Quick Look / Preview):
+ * - Minimal chrome: a single close affordance (top-right), prev/next only
+ *   when there is more than one image, and one unobtrusive status pill
+ *   (counter + live zoom %).
+ * - Everything floats on liquid-glass and fades together when the pointer
+ *   goes idle, reappearing on the slightest movement.
+ * - No checkerboard, no rotate/flip slab — the image is the subject.
+ */
+
+import { ChevronLeft, ChevronRight, X } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { MiddleEllipsis } from './MiddleEllipsis';
+
+interface LightboxChromeProps {
+  /** Visible (recent pointer activity) vs faded (idle). */
+  active: boolean;
+  /** 1-based index for the counter. */
+  index: number;
+  total: number;
+  /** Live zoom scale (1 = fit). The % pill only shows when zoomed in/out. */
+  scale: number;
+  fileName?: string;
+  onPrev: () => void;
+  onNext: () => void;
+  onClose: () => void;
+  /** Pin chrome open while the pointer hovers a control. */
+  onPinChange: (pinned: boolean) => void;
+  labels: { prev: string; next: string; close: string };
+}
+
+// Liquid-glass circular control — light icon on translucent vibrancy so it
+// stays legible over any photo (bright or dark) without a hard slab.
+const GLASS_BTN =
+  'glass-liquid pointer-events-auto inline-flex items-center justify-center ' +
+  'rounded-full text-white/90 transition-[background-color,transform,opacity] ' +
+  'hover:text-white hover:bg-white/15 active:scale-95 ' +
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/70';
+
+export function LightboxChrome({
+  active,
+  index,
+  total,
+  scale,
+  fileName,
+  onPrev,
+  onNext,
+  onClose,
+  onPinChange,
+  labels,
+}: LightboxChromeProps) {
+  const hasMultiple = total > 1;
+  // Only surface the zoom pill once the image is meaningfully off fit — at
+  // exactly fit (1.0) the % is noise.
+  const zoomed = Math.abs(scale - 1) > 0.01;
+  const zoomPct = `${Math.round(scale * 100)}%`;
+
+  // Whole chrome layer fades as one. `pointer-events-none` on the layer means
+  // the faded state never eats clicks meant for the image (pan/double-click).
+  return (
+    <div
+      className={cn(
+        'pointer-events-none absolute inset-0 z-20 transition-opacity duration-300 ease-out',
+        active ? 'opacity-100' : 'opacity-0',
+      )}
+      onMouseEnter={() => onPinChange(true)}
+      onMouseLeave={() => onPinChange(false)}
+    >
+      {/* Top bar: filename (left, whisper-quiet) + close (right).
+          The chip caps its width and middle-truncates long names so the start
+          and extension stay readable (Finder convention); `gap` + the pinned
+          close button guarantee no overlap. */}
+      <div className="absolute inset-x-0 top-0 flex items-start justify-between gap-3 p-3 sm:p-4">
+        {fileName ? (
+          <MiddleEllipsis
+            text={fileName}
+            className="glass-liquid pointer-events-auto max-w-[clamp(8rem,40vw,28rem)] rounded-full px-3 py-1.5 text-xs font-medium text-white/85"
+          />
+        ) : (
+          <span aria-hidden />
+        )}
+        <button
+          type="button"
+          aria-label={labels.close}
+          onClick={onClose}
+          className={cn(GLASS_BTN, 'h-9 w-9')}
+        >
+          <X className="h-[18px] w-[18px]" />
+        </button>
+      </div>
+
+      {/* Prev / next — edge-anchored, only when there is a gallery. */}
+      {hasMultiple && (
+        <>
+          <button
+            type="button"
+            aria-label={labels.prev}
+            onClick={onPrev}
+            className={cn(GLASS_BTN, 'absolute left-3 top-1/2 h-11 w-11 -translate-y-1/2 sm:left-5')}
+          >
+            <ChevronLeft className="h-5 w-5" />
+          </button>
+          <button
+            type="button"
+            aria-label={labels.next}
+            onClick={onNext}
+            className={cn(GLASS_BTN, 'absolute right-3 top-1/2 h-11 w-11 -translate-y-1/2 sm:right-5')}
+          >
+            <ChevronRight className="h-5 w-5" />
+          </button>
+        </>
+      )}
+
+      {/* Bottom status pill: counter + live zoom %. One quiet line. */}
+      {(hasMultiple || zoomed) && (
+        <div className="absolute inset-x-0 bottom-0 flex justify-center p-3 sm:p-4">
+          <div className="glass-liquid flex items-center gap-2 rounded-full px-3 py-1.5 text-xs font-medium tabular-nums text-white/85">
+            {hasMultiple && (
+              <span>
+                {index} / {total}
+              </span>
+            )}
+            {hasMultiple && zoomed && <span className="h-3 w-px bg-white/25" />}
+            {zoomed && <span className="font-mono text-white/70">{zoomPct}</span>}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}