@libshub/gif-tools 1.0.3 → 1.0.8

package/README.md

@@ -0,0 +1,193 @@
+# @libshub/gif-tools
+
+基于 Canvas 的 React GIF 播放组件，使用 [gifuct-js](https://github.com/matt-way/gifuct-js) 解码，支持播放控制、循环次数、资源缓存与加载性能统计。
+
+## 演示
+
+[![GifPlayer 演示](https://static.hanlinbo.cn/%E5%9B%BE%E7%89%87/github/gif-tools-demo.png)](http://www.hanxiaoxin.cn/gif-tools/)
+
+在线体验：[http://www.hanxiaoxin.cn/gif-tools/](http://www.hanxiaoxin.cn/gif-tools/)
+
+## 安装
+
+```bash
+npm install @libshub/gif-tools
+```
+
+需要 React 17+：
+
+```bash
+npm install react react-dom
+```
+
+## 快速开始
+
+```tsx
+import { GifPlayer } from '@libshub/gif-tools'
+import '@libshub/gif-tools/style.css'
+
+function App() {
+  return (
+    <GifPlayer
+      src="https://example.com/demo.gif"
+      autoPlay
+      showControls
+    />
+  )
+}
+```
+
+## GifPlayer
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `src` | `string` | — | GIF 地址（必填） |
+| `width` | `number \| string` | — | 画布宽度 |
+| `height` | `number \| string` | — | 画布高度 |
+| `className` | `string` | — | 根节点 class |
+| `style` | `CSSProperties` | — | 根节点样式 |
+| `autoPlay` | `boolean` | `true` | 加载完成后自动播放 |
+| `showControls` | `boolean` | `false` | 显示播放/暂停按钮 |
+| `debug` | `boolean` | `false` | 在画面上叠加加载耗时调试信息 |
+| `loopCount` | `number` | — | 循环次数，不传则按 GIF 自身循环或无限循环 |
+| `onLoaded` | `(stats: GifLoadStats) => void` | — | 加载完成 |
+| `onPlay` | `() => void` | — | 开始播放 |
+| `onPause` | `() => void` | — | 暂停 |
+| `onEnd` | `() => void` | — | 达到循环上限后结束 |
+| `onError` | `(error: Error) => void` | — | 加载或解码失败 |
+
+### Ref 方法
+
+通过 `ref` 可命令式控制播放器：
+
+```tsx
+import { useRef } from 'react'
+import { GifPlayer, type GifPlayerRef } from '@libshub/gif-tools'
+
+const ref = useRef<GifPlayerRef>(null)
+
+ref.current?.play()      // 播放
+ref.current?.pause()     // 暂停
+ref.current?.toggle()    // 切换播放/暂停
+ref.current?.reset()     // 回到第一帧并暂停
+ref.current?.reload()    // 重新加载（跳过 pending 复用，强制 fresh）
+ref.current?.isPlaying() // 是否正在播放
+```
+
+### 完整示例
+
+```tsx
+import { useRef } from 'react'
+import {
+  GifPlayer,
+  formatGifLoadStats,
+  type GifPlayerRef,
+} from '@libshub/gif-tools'
+import '@libshub/gif-tools/style.css'
+
+export default function Demo() {
+  const playerRef = useRef<GifPlayerRef>(null)
+
+  return (
+    <>
+      <button onClick={() => playerRef.current?.toggle()}>播放/暂停</button>
+
+      <GifPlayer
+        ref={playerRef}
+        src="https://example.com/demo.gif"
+        width="100%"
+        height="auto"
+        className="my-gif"
+        style={{ borderRadius: 8 }}
+        autoPlay
+        showControls
+        loopCount={2}
+        debug
+        onLoaded={(stats) => console.log(formatGifLoadStats(stats))}
+        onPlay={() => console.log('play')}
+        onPause={() => console.log('pause')}
+        onEnd={() => console.log('end')}
+        onError={(e) => console.error(e)}
+      />
+    </>
+  )
+}
+```
+
+## 资源缓存
+
+相同 `src` 的 GIF 在全局共享解码结果，多个 `GifPlayer` 实例不会重复 fetch / decode。
+
+```tsx
+import { clearGifResourceCache } from '@libshub/gif-tools'
+
+// 清空全部缓存
+clearGifResourceCache()
+```
+
+`onLoaded` 回调中的 `GifLoadStats` 可区分三种加载模式：
+
+- **fresh**：首次加载，包含 `fetchTimeMs` 与 `decodeTimeMs`
+- **pending**：复用进行中的请求，包含 `pendingWaitFetchMs` 与 `pendingWaitDecodeMs`
+- **cache**：命中缓存，耗时均为 0
+
+```tsx
+import { formatGifLoadStats, getGifLoadStatsView } from '@libshub/gif-tools'
+
+onLoaded={(stats) => {
+  console.log(formatGifLoadStats(stats))
+  // fresh
+  // fetch 120.5ms
+  // decode 45.2ms
+  // total 165.7ms
+
+  const view = getGifLoadStatsView(stats)
+  console.log(view.mode) // 'fresh' | 'pending' | 'cache'
+}}
+```
+
+## 底层 API
+
+不依赖 React 时，可直接在 Canvas 上创建控制器：
+
+```ts
+import { createGifController } from '@libshub/gif-tools'
+
+const canvas = document.querySelector('canvas')!
+const { controller, stats } = await createGifController(canvas, src, {
+  loopCount: 3,
+  onPlay: () => {},
+  onPause: () => {},
+  onEnd: () => {},
+})
+
+controller.play()
+controller.pause()
+controller.reset()
+controller.isPlaying()
+controller.getCompletedLoops()
+controller.destroy()
+```
+
+## 导出一览
+
+**组件**
+
+- `GifPlayer`
+
+**类型**
+
+- `GifPlayerProps`、`GifPlayerRef`、`GifPlayerComponent`
+- `GifLoadStats`、`GifController`、`CreateGifOptions`
+- `GifLoadStatsView`、`GifLoadStatsLine`、`GifLoadStatsMode`
+
+**工具函数**
+
+- `createGifController` — 在 Canvas 上创建 GIF 控制器
+- `clearGifResourceCache` — 清空 GIF 资源缓存
+- `formatGifLoadStats` — 格式化加载统计（多行）
+- `formatLoadTimeMs` — 格式化毫秒数
+- `getGifLoadStatsView` — 获取结构化加载统计视图
+- `getTotalLoadTimeMs` — 获取总加载耗时

package/dist/components/GifLoadStatsDebug.d.ts

@@ -0,0 +1,7 @@
+import { type RefObject } from 'react';
+import type { GifLoadStats } from '../utils';
+export declare function GifLoadStatsDebug({ stats, canvasRef, visible, }: {
+    stats: GifLoadStats;
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    visible: boolean;
+}): import("react").JSX.Element;

package/dist/components/GifPlayer.d.ts

@@ -1,4 +1,5 @@
 import { type CSSProperties, type ForwardRefExoticComponent, type RefAttributes } from 'react';
+import type { GifLoadStats } from '../utils';
 import './GifPlayer.css';
 export interface GifPlayerRef {
     play: () => void;
@@ -17,12 +18,11 @@ export interface GifPlayerProps {
     autoPlay?: boolean;
     showControls?: boolean;
     debug?: boolean;
-    /** 未设置则无限循环；1 播放一次；N 播放 N 次后触发 onEnd */
     loopCount?: number;
     onPlay?: () => void;
     onPause?: () => void;
     onEnd?: () => void;
-    onLoaded?: (decodeTimeMs: number) => void;
+    onLoaded?: (stats: GifLoadStats) => void;
     onError?: (error: Error) => void;
 }
 export type GifPlayerComponent = ForwardRefExoticComponent<GifPlayerProps & RefAttributes<GifPlayerRef>>;

package/dist/gif-tools.css

@@ -1,2 +1,2 @@
-.gif-player{line-height:0;display:inline-block;position:relative;overflow:hidden}.gif-player__media{max-width:100%;height:auto;display:block}.gif-player__controls{opacity:0;gap:6px;transition:opacity .2s;display:flex;position:absolute;bottom:8px;right:8px}.gif-player:hover .gif-player__controls,.gif-player--show-controls .gif-player__controls{opacity:1}.gif-player__btn{color:#fff;cursor:pointer;-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px);background:#0000008c;border:none;border-radius:50%;justify-content:center;align-items:center;width:32px;height:32px;padding:0;display:flex}.gif-player__btn:hover{background:#000000bf}.gif-player__btn svg{fill:currentColor;width:16px;height:16px}.gif-player__debug{color:#fff;pointer-events:none;background:#000000a6;border-radius:4px;padding:2px 8px;font-family:ui-monospace,monospace;font-size:12px;line-height:1.4;position:absolute;top:8px;left:8px}
+.gif-player{line-height:0;display:inline-block;position:relative;overflow:visible}.gif-player__media{max-width:100%;height:auto;display:block}.gif-player__controls{opacity:0;gap:6px;transition:opacity .2s;display:flex;position:absolute;bottom:8px;right:8px}.gif-player:hover .gif-player__controls,.gif-player--show-controls .gif-player__controls{opacity:1}.gif-player__btn{color:#fff;cursor:pointer;-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px);background:#0000008c;border:none;border-radius:50%;justify-content:center;align-items:center;width:32px;height:32px;padding:0;display:flex}.gif-player__btn:hover{background:#000000bf}.gif-player__btn svg{fill:currentColor;width:16px;height:16px}.gif-player__debug{z-index:1;pointer-events:none;-webkit-backdrop-filter:blur(8px);backdrop-filter:blur(8px);font-variant-numeric:tabular-nums;color:#e8eaed;background:#0c0e12d1;font-family:ui-monospace,Cascadia Code,SF Mono,monospace;position:absolute;top:0;left:0;box-shadow:0 2px 8px #0003}.gif-player__debug--compact{white-space:nowrap;border-radius:0 0 4px;padding:2px 5px;font-size:8px;line-height:1.2}.gif-player__debug--medium{border-radius:0 0 5px;padding:3px 6px;font-size:9px;line-height:1.2}.gif-player__debug--collapsible{pointer-events:auto;cursor:pointer;-webkit-user-select:none;user-select:none}.gif-player__debug--collapsible:hover{background:#12161ceb}.gif-player__debug--collapsible:focus-visible{outline-offset:1px;outline:1px solid #7ec8ffbf}.gif-player__debug--full{border-radius:0 0 6px;min-width:96px;padding:5px 7px;font-size:10px;line-height:1.35}.gif-player__debug--expanded{z-index:2;min-width:108px;max-width:none!important}.gif-player__debug-head{justify-content:space-between;align-items:center;gap:8px;display:flex}.gif-player__debug-badge{letter-spacing:.04em;color:#fff;background:#ffffff24;border-radius:3px;padding:1px 4px;font-size:8px;font-weight:600;display:inline-block}.gif-player__debug--full .gif-player__debug-badge{margin-bottom:4px;padding:1px 5px;font-size:9px}.gif-player__debug[data-mode=fresh] .gif-player__debug-badge{background:#4a90e28c}.gif-player__debug[data-mode=pending] .gif-player__debug-badge{background:#e6a23c8c}.gif-player__debug[data-mode=cache] .gif-player__debug-badge{background:#52c4808c}.gif-player__debug-body{flex-direction:column;gap:2px;display:flex}.gif-player__debug-row,.gif-player__debug-total{justify-content:space-between;align-items:baseline;gap:8px;display:flex}.gif-player__debug-label{color:#e8eaedb8;white-space:nowrap}.gif-player__debug-value{color:#fff;white-space:nowrap}.gif-player__debug-value--total{color:#7ec8ff;font-weight:600}.gif-player__debug[data-mode=cache] .gif-player__debug-value--total{color:#82e0aa}.gif-player__debug-total{border-top:1px solid #ffffff1f;margin-top:4px;padding-top:4px}.gif-player__debug-total .gif-player__debug-label{color:#e8eaede6;font-weight:600}.gif-player__debug-total .gif-player__debug-value{color:#7ec8ff;font-weight:600}.gif-player__debug[data-mode=cache] .gif-player__debug-total .gif-player__debug-value{color:#82e0aa}
 /*$vite$:1*/

package/dist/gif-tools.es.js

@@ -299,64 +299,122 @@ var c = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		});
 	};
 })))(), h = /* @__PURE__ */ new Map(), g = /* @__PURE__ */ new Map(), _ = /* @__PURE__ */ new Map();
