@djangocfg/widget-media 0.1.9 → 0.1.14

package/README.md

@@ -17,11 +17,11 @@ and a host mounting a lightbox must not pay for any of them.
 
 | Subpath | What it is | What it costs |
 |---|---|---|
-| `.` | `ImageViewer`, `LazyImageViewer`, its hooks, types and constants | `react-zoom-pan-pinch` |
+| `.` | `ImageLightbox`, `LazyImageLightbox`, `ImageViewer`, `LazyImageViewer`, hooks, types, constants | `yet-another-react-lightbox` (lightbox), `react-zoom-pan-pinch` (viewer) |
 | `./diagram` | `LazyDiagram`, `DiagramSource`, `diagramPlugin` | mermaid (~2.5 MB) — **always deferred** |
 | `./markdown` | `Markdown` — for a reader, outside any conversation | streamdown |
 | `./code` | `Code` — a read-only listing | streamdown + shiki |
-| `./i18n` | `MediaCopy`, `DEFAULT_MEDIA_COPY` | — |
+| `./i18n` | `MediaCopy`, `DEFAULT_MEDIA_COPY`, `MEDIA_DICTIONARIES`, `useMediaCopy` | — |
 
 ```tsx
 import { ImageViewer } from '@djangocfg/widget-media';
@@ -33,8 +33,10 @@ import { LazyDiagram } from '@djangocfg/widget-media/diagram';
 
 ## Copy
 
-The package owns its copy, typed. Pass `copy` to override any subset; keys you
-omit fall back to English, so translating one label does not blank the rest.
+The package owns its copy, typed, in the 17 `@djangocfg/i18n` locales. The
+language comes from the `@djangocfg/i18n` provider (English without one). Pass
+`copy` to override any subset; keys you omit keep the dictionary's text, so
+changing one label does not blank the rest.
 
 ```tsx
 <ImageViewer images={images} copy={{ zoomIn: 'Приблизить', close: 'Закрыть' }} />
@@ -43,13 +45,39 @@ omit fall back to English, so translating one label does not blank the rest.
 `MediaCopy` is the schema of record — a misspelled key is a `tsc` error, not
 `undefined` rendered into a toolbar button.
 
