@pharos-ds/core 0.1.9

package/src/hooks/useHotkeys.test.ts

@@ -0,0 +1,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useHotkeys.test.ts
+ * @input Uses vitest, @testing-library/react, useHotkeys hook
+ * @output Unit tests for useHotkeys hook
+ * @position Testing; validates useHotkeys.ts implementation
+ *
+ * SYNC: When useHotkeys.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {renderHook} from '@testing-library/react';
+import {useHotkeys, type Hotkey} from './useHotkeys';
+
+function stubApplePlatform() {
+  // jsdom's navigator has no userAgentData; platform drives detection.
+  vi.stubGlobal('navigator', {platform: 'MacIntel'});
+}
+
+function stubOtherPlatform() {
+  vi.stubGlobal('navigator', {platform: 'Win32'});
+}
+
+function press(
+  key: string,
+  init: KeyboardEventInit & {target?: HTMLElement} = {},
+): KeyboardEvent {
+  const {target, ...eventInit} = init;
+  const event = new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true,
+    ...eventInit,
+  });
+  (target ?? window).dispatchEvent(event);
+  return event;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  document.body.innerHTML = '';
+});
+
+describe('useHotkeys', () => {
+  it('fires on mod+k via metaKey on Apple platforms', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const event = press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(onPress).toHaveBeenCalledWith(event);
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it('maps mod to ctrlKey on non-Apple platforms', () => {
+    stubOtherPlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    press('k', {ctrlKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire a bare key when modifiers are held', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'k', onPress}]));
+
+    press('k', {metaKey: true});
+    press('k', {ctrlKey: true});
+    press('k', {altKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    press('k');
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('matches named keys: escape, enter, space, arrows', () => {
+    stubApplePlatform();
+    const onEscape = vi.fn();
+    const onEnter = vi.fn();
+    const onSpace = vi.fn();
+    const onDown = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'escape', onPress: onEscape},
+        {keys: 'enter', onPress: onEnter},
+        {keys: 'space', onPress: onSpace},
+        {keys: 'down', onPress: onDown},
+      ]),
+    );
+
+    press('Escape');
+    press('Enter');
+    press(' ');
+    press('ArrowDown');
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onEnter).toHaveBeenCalledTimes(1);
+    expect(onSpace).toHaveBeenCalledTimes(1);
+    expect(onDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('requires shift when specified and ignores shift otherwise', () => {
+    stubApplePlatform();
+    const onSlash = vi.fn();
+    const onLetter = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'shift+/', onPress: onSlash},
+        {keys: 'c', onPress: onLetter},
+      ]),
+    );
+
+    press('/');
+    expect(onSlash).not.toHaveBeenCalled();
+    press('/', {shiftKey: true});
+    expect(onSlash).toHaveBeenCalledTimes(1);
+
+    // Shift not specified → matches regardless of shift state.
+    press('C', {shiftKey: true});
+    press('c');
+    expect(onLetter).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips typing targets by default', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    press('k', {metaKey: true, target: input});
+    expect(onPress).not.toHaveBeenCalled();
+
+    const textarea = document.createElement('textarea');
+    document.body.appendChild(textarea);
+    press('k', {metaKey: true, target: textarea});
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('fires in typing targets when allowInInputs is true', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() =>
+      useHotkeys([{keys: 'escape', onPress, allowInInputs: true}]),
+    );
+
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    press('Escape', {target: input});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects isDisabled', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    const {rerender} = renderHook(
+      ({isDisabled}: {isDisabled: boolean}) =>
+        useHotkeys([{keys: 'mod+k', onPress, isDisabled}]),
+      {initialProps: {isDisabled: true}},
+    );
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    rerender({isDisabled: false});
+    press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips events that are already defaultPrevented', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    const event = new KeyboardEvent('keydown', {
+      key: 'k',
+      metaKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    event.preventDefault();
+    window.dispatchEvent(event);
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribes on unmount', () => {
+    stubApplePlatform();
+    const onPress = vi.fn();
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+    const {unmount} = renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    unmount();
+    expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function));
+
+    press('k', {metaKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+  });
+
+  it('does not re-subscribe on re-render, but uses latest handlers', () => {
+    stubApplePlatform();
+    const addSpy = vi.spyOn(window, 'addEventListener');
+    const first = vi.fn();
+    const second = vi.fn();
+
+    const {rerender} = renderHook(
+      ({hotkeys}: {hotkeys: Hotkey[]}) => useHotkeys(hotkeys),
+      {initialProps: {hotkeys: [{keys: 'mod+k', onPress: first}]}},
+    );
+
+    const keydownSubscriptions = () =>
+      addSpy.mock.calls.filter(([type]) => type === 'keydown').length;
+    const initialCount = keydownSubscriptions();
+
+    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
+    rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
+    expect(keydownSubscriptions()).toBe(initialCount);
+
+    press('k', {metaKey: true});
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('only fires the first matching hotkey per event', () => {
+    stubApplePlatform();
+    const first = vi.fn();
+    const second = vi.fn();
+    renderHook(() =>
+      useHotkeys([
+        {keys: 'mod+k', onPress: first},
+        {keys: 'mod+k', onPress: second},
+      ]),
+    );
+
+    press('k', {metaKey: true});
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useHotkeys.ts

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useHotkeys.ts
+ * @input Uses React useEffect, useRef
+ * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts
+ * @position Core hook; used by consumers for app-level keyboard shortcuts
+ *
+ * Registers a single window keydown listener per hook instance. Handlers
+ * are kept in a ref so re-renders never re-subscribe (subscribe once on
+ * mount, unsubscribe on unmount). SSR-safe — window is only touched
+ * inside the effect.
+ *
+ * Skips events that are already handled (defaultPrevented) and events
+ * targeting typing surfaces (input, textarea, select, contenteditable)
+ * unless a hotkey opts in via `allowInInputs`.
+ *
+ * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
+ * ctrlKey elsewhere — mirrors the detection used by Kbd.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useHotkeys.doc.mjs
+ */
+
+import {useEffect, useRef} from 'react';
+
+/**
+ * A single keyboard shortcut registration.
+ */
+export interface Hotkey {
+  /**
+   * Key combo, e.g. 'mod+k', 'shift+/', 'c', 'escape'.
+   * 'mod' = ⌘ on macOS, Ctrl elsewhere.
+   *
+   * Format: '+'-separated modifiers (mod, ctrl, meta, shift, alt) followed
+   * by a final key compared case-insensitively against event.key.
+   * Named keys: 'escape', 'enter', 'space', 'up', 'down', 'left', 'right'
+   * (arrow names map to ArrowUp/ArrowDown/ArrowLeft/ArrowRight).
+   * Use 'plus' for a literal '+' key.
+   *
+   * Shift semantics: when 'shift' is not specified, shift state is ignored,
+   * so single letters match regardless of shift. When 'shift' is specified,
+   * shiftKey must be pressed and the final key is still compared against
+   * event.key — for punctuation that shift transforms (e.g. shift+/ produces
+   * '?' on US layouts), prefer registering the produced character instead.
+   */
+  keys: string;
+  /** Called when the combo matches. The event has preventDefault() applied. */
+  onPress: (event: KeyboardEvent) => void;
+  /**
+   * Fire even when focus is in an input/textarea/select/contenteditable.
+   * @default false
+   */
+  allowInInputs?: boolean;
+  /** Temporarily disable this hotkey without unregistering it. */
+  isDisabled?: boolean;
+}
+
+/** Aliases for the final key of a combo, normalized to event.key values. */
+const KEY_ALIASES: Record<string, string> = {
+  esc: 'escape',
+  space: ' ',
+  up: 'arrowup',
+  down: 'arrowdown',
+  left: 'arrowleft',
+  right: 'arrowright',
+  return: 'enter',
+  plus: '+',
+};
+
+/**
+ * Detects whether the current platform is macOS/iOS.
+ * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
+ * falls back to navigator.platform (deprecated but universally supported).
+ * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
+ */
+function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
+  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
+    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+  }
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
+}
+
+/**
+ * Whether the event target is a typing surface where global shortcuts
+ * should stay silent by default.
+ */
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+  if (target.isContentEditable) {
+    return true;
+  }
+  const tag = target.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+}
+
+/**
+ * Whether a keydown event matches a '+'-separated combo string.
+ */
+function matchesCombo(
+  keys: string,
+  event: KeyboardEvent,
+  isApple: boolean,
+): boolean {
+  const parts = keys
+    .toLowerCase()
+    .split('+')
+    .map(part => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    return false;
+  }
+
+  const key = parts[parts.length - 1];
+  const mods = new Set(parts.slice(0, -1));
+
+  const wantsMod = mods.has('mod');
+  const wantsCtrl = mods.has('ctrl') || (wantsMod && !isApple);
+  const wantsMeta = mods.has('meta') || (wantsMod && isApple);
+  const wantsAlt = mods.has('alt');
+  const wantsShift = mods.has('shift');
+
+  // Non-shift modifiers must match exactly so 'k' doesn't fire on 'mod+k'.
+  if (event.ctrlKey !== wantsCtrl) {
+    return false;
+  }
+  if (event.metaKey !== wantsMeta) {
+    return false;
+  }
+  if (event.altKey !== wantsAlt) {
+    return false;
+  }
+  // Shift is only enforced when specified — see Hotkey.keys docs.
+  if (wantsShift && !event.shiftKey) {
+    return false;
+  }
+
+  const expected = KEY_ALIASES[key] ?? key;
+  return event.key.toLowerCase() === expected;
+}
+
+/**
+ * Registers global keyboard shortcuts on window.
+ *
+ * A single keydown listener is attached per hook instance; the hotkey
+ * definitions live in a ref, so re-renders update behavior without
+ * re-subscribing. First matching hotkey wins per event.
+ *
+ * Accessibility (WCAG 2.1.4 — Character Key Shortcuts): a shortcut whose
+ * combo is a single unmodified character (letter, digit, punctuation or
+ * symbol — e.g. 'c' or '/') is easily triggered by accident by speech-input
+ * users and keyboard users with motor impairments. If you register one, you
+ * MUST also provide at least one of: (a) a way to turn the shortcut off,
+ * (b) a way to remap it to include a modifier, or (c) scope it so it is only
+ * active while the relevant component has focus. Prefer `mod`-based combos
+ * where possible; the `isDisabled` flag can back a user-facing off switch.
+ *
+ * @param hotkeys - Shortcut registrations to listen for.
+ *
+ * @example
+ * ```
+ * useHotkeys([
+ *   { keys: 'mod+k', onPress: () => openCommandPalette() },
+ *   { keys: 'escape', onPress: () => closePanel(), allowInInputs: true },
+ *   { keys: 'c', onPress: () => compose(), isDisabled: isModalOpen },
+ * ]);
+ * ```
+ */
+export function useHotkeys(hotkeys: Hotkey[]): void {
+  const hotkeysRef = useRef(hotkeys);
+
+  // Keep the latest definitions available to the stable listener.
+  useEffect(() => {
+    hotkeysRef.current = hotkeys;
+  });
+
+  useEffect(() => {
+    const isApple = isApplePlatform();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) {
+        return;
+      }
+      const isTyping = isTypingTarget(event.target);
+      for (const hotkey of hotkeysRef.current) {
+        if (hotkey.isDisabled) {
+          continue;
+        }
+        if (isTyping && !hotkey.allowInInputs) {
+          continue;
+        }
+        if (matchesCombo(hotkey.keys, event, isApple)) {
+          event.preventDefault();
+          hotkey.onPress(event);
+          return;
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, []);
+}

package/src/hooks/useImageMode.doc.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useImageMode',
+  displayName: 'useImageMode',
+  keywords: ['image', 'dark', 'light', 'mode', 'luminance', 'color', 'detect', 'theme', 'media', 'apca', 'contrast'],
+  params: [
+    {
+      name: 'src',
+      type: 'string | null | undefined',
+      description: 'Image source URL to analyze. When null/undefined, returns the fallback value.',
+      required: true,
+    },
+    {
+      name: 'options',
+      type: 'UseImageModeOptions',
+      description: 'Optional configuration for image analysis.',
+      required: false,
+    },
+    {
+      name: 'options.region',
+      type: 'ImageSampleRegion',
+      description: 'Region to sample within the image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to the full image.',
+      required: false,
+    },
+    {
+      name: 'options.threshold',
+      type: 'number',
+      description: 'Luminance threshold for the dark/light split. Below = dark, above = light.',
+      default: '0.5',
+      required: false,
+    },
+    {
+      name: 'options.fallback',
+      type: "'dark' | 'light' | null",
+      description: 'Fallback value while loading or on error.',
+      default: 'null',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'mode',
+      type: "'dark' | 'light' | null",
+      description: "Detected luminance mode of the image. Returns null while loading or if src is null/undefined.",
+    },
+  ],
+  usage: {
+    description:
+      'Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.',
+    bestPractices: [
+      { guidance: true, description: 'Pair with MediaTheme to automatically adapt text color over dynamic background images.' },
+      { guidance: true, description: 'Use the region option to sample only the area where text overlays will appear for more accurate results.' },
+      { guidance: false, description: 'Use for images that change rapidly (e.g., video frames); each src change triggers a new fetch and analysis.' },
+    ],
+  },
+  relatedComponents: ['MediaTheme'],
+  relatedHooks: ['useMediaQuery'],
+  importPath: '@pharos-ds/core/hooks',
+  category: 'media',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
+  paramDescriptions: {
+    src: 'image source URL to analyze. When null/undefined, returns fallback value.',
+    options: 'optional config for image analysis.',
+    'options.region': 'region to sample within image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to full image.',
+    'options.threshold': 'luminance threshold for dark/light split. Below = dark, above = light.',
+    'options.fallback': 'fallback value while loading / on error.',
+  },
+  returnDescriptions: {
+    mode: 'detected luminance mode of image. Returns null while loading / if src null/undefined.',
+  },
+  usage: {
+    description:
+      'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
+    bestPractices: [
+      { guidance: true, description: 'Pair w/ MediaTheme to automatically adapt text color over dynamic background images.' },
+      { guidance: true, description: 'Use region option to sample only area where text overlays will appear for more accurate results.' },
+      { guidance: false, description: 'Use for images that change rapidly (e.g. video frames); each src change triggers new fetch + analysis.' },
+    ],
+  },
+};

package/src/hooks/useImageMode.test.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useImageMode.test.ts
+ * @input Uses vitest, @testing-library/react, useImageMode hook
+ * @output Unit tests for useImageMode hook
+ * @position Testing; validates useImageMode.ts pixel-sampling + CORS behavior
+ *
+ * SYNC: When useImageMode.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {renderHook, waitFor, act} from '@testing-library/react';
+import {useImageMode} from './useImageMode';
+
+// jsdom has no fetch/createImageBitmap/OffscreenCanvas — stub them per test so
+// we can exercise the sampling path and the cross-origin failure path.
+
+/** Fill the sampled canvas with a flat RGB so perceptualLightness is deterministic. */
+function stubSamplingPipeline(rgb: [number, number, number]) {
+  // fetch resolves to a blob (same-origin / CORS-enabled image)
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => ({blob: async () => ({}) as Blob})),
+  );
+  vi.stubGlobal(
+    'createImageBitmap',
+    vi.fn(async () => ({width: 100, height: 100}) as ImageBitmap),
+  );
+  const [r, g, b] = rgb;
+  class FakeOffscreenCanvas {
+    constructor(
+      public width: number,
+      public height: number,
+    ) {}
+    getContext() {
+      return {
+        drawImage: vi.fn(),
+        getImageData: (_x: number, _y: number, w: number, h: number) => {
+          const data = new Uint8ClampedArray(w * h * 4);
+          for (let i = 0; i < data.length; i += 4) {
+            data[i] = r;
+            data[i + 1] = g;
+            data[i + 2] = b;
+            data[i + 3] = 255;
+          }
+          return {data};
+        },
+      };
+    }
+  }
+  vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas);
+}
+
+/** Simulate a cross-origin image with no CORS headers: fetch rejects. */
+function stubCorsBlockedFetch() {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => {
+      throw new TypeError(
+        'Failed to fetch: No Access-Control-Allow-Origin header',
+      );
+    }),
+  );
+  vi.stubGlobal('createImageBitmap', vi.fn());
+  vi.stubGlobal('OffscreenCanvas', class {});
+}
+
+describe('useImageMode', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('returns the fallback while no src is provided', () => {
+    const {result} = renderHook(() => useImageMode(null, {fallback: 'dark'}));
+    expect(result.current).toBe('dark');
+  });
+
+  it('samples a dark image and reports "dark"', async () => {
+    stubSamplingPipeline([10, 10, 10]);
+    const {result} = renderHook(() =>
+      useImageMode('data:image/png;base64,AAAA'),
+    );
+    await waitFor(() => expect(result.current).toBe('dark'));
+  });
+
+  it('samples a light image and reports "light"', async () => {
+    stubSamplingPipeline([240, 240, 240]);
+    const {result} = renderHook(() =>
+      useImageMode('data:image/png;base64,AAAA'),
+    );
+    await waitFor(() => expect(result.current).toBe('light'));
+  });
+
+  // ── Reproduction for BB-001 (cluster C6) ────────────────────────────────
+  // A cross-origin image with no `Access-Control-Allow-Origin` header cannot be
+  // fetched with `mode: 'cors'`, so the APCA sampling pipeline never runs and the
+  // hook silently stays on its fallback. This is why image-backed Thumbnail
+  // overlay/remove-button contrast is unreliable for hosted demo examples that
+  // point `src` at a non-CORS CDN URL.
+  it('stays on fallback when a cross-origin image cannot be sampled (CORS)', async () => {
+    stubCorsBlockedFetch();
+    const {result} = renderHook(() =>
+      useImageMode(
+        'https://pharos-ds.vercel.app/assets/moody-scene-vertical-2.png',
+        {fallback: null},
+      ),
+    );
+    // Give the rejected fetch + state update a chance to flush.
+    await act(async () => {
+      await new Promise(r => setTimeout(r, 0));
+    });
+    expect(result.current).toBeNull();
+  });
+
+  it('requests the image with CORS mode (the constraint that fails for non-CORS hosts)', async () => {
+    const fetchSpy = vi.fn(async () => {
+      throw new TypeError('CORS');
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+    vi.stubGlobal('createImageBitmap', vi.fn());
+    vi.stubGlobal('OffscreenCanvas', class {});
+    renderHook(() => useImageMode('https://cross-origin.example/x.png'));
+    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://cross-origin.example/x.png',
+      {mode: 'cors'},
+    );
+  });
+});