@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/hooks/useAutoMediaMode.ts

@@ -6,33 +6,20 @@
  * @file useAutoMediaMode.ts
  * @input Ref to the element whose backdrop should be measured
  * @output 'dark' | 'light' | null (not yet measurable)
- * @position INTERNAL — powers `MediaTheme mode="auto"`. Not exported from the
- *   package: MediaTheme is the supported surface for this behavior.
- *   Sibling to useImageMode, which answers the same question for images.
- *
- * Picks the media context a surface wants by measuring what the browser
- * actually painted, rather than trusting a token's name.
- *
- * The bug it exists for: `--color-background-inverted` is not required to be
- * inverted. A theme can define it as a pale grey, and a hardcoded
- * `mode="dark"` then paints white text on it at 1.25:1. Because the surface
- * colour is a runtime value and the mode is a compile-time guess, no amount
- * of care in the component can catch that.
- *
- * The answer can also be `'off'`: when the surface's own ambient text already
- * reads on it, the surface is not effectively inverted and does not want a
- * media context. Verified in Chromium that this loses nothing on a surface
- * that is chromatic but legible — the dark-mode error toast renders
- * identically either way, because a dark page already resolves those tokens
- * to the values the media context would install.
- *
- * @example
- * ```
- * // Inside MediaTheme; see its `mode="auto"`.
- * const detected = useAutoMediaMode(ref, mode === 'auto');
- * ```
+ * @position Internal; powers `MediaTheme mode="auto"`. Not exported from the
+ *   package. Sibling to useImageMode, which does the same for images.
  */
 
+// The hook measures what the browser painted and does not trust a token's
+// name. `--color-background-inverted` need not be inverted: a theme can make
+// it pale grey, and a fixed `mode="dark"` then paints white text on it at
+// 1.25:1. The surface color is a runtime value, so only a measurement can
+// catch this.
+//
+// The answer can be `'off'` when the surface's own text already reads on it.
+// A dark page already resolves those tokens to the media context's values,
+// so a chromatic but legible surface loses nothing.
+
 import {useRef, useState} from 'react';
 import type {RefObject} from 'react';
 import type {RGBA} from '../utils/color';
