feat(core): add loadingDelay prop with anti-flicker delay-before-show

Loading indicator was synchronously set on every page change and only cleared
by a 500ms polling fallback. Cached / key-reused pages flashed the spinner
~500ms then hid it — annoying visual noise especially when paging quickly
through pre-loaded images.

Three coordinated changes implement the industry-standard "delay-before-show"
pattern (see Ant Design Spin `delay`, react-loadable `delay`, TanStack Query):

1. New public prop `loadingDelay: number` (default 200ms; range 0-1000 in
   playground). Defers `isFetching=true` setState by N ms; if the image
   loads within the window via any path (onLoad event, polling, or cdU
   fast-path), the delay timer is cancelled → loading indicator never shows.

2. cdU page-change fast-path: when `node.complete && naturalWidth > 0`
   on the new center (cached image, key-reused side→center), call
   `handleImageLoadEnd` directly. Skips loading state entirely, no timer
   needed. Combined with the scale-calibration interrupt and canZoom
   recompute already wired here, all three concerns now share the same
   "new center is ready" branch.

3. handleImageLoad (centerOnLoad path) now calls handleImageLoadEnd. Was
   relying solely on 500ms polling to clear loading; onLoad is the canonical
   "image is loaded" signal — using it directly cuts the polling-driven
   flash window from ~500ms to one render cycle.

Behavior matrix:
  Cached page change          → no Loading shown (fast-path)
  Fast load (<200ms)          → no Loading shown (delay timer cancelled)
  Medium load (200-500ms)     → Loading shown 0-300ms
  Slow load (>500ms)          → Loading shown N-200ms (vs N-500ms before)

Tests added (4 new, 112 total):
  - Cached page change: #zmageLoading not in DOM throughout (fast-path lock)
  - loadingDelay=50 prop: Loading appears around 50ms for uncached page
  - Fast onLoad cancels delay timer: Loading never shown
  - StrictMode unmount cancels loadingShowDelayTimer (cleanup invariant)

Public docs synced (sync-public-docs skill, all 8 destinations):
  - types/global.ts InterfaceAndInteractionParams; defProp.loadingDelay
  - getConfigFromProps + Browser context value (single-source plumbing)
  - home/schema/param-schema.ts (PARAM_SCHEMA + defProp mirror)
  - 7 i18n files (en/de/es/fr/ja/ko/zh-CN), all 283 keys parity verified
  - README.md / README.zh-CN.md interface props table + Full type comment
  - AGENTS.md prop quick-reference Interface row
  - llms.txt API table row; docs/llms.txt regenerated via home build
  - llms-eval/eval.test.mjs new contract assertion (16/16 pass)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Caldis

AGENTS.md

@@ -84,7 +84,7 @@ Single `BaseType` covers all. Grouped here by purpose:
 | Preset | `preset: 'desktop' \| 'mobile' \| 'auto'` | drives default `controller` / `hotKey` / `animate`. `'auto'` resolves via `matchMedia('(pointer: coarse) and (hover: none)')` on the client; SSR falls back to desktop |
 | Controlled | `browsing` | omit for self-managed; pair with `onBrowsing` if set |
 | Functional | `controller`, `hotKey`, `animate` | pass `boolean` to disable, or partial object to override. `controller.flip` and `hotKey.flip` are umbrellas over their per-side counterparts (`flipLeft` / `flipRight`); enabling the umbrella forces both sides on. `controller.backdrop` / `controller.color` decouple the toolbar bg/icon-color from the modal `backdrop` (set both when `backdrop` is solid dark) |
-| Interface | `hideOnScroll`, `coverVisible`, `backdrop`, `zIndex`, `radius`, `edge`, `loop`, `closeOnDoubleClick` | desktop-only flags noted in README. `closeOnDoubleClick` defaults `false`; turn on to dismiss the viewer with a dblclick on the image |
+| Interface | `hideOnScroll`, `coverVisible`, `backdrop`, `zIndex`, `radius`, `edge`, `loop`, `closeOnDoubleClick`, `loadingDelay` | desktop-only flags noted in README. `closeOnDoubleClick` defaults `false`; turn on to dismiss the viewer with a dblclick on the image. `loadingDelay` defaults `200ms` — anti-flicker delay before showing the loading indicator (set 0 for legacy instant-show) |
 | Lifecycle | `onBrowsing`, `onZooming`, `onSwitching`, `onRotating`, `onError` | first 4 callback args: `boolean`/`boolean`/`number`/`number`. `onError(e: SyntheticEvent<HTMLImageElement>)` fires for cover **or** viewer img-load failure — the only hook for the viewer-side failure (cover also flows via native `<img>` `onError` passthrough) |
 | Native | All `HTMLAttributes<HTMLImageElement>` | className, style, onClick, etc. transparently forwarded to inner `<img>` |
 

README.md