-async function v(e) {
-	let t = await fetch(e, {
+function v(e, t, n) {
+	return n === null || e >= n ? {
+		pendingWaitFetchMs: 0,
+		pendingWaitDecodeMs: t - e
+	} : {
+		pendingWaitFetchMs: n - e,
+		pendingWaitDecodeMs: t - n
+	};
+}
+function y() {
+	return {
+		fetchTimeMs: 0,
+		decodeTimeMs: 0,
+		pendingWaitFetchMs: 0,
+		pendingWaitDecodeMs: 0,
+		fromCache: !0,
+		fromPending: !1
+	};
+}
+function b(e, t) {
+	return {
+		fetchTimeMs: e,
+		decodeTimeMs: t,
+		pendingWaitFetchMs: 0,
+		pendingWaitDecodeMs: 0,
+		fromCache: !1,
+		fromPending: !1
+	};
+}
+async function x(e, t) {
+	let n = performance.now(), r = await fetch(e, {
 		mode: "cors",
 		credentials: "omit"
 	});
-	if (!t.ok) throw Error(`Failed to load gif: ${t.status}`);
-	let n = await t.arrayBuffer(), r = performance.now(), i = (0, m.parseGIF)(n), a = (0, m.decompressFrames)(i, !0), o = performance.now() - r;
-	if (!a.length) throw Error("GIF has no frames");
+	if (!r.ok) throw Error(`Failed to load gif: ${r.status}`);
+	let i = await r.arrayBuffer(), a = performance.now() - n;
+	t && (t.fetchDoneAt = performance.now());
+	let o = performance.now(), s = (0, m.parseGIF)(i), c = (0, m.decompressFrames)(s, !0), l = performance.now() - o;
+	if (!c.length) throw Error("GIF has no frames");
 	return {
 		gif: {
-			frames: a,
-			width: i.lsd.width,
-			height: i.lsd.height
+			frames: c,
+			width: s.lsd.width,
+			height: s.lsd.height
 		},
-		decodeTimeMs: o
+		fetchTimeMs: a,
+		decodeTimeMs: l
 	};
 }
-async function y(e, t) {
+async function S(e, t) {
 	let n = h.get(e);
-	if (n) return n.refCount += 1, {
+	if (n) return {
 		gif: n.data,
-		decodeTimeMs: 0
+		stats: y()
 	};
 	if (!t?.skipPending && g.has(e)) {
-		let { gif: t } = await g.get(e);
-		return h.get(e).refCount += 1, {
-			gif: t,
-			decodeTimeMs: 0
+		let t = g.get(e), n = performance.now(), { gif: r, fetchTimeMs: i, decodeTimeMs: a } = await t.promise, { pendingWaitFetchMs: o, pendingWaitDecodeMs: s } = v(n, performance.now(), t.fetchDoneAt), c = h.get(e);
+		return c ||= (h.set(e, {
+			data: r,
+			refCount: 0,
+			fetchTimeMs: i,
+			decodeTimeMs: a
+		}), h.get(e)), {
+			gif: c.data,
+			stats: {
+				fetchTimeMs: 0,
+				decodeTimeMs: 0,
+				pendingWaitFetchMs: o,
+				pendingWaitDecodeMs: s,
+				fromCache: !1,
+				fromPending: !0
+			}
 		};
 	}
 	let r = (_.get(e) ?? 0) + 1;
 	_.set(e, r);
-	let i = v(e).then(({ gif: t, decodeTimeMs: n }) => _.get(e) === r ? (g.delete(e), h.set(e, {
+	let i = {
+		fetchDoneAt: null,
+		promise: void 0
+	};
+	i.promise = x(e, i).then(({ gif: t, fetchTimeMs: n, decodeTimeMs: i }) => _.get(e) === r ? (g.delete(e), h.set(e, {
 		data: t,
-		refCount: 0
+		refCount: 0,
+		fetchTimeMs: n,
+		decodeTimeMs: i
 	}), {
 		gif: t,
-		decodeTimeMs: n
+		fetchTimeMs: n,
+		decodeTimeMs: i
 	}) : {
 		gif: t,
-		decodeTimeMs: n
+		fetchTimeMs: n,
+		decodeTimeMs: i
 	}).catch((t) => {
 		throw _.get(e) === r && g.delete(e), t;
-	});
-	g.set(e, i);
-	let { gif: a, decodeTimeMs: o } = await i;
-	return _.get(e) === r && (h.get(e).refCount += 1), {
+	}), g.set(e, i);
+	let { gif: a, fetchTimeMs: o, decodeTimeMs: s } = await i.promise;
+	return {
 		gif: a,
-		decodeTimeMs: o
+		stats: b(o, s)
 	};
 }
-function b(e) {
+function C(e) {
+	let t = h.get(e);
+	t && (t.refCount += 1);
+}
+function w(e) {
 	let t = h.get(e);
 	t && (--t.refCount, t.refCount <= 0 && h.delete(e));
 }
+function T() {
+	h.clear(), g.clear(), _.clear();
+}
 //#endregion
 //#region src/utils/gifController.ts
-function x(e, t, n, r, i = {}) {
+function E(e, t, n, r, i = {}) {
 	let a = e.getContext("2d");
 	if (!a) throw Error("Canvas 2d context unavailable");
 	let o = a;
@@ -400,8 +458,8 @@ function x(e, t, n, r, i = {}) {
 	function x() {
 		b(), u = 0, d = 0, o.clearRect(0, 0, n, r), g(0);
 	}
-	function S() {
-		b(), p = null, s.width = 0, s.height = 0, e.width = 0, e.height = 0;
+	function S(t) {
+		b(), p = null, s.width = 0, s.height = 0, t?.clearCanvas !== !1 && (e.width = 0, e.height = 0);
 	}
 	return g(0), {
 		play: y,
@@ -412,58 +470,252 @@ function x(e, t, n, r, i = {}) {
 		getCompletedLoops: () => d
 	};
 }
-async function S(e, t, n = {}) {
-	let { skipPending: r, onLoaded: i, ...a } = n, { gif: o, decodeTimeMs: s } = await y(t, { skipPending: r });
-	i?.(s);
-	let c = x(e, o.frames, o.width, o.height, a), l = c.destroy;
-	return c.destroy = () => {
-		l(), b(t);
-	}, c;
+async function D(e, t, n = {}) {
+	let { skipPending: r, onLoaded: i, ...a } = n, { gif: o, stats: s } = await S(t, { skipPending: r });
+	return i?.(s), {
+		controller: E(e, o.frames, o.width, o.height, a),
+		stats: s
+	};
+}
+//#endregion
+//#region src/utils/loadStats.ts
+function O(e) {
+	return e.fromCache ? 0 : e.fromPending ? e.pendingWaitFetchMs + e.pendingWaitDecodeMs : e.fetchTimeMs + e.decodeTimeMs;
+}
+function k(e) {
+	return e.fromCache ? {
+		mode: "cache",
+		lines: [{
+			label: "wait fetch",
+			valueMs: 0
+		}, {
+			label: "wait decode",
+			valueMs: 0
+		}],
+		totalMs: 0
+	} : e.fromPending ? {
+		mode: "pending",
+		lines: [{
+			label: "wait fetch",
+			valueMs: e.pendingWaitFetchMs
+		}, {
+			label: "wait decode",
+			valueMs: e.pendingWaitDecodeMs
+		}],
+		totalMs: e.pendingWaitFetchMs + e.pendingWaitDecodeMs
+	} : {
+		mode: "fresh",
+		lines: [{
+			label: "fetch",
+			valueMs: e.fetchTimeMs
+		}, {
+			label: "decode",
+			valueMs: e.decodeTimeMs
+		}],
+		totalMs: e.fetchTimeMs + e.decodeTimeMs
+	};
+}
+function A(e) {
+	let t = k(e), n = t.lines.map((e) => `${e.label} ${e.valueMs.toFixed(1)}ms`).join("\n");
+	return `${t.mode}\n${n}\ntotal ${t.totalMs.toFixed(1)}ms`;
+}
+function j(e) {
+	return `${e.toFixed(1)}ms`;
+}
+function M(e, t) {
+	let n = Math.min(e, t);
+	return n < 130 ? "compact" : n < 220 ? "medium" : "full";
+}
+var N = {
+	fresh: "F",
+	pending: "P",
+	cache: "C"
+};
+function P(e) {
+	let t = k(e), n = N[t.mode];
+	return t.mode === "cache" ? `${n} · 0` : `${n} · ${j(t.totalMs)}`;
+}
+function F(e, t) {
+	return t === "fresh" ? e.label === "fetch" ? "f" : "d" : e.label === "wait fetch" ? "wf" : "wd";
+}
+//#endregion
+//#region src/components/GifLoadStatsDebug.tsx
+var I = {
+	fresh: "FRESH",
+	pending: "PND",
+	cache: "CACHE"
+};
+function L(e, t) {
+	let [r, i] = a({
+		width: 0,
+		height: 0
+	});
+	return n(() => {
+		let n = e.current;
+		if (!n || !t) return;
+		let r = () => {
+			i({
+				width: n.clientWidth,
+				height: n.clientHeight
+			});
+		};
+		r();
+		let a = new ResizeObserver(r);
+		return a.observe(n), () => a.disconnect();
+	}, [e, t]), r;
+}
+function R({ label: e, valueMs: t }) {
+	return /* @__PURE__ */ s("div", {
+		className: "gif-player__debug-row",
+		children: [/* @__PURE__ */ o("span", {
+			className: "gif-player__debug-label",
+			children: e
+		}), /* @__PURE__ */ o("span", {
+			className: "gif-player__debug-value",
+			children: j(t)
+		})]
+	});
+}
+function z({ view: e, width: t, expanded: n, onToggle: r }) {
+	return /* @__PURE__ */ s("div", {
+		className: [
+			"gif-player__debug",
+			"gif-player__debug--full",
+			n && "gif-player__debug--expanded",
+			r && "gif-player__debug--collapsible"
+		].filter(Boolean).join(" "),
+		"data-mode": e.mode,
+		style: { maxWidth: !n && t > 0 ? Math.min(152, Math.round(t * .52)) : void 0 },
+		role: r ? "button" : void 0,
+		tabIndex: r ? 0 : void 0,
+		title: r ? n ? "点击收起" : "点击展开详情" : void 0,
+		onClick: r,
+		onKeyDown: r ? (e) => {
+			(e.key === "Enter" || e.key === " ") && (e.preventDefault(), r());
+		} : void 0,
+		children: [
+			/* @__PURE__ */ o("span", {
+				className: "gif-player__debug-badge",
+				children: I[e.mode]
+			}),
+			/* @__PURE__ */ o("div", {
+				className: "gif-player__debug-body",
+				children: e.lines.map((t) => /* @__PURE__ */ o(R, {
+					label: F(t, e.mode),
+					valueMs: t.valueMs
+				}, t.label))
+			}),
+			/* @__PURE__ */ s("div", {
+				className: "gif-player__debug-total",
+				children: [/* @__PURE__ */ o("span", {
+					className: "gif-player__debug-label",
+					children: "Σ"
+				}), /* @__PURE__ */ o("span", {
+					className: "gif-player__debug-value",
+					children: j(e.totalMs)
+				})]
+			})
+		]
+	});
+}
+function B({ stats: e, canvasRef: t, visible: r }) {
+	let { width: i, height: c } = L(t, r), l = k(e), u = M(i, c), [d, f] = a(!1), p = u !== "full";
+	n(() => {
+		f(!1);
+	}, [e]), n(() => {
+		p || f(!1);
+	}, [p]);
+	let m = () => {
+		p && f((e) => !e);
+	};
+	return p && d ? /* @__PURE__ */ o(z, {
+		view: l,
+		width: i,
+		expanded: !0,
+		onToggle: m
+	}) : u === "compact" ? /* @__PURE__ */ o("div", {
+		className: "gif-player__debug gif-player__debug--compact gif-player__debug--collapsible",
+		"data-mode": l.mode,
+		role: "button",
+		tabIndex: 0,
+		title: "点击展开详情",
+		onClick: m,
+		onKeyDown: (e) => {
+			(e.key === "Enter" || e.key === " ") && (e.preventDefault(), m());
+		},
+		children: P(e)
+	}) : u === "medium" ? /* @__PURE__ */ o("div", {
+		className: "gif-player__debug gif-player__debug--medium gif-player__debug--collapsible",
+		"data-mode": l.mode,
+		role: "button",
+		tabIndex: 0,
+		title: "点击展开详情",
+		onClick: m,
+		onKeyDown: (e) => {
+			(e.key === "Enter" || e.key === " ") && (e.preventDefault(), m());
+		},
+		children: /* @__PURE__ */ s("div", {
+			className: "gif-player__debug-head",
+			children: [/* @__PURE__ */ o("span", {
+				className: "gif-player__debug-badge",
+				children: I[l.mode]
+			}), /* @__PURE__ */ o("span", {
+				className: "gif-player__debug-value gif-player__debug-value--total",
+				children: j(l.totalMs)
+			})]
+		})
+	}) : /* @__PURE__ */ o(z, {
+		view: l,
+		width: i,
+		expanded: !1
+	});
 }
 //#endregion
 //#region src/components/GifPlayer.tsx
-var C = e(({ src: e, autoPlay: c = !0, showControls: l = !1, debug: u = !1, loopCount: d, className: f, style: p, width: m, height: h, onPlay: g, onPause: _, onEnd: v, onLoaded: y, onError: b }, x) => {
-	let C = i(null), w = i(null), T = i(g), E = i(_), D = i(v), O = i(y), k = i(b), [A, j] = a(c), [M, N] = a(!1), [P, F] = a(null), [I, L] = a(0), R = i(!1);
-	T.current = g, E.current = _, D.current = v, O.current = y, k.current = b;
-	let z = t(() => {
-		w.current?.play(), j(!0);
-	}, []), B = t(() => {
-		w.current?.pause(), j(!1);
-	}, []), V = t(() => {
-		w.current?.isPlaying() ? B() : z();
-	}, [B, z]), H = t(() => {
-		w.current?.reset(), j(!1);
-	}, []), U = t(() => {
-		R.current = !0, L((e) => e + 1);
+var V = e(({ src: e, autoPlay: c = !0, showControls: l = !1, debug: u = !1, loopCount: d, className: f, style: p, width: m, height: h, onPlay: g, onPause: _, onEnd: v, onLoaded: y, onError: b }, x) => {
+	let S = i(null), T = i(null), E = i(g), O = i(_), k = i(v), A = i(y), j = i(b), [M, N] = a(c), [P, F] = a(!1), [I, L] = a(null), [R, z] = a(0), V = i(!1), H = i(0);
+	E.current = g, O.current = _, k.current = v, A.current = y, j.current = b;
+	let U = t(() => {
+		T.current?.play(), N(!0);
 	}, []), W = t(() => {
-		let t = !1, n = C.current;
-		if (!n) return () => {};
-		let r = R.current;
-		return R.current = !1, N(!1), j(!1), F(null), w.current?.destroy(), w.current = null, S(n, e, {
-			skipPending: r,
+		T.current?.pause(), N(!1);
+	}, []), G = t(() => {
+		T.current?.isPlaying() ? W() : U();
+	}, [W, U]), K = t(() => {
+		T.current?.reset(), N(!1);
+	}, []), q = t(() => {
+		V.current = !0, z((e) => e + 1);
+	}, []), J = t(() => {
+		if (!e) return () => {};
+		let t = ++H.current, n = !1, r = S.current;
+		if (!r) return () => {};
+		let i = V.current;
+		return V.current = !1, F(!1), N(!1), L(null), T.current?.destroy(), T.current = null, D(r, e, {
+			skipPending: i,
 			loopCount: d,
 			onPlay: () => {
-				j(!0), T.current?.();
+				t === H.current && N(!0), E.current?.();
 			},
 			onPause: () => {
-				j(!1), E.current?.();
+				t === H.current && N(!1), O.current?.();
 			},
 			onEnd: () => {
-				j(!1), D.current?.();
-			},
-			onLoaded: (e) => {
-				F(e), O.current?.(e);
+				t === H.current && N(!1), k.current?.();
 			}
-		}).then((e) => {
-			if (t) {
-				e.destroy();
+		}).then(({ controller: r, stats: i }) => {
+			if (A.current?.(i), n || t !== H.current) {
+				r.destroy({ clearCanvas: !1 });
 				return;
 			}
-			w.current = e, N(!0), c && (e.play(), j(!0));
+			C(e), T.current = r;
+			let a = r.destroy.bind(r);
+			r.destroy = (t) => {
+				a(t), w(e);
+			}, F(!0), L(i), c && (r.play(), N(!0));
 		}).catch((e) => {
-			t || (F(null), k.current?.(e instanceof Error ? e : Error(String(e))));
+			t === H.current && L(null), j.current?.(e instanceof Error ? e : Error(String(e)));
 		}), () => {
-			t = !0, w.current?.destroy(), w.current = null;
+			n = !0, t === H.current && (T.current?.destroy(), T.current = null);
 		};
 	}, [
 		e,
@@ -471,19 +723,19 @@ var C = e(({ src: e, autoPlay: c = !0, showControls: l = !1, debug: u = !1, loop
 		c
 	]);
 	return r(x, () => ({
-		play: z,
-		pause: B,
-		toggle: V,
-		reset: H,
-		reload: U,
-		isPlaying: () => w.current?.isPlaying() ?? !1
+		play: U,
+		pause: W,
+		toggle: G,
+		reset: K,
+		reload: q,
+		isPlaying: () => T.current?.isPlaying() ?? !1
 	}), [
-		z,
-		B,
-		V,
-		H,
-		U
-	]), n(() => W(), [W, I]), /* @__PURE__ */ s("div", {
+		U,
+		W,
+		G,
+		K,
+		q
+	]), n(() => J(), [J, R]), /* @__PURE__ */ s("div", {
 		className: [
 			"gif-player",
 			l && "gif-player--show-controls",
@@ -492,26 +744,27 @@ var C = e(({ src: e, autoPlay: c = !0, showControls: l = !1, debug: u = !1, loop
 		style: p,
 		children: [
 			/* @__PURE__ */ o("canvas", {
-				ref: C,
+				ref: S,
 				className: "gif-player__media",
 				role: "img",
 				style: {
 					...m === void 0 ? {} : { width: m },
 					...h === void 0 ? {} : { height: h },
-					...M ? {} : { visibility: "hidden" }
+					...P ? {} : { visibility: "hidden" }
 				}
 			}),
-			u && P !== null && /* @__PURE__ */ s("span", {
-				className: "gif-player__debug",
-				children: [P.toFixed(1), "ms"]
+			u && I !== null && P && /* @__PURE__ */ o(B, {
+				stats: I,
+				canvasRef: S,
+				visible: P
 			}),
-			l && M && /* @__PURE__ */ o("div", {
+			l && P && /* @__PURE__ */ o("div", {
 				className: "gif-player__controls",
 				children: /* @__PURE__ */ o("button", {
 					type: "button",
 					className: "gif-player__btn",
-					onClick: V,
-					children: A ? /* @__PURE__ */ s("svg", {
+					onClick: G,
+					children: M ? /* @__PURE__ */ s("svg", {
 						viewBox: "0 0 24 24",
 						"aria-hidden": "true",
 						children: [/* @__PURE__ */ o("rect", {
@@ -537,6 +790,6 @@ var C = e(({ src: e, autoPlay: c = !0, showControls: l = !1, debug: u = !1, loop
 		]
 	});
 });
-C.displayName = "GifPlayer";
+V.displayName = "GifPlayer";
 //#endregion
-export { C as GifPlayer, S as createGifController };
+export { V as GifPlayer, T as clearGifResourceCache, D as createGifController, A as formatGifLoadStats, j as formatLoadTimeMs, k as getGifLoadStatsView, O as getTotalLoadTimeMs };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { GifPlayer } from './components/GifPlayer';
 export type { GifPlayerComponent, GifPlayerProps, GifPlayerRef, } from './components/GifPlayer';
-export { createGifController } from './utils';
-export type { CreateGifOptions, GifController } from './utils';
+export { createGifController, clearGifResourceCache, formatGifLoadStats, formatLoadTimeMs, getGifLoadStatsView, getTotalLoadTimeMs } from './utils';
+export type { CreateGifOptions, GifController, GifLoadStats, GifLoadStatsLine, GifLoadStatsMode, GifLoadStatsView } from './utils';

package/dist/utils/gifController.d.ts

@@ -1,2 +1,5 @@
-import type { CreateGifOptions, GifController } from './types';
-export declare function createGifController(canvas: HTMLCanvasElement, src: string, options?: CreateGifOptions): Promise<GifController>;
+import type { CreateGifOptions, GifController, GifLoadStats } from './types';
+export declare function createGifController(canvas: HTMLCanvasElement, src: string, options?: CreateGifOptions): Promise<{
+    controller: GifController;
+    stats: GifLoadStats;
+}>;

package/dist/utils/gifResourceManager.d.ts

@@ -1,13 +1,13 @@
-import type { LoadedGif } from './types';
+import type { LoadedGif, GifLoadStats } from './types';
 interface LoadGifResourceOptions {
-    /** reload 等场景：不复用进行中的请求，直接发起新 fetch */
     skipPending?: boolean;
 }
 interface LoadGifResult {
     gif: LoadedGif;
-    decodeTimeMs: number;
+    stats: GifLoadStats;
 }
 export declare function loadGifResource(src: string, options?: LoadGifResourceOptions): Promise<LoadGifResult>;
+export declare function acquireGifResource(src: string): void;
 export declare function releaseGifResource(src: string): void;
 export declare function clearGifResourceCache(): void;
 export {};

package/dist/utils/index.d.ts

@@ -1,2 +1,5 @@
 export { createGifController } from './gifController';
-export type { CreateGifOptions, GifController } from './types';
+export { acquireGifResource, clearGifResourceCache, releaseGifResource } from './gifResourceManager';
+export { formatGifLoadStats, formatGifLoadStatsCompact, formatLoadTimeMs, getDebugDensity, getGifLoadStatsView, getTotalLoadTimeMs } from './loadStats';
+export type { GifLoadStatsLine, GifLoadStatsMode, GifLoadStatsView } from './loadStats';
+export type { CreateGifOptions, GifController, GifLoadStats } from './types';

package/dist/utils/loadStats.d.ts

@@ -0,0 +1,18 @@
+import type { GifLoadStats } from './types';
+export declare function getTotalLoadTimeMs(stats: GifLoadStats): number;
+export type GifLoadStatsMode = 'fresh' | 'pending' | 'cache';
+export interface GifLoadStatsLine {
+    label: string;
+    valueMs: number;
+}
+export interface GifLoadStatsView {
+    mode: GifLoadStatsMode;
+    lines: GifLoadStatsLine[];
+    totalMs: number;
+}
+export declare function getGifLoadStatsView(stats: GifLoadStats): GifLoadStatsView;
+export declare function formatGifLoadStats(stats: GifLoadStats): string;
+export declare function formatLoadTimeMs(ms: number): string;
+export declare function getDebugDensity(width: number, height: number): 'compact' | 'medium' | 'full';
+export declare function formatGifLoadStatsCompact(stats: GifLoadStats): string;
+export declare function getGifLoadStatsLineLabel(line: GifLoadStatsLine, mode: GifLoadStatsMode): string;

package/dist/utils/types.d.ts

@@ -4,20 +4,33 @@ export interface LoadedGif {
     width: number;
     height: number;
 }
+export interface GifLoadStats {
+    /** 本次实际 fetch 耗时，仅 fresh 发起方有值 */
+    fetchTimeMs: number;
+    /** 本次实际 decode 耗时，仅 fresh 发起方有值 */
+    decodeTimeMs: number;
+    /** 等待进行中的 fetch 阶段，仅 pending */
+    pendingWaitFetchMs: number;
+    /** 等待进行中的 decode 阶段，仅 pending */
+    pendingWaitDecodeMs: number;
+    fromCache: boolean;
+    fromPending: boolean;
+}
 export interface CreateGifOptions {
     loopCount?: number;
     onEnd?: () => void;
     onPlay?: () => void;
     onPause?: () => void;
-    onLoaded?: (decodeTimeMs: number) => void;
-    /** reload 等场景：不复用进行中的请求，直接发起新 fetch */
+    onLoaded?: (stats: GifLoadStats) => void;
     skipPending?: boolean;
 }
 export interface GifController {
     play: () => void;
     pause: () => void;
     reset: () => void;
-    destroy: () => void;
+    destroy: (options?: {
+        clearCanvas?: boolean;
+    }) => void;
     isPlaying: () => boolean;
     getCompletedLoops: () => number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libshub/gif-tools",
-  "version": "1.0.3",
+  "version": "1.0.8",
   "description": "",
   "module": "./dist/gif-tools.es.js",
   "types": "./dist/index.d.ts",
@@ -27,6 +27,8 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build && tsc -p tsconfig.lib.json",
+    "build:example": "vite build --config vite.example.config.ts",
+    "preview:example": "vite preview --config vite.example.config.ts",
     "lint": "eslint .",
     "preview": "vite preview"
   },
@@ -53,4 +55,4 @@
   "dependencies": {
     "gifuct-js": "^2.1.2"
   }
-}
+}