自定义 Portal 挂载点: 新增 portalTarget，可以把查看器 Portal 挂到宿主应用的 overlay root、modal root、shadow host 或微前端容器。它只改变 DOM 父节点，查看器仍保持 fixed 全屏布局；需要调整层级时继续使用 zIndex。

import { useState } from 'react'
import Zmage from 'react-zmage'
import 'react-zmage/style.css'

export function GalleryImage() {
  const [viewerRoot, setViewerRoot] = useState<HTMLElement | null>(null)

  return (
    <>
      <div id="app-overlay-root" ref={setViewerRoot} />
      <Zmage src="/photo.jpg" alt="Photo" portalTarget={viewerRoot} />
    </>
  )
}

Custom Portal target: Added portalTarget so the viewer Portal can mount into a host overlay root, modal root, shadow host, or micro-frontend container. It changes only the DOM parent; the viewer still uses fullscreen fixed positioning. Use zIndex for stacking.

import { useState } from 'react'
import Zmage from 'react-zmage'
import 'react-zmage/style.css'

export function GalleryImage() {
  const [viewerRoot, setViewerRoot] = useState<HTMLElement | null>(null)

  return (
    <>
      <div id="app-overlay-root" ref={setViewerRoot} />
      <Zmage src="/photo.jpg" alt="Photo" portalTarget={viewerRoot} />
    </>
  )
}

新增 blur 翻页效果: animate.flip 现在支持 'blur'。多图浏览切换时，当前图会轻微失焦并淡出，下一张图同步淡入；caption 也会跟随同一段切换节奏更新。

<Zmage
  src="cover.jpg"
  set={gallery}
  animate={{ flip: 'blur' }}
/>

New blur flip effect: animate.flip now supports 'blur'. During multi-image browsing, the outgoing image softly blurs and fades while the next image fades in; captions switch on the same transition rhythm.

<Zmage
  src="cover.jpg"
  set={gallery}
  animate={{ flip: 'blur' }}
/>

controller.layout inset 更完整: controller.layout 的数字型 inset 现在会按目标组件自己的位置解释，不再一律当作底部偏移。toolbar 会跟随 controller.placement 判断安全边距，pagination 和 caption 继续按底部区域处理，左右 flip 按钮也可以单独向内收。

<Zmage
  src="hero.jpg"
  controller={{
    layout: {
      toolbar: { inset: 24 },
      flip: { inset: 32 },
      pagination: { inset: 20 },
      caption: { inset: 64 },
    },
  }}
/>

文档与调试台同步: 参数调试台、README、docs/llms.txt 和公开类型说明已经同步到新的 layout 行为，方便直接调试 toolbar、flip、pagination 和 caption 的安全区。

More complete controller.layout insets: Numeric controller.layout inset values now follow each overlay target's natural edge instead of always mapping to the bottom edge. The toolbar follows controller.placement, pagination and caption keep their bottom-area behavior, and left / right flip buttons can now be inset from the side edges.

<Zmage
  src="hero.jpg"
  controller={{
    layout: {
      toolbar: { inset: 24 },
      flip: { inset: 32 },
      pagination: { inset: 20 },
      caption: { inset: 64 },
    },
  }}
/>

Docs and playground sync: The playground controls, README, docs/llms.txt, and public type docs now describe the updated layout behavior for toolbar, flip, pagination, and caption safe-area tuning.

慢动作转场: 新增 animate.slowMotion，默认关闭。开启后，按住 Shift 打开或关闭图片会把完整 browsing 转场放慢到 10x，便于演示和检查动画细节。

<Zmage src="photo.jpg" animate={{ slowMotion: true }} />

覆盖层布局: 新增 controller.layout 和对应导出类型，可单独调整 toolbar、pagination、caption 的安全偏移，不改变图片首帧、缩放或关闭动画的几何计算。

<Zmage
  src="photo.jpg"
  controller={{
    placement: 'bottom-center',
    layout: {
      pagination: { inset: 32 },
      caption: { inset: { bottom: 72 } },
    },
  }}
/>

Slow-motion transitions: Added animate.slowMotion, off by default. When enabled, holding Shift while opening or closing slows the full browsing transition to 10x for demos and animation inspection.

<Zmage src="photo.jpg" animate={{ slowMotion: true }} />

Overlay layout: Added controller.layout and exported layout types so consumers can inset the toolbar, pagination, and caption overlays without changing first-frame, zoom, or close-animation geometry.

<Zmage
  src="photo.jpg"
  controller={{
    placement: 'bottom-center',
    layout: {
      pagination: { inset: 32 },
      caption: { inset: { bottom: 72 } },
    },
  }}
/>

移动端缩放手势: preset="mobile" 和默认的 preset="auto" 现在支持双指 pinch zoom、单指双击 zoom、缩放后的单指拖曳平移，以及接近边缘时带阻尼的回弹手感。