@@ -45,17 +32,11 @@ import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 export type DetectedMediaMode = 'dark' | 'light' | 'off';
 
 /**
- * Resolve token references to the colors they actually paint, by reading them
- * back off a hidden probe.
- *
- * A custom property cannot simply be read: `getPropertyValue` returns the
- * token's *specified* text, and Astryx tokens are `light-dark(a, b)` pairs
- * that resolve only once used in a real property. The probe assigns each
- * token to `color` and reads the computed value back, which the browser has
- * resolved against the host's own color-scheme and any overrides.
- *
- * `display: none` keeps the probe out of layout — computed color still
- * resolves — so this costs a style recalc and no reflow.
+ * Resolve token references to the colors they paint, through a hidden probe.
+ * `getPropertyValue` returns a token's specified text, and Astryx tokens are
+ * `light-dark(a, b)` pairs that resolve only in a real property. The probe
+ * sets each token as `color` and reads the computed value. `display: none`
+ * keeps the probe out of layout, so this costs a style recalc and no reflow.
  */
 function resolvePaintedColors(
   host: HTMLElement,
@@ -116,14 +97,11 @@ function resolveBackdrop(element: HTMLElement): RGBA | null {
 }
 
 /**
- * Contrast at which a surface's own ambient text counts as reading well
- * enough that no media context is wanted.
- *
- * WCAG's non-text / large-text line. It is deliberately low: this decides
- * whether a surface is *effectively inverted*, not whether its text meets a
- * standard. A pairing that clears 3:1 is one the theme is rendering
- * successfully, and swapping in a media context there changes accent,
- * overlays and borders for no legibility gain.
+ * Contrast at which a surface's own text reads well enough that no media
+ * context is wanted. This is WCAG's large-text line. It is low on purpose: it
+ * decides if a surface is effectively inverted, not if its text meets a
+ * standard. A media context on a 3:1 pairing changes accent, overlays and
+ * borders with no legibility gain.
  */
 const AMBIENT_READS_AT = 3;
 
@@ -182,12 +160,10 @@ export function useAutoMediaMode(
   const {tokens} = useTheme();
   const lastRef = useRef<{background: string; tokens: unknown} | null>(null);
 
-  // Deliberately no dependency array. A surface's color is a painted value:
-  // it changes when a prop on some ancestor changes, and no dependency this
-  // hook could name would catch that (an earlier revision took a `watch`
-  // array and silently went stale whenever a caller forgot an entry). So the
-  // measurement re-runs whenever anything re-renders, and skips its own
-  // expensive half when nothing moved — see the early return below.
+  // No dependency array. A surface color is a painted value, and it changes
+  // when a prop on some ancestor changes. No dependency that this hook can
+  // name catches that. So the measurement runs on each render, and it skips
+  // its expensive half when nothing moved (see the early return below).
   useIsomorphicLayoutEffect(() => {
     const surface = ref.current?.parentElement ?? null;
     if (!isEnabled || surface === null) {
@@ -199,10 +175,9 @@ export function useAutoMediaMode(
       return;
     }
 
-    // The backdrop walk above is a couple of getComputedStyle reads; the
-    // probe below appends a node and forces another style resolution. Skip
-    // it when neither the painted backdrop nor the theme has moved, which is
-    // the overwhelmingly common render.
+    // The probe adds a node and forces another style resolution. Skip it when
+    // neither the painted backdrop nor the theme moved, which is the usual
+    // case.
     const backgroundKey = formatColor(background);
     const last = lastRef.current;
     if (

package/src/hooks/useBusyAnnouncement.ts

@@ -8,24 +8,19 @@
  *   to an element inside the control
  * @output Announces each busy start once, through the shared polite channel
  *   or a persistent region inside the open modal dialog holding the control
- * @position Core a11y hook for controls that show a decorative busy Spinner
- *
- * The busy Spinner inside a control is decorative (hidden, no live role); the
- * control announces its busy state instead (`spec:AST-086` FR8), once per busy
- * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
- * re-arms it. The returned function is called by an owner announcing the
- * busy operation's outcome: a busy start not yet announced is dropped, so it
- * never follows its own outcome (FR8). While a native modal is open, the body-level channel is not
- * exposed, so a control inside it announces through that dialog's polite
- * container, the one `useAnnounce` uses for every message from inside the
- * modal (FR14), inserted empty and filled a frame later (FR3); the control's
- * own element locates the modal, so a busy start inside a native modal an app
- * renders without Astryx is heard inside it too.
- *
- * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
- * this is a shared implementation detail of Astryx's busy controls.
+ * @position Core a11y hook for controls that show a decorative busy Spinner.
+ *   It is a shared detail of the busy controls, so it is not in hooks/index.ts.
  */
 
+// The busy Spinner is decorative, so the control announces its busy state,
+// once for each busy start (AST-086). A re-render or a StrictMode replay does
+// not repeat it, and the settle re-arms it. An owner calls the returned function
+// when it announces the outcome. A busy start that is not yet announced is
+// then dropped, so it never follows its own outcome. While a native modal is
+// open, the page-body channel is not exposed. So a control in a modal
+// announces through that dialog's polite region, also in a modal that an app
+// renders without Astryx.
+
 import {useCallback, useEffect, useRef, type RefObject} from 'react';
 import {
   announceInModal,
@@ -65,10 +60,8 @@ export function useBusyAnnouncement(
     const frame = requestAnimationFrame(() => {
       frameRef.current = null;
       hasAnnouncedRef.current = true;
-      // The nearest open native modal around the control's own element,
-      // Astryx or app-rendered, so a busy start inside a modal an app renders
-      // without Astryx is still heard inside it (`spec:AST-086` FR14); the
-      // shared `useAnnounce` route otherwise, which itself follows the
+      // The nearest open native modal around the control's element, Astryx or
+      // app-rendered. Else the shared `useAnnounce` route, which follows the
       // nearest Astryx modal around this hook's caller.
       const dialog = enclosingModalDialog(elementRef.current);
       if (dialog != null) {

package/src/hooks/useClickableContainer.ts

@@ -5,24 +5,27 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
- * @position Core hook for clickable containers that safely handle nested interactive elements
- *
- * Solves the "nested interactive elements" problem: when a card is clickable
- * but contains buttons/links, clicking those should NOT trigger the card's action.
- *
- * Every navigation exit here (window.open, location.href, and the delegated
- * click on the interactive ref) runs after the shared navigation-destination
- * rule in utils/safeUrl.ts; a blocked href does not navigate by any
- * activation method.
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
+ * @position Core hook for clickable containers with nested interactive
+ *   elements. A click on a nested button or link does not run the card's
+ *   action. Each navigation passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
  */
 
 import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';
+import {isLayerSurface} from '../Layer/layerSurfacePress';
 import {isSafeUrl} from '../utils/safeUrl';
 
+/**
+ * The attribute this hook sets on the container it makes clickable. A click
+ * inside a nested marked container belongs to that container (see
+ * INTERACTIVE_SELECTORS).
+ */
+export const PRESSABLE_CONTAINER_ATTRIBUTE = 'data-pressable-container';
+
 /**
  * Canonical list of interactive element selectors — native controls plus
  * role-based interactive elements. Clicks on these (or their descendants)
@@ -52,34 +55,67 @@ export const INTERACTIVE_SELECTORS = [
   '[role="listbox"]',
   '[role="slider"]',
   '[role="spinbutton"]',
-  '[data-pressable-container]',
+  `[${PRESSABLE_CONTAINER_ATTRIBUTE}]`,
 ].join(',');
 
 const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
 
 /**
- * Check whether an element has an interactive ancestor between it and the root.
- * If the click target is inside a nested button/link/etc., we should NOT
- * handle it at the container level.
+ * Whether this element is interactive by INTERACTIVE_SELECTORS: a control,
+ * link, editor, or nested clickable container, and not marked read-only.
+ */
+export function matchesInteractiveSelectors(element: Element): boolean {
+  return (
+    element.matches(INTERACTIVE_SELECTORS) &&
+    !element.matches(NON_INTERACTIVE_SELECTORS)
+  );
+}
+
+/**
+ * The innermost element, from `el` up to (not including) `rootEl` or the
+ * document body, that `isInteractive` accepts: by default the
+ * INTERACTIVE_SELECTORS match. The one walk every "does this event belong
+ * to a control" check shares; a hover layer's tap passes its own test
+ * (useTouchTrigger's `tapLandsOnDisabledControl`).
+ */
+export function innermostInteractive(
+  el: Element,
+  rootEl: Element | null,
+  isInteractive: (element: Element) => boolean = matchesInteractiveSelectors,
+): Element | null {
+  let current: Element | null = el;
+  while (current != null && current !== rootEl && current !== document.body) {
+    if (isInteractive(current)) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Check whether an element has an interactive ancestor between it and the
+ * root (the element itself included). If the click target is inside a nested
+ * button/link/etc., we should NOT handle it at the container level.
  *
  * Exported for containers that cannot use the hook itself — a `<tr>` whose
  * props are assembled inside a Table plugin's `transformBodyRow`, for
  * instance, has no ref to hand the hook but needs the identical rule. Sharing
  * the walk keeps one definition of "this click belongs to something else"
  * instead of a short hand-rolled selector list per caller.
+ *
+ * A press inside an open Tooltip or HoverCard surface also answers true: it
+ * belongs to that surface, not the container around its trigger.
  */
 export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {
-  let current: Element | null = el;
-  while (current != null && current !== rootEl && current !== document.body) {
-    if (
-      current.matches(INTERACTIVE_SELECTORS) &&
-      !current.matches(NON_INTERACTIVE_SELECTORS)
-    ) {
-      return true;
-    }
-    current = current.parentElement;
-  }
-  return false;
+  return innermostInteractive(el, rootEl, belongsToSomethingElse) != null;
+}
+
+// hasInteractiveAncestor documents this answer until the next minor.
+// A layer root stops such a press before any bubble-phase React handler.
+// A native listener or a capture-phase handler still sees it.
+function belongsToSomethingElse(element: Element): boolean {
+  return matchesInteractiveSelectors(element) || isLayerSurface(element);
 }
 
 /**
@@ -164,7 +200,7 @@ export function useClickableContainer({
   useEffect(() => {
     const el = containerRef.current;
     if (el) {
-      el.setAttribute('data-pressable-container', 'true');
+      el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');
     }
   }, [containerRef]);
 
@@ -179,7 +215,6 @@ export function useClickableContainer({
         return;
       }
 
-      // Don't trigger on text selection
       if (hasTextSelection(containerEl)) {
         return;
       }
@@ -189,7 +224,6 @@ export function useClickableContainer({
         return;
       }
 
-      // If the click landed on or inside a nested interactive element, bail
       if (
         eventTarget !== event.currentTarget &&
         hasInteractiveAncestor(eventTarget, containerEl)
@@ -197,17 +231,15 @@ export function useClickableContainer({
         return;
       }
 
-      // Fire the click handler
       onClickProp?.(event);
       if (event.defaultPrevented) {
         return;
       }
 
-      // Navigate if href is provided. React DOM vets the hrefs it writes as
-      // attributes; nothing below passes through React, so the shared
-      // navigation rule decides once, before target, modifier key, or the
-      // delegated anchor can select a sink. A blocked href simply does not
-      // navigate — the click handler above still ran.
+      // React DOM checks the hrefs that it writes, but nothing below passes
+      // through React. So the shared navigation rule decides once, before the
+      // target, a modifier key, or the delegated anchor picks a sink. A
+      // blocked href does not navigate, but the click handler above still ran.
       if (href != null && isSafeUrl(href)) {
         const shouldOpenNewTab =
           target === '_blank' || event.ctrlKey || event.metaKey;

package/src/hooks/useContainerReveal.ts

@@ -4,42 +4,10 @@
 
 /**
  * @file useContainerReveal.ts
- * @input Uses the containerReveal styles
- * @output Exports useContainerReveal — a headless hover/focus reveal primitive
- * @position Core hook. Consumed by any component that reveals (or conceals)
- *   content when its container is hovered or focused — e.g. Thumbnail's remove
- *   button, TreeList row actions.
- *
- * Gives a container a scoped hover/focus-within trigger that reveals or
- * conceals content inside it, entirely in CSS (no hover state in JS, no
- * re-render on hover). The caller authors NO StyleX: the hook hands out the
- * container style and the matching content styles.
- *
- * Scoping is by inheritance: the container publishes its reveal state as
- * custom properties on itself and the content reads them, so a nested
- * container shadows its ancestor's state for its own subtree. See
- * containerReveal.stylex.ts.
- *
- * Two levers sit on top of the pointer, both still CSS-only. On the container:
- * `hoverDelay` (dwell before the reveal starts — the Tooltip / HoverCard
- * intent gate applied to a reveal) and `forceState` (pin the trigger state a
- * caller owns: a motion gate, a scroll, an open menu). On a single piece of
- * content: `forceVisibility`, which pins how THAT element looks. State belongs
- * to the container because one container feeds children whose looks are
- * opposite; appearance belongs to the element, where it is unambiguous.
- * Neither lever can hide content from a keyboard user — see ACCESSIBILITY.
- *
- * ACCESSIBILITY (WCAG 2.2 by construction):
- * - Revealed content is visually hidden at rest via position + opacity, so it
- *   stays in the accessibility tree and tab order — never display:none.
- * - Keyboard: revealed on :focus-within, so tabbing in shows it — with no dwell
- *   to wait through, and neither an inactive container nor a forced-hidden
- *   element can keep it dark.
- * - Touch: always visible on coarse pointers; never gated behind hover.
- * - Concealed (inverted) content is a mouse-only visual swap: it ignores
- *   :focus-within (a keyboard user must never watch content vanish) and stays
- *   visible on touch and in the a11y tree.
- * - Motion: honors prefers-reduced-motion.
+ * @input The containerReveal styles
+ * @output useContainerReveal, a headless hover and focus reveal primitive
+ * @position Core hook for content that shows or hides when its container is
+ *   hovered or focused, such as Thumbnail's remove button
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -138,6 +106,11 @@ const EMPTY = Object.freeze({});
 /**
  * Scoped, CSS-only hover/focus reveal for content inside a container.
  *
+ * Revealed content stays in the accessibility tree and the tab order. It
+ * shows on :focus-within without a delay, and it always shows on touch.
+ * Concealed content hides only for a mouse. Motion honors
+ * prefers-reduced-motion.
+ *
  * @example
  * ```
  * const {getContainerProps, getContentRevealProps} = useContainerReveal({

package/src/hooks/useDevWarning.ts

@@ -6,14 +6,9 @@
  * @file useDevWarning.ts
  * @input A component name, a message, and a boolean condition
  * @output Fires a dev-only `Component: message` warning once per mount
- * @position Core hook; the render-safe way to warn the builder from a component
- *
- * The right way to surface a dev guardrail from inside a component. A naive
- * `if (condition) console.warn(...)` in the render body repeats on every
- * render, and reaching for `useState` to gate it adds needless state and
- * re-renders. This hook uses a ref + effect: the warning fires once per mount
- * when the condition holds, never during render, and never triggers a
- * re-render. Messages use the standardized `Component: message` format.
+ * @position Core hook; the render-safe way to warn the builder from a component.
+ *   A ref and an effect fire the warning once per mount, never during
+ *   render, and without a re-render.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts

package/src/hooks/useEntryAnimation.ts

@@ -7,9 +7,7 @@
  * @output Exports useEntryAnimation hook for mount-only entry animations
  * @position Hook utility; consumed by FieldStatus and available to consumers
  *
- * Provides entry animations for conditionally rendered elements.
- * Only animates when the element is dynamically mounted after the initial
- * page paint — statically rendered elements on page load are not animated.
+ * It animates only an element that mounts after the first page paint.
  * Server-rendered elements hydrate without the entry style and never play it
  * (spec:AST-013 FR13).
  */

package/src/hooks/useFocusReturnVisibility.ts

@@ -4,35 +4,38 @@
 
 /**
  * @file useFocusReturnVisibility.ts
- * @input Uses the shared interaction-modality tracker
+ * @input The component's shared interaction-modality tracking
  * @output Preserves returned focus while suppressing pointer-only focus rings
  * @position Internal focus-return policy for adaptive overlays
  */
 
 import {useCallback, useState} from 'react';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import type {InteractionModalityTracking} from '../utils/interactionModality';
 
-export function useFocusReturnVisibility() {
+/**
+ * Pass the component's one modality tracking (its `ref` attached to the
+ * overlay's element or trigger) so the ring follows the last input in that
+ * element's own document (a same-origin iframe, a Document Picture-in-Picture
+ * window), not the page's.
+ */
+export function useFocusReturnVisibility({
+  readModality,
+}: Pick<InteractionModalityTracking, 'readModality'>) {
   const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
 
-  useInteractionModalityTracking();
-
   const prepareFocusReturn = useCallback(() => {
-    setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
-  }, []);
+    setIsFocusRingSuppressed(readModality() === 'pointer');
+  }, [readModality]);
 
   const resetFocusReturn = useCallback(() => {
     setIsFocusRingSuppressed(false);
   }, []);
 
   const onFocusReturnTargetFocus = useCallback(() => {
-    if (getInteractionModality() === 'keyboard') {
+    if (readModality() === 'keyboard') {
       setIsFocusRingSuppressed(false);
     }
-  }, []);
+  }, [readModality]);
 
   return {
     isFocusRingSuppressed,

package/src/hooks/useFocusTrap.ts

@@ -17,6 +17,7 @@
  */
 
 import {useCallback, useEffect, useRef} from 'react';
+import {isFocusLost} from '../utils/focusReturn';
 
 import {FOCUSABLE_SELECTOR} from './focusableSelector';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
@@ -324,14 +325,7 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      const active = doc.activeElement;
-      const focusWasLost =
-        active == null ||
-        active === doc.body ||
-        active === doc.documentElement ||
-        (container != null && container.contains(active));
-
-      if (!focusWasLost) {
+      if (!isFocusLost(container, doc)) {
         return;
       }
 

package/src/hooks/useHighlightedOptionScroll.ts

@@ -22,9 +22,7 @@ interface UseHighlightedOptionScrollOptions {
   getOptionId: (index: number) => string;
   /**
    * Current option count, when the list can change while open (filtered or
-   * min/max-clamped lists). A count change re-runs the scroll, matching the
-   * list-length dependency the per-component effects carried before this hook
-   * existed.
+   * min/max-clamped lists). A count change runs the scroll again.
    */
   itemCount?: number;
 }
@@ -33,7 +31,7 @@ interface UseHighlightedOptionScrollOptions {
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
  * option under the stationary pointer, whose mouseenter re-highlights and
- * scrolls again — a runaway auto-scroll loop with no user input (#6077).
+ * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
  */

package/src/hooks/useHotkeys.ts

@@ -4,22 +4,10 @@
 
 /**
  * @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) or during IME composition,
- * 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, through the same isApplePlatform util Kbd reads, so
- * displayed and handled shortcuts cannot disagree.
+ * @input React effects and refs
+ * @output useHotkeys hook and Hotkey interface for global keyboard shortcuts
+ * @position Core hook for app-level keyboard shortcuts. `mod` uses the same
+ *   isApplePlatform util as Kbd, so shown and handled shortcuts agree.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts

package/src/hooks/useImageMode.ts

@@ -7,31 +7,6 @@
  * @input Image source URL
  * @output Detected mode luminance: 'dark' | 'light' | null
  * @position Hook; used alongside MediaTheme for auto-detection
- *
- * Detects whether an image is predominantly dark or light by sampling
- * its pixels via OffscreenCanvas. Runs entirely off the paint path —
- * no visible canvas element, no layout thrash.
- *
- * Uses APCA perceptual lightness (sRGB linearization + power curve)
- * which handles saturated colors better than BT.709 gamma-luma or
- * WCAG 2 relative luminance.
- *
- * For regional detection (e.g. "what's the luminance where the text
- * overlay sits"), pass a `region` option to sample a specific area.
- *
- * @example
- * ```tsx
- * function ImageCard({ src }: { src: string }) {
- *   const mode = useImageMode(src);
- *   return (
- *     <div style={{ backgroundImage: `url(${src})` }}>
- *       <MediaTheme mode={mode ?? 'dark'}>
- *         <Text>Auto-detected text color</Text>
- *       </MediaTheme>
- *     </div>
- *   );
- * }
- * ```
  */
 
 import {useState, useEffect} from 'react';
@@ -72,18 +47,9 @@ export interface UseImageModeOptions {
 }
 
 /**
- * APCA perceptual lightness from sRGB values (0-255).
- *
- * Linearizes sRGB with a 2.4 exponent, computes luminance Y using
- * APCA coefficients (slightly refined from BT.709), then applies a
- * perceptual power curve (Y^0.56) that maps linear light to a scale
- * where 0.5 ≈ perceptual mid-gray.
- *
- * This outperforms both raw BT.709 gamma-luma and WCAG 2 relative
- * luminance for dark/light surface detection — especially on saturated
- * colors (reds, blues) where gamma-encoded luma overestimates brightness.
- *
- * Returns 0–1 where 0 is black, 1 is white.
+ * APCA perceptual lightness from sRGB values (0-255), from 0 (black) to 1
+ * (white). It handles saturated colors better than BT.709 gamma-luma or WCAG
+ * 2 relative luminance, which overestimate the brightness of reds and blues.
  */
 function perceptualLightness(r: number, g: number, b: number): number {
   const lin = (c: number) => Math.pow(c / 255, 2.4);
@@ -117,7 +83,6 @@ export function useImageMode(
 
     async function detect() {
       try {
-        // Load image as bitmap (async, doesn't block rendering)
         const response = await fetch(srcUrl, {mode: 'cors'});
         const blob = await response.blob();
         const bitmap = await createImageBitmap(blob);
@@ -126,7 +91,6 @@ export function useImageMode(
           return;
         }
 
-        // Determine source region
         const sx = region ? Math.round(region.x * bitmap.width) : 0;
         const sy = region ? Math.round(region.y * bitmap.height) : 0;
         const sw = region
@@ -136,9 +100,9 @@ export function useImageMode(
           ? Math.round(region.height * bitmap.height)
           : bitmap.height;
 
-        // Sample at a small size and average all pixels manually.
-        // OffscreenCanvas 1×1 drawImage can produce inaccurate results
-        // depending on the browser's resampling algorithm.
+        // Sample at a small size and average the pixels here. A 1×1
+        // OffscreenCanvas drawImage can be inaccurate, because browsers
+        // resample in different ways.
         const sampleSize = 10;
         const canvas = new OffscreenCanvas(sampleSize, sampleSize);
         const ctx = canvas.getContext('2d');
@@ -149,7 +113,6 @@ export function useImageMode(
         ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, sampleSize, sampleSize);
         const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize).data;
 
-        // Average all sampled pixels
         let totalR = 0,
           totalG = 0,
           totalB = 0;