+## Image lightbox
+
+The modal gallery a click on a picture opens, on
+[yet-another-react-lightbox](https://github.com/igordanchenko/yet-another-react-lightbox):
+focus trap, swipe, preload of the neighbours, keyboard, wheel/pinch zoom,
+thumbnails and a counter. Double-click zooms in at the pointer and the next one
+zooms back out; the cursor is a magnifier at rest and a hand only while zoomed.
+The skin is `src/image-viewer/lightbox/lightbox.css`: YARL's `--yarl__*`
+variables mapped to ui-core tokens, so it follows light/dark and every preset.
+
+```tsx
+import { LazyImageLightbox } from '@djangocfg/widget-media';
+
+<LazyImageLightbox
+  images={[{ name: 'a.jpg', src, downloadSrc }]}
+  open={index !== null}
+  index={index ?? 0}
+  onIndexChange={setIndex}
+  onClose={() => setIndex(null)}
+/>
+```
+
+It takes addresses (`LightboxImage`), never raw bytes; an in-memory image goes
+through `ImageViewer`. `LazyImageLightbox` renders nothing until `open`.
+
 ## Image viewer
 
-Zoom (wheel + presets 25/50/100/200/400%), pan by drag, rotate 90°, flip H/V,
-fullscreen dialog, keyboard shortcuts (`+`/`-`, `0` reset, `r` rotate),
-progressive loading with LQIP, checkerboard transparency ground, and cached
-dimension display. `LazyImageViewer` ships from the same entry, so choosing it
-costs no extra subpath.
+The embedded editor: zoom (wheel + presets 25/50/100/200/400%), pan by drag,
+rotate 90°, flip H/V, fullscreen dialog, keyboard shortcuts (`+`/`-`, `0`
+reset, `r` rotate), progressive loading with LQIP, checkerboard transparency
+ground, cached dimension display. Double-click zooms to the pointer from fit and
+back to fit from anywhere else. The `lightbox` prop is the older fullscreen
+presentation, superseded by `ImageLightbox` and kept so existing hosts compile.
 
 ## Verify
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-media",
-  "version": "0.1.9",
+  "version": "0.1.14",
   "description": "Media viewers for a conversation or a file preview: zoom/pan image lightbox, mermaid diagrams, markdown and code listings",
   "keywords": [
     "image-viewer",
@@ -53,17 +53,20 @@
     "beautiful-mermaid": "^1.1.3",
     "react-zoom-pan-pinch": "^3.7.0",
     "rehype-harden": "^1.1.8",
+    "yet-another-react-lightbox": "^3.32.2",
     "zustand": "^5.0.0"
   },
   "peerDependencies": {
-    "@djangocfg/ui-core": "^2.1.550",
+    "@djangocfg/i18n": "^2.1.592",
+    "@djangocfg/ui-core": "^2.1.592",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "streamdown": "^2.6.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.550",
-    "@djangocfg/ui-core": "^2.1.550",
+    "@djangocfg/i18n": "^2.1.592",
+    "@djangocfg/typescript-config": "^2.1.592",
+    "@djangocfg/ui-core": "^2.1.592",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/i18n/index.ts

@@ -1,60 +1,49 @@
 'use client';
 
-/**
- * The package owns its copy, typed.
- *
- * `MediaCopy` is the schema of record: a missing or misspelled key is a `tsc`
- * error rather than `undefined` rendered into a toolbar button. Copy used to
- * arrive through a host i18n provider, which made the viewer unmountable
- * without one — a story, a preview route and a test each had to stand a
- * provider up to draw one image.
- *
- * A host that already translates passes `copy` to override any subset; keys it
- * omits fall back to English.
- */
+import { useMemo } from 'react';
 
-export interface MediaCopy {
-  close: string;
-  diagram: string;
-  download: string;
-  failedToLoad: string;
-  fitToView: string;
-  flipHorizontal: string;
-  flipVertical: string;
-  fullscreen: string;
-  loading: string;
-  next: string;
-  noImage: string;
-  previous: string;
-  rotate: string;
-  zoomIn: string;
-  zoomOut: string;
-}
+import { createCopy, type Locale } from '@djangocfg/i18n/copy';
+
+import { ar } from './locales/ar';
+import { da } from './locales/da';
+import { de } from './locales/de';
+import { en } from './locales/en';
+import { es } from './locales/es';
+import { fr } from './locales/fr';
+import { it } from './locales/it';
+import { ja } from './locales/ja';
+import { ko } from './locales/ko';
+import { nl } from './locales/nl';
+import { no } from './locales/no';
+import { pl } from './locales/pl';
+import { ptBR } from './locales/ptBR';
+import { ru } from './locales/ru';
+import { sv } from './locales/sv';
+import { tr } from './locales/tr';
+import { zh } from './locales/zh';
 
-export const DEFAULT_MEDIA_COPY: MediaCopy = {
-  close: 'Close',
-  diagram: 'Diagram',
-  download: 'Download',
-  failedToLoad: 'Failed to load',
-  fitToView: 'Fit to view',
-  flipHorizontal: 'Flip horizontal',
-  flipVertical: 'Flip vertical',
-  fullscreen: 'Fullscreen',
-  loading: 'Loading…',
-  next: 'Next',
-  noImage: 'No image',
-  previous: 'Previous',
-  rotate: 'Rotate',
-  zoomIn: 'Zoom in',
-  zoomOut: 'Zoom out',
+import type { MediaCopy } from './types';
+
+export type { MediaCopy } from './types';
+
+/** Every bundled dictionary, typed complete over the shared `Locale` union. */
+export const MEDIA_DICTIONARIES: Readonly<Record<Locale, MediaCopy>> = {
+  en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pl, sv, no, da,
+  'pt-BR': ptBR,
 };
 
+/** English, for a host that wants the unlocalised defaults. */
+export const DEFAULT_MEDIA_COPY: MediaCopy = en;
+
+const kit = createCopy(MEDIA_DICTIONARIES);
+
 /**
- * Resolve the copy a component renders. Takes the host's partial override and
- * fills the rest from the defaults, so a caller supplying one string does not
- * blank the other fourteen.
+ * The copy a component renders: the dictionary for the active language (the
+ * `locale` argument, else the `@djangocfg/i18n` provider, else English), with
+ * the host's partial override on top. A host that overrides one string does
+ * not blank the other fourteen.
  */
-export function useMediaCopy(copy?: Partial<MediaCopy>): MediaCopy {
-  if (!copy) return DEFAULT_MEDIA_COPY;
-  return { ...DEFAULT_MEDIA_COPY, ...copy };
+export function useMediaCopy(copy?: Partial<MediaCopy>, locale?: string): MediaCopy {
+  const base = kit.useCopy(locale);
+  return useMemo(() => (copy ? { ...base, ...copy } : base), [base, copy]);
 }

package/src/i18n/locales/ar.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const ar: MediaCopy = {
+  close: 'إغلاق',
+  diagram: 'مخطط',
+  download: 'تنزيل',
+  failedToLoad: 'فشل التحميل',
+  fitToView: 'ملاءمة للنافذة',
+  flipHorizontal: 'قلب أفقي',
+  flipVertical: 'قلب عمودي',
+  fullscreen: 'ملء الشاشة',
+  loading: 'جارٍ التحميل…',
+  next: 'التالي',
+  noImage: 'لا توجد صورة',
+  previous: 'السابق',
+  rotate: 'تدوير',
+  zoomIn: 'تكبير',
+  zoomOut: 'تصغير',
+};

package/src/i18n/locales/da.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const da: MediaCopy = {
+  close: 'Luk',
+  diagram: 'Diagram',
+  download: 'Download',
+  failedToLoad: 'Kunne ikke indlæses',
+  fitToView: 'Tilpas til vindue',
+  flipHorizontal: 'Spejlvend vandret',
+  flipVertical: 'Spejlvend lodret',
+  fullscreen: 'Fuld skærm',
+  loading: 'Indlæser…',
+  next: 'Næste',
+  noImage: 'Intet billede',
+  previous: 'Forrige',
+  rotate: 'Roter',
+  zoomIn: 'Zoom ind',
+  zoomOut: 'Zoom ud',
+};

package/src/i18n/locales/de.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const de: MediaCopy = {
+  close: 'Schließen',
+  diagram: 'Diagramm',
+  download: 'Herunterladen',
+  failedToLoad: 'Laden fehlgeschlagen',
+  fitToView: 'An Fenster anpassen',
+  flipHorizontal: 'Horizontal spiegeln',
+  flipVertical: 'Vertikal spiegeln',
+  fullscreen: 'Vollbild',
+  loading: 'Wird geladen…',
+  next: 'Weiter',
+  noImage: 'Kein Bild',
+  previous: 'Zurück',
+  rotate: 'Drehen',
+  zoomIn: 'Vergrößern',
+  zoomOut: 'Verkleinern',
+};

package/src/i18n/locales/en.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const en: MediaCopy = {
+  close: 'Close',
+  diagram: 'Diagram',
+  download: 'Download',
+  failedToLoad: 'Failed to load',
+  fitToView: 'Fit to view',
+  flipHorizontal: 'Flip horizontal',
+  flipVertical: 'Flip vertical',
+  fullscreen: 'Fullscreen',
+  loading: 'Loading…',
+  next: 'Next',
+  noImage: 'No image',
+  previous: 'Previous',
+  rotate: 'Rotate',
+  zoomIn: 'Zoom in',
+  zoomOut: 'Zoom out',
+};

package/src/i18n/locales/es.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const es: MediaCopy = {
+  close: 'Cerrar',
+  diagram: 'Diagrama',
+  download: 'Descargar',
+  failedToLoad: 'Error al cargar',
+  fitToView: 'Ajustar a la ventana',
+  flipHorizontal: 'Voltear horizontalmente',
+  flipVertical: 'Voltear verticalmente',
+  fullscreen: 'Pantalla completa',
+  loading: 'Cargando…',
+  next: 'Siguiente',
+  noImage: 'Sin imagen',
+  previous: 'Anterior',
+  rotate: 'Girar',
+  zoomIn: 'Acercar',
+  zoomOut: 'Alejar',
+};

package/src/i18n/locales/fr.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const fr: MediaCopy = {
+  close: 'Fermer',
+  diagram: 'Diagramme',
+  download: 'Télécharger',
+  failedToLoad: 'Échec du chargement',
+  fitToView: 'Ajuster à la fenêtre',
+  flipHorizontal: 'Retourner horizontalement',
+  flipVertical: 'Retourner verticalement',
+  fullscreen: 'Plein écran',
+  loading: 'Chargement…',
+  next: 'Suivant',
+  noImage: 'Aucune image',
+  previous: 'Précédent',
+  rotate: 'Pivoter',
+  zoomIn: 'Zoom avant',
+  zoomOut: 'Zoom arrière',
+};

package/src/i18n/locales/it.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const it: MediaCopy = {
+  close: 'Chiudi',
+  diagram: 'Diagramma',
+  download: 'Scarica',
+  failedToLoad: 'Caricamento non riuscito',
+  fitToView: 'Adatta alla finestra',
+  flipHorizontal: 'Capovolgi orizzontalmente',
+  flipVertical: 'Capovolgi verticalmente',
+  fullscreen: 'Schermo intero',
+  loading: 'Caricamento…',
+  next: 'Avanti',
+  noImage: 'Nessuna immagine',
+  previous: 'Indietro',
+  rotate: 'Ruota',
+  zoomIn: 'Ingrandisci',
+  zoomOut: 'Riduci',
+};

package/src/i18n/locales/ja.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const ja: MediaCopy = {
+  close: '閉じる',
+  diagram: 'ダイアグラム',
+  download: 'ダウンロード',
+  failedToLoad: '読み込めませんでした',
+  fitToView: '画面に合わせる',
+  flipHorizontal: '左右反転',
+  flipVertical: '上下反転',
+  fullscreen: '全画面表示',
+  loading: '読み込み中…',
+  next: '次へ',
+  noImage: '画像がありません',
+  previous: '前へ',
+  rotate: '回転',
+  zoomIn: '拡大',
+  zoomOut: '縮小',
+};

package/src/i18n/locales/ko.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const ko: MediaCopy = {
+  close: '닫기',
+  diagram: '다이어그램',
+  download: '다운로드',
+  failedToLoad: '불러오지 못했습니다',
+  fitToView: '화면에 맞추기',
+  flipHorizontal: '좌우 반전',
+  flipVertical: '상하 반전',
+  fullscreen: '전체 화면',
+  loading: '로딩 중…',
+  next: '다음',
+  noImage: '이미지 없음',
+  previous: '이전',
+  rotate: '회전',
+  zoomIn: '확대',
+  zoomOut: '축소',
+};

package/src/i18n/locales/nl.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const nl: MediaCopy = {
+  close: 'Sluiten',
+  diagram: 'Diagram',
+  download: 'Downloaden',
+  failedToLoad: 'Laden mislukt',
+  fitToView: 'Aanpassen aan venster',
+  flipHorizontal: 'Horizontaal spiegelen',
+  flipVertical: 'Verticaal spiegelen',
+  fullscreen: 'Volledig scherm',
+  loading: 'Laden…',
+  next: 'Volgende',
+  noImage: 'Geen afbeelding',
+  previous: 'Vorige',
+  rotate: 'Draaien',
+  zoomIn: 'Inzoomen',
+  zoomOut: 'Uitzoomen',
+};

package/src/i18n/locales/no.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const no: MediaCopy = {
+  close: 'Lukk',
+  diagram: 'Diagram',
+  download: 'Last ned',
+  failedToLoad: 'Kunne ikke lastes',
+  fitToView: 'Tilpass til vinduet',
+  flipHorizontal: 'Speilvend horisontalt',
+  flipVertical: 'Speilvend vertikalt',
+  fullscreen: 'Fullskjerm',
+  loading: 'Laster…',
+  next: 'Neste',
+  noImage: 'Ingen bilde',
+  previous: 'Forrige',
+  rotate: 'Roter',
+  zoomIn: 'Zoom inn',
+  zoomOut: 'Zoom ut',
+};

package/src/i18n/locales/pl.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const pl: MediaCopy = {
+  close: 'Zamknij',
+  diagram: 'Diagram',
+  download: 'Pobierz',
+  failedToLoad: 'Nie udało się wczytać',
+  fitToView: 'Dopasuj do okna',
+  flipHorizontal: 'Odbij w poziomie',
+  flipVertical: 'Odbij w pionie',
+  fullscreen: 'Pełny ekran',
+  loading: 'Ładowanie…',
+  next: 'Dalej',
+  noImage: 'Brak obrazu',
+  previous: 'Wstecz',
+  rotate: 'Obróć',
+  zoomIn: 'Powiększ',
+  zoomOut: 'Pomniejsz',
+};

package/src/i18n/locales/ptBR.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const ptBR: MediaCopy = {
+  close: 'Fechar',
+  diagram: 'Diagrama',
+  download: 'Baixar',
+  failedToLoad: 'Falha ao carregar',
+  fitToView: 'Ajustar à janela',
+  flipHorizontal: 'Espelhar na horizontal',
+  flipVertical: 'Espelhar na vertical',
+  fullscreen: 'Tela cheia',
+  loading: 'Carregando…',
+  next: 'Próximo',
+  noImage: 'Sem imagem',
+  previous: 'Anterior',
+  rotate: 'Girar',
+  zoomIn: 'Aproximar',
+  zoomOut: 'Afastar',
+};

package/src/i18n/locales/ru.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const ru: MediaCopy = {
+  close: 'Закрыть',
+  diagram: 'Диаграмма',
+  download: 'Скачать',
+  failedToLoad: 'Не удалось загрузить',
+  fitToView: 'По размеру окна',
+  flipHorizontal: 'Отразить по горизонтали',
+  flipVertical: 'Отразить по вертикали',
+  fullscreen: 'Во весь экран',
+  loading: 'Загрузка…',
+  next: 'Далее',
+  noImage: 'Нет изображения',
+  previous: 'Назад',
+  rotate: 'Повернуть',
+  zoomIn: 'Увеличить',
+  zoomOut: 'Уменьшить',
+};

package/src/i18n/locales/sv.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const sv: MediaCopy = {
+  close: 'Stäng',
+  diagram: 'Diagram',
+  download: 'Ladda ner',
+  failedToLoad: 'Det gick inte att ladda',
+  fitToView: 'Anpassa till fönstret',
+  flipHorizontal: 'Vänd horisontellt',
+  flipVertical: 'Vänd vertikalt',
+  fullscreen: 'Helskärm',
+  loading: 'Laddar…',
+  next: 'Nästa',
+  noImage: 'Ingen bild',
+  previous: 'Föregående',
+  rotate: 'Rotera',
+  zoomIn: 'Zooma in',
+  zoomOut: 'Zooma ut',
+};

package/src/i18n/locales/tr.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const tr: MediaCopy = {
+  close: 'Kapat',
+  diagram: 'Diyagram',
+  download: 'İndir',
+  failedToLoad: 'Yüklenemedi',
+  fitToView: 'Pencereye sığdır',
+  flipHorizontal: 'Yatay çevir',
+  flipVertical: 'Dikey çevir',
+  fullscreen: 'Tam ekran',
+  loading: 'Yükleniyor…',
+  next: 'Sonraki',
+  noImage: 'Görsel yok',
+  previous: 'Önceki',
+  rotate: 'Döndür',
+  zoomIn: 'Yakınlaştır',
+  zoomOut: 'Uzaklaştır',
+};

package/src/i18n/locales/zh.ts

@@ -0,0 +1,19 @@
+import type { MediaCopy } from '../types';
+
+export const zh: MediaCopy = {
+  close: '关闭',
+  diagram: '图表',
+  download: '下载',
+  failedToLoad: '加载失败',
+  fitToView: '适应窗口',
+  flipHorizontal: '水平翻转',
+  flipVertical: '垂直翻转',
+  fullscreen: '全屏',
+  loading: '加载中…',
+  next: '下一个',
+  noImage: '没有图片',
+  previous: '上一个',
+  rotate: '旋转',
+  zoomIn: '放大',
+  zoomOut: '缩小',
+};

package/src/i18n/types.ts

@@ -0,0 +1,22 @@
+/**
+ * The media package's copy schema. English is the schema of record: every
+ * locale is typed against `MediaCopy`, so a missing key is a `tsc` error rather
+ * than `undefined` rendered into a toolbar button.
+ */
+export interface MediaCopy {
+  close: string;
+  diagram: string;
+  download: string;
+  failedToLoad: string;
+  fitToView: string;
+  flipHorizontal: string;
+  flipVertical: string;
+  fullscreen: string;
+  loading: string;
+  next: string;
+  noImage: string;
+  previous: string;
+  rotate: string;
+  zoomIn: string;
+  zoomOut: string;
+}

package/src/image-viewer/components/ImageViewer.tsx

@@ -41,7 +41,8 @@ import {
   MAX_ZOOM,
   WHEEL_SMOOTH_STEP,
   PINCH_STEP,
-  DOUBLE_CLICK_STEP,
+  DOUBLE_CLICK_ZOOM,
+  FIT_EPSILON,
 } from '../utils';
 import type { ImageViewerProps } from '../types';
 
@@ -91,6 +92,7 @@ export function ImageViewer({
   const [imgDecoded, setImgDecoded] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
   const controlsRef = useRef<ReactZoomPanPinchRef | null>(null);
+  const atRest = Math.abs(scale - 1) < FIT_EPSILON;
   const imgRef = useRef<HTMLImageElement>(null);
 
   // Idle-fading chrome (lightbox only). Pointer movement over the canvas keeps
@@ -161,6 +163,24 @@ export function ImageViewer({
     resetKey: current?.file.path ?? '',
   });
 
+  // Double-click / double-tap: zoom to the pointer from fit, back to fit from
+  // anywhere else. The point under the pointer stays put (focal-point zoom).
+  const handleDoubleClick = useCallback((event: React.MouseEvent<HTMLDivElement>) => {
+    const controls = controlsRef.current;
+    const wrapper = controls?.instance.wrapperComponent;
+    if (!controls || !wrapper) return;
+    const { scale: current, positionX, positionY } = controls.instance.transformState;
+    if (Math.abs(current - 1) >= FIT_EPSILON) {
+      controls.resetTransform(200);
+      return;
+    }
+    const rect = wrapper.getBoundingClientRect();
+    const px = event.clientX - rect.left;
+    const py = event.clientY - rect.top;
+    const ratio = DOUBLE_CLICK_ZOOM / current;
+    controls.setTransform(px - (px - positionX) * ratio, py - (py - positionY) * ratio, DOUBLE_CLICK_ZOOM, 200);
+  }, []);
+
   const handleZoomPreset = useCallback((value: number | 'fit') => {
     const controls = controlsRef.current;
     if (!controls) return;
@@ -353,7 +373,10 @@ export function ImageViewer({
         smooth
         wheel={{ smoothStep: WHEEL_SMOOTH_STEP }}
         pinch={{ step: PINCH_STEP }}
-        doubleClick={{ mode: 'toggle', step: DOUBLE_CLICK_STEP }}
+        // The library's `toggle` zooms in only at scale === 1 exactly, so after
+        // any zoom every double-click was another step OUT. Ours is handled in
+        // `handleDoubleClick`: at rest zoom to the pointer, otherwise back to fit.
+        doubleClick={{ disabled: true }}
         panning={{ velocityDisabled: false }}
         onTransformed={(ref, state) => {
           controlsRef.current = ref;
@@ -376,7 +399,11 @@ export function ImageViewer({
         )}
 
         <TransformComponent
-          wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
+          wrapperClass={cn(
+            '!w-full !h-full',
+            atRest ? 'cursor-zoom-in' : 'cursor-grab active:cursor-grabbing',
+          )}
+          wrapperProps={{ onDoubleClick: handleDoubleClick }}
           contentClass="!w-full !h-full flex items-center justify-center"
         >
           {/*

package/src/image-viewer/index.ts

@@ -24,6 +24,10 @@ export { ImageViewer, ImageToolbar, ImageInfo } from './components';
 // picture. Exported from the same entry so choosing it costs no extra subpath.
 export { LazyImageViewer } from './lazy';
 
+// The modal gallery (yet-another-react-lightbox). Prefer it to the `lightbox`
+// presentation of `ImageViewer`; `LazyImageLightbox` defers the engine.
+export { ImageLightbox, LazyImageLightbox } from './lightbox';
+
 // =============================================================================
 // HOOKS
 // =============================================================================
@@ -43,6 +47,8 @@ export type {
 export type {
   ImageFile,
   ImageViewerProps,
+  ImageLightboxProps,
+  LightboxImage,
   ImageToolbarProps,
   ImageInfoProps,
   ImageTransform,

package/src/image-viewer/lightbox/ImageLightbox.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+/**
+ * ImageLightbox - modal gallery on yet-another-react-lightbox.
+ *
+ * The engine owns what is costly to get right: focus trap, swipe, preload of
+ * the neighbours, keyboard, wheel/pinch zoom, and a double-click that zooms in
+ * and back out. This file only configures it, themes it from tokens
+ * (`lightbox.css`) and adds the SAVE button with the same same-origin rule the
+ * embedded viewer has.
+ */
+
+import { Download } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import Lightbox, { IconButton, useLightboxState } from 'yet-another-react-lightbox';
+import Counter from 'yet-another-react-lightbox/plugins/counter';
+import Thumbnails from 'yet-another-react-lightbox/plugins/thumbnails';
+import Zoom from 'yet-another-react-lightbox/plugins/zoom';
+
+import 'yet-another-react-lightbox/styles.css';
+import 'yet-another-react-lightbox/plugins/counter.css';
+import 'yet-another-react-lightbox/plugins/thumbnails.css';
+import './lightbox.css';
+
+import { useMediaCopy } from '../../i18n';
+import type { ImageLightboxProps, LightboxImage } from '../types';
+
+declare module 'yet-another-react-lightbox' {
+  interface Labels {
+    /** Title of the SAVE button this widget adds to the toolbar. */
+    Save?: string;
+  }
+}
+
+/** Double-click: one stop in, the next one out. */
+const ZOOM = {
+  doubleClickMaxStops: 1,
+  zoomInMultiplier: 2.5,
+  maxZoomPixelRatio: 3,
+  scrollToZoom: true,
+} as const;
+
+export function ImageLightbox({
+  images,
+  open,
+  index = 0,
+  onClose,
+  onIndexChange,
+  thumbnails = true,
+  copy,
+}: ImageLightboxProps) {
+  const labels = useMediaCopy(copy);
+  const [zoomed, setZoomed] = useState(false);
+
+  const slides = useMemo(
+    () =>
+      images.map((image) => ({
+        src: image.src,
+        alt: image.name,
+        width: image.width,
+        height: image.height,
+      })),
+    [images],
+  );
+
+  const handleView = useCallback(
+    ({ index: next }: { index: number }) => onIndexChange?.(next),
+    [onIndexChange],
+  );
+
+  return (
+    <Lightbox
+      open={open}
+      close={onClose}
+      index={index}
+      slides={slides}
+      className={zoomed ? 'dj-lightbox dj-lightbox--zoomed' : 'dj-lightbox'}
+      plugins={thumbnails && slides.length > 1 ? [Counter, Thumbnails, Zoom] : [Counter, Zoom]}
+      zoom={ZOOM}
+      carousel={{ finite: true, preload: 2 }}
+      animation={{ swipe: 250 }}
+      controller={{ closeOnBackdropClick: true, closeOnPullDown: true }}
+      thumbnails={{ position: 'bottom', vignette: false, border: 0, gap: 8 }}
+      labels={{
+        Close: labels.close,
+        Next: labels.next,
+        Previous: labels.previous,
+        Save: labels.download,
+        'Zoom in': labels.zoomIn,
+        'Zoom out': labels.zoomOut,
+      }}
+      on={{ view: handleView, zoom: ({ zoom }) => setZoomed(zoom > 1.01) }}
+      toolbar={{
+        buttons: [<SaveButton key="save" images={images} />, 'close'],
+      }}
+      render={slides.length > 1 ? undefined : { buttonPrev: () => null, buttonNext: () => null }}
+    />
+  );
+}
+
+/**
+ * Saves the slide on screen. `download` is honoured only for a same-origin
+ * address, so a picture shown from a CDN is saved from `downloadSrc` when the
+ * host has one.
+ */
+function SaveButton({ images }: { images: LightboxImage[] }) {
+  const { currentIndex } = useLightboxState();
+  const image = images[currentIndex];
+  const save = useCallback(() => {
+    if (!image) return;
+    const link = document.createElement('a');
+    link.href = image.downloadSrc ?? image.src;
+    link.download = image.name;
+    link.rel = 'noopener';
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+  }, [image]);
+
+  if (!image) return null;
+  return (
+    <IconButton
+      label="Save"
+      icon={() => null}
+      renderIcon={() => <Download className="yarl__icon" aria-hidden />}
+      onClick={save}
+    />
+  );
+}

package/src/image-viewer/lightbox/index.ts

@@ -0,0 +1,2 @@
+export { ImageLightbox } from './ImageLightbox';
+export { LazyImageLightbox } from './lazy';

package/src/image-viewer/lightbox/lazy.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+/**
+ * Lazy ImageLightbox: the engine and its three plugins load when a reader first
+ * opens a picture, not with the page. Mounted only while `open`, so nothing is
+ * fetched (and nothing renders on the server) until then.
+ */
+
+import { lazy, Suspense } from 'react';
+
+import type { ImageLightboxProps } from '../types';
+
+const ImageLightboxImpl = lazy(() =>
+  import('./ImageLightbox').then((mod) => ({ default: mod.ImageLightbox })),
+);
+
+export function LazyImageLightbox(props: ImageLightboxProps) {
+  if (!props.open) return null;
+  return (
+    <Suspense fallback={null}>
+      <ImageLightboxImpl {...props} />
+    </Suspense>
+  );
+}

package/src/image-viewer/lightbox/lightbox.css

@@ -0,0 +1,84 @@
+/*
+ * Theme for ImageLightbox: yet-another-react-lightbox reads `--yarl__*`
+ * variables, so the whole skin is this one mapping onto ui-core tokens. It
+ * follows light/dark and every preset with no JS. Scoped to `.dj-lightbox` so a
+ * host's own YARL instance is untouched.
+ */
+.dj-lightbox {
+  /* Above dialogs (z-1300), below popovers (z-1400): a lightbox opened from a
+     dialog must cover it, a menu opened from the toolbar must cover the box. */
+  --yarl__portal_zindex: 1350;
+  --yarl__color_backdrop: color-mix(in oklab, var(--background) 94%, transparent);
+  --yarl__container_background_color: var(--yarl__color_backdrop);
+  --yarl__color_button: var(--foreground);
+  --yarl__color_button_active: var(--foreground);
+  --yarl__color_button_disabled: var(--muted-foreground);
+  /* No drop shadow behind icons: the backdrop is a token surface, not a photo. */
+  --yarl__button_filter: none;
+  --yarl__icon_size: 20px;
+  --yarl__button_padding: 10px;
+  --yarl__toolbar_padding: 12px;
+  --yarl__navigation_button_padding: 12px;
+  --yarl__slide_icon_loading_color: var(--muted-foreground);
+  --yarl__slide_icon_error_color: var(--destructive);
+  --yarl__counter_color: var(--foreground);
+  --yarl__counter_filter: none;
+  --yarl__counter_top: 12px;
+  --yarl__counter_left: 20px;
+  --yarl__thumbnails_container_background_color: transparent;
+  --yarl__thumbnails_thumbnail_background: var(--muted);
+  --yarl__thumbnails_thumbnail_border_color: transparent;
+  --yarl__thumbnails_thumbnail_active_border_color: var(--primary);
+  --yarl__thumbnails_thumbnail_border_radius: var(--radius-control, 8px);
+  --yarl__thumbnails_thumbnail_width: 72px;
+  --yarl__thumbnails_thumbnail_height: 52px;
+  --yarl__thumbnails_thumbnail_gap: 8px;
+  --yarl__thumbnails_thumbnail_padding: 2px;
+}
+
+.dj-lightbox .yarl__container {
+  backdrop-filter: blur(24px) saturate(1.2);
+}
+
+/* Round controls on a translucent token surface, so an icon or the counter stays
+   legible over any photo, bright or dark. */
+.dj-lightbox .yarl__button,
+.dj-lightbox .yarl__counter {
+  border-radius: 9999px;
+  background-color: color-mix(in oklab, var(--background) 60%, transparent);
+  backdrop-filter: blur(12px);
+  transition: background-color 150ms ease;
+}
+.dj-lightbox .yarl__toolbar {
+  gap: 8px;
+}
+.dj-lightbox .yarl__button:hover:not(:disabled) {
+  background-color: color-mix(in oklab, var(--foreground) 14%, var(--background) 60%);
+}
+.dj-lightbox .yarl__button:focus-visible {
+  box-shadow: 0 0 0 2px var(--ring);
+}
+.dj-lightbox .yarl__navigation_prev,
+.dj-lightbox .yarl__navigation_next {
+  margin: 0 12px;
+  padding: 12px;
+}
+
+.dj-lightbox .yarl__counter {
+  padding: 4px 12px;
+  color: var(--foreground);
+  font-size: var(--text-sm);
+  font-variant-numeric: tabular-nums;
+}
+
+/* The image says what a double-click does: zoom in at rest, a hand to pan once
+   zoomed. (A permanent hand promised a pan that had nowhere to go.) */
+.dj-lightbox .yarl__slide_image {
+  cursor: zoom-in;
+}
+.dj-lightbox--zoomed .yarl__slide_image {
+  cursor: grab;
+}
+.dj-lightbox--zoomed .yarl__slide_image:active {
+  cursor: grabbing;
+}

package/src/image-viewer/types.ts

@@ -87,6 +87,34 @@ export interface ImageViewerProps {
   copy?: Partial<MediaCopy>;
 }
 
+/** One slide of `ImageLightbox`: an address, never raw bytes. */
+export interface LightboxImage {
+  /** Image URL. */
+  src: string;
+  /** Shown as the alt text and used as the saved file's name. */
+  name: string;
+  /** Intrinsic size when known: lets the engine lay out before the bytes arrive. */
+  width?: number;
+  height?: number;
+  /** Same-origin address the SAVE button reads (see `ImageItem.downloadSrc`). */
+  downloadSrc?: string;
+}
+
+export interface ImageLightboxProps {
+  images: LightboxImage[];
+  /** Controlled visibility. */
+  open: boolean;
+  /** Slide on screen (default 0). */
+  index?: number;
+  /** Esc, backdrop click, pull-down or the close button. */
+  onClose: () => void;
+  onIndexChange?: (index: number) => void;
+  /** Thumbnail strip for more than one image (default true). */
+  thumbnails?: boolean;
+  /** Override any subset of the widget's English copy. */
+  copy?: Partial<MediaCopy>;
+}
+
 export interface ImageToolbarProps {
   /** Current zoom scale */
   scale: number;

package/src/image-viewer/utils/constants.ts

@@ -62,8 +62,11 @@ export const WHEEL_SMOOTH_STEP = 0.0055;
 /** Touch pinch sensitivity (two-finger pinch on touchscreens). */
 export const PINCH_STEP = 5;
 
-/** Double-click / double-tap zoom multiplier (fit ↔ zoomed toward the point). */
-export const DOUBLE_CLICK_STEP = 1.4;
+/** Scale a double-click / double-tap zooms to, centred on the pointer. */
+export const DOUBLE_CLICK_ZOOM = 2.5;
+
+/** Within this of fit (scale 1) the image counts as "at rest". */
+export const FIT_EPSILON = 0.02;
 
 /** Idle delay (ms) before the lightbox chrome fades out when the pointer rests. */
 export const CHROME_IDLE_MS = 2200;

package/src/image-viewer/utils/index.ts

@@ -14,7 +14,8 @@ export {
   KEYBOARD_PAN_STEP,
   WHEEL_SMOOTH_STEP,
   PINCH_STEP,
-  DOUBLE_CLICK_STEP,
+  DOUBLE_CLICK_ZOOM,
+  FIT_EPSILON,
   CHROME_IDLE_MS,
   ZOOM_PRESETS,
   DEFAULT_TRANSFORM,

package/src/index.ts

@@ -7,4 +7,4 @@
 // undo the split silently.
 export * from "./image-viewer";
 export type { MediaCopy } from "./i18n";
-export { DEFAULT_MEDIA_COPY } from "./i18n";
+export { DEFAULT_MEDIA_COPY, MEDIA_DICTIONARIES, useMediaCopy } from "./i18n";