cursedbelt 5.97.0 → 5.99.0

package/src/react/media/ImageOriginalToggle.tsx

@@ -0,0 +1,51 @@
+/**
+ * The "Original" toggle every image viewer shows beside its picture (forge task 3873).
+ * `imageOriginal.ts` holds what the choice MEANS; this is only how it is pressed.
+ *
+ * A pressed Button, because the choice is on/off — "always the original", or the web copy with
+ * the original once a zoom needs it — and it reads the way the video menu's "2160p · Original"
+ * does. 🔴 Never hidden: where the original cannot be drawn (a HEIC, a RAW) it is refused with
+ * the reason, which reaches a phone on a tap (`unavailableReason`).
+ */
+import type { ComponentPropsWithoutRef } from 'react';
+import { Button } from '../components/Button.js';
+import type { ImageOriginalControl } from './imageOriginal.js';
+
+export interface ImageOriginalToggleProps extends Omit<ComponentPropsWithoutRef<'button'>, 'children' | 'onClick'> {
+  /** From `useImageOriginal`. Null — the item has no original — draws nothing. */
+  control: ImageOriginalControl | null;
+  className?: string;
+  /** `ghost` inside a toolbar of ghost buttons (photos' zoom bar); `secondary` on its own over a picture. */
+  variant?: 'secondary' | 'ghost';
+  /** `md` beside a toolbar's other `md` buttons, so the row is one height (DESIGN FND-4); `sm` on its own over a picture. */
+  size?: 'sm' | 'md';
+}
+
+/** The hint for a live toggle: what pressing it does from here. */
+function hint(control: ImageOriginalControl): string {
+  if (control.pinned) return 'Showing the original at full resolution — press to show the web copy until you zoom past it';
+  return control.showing
+    ? 'Showing the original, because the zoom needed it — press to always show it'
+    : 'Showing the web copy; the original loads when you zoom past it — press to always show it';
+}
+
+export function ImageOriginalToggle({ control, className, variant = 'secondary', size = 'sm', ...rest }: ImageOriginalToggleProps) {
+  if (!control) return null;
+  return (
+    <Button
+      {...rest}
+      aria-pressed={control.pinned}
+      className={className}
+      data-showing={control.showing ? 'original' : 'web'}
+      loading={control.loading}
+      onClick={control.toggle}
+      size={size}
+      tooltip={hint(control)}
+      // A refused press is the reason's tap on a phone; a live one's words are already on it.
+      {...(control.unavailable ? { unavailableReason: control.unavailable, tooltipMobile: 'tap' as const } : {})}
+      variant={variant}
+    >
+      Original
+    </Button>
+  );
+}

package/src/react/media/VideoPlayer.spec.tsx

@@ -19,6 +19,7 @@ import {
   useLiveScrub,
   VideoPlayer,
 } from './VideoPlayer.js';
+import { bindVidstackQuality } from './vidstackQuality.js';
 
 afterEach(cleanup);
 