@@ -242,6 +242,7 @@ Defaults: desktop = `{ browsing: true, flip: 'crossFade' }`, mobile = `{ browsin
 | `edge` | `number` | `0` | Minimum margin between image and viewport (px). |
 | `loop` | `boolean` | `true` | Wrap-around when paging past the ends. |
 | `closeOnDoubleClick` | `boolean` | `false` | Close the viewer on image double-click. Off by default; turn on to allow dismissing with a double-click. |
+| `loadingDelay` | `number` | `200` | Delay (ms) before showing the loading indicator. If the image loads within this window, the indicator never appears — prevents the flash on cached page changes. Set 0 for legacy instant-show. |
 
 ### Lifecycle
 
@@ -270,7 +271,7 @@ export type BaseType =
   & BaseParams                    // src / alt / caption / set / defaultPage
   & PresetParams                  // preset
   & FunctionalParams              // controller / hotKey / animate
-  & InterfaceAndInteractionParams // hideOnScroll / coverVisible / backdrop / zIndex / radius / edge / loop / closeOnDoubleClick
+  & InterfaceAndInteractionParams // hideOnScroll / coverVisible / backdrop / zIndex / radius / edge / loop / closeOnDoubleClick / loadingDelay
   & LifeCycleParams               // onBrowsing / onZooming / onSwitching / onRotating / onError
   & ControlledParams              // browsing
   & HTMLAttributes<HTMLImageElement>

README.zh-CN.md

@@ -237,6 +237,7 @@ interface Animate {
 | `edge` | `number` | `0` | 图片距屏幕边缘的留白 (px)。 |
 | `loop` | `boolean` | `true` | 多图模式：尾页是否循环回首页。 |
 | `closeOnDoubleClick` | `boolean` | `false` | 双击图片时关闭查看器。默认关闭；启用后浏览态双击图片即退出。 |
+| `loadingDelay` | `number` | `200` | Loading 指示器显示前的延迟 (ms)。在此期间内图片加载完成则不显示 loading，避免快速切换缓存图时的视觉闪烁。默认 200ms (业界 react-loadable 经典值)；设为 0 = 立即显示 (旧行为)。 |
 
 ### 生命周期
 
@@ -265,7 +266,7 @@ export type BaseType =
   & BaseParams                    // src / alt / caption / set / defaultPage
   & PresetParams                  // preset
   & FunctionalParams              // controller / hotKey / animate
-  & InterfaceAndInteractionParams // hideOnScroll / coverVisible / backdrop / zIndex / radius / edge / loop / closeOnDoubleClick
+  & InterfaceAndInteractionParams // hideOnScroll / coverVisible / backdrop / zIndex / radius / edge / loop / closeOnDoubleClick / loadingDelay
   & LifeCycleParams               // onBrowsing / onZooming / onSwitching / onRotating / onError
   & ControlledParams              // browsing
   & HTMLAttributes<HTMLImageElement>

docs/404.html

@@ -72,8 +72,8 @@
         document.documentElement.classList.toggle('dark', theme === 'dark')
       } catch {}
     </script>
-    <script type="module" crossorigin src="/assets/index-CUsU0GPn.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-xvpohMzA.css">
+    <script type="module" crossorigin src="/assets/index-DsrOIYKm.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-ButVaVSj.css">
   </head>
   <body>
     <div id="app"></div>

docs/assets/index-xvpohMzA.css docs/assets/index-ButVaVSj.cssdocs/assets/index-xvpohMzA.css renamed to docs/assets/index-ButVaVSj.css

@@ -72,8 +72,8 @@
         document.documentElement.classList.toggle('dark', theme === 'dark')
       } catch {}
     </script>
-    <script type="module" crossorigin src="/assets/index-CUsU0GPn.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-xvpohMzA.css">
+    <script type="module" crossorigin src="/assets/index-DsrOIYKm.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-ButVaVSj.css">
   </head>
   <body>
     <div id="app"></div>

docs/assets/index-CUsU0GPn.js

@@ -71,6 +71,7 @@ const [open, setOpen] = useState(false)
 | `zIndex` / `radius` / `edge` | `number` | `1000` / `0` / `0` | Modal stacking, image corner radius, viewport padding. |
 | `loop` | `boolean` | `true` | Wrap-around when paging past the ends. |
 | `closeOnDoubleClick` | `boolean` | `false` | Close the viewer on image double-click. Off by default to preserve current single-click semantics; turn on to dismiss with a double-click. |
+| `loadingDelay` | `number` | `200` | Delay (ms) before showing the loading indicator. If the image loads within this window, the indicator never appears — prevents the flash on cached page changes. Set 0 for legacy instant-show. |
 | `onBrowsing` | `(isBrowsing: boolean) => void` | — | Fires on open/close. |
 | `onZooming` | `(isZooming: boolean) => void` | — | Fires on zoom in/out. |
 | `onSwitching` | `(page: number) => void` | — | Fires on page change. |

docs/assets/index-DsrOIYKm.js

@@ -71,6 +71,7 @@ const [open, setOpen] = useState(false)
 | `zIndex` / `radius` / `edge` | `number` | `1000` / `0` / `0` | Modal stacking, image corner radius, viewport padding. |
 | `loop` | `boolean` | `true` | Wrap-around when paging past the ends. |
 | `closeOnDoubleClick` | `boolean` | `false` | Close the viewer on image double-click. Off by default to preserve current single-click semantics; turn on to dismiss with a double-click. |
+| `loadingDelay` | `number` | `200` | Delay (ms) before showing the loading indicator. If the image loads within this window, the indicator never appears — prevents the flash on cached page changes. Set 0 for legacy instant-show. |
 | `onBrowsing` | `(isBrowsing: boolean) => void` | — | Fires on open/close. |
 | `onZooming` | `(isZooming: boolean) => void` | — | Fires on zoom in/out. |
 | `onSwitching` | `(page: number) => void` | — | Fires on page change. |