<Zmage
  src="photo.jpg"
  gesture={{
    pinchZoom: { resetBelowFit: true },
    doubleTapZoom: { scale: 2.5 },
  }}
/>

移动端拖曳切换与退出: mobile preset 支持横向拖曳切换图片、纵向拖曳退出浏览层，并和现有 browsing close 动画保持一致。

控制器自定义: controller.placement 可以移动工具栏位置，controller.render({ state, actions, slots }) 可以完全接管控制器 UI，同时复用内置按钮 slot。

<Zmage
  src="photo.jpg"
  controller={{
    placement: 'bottom-center',
    render: ({ state, actions, slots }) => (
      <div>
        {slots.zoom}
        <span>{state.page + 1} / {state.total}</span>
        <button onClick={actions.close}>Close</button>
      </div>
    ),
  }}
/>

封面几何匹配: animate.cover 现在会在打开 / 关闭时匹配 cover <img> 的 object-fit、object-position、clip 和 border radius，减少封面被裁剪或圆角不一致时的首帧跳变。

Mobile zoom gestures: preset="mobile" and the default preset="auto" now support pinch zoom, double-tap zoom, one-finger panning while zoomed, and damped edge resistance.

<Zmage
  src="photo.jpg"
  gesture={{
    pinchZoom: { resetBelowFit: true },
    doubleTapZoom: { scale: 2.5 },
  }}
/>

Mobile drag paging and drag-to-exit: the mobile preset supports horizontal drag paging and vertical drag-to-exit, using the same browsing close animation path as the rest of the viewer.

Controller customization: controller.placement moves the toolbar, and controller.render({ state, actions, slots }) lets consumers replace the whole controller UI while reusing built-in button slots.

<Zmage
  src="photo.jpg"
  controller={{
    placement: 'bottom-center',
    render: ({ state, actions, slots }) => (
      <div>
        {slots.zoom}
        <span>{state.page + 1} / {state.total}</span>
        <button onClick={actions.close}>Close</button>
      </div>
    ),
  }}
/>

Cover geometry matching: animate.cover now matches the cover <img> object-fit, object-position, clip, and border radius during open / close transitions, reducing first-frame jumps for cropped or rounded covers.

快捷键扩展: 旋转 + 下载 + 自定义描述符: 桌面端默认开启 [ / ] 旋转图片; Mod+S 下载当前图片 (默认关闭, 启用即劫持浏览器"另存为网页"). 全部 HotKey entry 接受 boolean | string | string[], 支持自定义按键描述符. 描述符基于 e.code (按键物理位置, 与键盘布局无关), Mod 前缀跨平台代表 ⌘ (macOS) 或 Ctrl (Windows/Linux). 严格修饰键匹配 — 'Space' 不会被 Cmd+Space (输入法切换) 误触发.

// 启用 Cmd/Ctrl+S 下载
<Zmage src="..." hotKey={{ download: true }} />
// 把旋转重绑到 A / D
<Zmage src="..." hotKey={{ rotate: false, rotateLeft: 'KeyA', rotateRight: 'KeyD' }} />
// 多绑: Q 作为第二个关闭键
<Zmage src="..." hotKey={{ close: ['Escape', 'KeyQ'] }} />

新增 loadingDelay prop — 显示 Loading 指示器前的延迟 (默认 200ms, 经典抗闪烁阈值). 在此窗口内图片加载完成则永不显示 Loading, 解决快速切换缓存图时的指示器闪烁. 设为 0 恢复旧的"立即显示"行为.

HotKey extensions: rotate + download + custom descriptors: desktop preset now ships [ / ] to rotate the image and Mod+S to download the current image (download is opt-in — turning it on hijacks the browser's "Save Page As"). Every HotKey entry accepts boolean | string | string[], supporting custom key descriptors. Descriptors use e.code names (physical key positions, layout-independent); the Mod prefix is cross-platform — ⌘ on macOS, Ctrl on Windows/Linux. Strict modifier matching — 'Space' is never matched by Cmd+Space (macOS input-method switch).

// Enable Cmd/Ctrl+S to download
<Zmage src="..." hotKey={{ download: true }} />
// Rebind rotate to A / D
<Zmage src="..." hotKey={{ rotate: false, rotateLeft: 'KeyA', rotateRight: 'KeyD' }} />
// Multi-binding: Q as a second close key
<Zmage src="..." hotKey={{ close: ['Escape', 'KeyQ'] }} />

New loadingDelay prop — delay (ms) before the loading indicator appears (default 200, classic anti-flicker threshold). If the image loads within this window the indicator never shows, eliminating the flash on cached page changes. Set 0 to restore the legacy instant-show behaviour.