@@ -654,7 +655,11 @@ describe('🔴 hls.js is served from this bundle, never from a CDN', () => {
 
   test('the player wires it — an unwired prop leaves the CDN default in place', () => {
     const source = readFileSync(join(import.meta.dir, 'VideoPlayer.tsx'), 'utf8');
-    expect(/onProviderChange=\{preferBundledHls\}/.test(source)).toBe(true);
+    // Either the bare prop or a handler whose FIRST act is the call — the quality binding
+    // (task 3868) rides the same handler, after it.
+    expect(
+      /onProviderChange=\{(preferBundledHls\}|\(provider\) => \{\s*preferBundledHls\(provider\);)/.test(source),
+    ).toBe(true);
   });
 
   test('hls.js is imported LAZILY — a static import lands it in every consumer\'s entry chunk', () => {
@@ -681,3 +686,41 @@ describe('🔴 an answered source is not a slow one', () => {
     expect(queryByRole('status')).toBeNull();
   });
 });
+
+/**
+ * 🔴 The stage's quality choice (forge task 3868): Vidstack's hls.js gets the viewer's cap
+ * BEFORE it is built, and every engine it builds is bound to the menu's store.
+ */
+describe('bindVidstackQuality', () => {
+  test("Auto caps Vidstack's hls.js too, Max does not, and each instance is bound", async () => {
+    const { createVideoQualityStore, VIDEO_QUALITY_KEY } = await import('./videoQuality.js');
+    const store = createVideoQualityStore();
+    const bound: unknown[] = [];
+    const provider = (): { $$PROVIDER_TYPE: string; config: Record<string, unknown>; onInstance: (cb: unknown) => void } => ({
+      $$PROVIDER_TYPE: 'HLS',
+      config: { keep: 1 },
+      onInstance: (cb) => bound.push(cb),
+    });
+    localStorage.removeItem(VIDEO_QUALITY_KEY);
+    const auto = provider();
+    bindVidstackQuality(auto as never, store, true);
+    expect(auto.config).toEqual({ keep: 1, capLevelToPlayerSize: true });
+    localStorage.setItem(VIDEO_QUALITY_KEY, 'max');
+    const max = provider();
+    bindVidstackQuality(max as never, store, true);
+    expect(max.config.capLevelToPlayerSize).toBe(false);
+    expect(bound).toHaveLength(2);
+    localStorage.removeItem(VIDEO_QUALITY_KEY);
+  });
+
+  test("Safari's own HLS and the progressive copy say why nothing can be chosen", async () => {
+    const { createVideoQualityStore, NATIVE_HLS_REASON, NO_LADDER_REASON } = await import('./videoQuality.js');
+    const store = createVideoQualityStore();
+    bindVidstackQuality({ $$PROVIDER_TYPE: 'VIDEO' } as never, store, true);
+    expect(store.get()?.unavailable).toBe(NATIVE_HLS_REASON);
+    bindVidstackQuality({ $$PROVIDER_TYPE: 'VIDEO' } as never, store, false);
+    expect(store.get()?.unavailable).toBe(NO_LADDER_REASON);
+    bindVidstackQuality(null, store, true);
+    expect(store.get()).toBeNull();
+  });
+});

package/src/react/media/VideoPlayer.tsx

@@ -17,7 +17,14 @@ import {
   type DefaultVideoLayoutSlots,
   defaultLayoutIcons,
 } from '@vidstack/react/player/layouts/default';
-import { type MouseEvent as ReactMouseEvent, type RefObject, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type MouseEvent as ReactMouseEvent,
+  type RefObject,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import type { PlayableVideo } from 'cursedbelt-core/media';
 import {
   PLAYER_VOLUME_KEY,
@@ -35,6 +42,8 @@ import { BarButton, mergeSlots, sectionSlots } from './controlBar.js';
 import { takePlayhead } from './playheadHandoff.js';
 import { isSurfaceControl } from './surfaceGesture.js';
 import { chapterSpans, type ChapteredVideo, type VideoChapter } from './videoChapters.js';
+import { bindVidstackQuality, qualitySlots } from './vidstackQuality.js';
+import { createVideoQualityStore } from './videoQuality.js';
 
 /**
  * The reusable video player primitive. Consumes a {@link PlayableVideo} (URLs already
@@ -683,14 +692,16 @@ export function VideoPlayer({
   // Memoized because `slots` holds React elements: a fresh object every render remounts
   // Vidstack's whole layout, which drops the control bar mid-hover and restarts its
   // auto-hide timer on every state change the player makes (i.e. constantly, while playing).
+  const [qualityStore] = useState(createVideoQualityStore);
   const slots = useMemo(
     () =>
       mergeSlots(
         stepSlots(onStep, canStep),
         sectionSlots(video.chapters),
+        qualitySlots(qualityStore),
         fillWindowSlots(fillWindow, onFillWindowChange),
       ),
-    [onStep, canStep, video.chapters, fillWindow, onFillWindowChange],
+    [onStep, canStep, video.chapters, qualityStore, fillWindow, onFillWindowChange],
   );
 
   return (
@@ -719,7 +730,10 @@ export function VideoPlayer({
         // 🔴 The hls.js engine is served from this origin, not from jsdelivr. See
         // `preferBundledHls` — without it an adaptive ladder depends on a third-party CDN
         // and fails as a permanent spinner when that CDN is unreachable.
-        onProviderChange={preferBundledHls}
+        onProviderChange={(provider) => {
+          preferBundledHls(provider);
+          bindVidstackQuality(provider, qualityStore, typeof src !== 'string');
+        }}
         /* See {@link hlsErrorIsAnswer}. Typed `unknown` on purpose: `hls.js` is an OPTIONAL
            peer, so its `ErrorData` must not become a static type dependency of this file. */
         onHlsError={(detail: unknown) => {

package/src/react/media/VideoQualitySelect.spec.tsx

@@ -0,0 +1,47 @@
+/**
+ * 🔴 The quality menu is never hidden (forge task 3868): where nothing can be chosen it is
+ * disabled, and where a ladder exists it offers Auto · Max · each rung, the original named.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { cleanup, render } from '@testing-library/react';
+import { NATIVE_HLS_REASON, unavailableQuality, type VideoQualityControl } from './videoQuality.js';
+import { VideoQualitySelect } from './VideoQualitySelect.js';
+
+afterEach(cleanup);
+
+const control = (over: Partial<VideoQualityControl> = {}): VideoQualityControl => ({
+  levels: [
+    { height: 2160, original: true },
+    { height: 720, original: false },
+  ],
+  choice: 'auto',
+  playingHeight: 720,
+  unavailable: null,
+  select: () => {},
+  ...over,
+});
+
+describe('VideoQualitySelect', () => {
+  test("Auto says the rung it is showing, and the trigger is live", () => {
+    const view = render(<VideoQualitySelect control={control()} />);
+    const trigger = view.getByLabelText('Video quality');
+    expect(trigger.textContent).toContain('Auto (720p)');
+    expect(trigger.hasAttribute('disabled')).toBe(false);
+  });
+
+  test('a remembered height the film lacks shows as the rung it resolves to', () => {
+    const view = render(<VideoQualitySelect control={control({ choice: 1080 })} />);
+    expect(view.getByLabelText('Video quality').textContent).toContain('720p');
+  });
+
+  test("🔴 Safari's own HLS: disabled and visible, not absent", () => {
+    const view = render(<VideoQualitySelect control={unavailableQuality(NATIVE_HLS_REASON)} />);
+    const trigger = view.getByLabelText('Video quality');
+    expect(trigger.hasAttribute('disabled')).toBe(true);
+  });
+
+  test('before a source is attached it is drawn disabled', () => {
+    const view = render(<VideoQualitySelect control={null} />);
+    expect(view.getByLabelText('Video quality').hasAttribute('disabled')).toBe(true);
+  });
+});

package/src/react/media/VideoQualitySelect.tsx

@@ -0,0 +1,81 @@
+/**
+ * The quality menu every player surface shows — Auto · Max · each rung (forge task 3868).
+ * `videoQuality.ts` holds what the choices MEAN; this is only how one is picked.
+ *
+ * A {@link SelectField}, because choosing one value from a list is what it is for, and because
+ * its popover follows the full-screen element (`floatingContainer.ts`) — the one place a video's
+ * menu has to work.
+ *
+ * 🔴 Never hidden. Where nothing can be chosen (Safari's own HLS, a film with no ladder) it is
+ * disabled with the reason on hover (and on a tap), per the fleet's one-UI rule.
+ */
+import type { ComponentPropsWithoutRef } from 'react';
+import { SelectField } from '../components/SelectField.js';
+import { Tooltip } from '../components/Tooltip.js';
+import { cn } from '../lib/cn.js';
+import {
+  parseVideoQuality,
+  rungLabel,
+  serializeVideoQuality,
+  type VideoQualityControl,
+} from './videoQuality.js';
+
+export interface VideoQualitySelectProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children' | 'id'> {
+  /** `null` until the surface has attached a source — drawn disabled meanwhile. */
+  control: VideoQualityControl | null;
+  /** A form-field look (the focus viewer's transport) or a bare chip (inside a control bar). */
+  fieldStyle?: boolean;
+  className?: string;
+  /** The trigger's id, for a `<label htmlFor>`. */
+  id?: string;
+}
+
+/** The trigger's text for Auto: what it is showing right now, the way YouTube says it. */
+function autoLabel(playingHeight: number | null): string {
+  return playingHeight ? `Auto (${playingHeight}p)` : 'Auto';
+}
+
+export function VideoQualitySelect({ control, fieldStyle = true, className, id, ...rest }: VideoQualitySelectProps) {
+  const reason = control ? control.unavailable : 'Loading the video';
+  const playing = control?.playingHeight ?? null;
+  const groups = [
+    {
+      options: [
+        { value: 'auto', label: autoLabel(playing), description: "Adapts to the connection, up to the player's size" },
+        { value: 'max', label: 'Max', description: 'Adapts to the connection, up to the original' },
+      ],
+    },
+    ...(control && control.levels.length > 0
+      ? [{ label: 'Fixed', options: control.levels.map((level) => ({ value: String(level.height), label: rungLabel(level) })) }]
+      : []),
+  ];
+  const value = control ? serializeVideoQuality(control.choice) : 'auto';
+  // A remembered height this film has no rung for is still the viewer's choice; show it as
+  // the rung it resolves to rather than as a blank trigger.
+  const known = groups.some((group) => group.options.some((option) => option.value === value));
+  const shown = known ? value : String(control?.levels.find((l) => l.height <= Number(value))?.height ?? 'auto');
+  const field = (
+    <span {...rest} className={cn('inline-flex', className)}>
+      <SelectField
+        aria-label='Video quality'
+        className='w-auto'
+        disabled={Boolean(reason)}
+        fieldStyle={fieldStyle}
+        groups={groups}
+        {...(id ? { id } : {})}
+        onValueChange={(next) => control?.select(parseVideoQuality(next))}
+        size='sm'
+        value={shown}
+      />
+    </span>
+  );
+  // A disabled trigger fires no pointer events, so the reason hangs off the wrapper — and taps
+  // through on touch, because an iPhone is exactly where Safari's own HLS disables it.
+  return reason ? (
+    <Tooltip content={reason} mobile='tap' multiline>
+      {field}
+    </Tooltip>
+  ) : (
+    field
+  );
+}

package/src/react/media/hlsSource.spec.ts

@@ -86,3 +86,13 @@ describe('attachHlsSource — every road ends at something playable', () => {
     }
   });
 });
+
+describe('the quality control a surface draws (task 3868)', () => {
+  test("🔴 Safari's own HLS reports a menu that can choose nothing, and why — never no menu", async () => {
+    const { NATIVE_HLS_REASON, NO_LADDER_REASON } = await import('./videoQuality.js');
+    const reasons: (string | null)[] = [];
+    attachHlsSource(videoEl(true), { hlsUrl: LADDER, streamUrl: REMUX }, { onQuality: (c) => reasons.push(c.unavailable) })();
+    attachHlsSource(videoEl(true), { streamUrl: REMUX }, { onQuality: (c) => reasons.push(c.unavailable) })();
+    expect(reasons).toEqual([NATIVE_HLS_REASON, NO_LADDER_REASON]);
+  });
+});

package/src/react/media/hlsSource.ts

@@ -83,8 +83,17 @@
  * starting bandwidth estimate makes it open on the bottom rung and climb. Both are widened
  * below, each with its number's reason on the line.
  */
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { probeSourceFault, type SourceFault, sourceFaultFromStatus } from './sourceFault.js';
+import {
+  bindHlsQuality,
+  type HlsQualityEngine,
+  NATIVE_HLS_REASON,
+  NO_LADDER_REASON,
+  readVideoQuality,
+  unavailableQuality,
+  type VideoQualityControl,
+} from './videoQuality.js';
 
 /**
  * The shape of an hls.js `ERROR` payload this module reads.
@@ -118,6 +127,12 @@ export interface HlsSourceHooks {
    * film that is about to start watching is worse off than one told nothing.
    */
   onFault?: (fault: SourceFault, source: HlsSourceKind) => void;
+  /**
+   * The viewer's quality choice and the ladder's rungs, each time either changes — what a
+   * surface's quality menu draws (`VideoQualitySelect`, task 3868). On Safari's own HLS and on
+   * the progressive copy it reports a control that can choose nothing, with the reason.
+   */
+  onQuality?: (control: VideoQualityControl) => void;
 }
 
 /** Which URLs a surface has for one video. `streamUrl` is the one that always exists. */
@@ -208,6 +223,10 @@ export const HLS_CONFIG = {
    * draw it at a quarter of its pixels. hls.js caps the level at the element's size times
    * `devicePixelRatio`, and re-evaluates when the player grows, so full screen on a 4K screen
    * still reaches the master. The owner: *"lower bandwidth usage"*.
+   *
+   * 🔴 This is the AUTO choice's cap, and only its (task 3868): the viewer's remembered choice
+   * (`videoQuality.ts`) turns it off for Max or a fixed rung, because a windowed player held to
+   * 480/720 on any connection was the blur the owner kept seeing.
    */
   capLevelToPlayerSize: true,
   /** A cold segment off the tunnel can take seconds; 20 s (the default) times out a fetch
@@ -251,6 +270,7 @@ export function attachHlsSource(
     engine?.destroy();
     engine = null;
     el.src = urls.streamUrl;
+    hooks.onQuality?.(unavailableQuality(NO_LADDER_REASON));
     if (at > 0) {
       // `loadedmetadata` is the first moment a seek on a fresh source is honored; setting
       // `currentTime` before it is silently dropped.
@@ -306,6 +326,7 @@ export function attachHlsSource(
   if (urls.hlsUrl && canPlayHlsNatively(el)) {
     attached = 'ladder';
     el.src = urls.hlsUrl;
+    hooks.onQuality?.(unavailableQuality(NATIVE_HLS_REASON));
   } else if (urls.hlsUrl) {
     // ~525 KB, and only this branch needs it — see `preferBundledHls` for why it is never a
     // top-level import and never a CDN.
@@ -314,10 +335,13 @@ export function attachHlsSource(
         if (destroyed) return;
         if (!Hls.isSupported()) {
           el.src = urls.streamUrl;
+          hooks.onQuality?.(unavailableQuality(NO_LADDER_REASON));
           return;
         }
-        const hls = new Hls(HLS_CONFIG);
+        // The cap is the Auto choice's; a viewer who chose Max never loads a capped first rung.
+        const hls = new Hls({ ...HLS_CONFIG, capLevelToPlayerSize: readVideoQuality() === 'auto' });
         engine = hls;
+        if (hooks.onQuality) bindHlsQuality(hls as unknown as HlsQualityEngine, hooks.onQuality);
         let spent = 0;
         hls.on(Hls.Events.ERROR, (_event: unknown, data: HlsErrorData) => {
           // Non-fatal errors are hls.js's own retry machinery working. Reacting to them would
@@ -388,10 +412,13 @@ export function attachHlsSource(
       })
       .catch(() => {
         // The library is genuinely unavailable. The remux still plays.
-        if (!destroyed) el.src = urls.streamUrl;
+        if (destroyed) return;
+        el.src = urls.streamUrl;
+        hooks.onQuality?.(unavailableQuality(NO_LADDER_REASON));
       });
   } else {
     el.src = urls.streamUrl;
+    hooks.onQuality?.(unavailableQuality(NO_LADDER_REASON));
   }
 
   return () => {
@@ -405,7 +432,8 @@ export function attachHlsSource(
 }
 
 /**
- * {@link attachHlsSource} as an effect, re-attaching whenever either URL changes.
+ * {@link attachHlsSource} as an effect, re-attaching whenever either URL changes. Returns the
+ * quality control for the surface's menu (`VideoQualitySelect`) — `null` until attached.
  *
  * 🔴 `onFault` is held in a REF, not listed as a dependency. A consumer passing the inline
  * arrow this hook invites would otherwise tear the engine down and re-attach it on every
@@ -415,9 +443,10 @@ export function attachHlsSource(
 export function useHlsSource(
   ref: { current: HTMLVideoElement | null },
   urls: HlsSourceUrls,
-  hooks: HlsSourceHooks = {},
-): void {
+  hooks: Pick<HlsSourceHooks, 'onFault'> = {},
+): VideoQualityControl | null {
   const { hlsUrl, streamUrl } = urls;
+  const [quality, setQuality] = useState<VideoQualityControl | null>(null);
   const { onFault } = hooks;
   const faultRef = useRef(onFault);
   useEffect(() => {
@@ -429,13 +458,18 @@ export function useHlsSource(
   useEffect(() => {
     const el = ref.current;
     if (!el) return;
+    setQuality(null);
     return attachHlsSource(
       el,
       { hlsUrl, streamUrl },
-      listening ? { onFault: (fault, source) => faultRef.current?.(fault, source) } : {},
+      {
+        onQuality: setQuality,
+        ...(listening ? { onFault: (fault: SourceFault, source: HlsSourceKind) => faultRef.current?.(fault, source) } : {}),
+      },
     );
     // `ref` and `faultRef` are stable objects; the URLs are what a re-attach depends on.
   }, [ref, hlsUrl, streamUrl, listening]);
+  return quality;
 }
 
 /**

package/src/react/media/imageOriginal.spec.tsx

@@ -0,0 +1,183 @@
+/**
+ * 🔴 A picture's original past its web copy (forge task 3873): fetched when the picture is drawn
+ * with more device pixels than the web copy holds or when the viewer pinned it, drawn only once
+ * it has DECODED, refused with the reason for a type no browser draws, and remembered per viewer.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render, renderHook } from '@testing-library/react';
+import {
+  IMAGE_ORIGINAL_KEY,
+  ORIGINAL_FAILED_REASON,
+  originalNeeded,
+  originalUndrawableReason,
+  readImageOriginalPinned,
+  writeImageOriginalPinned,
+} from './imageOriginal.js';
+import { ImageOriginalToggle } from './ImageOriginalToggle.js';
+import { type UseImageOriginalOptions, useImageOriginal } from './useImageOriginal.js';
+
+const WEB = 'https://x/a.jpg.web.jpg';
+const ORIGINAL = 'https://x/a.jpg';
+
+/** Every off-screen decode, held open until the spec settles it. */
+let decodes: { url: string; resolve: () => void; reject: () => void }[] = [];
+const RealImage = globalThis.Image;
+
+beforeEach(() => {
+  decodes = [];
+  localStorage.clear();
+  class FakeImage {
+    decoding = '';
+    src = '';
+    decode(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        decodes.push({ url: this.src, resolve: () => resolve(), reject: () => reject(new Error('decode')) });
+      });
+    }
+  }
+  globalThis.Image = FakeImage as unknown as typeof Image;
+});
+afterEach(() => {
+  cleanup();
+  globalThis.Image = RealImage;
+  localStorage.clear();
+});
+
+const options = (over: Partial<UseImageOriginalOptions> = {}): UseImageOriginalOptions => ({
+  src: WEB,
+  originalSrc: ORIGINAL,
+  mime: 'image/jpeg',
+  name: 'a.jpg',
+  drawnWidth: 1200,
+  webWidth: 2560,
+  ...over,
+});
+
+describe('originalUndrawableReason', () => {
+  test('a JPEG, PNG or WebP is drawable', () => {
+    expect(originalUndrawableReason('image/jpeg', 'a.jpg')).toBeNull();
+    expect(originalUndrawableReason('image/png', 'a.png')).toBeNull();
+    expect(originalUndrawableReason('image/webp', null)).toBeNull();
+  });
+  test('a HEIC, a TIFF and a camera RAW are refused with the reason — by mime or by name', () => {
+    expect(originalUndrawableReason('image/heic', 'IMG_1.HEIC')).toContain('HEIC');
+    expect(originalUndrawableReason('application/octet-stream', 'IMG_1.HEIC')).toContain('HEIC');
+    expect(originalUndrawableReason('image/tiff', 'scan.tif')).toContain('TIFF');
+    expect(originalUndrawableReason('image/x-adobe-dng', 'a.dng')).toContain('camera RAW');
+    expect(originalUndrawableReason('', 'DSC_1.NEF')).toContain('camera RAW');
+  });
+});
+
+describe('originalNeeded', () => {
+  test('a picture drawn inside the web copy needs nothing; past it, it needs the original', () => {
+    expect(originalNeeded(1200, 2560, 1)).toBe(false);
+    expect(originalNeeded(1200, 2560, 2)).toBe(false); // 2400 device px — inside the copy
+    expect(originalNeeded(1600, 2560, 2)).toBe(true); // a 5K screen, or a 1.33× zoom on a retina one
+    expect(originalNeeded(6000, 2560, 1)).toBe(true); // a zoom
+  });
+  test('nothing measured yet is never a reason to fetch 20 MB', () => {
+    expect(originalNeeded(0, 2560, 2)).toBe(false);
+    expect(originalNeeded(6000, 0, 2)).toBe(false);
+  });
+});
+
+describe('the remembered choice', () => {
+  test('is one key, per viewer, and absent means auto', () => {
+    expect(readImageOriginalPinned()).toBe(false);
+    writeImageOriginalPinned(true);
+    expect(localStorage.getItem(IMAGE_ORIGINAL_KEY)).toBe('original');
+    expect(readImageOriginalPinned()).toBe(true);
+    writeImageOriginalPinned(false);
+    expect(localStorage.getItem(IMAGE_ORIGINAL_KEY)).toBeNull();
+  });
+});
+
+describe('useImageOriginal', () => {
+  test('inside the web copy it draws the web copy and fetches nothing', () => {
+    const { result } = renderHook(() => useImageOriginal(options()));
+    expect(result.current.src).toBe(WEB);
+    expect(result.current.control?.showing).toBe(false);
+    expect(decodes).toHaveLength(0);
+  });
+
+  test('zoomed past the web copy it fetches the original — and keeps the web copy until it has decoded', async () => {
+    const { result, rerender } = renderHook((props: UseImageOriginalOptions) => useImageOriginal(props), {
+      initialProps: options(),
+    });
+    rerender(options({ drawnWidth: 6000 }));
+    expect(decodes.map((d) => d.url)).toEqual([ORIGINAL]);
+    expect(result.current.src).toBe(WEB);
+    expect(result.current.control?.loading).toBe(true);
+    await act(async () => decodes[0]?.resolve());
+    expect(result.current.src).toBe(ORIGINAL);
+    expect(result.current.control?.showing).toBe(true);
+    // Zooming back out keeps it: the bytes are here, and swapping back would only flicker.
+    rerender(options({ drawnWidth: 1200 }));
+    expect(result.current.src).toBe(ORIGINAL);
+  });
+
+  test('pinned, it draws the original at any size, and the pin is remembered', async () => {
+    const { result } = renderHook(() => useImageOriginal(options()));
+    act(() => result.current.control?.toggle());
+    expect(readImageOriginalPinned()).toBe(true);
+    expect(result.current.control?.pinned).toBe(true);
+    await act(async () => decodes[0]?.resolve());
+    expect(result.current.src).toBe(ORIGINAL);
+    act(() => result.current.control?.toggle());
+    expect(result.current.src).toBe(WEB);
+  });
+
+  test('a HEIC original is never fetched, and the control says why', () => {
+    writeImageOriginalPinned(true);
+    const { result } = renderHook(() =>
+      useImageOriginal(options({ mime: 'image/heic', name: 'IMG_1.HEIC', drawnWidth: 6000 })),
+    );
+    expect(result.current.src).toBe(WEB);
+    expect(result.current.control?.unavailable).toContain('HEIC');
+    expect(decodes).toHaveLength(0);
+  });
+
+  test('an original that fails to decode leaves the web copy up and says so', async () => {
+    const { result } = renderHook(() => useImageOriginal(options({ drawnWidth: 6000 })));
+    await act(async () => decodes[0]?.reject());
+    expect(result.current.src).toBe(WEB);
+    expect(result.current.control?.unavailable).toBe(ORIGINAL_FAILED_REASON);
+  });
+
+  test('no original, no control', () => {
+    const { result } = renderHook(() => useImageOriginal(options({ originalSrc: undefined, drawnWidth: 6000 })));
+    expect(result.current.control).toBeNull();
+    expect(result.current.src).toBe(WEB);
+  });
+});
+
+describe('ImageOriginalToggle', () => {
+  const control = {
+    pinned: false,
+    showing: false,
+    loading: false,
+    unavailable: null as string | null,
+    toggle: () => {},
+  };
+  test('a pressed toggle named Original, pressed when pinned', () => {
+    const view = render(<ImageOriginalToggle control={{ ...control, pinned: true }} />);
+    const button = view.getByRole('button', { name: 'Original' });
+    expect(button.getAttribute('aria-pressed')).toBe('true');
+    expect(button.getAttribute('aria-disabled')).not.toBe('true');
+  });
+  test('refused — visible, disabled — where the original cannot be drawn', () => {
+    const reason = originalUndrawableReason('image/heic', 'a.heic') as string;
+    const view = render(<ImageOriginalToggle control={{ ...control, unavailable: reason }} />);
+    expect(view.getByRole('button', { name: /Original/ }).getAttribute('aria-disabled')).toBe('true');
+  });
+  test('one height with the toolbar it sits in: md when asked, sm on its own', () => {
+    const md = render(<ImageOriginalToggle control={control} size='md' />).getByRole('button', { name: 'Original' });
+    cleanup();
+    const sm = render(<ImageOriginalToggle control={control} />).getByRole('button', { name: 'Original' });
+    expect(md.className).not.toBe(sm.className);
+  });
+  test('no control, nothing drawn', () => {
+    const view = render(<ImageOriginalToggle control={null} />);
+    expect(view.container.innerHTML).toBe('');
+  });
+});