react-zmage: Instructions file for Codex

AGENTS.md — react-zmage

给 AI Agent / LLM 编排用的浓缩版项目信息。 人类完整文档见 README.md。

Works

如果你发现工作区中有额外变更, 始终假定是另一个 AI Agent 在当前分支中同步工作, 你需要做的是优先处理重突 (如果有) 并遵循工作互不干涉原则

如果非用户主动要求, 不允许在 worktree 上执行改动。

What this package does (1 sentence)

A React component that turns any <img> into a fullscreen-zoomable, multi-image, keyboard-navigable image viewer. Drop-in replacement for <img>.

Public API surface (treat as contract)

// Default + statics
import Zmage from 'react-zmage'                  // browser / bundler entry
import Zmage from 'react-zmage/ssr'              // SSR / RSC entry
import 'react-zmage/style.css'                   // required for visuals

// Types (also exported from the same module)
import type {
  BaseType,                  // union of all props (use this when typing config objects)
  ReactZmageComponent,       // typeof Zmage
  Set,                       // shape of items in `set` prop
  Preset,                    // 'desktop' | 'mobile' | 'auto' (auto = matchMedia-driven)
  ControllerSet, ControllerPlacement, ControllerOverlayLayout, ControllerLayoutTargets,
  ControllerLayoutTarget, ControllerLayoutInset, ControllerLayoutInsetValue, ControllerRender, ControllerRenderState,
  ControllerRenderActions, ControllerRenderSlots, HotKey, Animate, AnimateFlip, AnimateCoverOptions,
  GestureSet, GestureSwipeOptions, GestureDragExitOptions, GestureWheelZoomOptions,
  GesturePinchZoomOptions, GestureDoubleTapZoomOptions, GestureTouchAction,
} from 'react-zmage'

// Three usage modes
<Zmage src="..." />                                  // 1. Component
Zmage.browsing(props): () => void                    // 2. Imperative; returns destructor
<Zmage.Wrapper>{children}</Zmage.Wrapper>            // 3. Auto-attach to <img> in children

// Ref forwarding
const ref = useRef<HTMLImageElement>(null)
<Zmage src="..." ref={ref} />                        // ref points to the cover <img>

Required peer deps

• react: >=16.8.0 <20
• react-dom: >=16.8.0 <20