@wapri/preview 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wapri contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @wapri/preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 H5 的文件预览包：文本、PDF、Word（docx）、Excel（xlsx / xls / csv）。解析与渲染分离，按可视区域懒渲染，支持本地文件与远程地址。
+
+## 安装
+
+```bash
+pnpm add @wapri/preview
+```
+
+## 快速开始
+
+```ts
+import { previewFile } from '@wapri/preview'
+
+const handle = await previewFile(file, {
+  container: document.querySelector('#viewer')!,
+  pdf: { thumbnails: true },
+})
+
+handle.refresh() // 容器尺寸变化后重排
+handle.destroy() // 释放 canvas、worker、objectURL
+```
+
+远程文件与自定义请求头：
+
+```ts
+const handle = await previewFile(
+  { url: '/files/report.pdf', headers: { Authorization: 'Bearer token' } },
+  { container: document.querySelector('#viewer')! },
+)
+```
+
+`previewFile` 会读取文件头识别类型，再分发到 `previewText` / `previewPdf` / `previewWord` / `previewXlsx`。
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `previewFile(input, options)` | 自动识别类型并预览 |
+| `previewText(input, options)` | 文本预览，按行分块懒渲染 |
+| `previewPdf(input, options)` | PDF 预览，pdf.js + Canvas，支持缩略图 |
+| `previewWord(input, options)` | Word 预览，mammoth 解析 + opentype 排版 + Canvas 分页 |
+| `previewXlsx(input, options)` | Excel 预览，SheetJS 解析 + 虚拟表格 |
+| `configurePdfjs(config)` | 配置 pdf.js worker、CMap、标准字体地址 |
+
+`input` 支持 `File` / `Blob` / `ArrayBuffer` / `ArrayBufferView` / URL 字符串 / `{ url, fileName?, headers? }`。
+
+通用 options：`container`、`className`、`lazy`、`overscan`、`theme`、`onProgress`。
+
+## 渲染策略
+
+| 类型 | 解析 | 渲染 | 懒渲染粒度 |
+| --- | --- | --- | --- |
+| 文本 | 主线程按行分块 | DOM | 80 行一块 |
+| PDF | pdf.js worker | Canvas | 每页 |
+| Word | mammoth + opentype 排版 | Canvas | 每页 |
+| XLSX | SheetJS（worker 优先） | DOM 绝对定位单元格 | 可视行列 |
+
+## 资源与配置
+
+- PDF：必须调用 `configurePdfjs({ workerSrc })` 指定可访问的 `pdf.worker.min.mjs` 地址。打包器会把 `import.meta.url` 改写成构建路径（webpack 下是 `file://`），包内相对路径无法可靠定位 worker；文档站 demo 使用 `/pdf.worker.min.mjs`，业务按自己的部署位置配置。中文 PDF 建议同时配置 `cMapUrl`。
+- XLSX：默认尝试用包内 `dist/vendor/xlsx.full.min.js` 在 worker 中解析，地址不可用时自动回退主线程；也可以用 `workerScript` 显式指定自己的 UMD 地址。
+- Word：传入 `fonts`（TTF / OTF 的 `ArrayBuffer[]`）可用 opentype.js 精确测量并绘制，不传时回退 Canvas 字体。
+
+## 依赖
+
+- `@wapri/gbase`：Worker 通道、Object URL 管理、文件读取、类型嗅探、可视区域观察
+- `pdfjs-dist`、`mammoth`、`xlsx`、`opentype.js`
+
+## 注意
+
+- 预览只读取用户选择的文件，不上传、不落盘。
+- 大文件解析会占用主线程内存，`maxCells`（XLSX）等上限参数可按业务调整。
+
+
+## 在线文档
+
+https://sdmu-gaoqi.github.io/wapri/previews

package/dist/constant/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 预览包常量：class 前缀、默认尺寸与分块参数。
+ */
+export declare const PREVIEW_PACKAGE_NAME = "@wapri/preview";
+/** 所有节点 class 统一用它做前缀，便于业务方覆盖样式 */
+export declare const PREVIEW_PREFIX = "wa-preview";
+export declare const PREVIEW_CLASS: {
+    readonly root: "wa-preview";
+    readonly viewport: "wa-preview__viewport";
+    readonly page: "wa-preview__page";
+    readonly pageCanvas: "wa-preview__page-canvas";
+    readonly pageLabel: "wa-preview__page-label";
+    readonly thumbnails: "wa-preview__thumbnails";
+    readonly thumbnail: "wa-preview__thumbnail";
+    readonly text: "wa-preview__text";
+    readonly textChunk: "wa-preview__text-chunk";
+    readonly textLine: "wa-preview__text-line";
+    readonly sheetTabs: "wa-preview__sheet-tabs";
+    readonly sheetTab: "wa-preview__sheet-tab";
+    readonly sheetTabActive: "wa-preview__sheet-tab--active";
+    readonly grid: "wa-preview__grid";
+    readonly gridHeader: "wa-preview__grid-header";
+    readonly gridCell: "wa-preview__grid-cell";
+    readonly gridRow: "wa-preview__grid-row";
+    readonly empty: "wa-preview__empty";
+    readonly error: "wa-preview__error";
+};
+/** 文本预览默认按 80 行分一块 */
+export declare const TEXT_CHUNK_LINES = 80;
+/** XLSX 默认行列尺寸，单位 px */
+export declare const XLSX_DEFAULT_COL_WIDTH = 100;
+export declare const XLSX_DEFAULT_ROW_HEIGHT = 24;
+/** 单表最多解析单元格数量，避免超大表把内存打爆 */
+export declare const XLSX_MAX_CELLS = 200000;
+/** Word 默认页面为 A4 @96dpi */
+export declare const WORD_PAGE_WIDTH = 794;
+export declare const WORD_PAGE_HEIGHT = 1123;
+export declare const WORD_PAGE_PADDING = 72;
+/** PDF 缩略图宽度 */
+export declare const PDF_THUMBNAIL_WIDTH = 96;
+/** 默认主题 */
+export declare const DEFAULT_THEME: {
+    readonly color: "#1f2329";
+    readonly mutedColor: "#8f959e";
+    readonly background: "#f2f3f5";
+    readonly paper: "#ffffff";
+    readonly accent: "#3370ff";
+    readonly fontFamily: "-apple-system, BlinkMacSystemFont, \"PingFang SC\", \"Hiragino Sans GB\", \"Microsoft YaHei\", sans-serif";
+    readonly fontSize: 14;
+    readonly lineHeight: 1.7;
+};

package/dist/constant/index.js

@@ -0,0 +1,58 @@
+/**
+ * 预览包常量：class 前缀、默认尺寸与分块参数。
+ */
+
+export var PREVIEW_PACKAGE_NAME = '@wapri/preview';
+
+/** 所有节点 class 统一用它做前缀，便于业务方覆盖样式 */
+export var PREVIEW_PREFIX = 'wa-preview';
+export var PREVIEW_CLASS = {
+  root: PREVIEW_PREFIX,
+  viewport: "".concat(PREVIEW_PREFIX, "__viewport"),
+  page: "".concat(PREVIEW_PREFIX, "__page"),
+  pageCanvas: "".concat(PREVIEW_PREFIX, "__page-canvas"),
+  pageLabel: "".concat(PREVIEW_PREFIX, "__page-label"),
+  thumbnails: "".concat(PREVIEW_PREFIX, "__thumbnails"),
+  thumbnail: "".concat(PREVIEW_PREFIX, "__thumbnail"),
+  text: "".concat(PREVIEW_PREFIX, "__text"),
+  textChunk: "".concat(PREVIEW_PREFIX, "__text-chunk"),
+  textLine: "".concat(PREVIEW_PREFIX, "__text-line"),
+  sheetTabs: "".concat(PREVIEW_PREFIX, "__sheet-tabs"),
+  sheetTab: "".concat(PREVIEW_PREFIX, "__sheet-tab"),
+  sheetTabActive: "".concat(PREVIEW_PREFIX, "__sheet-tab--active"),
+  grid: "".concat(PREVIEW_PREFIX, "__grid"),
+  gridHeader: "".concat(PREVIEW_PREFIX, "__grid-header"),
+  gridCell: "".concat(PREVIEW_PREFIX, "__grid-cell"),
+  gridRow: "".concat(PREVIEW_PREFIX, "__grid-row"),
+  empty: "".concat(PREVIEW_PREFIX, "__empty"),
+  error: "".concat(PREVIEW_PREFIX, "__error")
+};
+
+/** 文本预览默认按 80 行分一块 */
+export var TEXT_CHUNK_LINES = 80;
+
+/** XLSX 默认行列尺寸，单位 px */
+export var XLSX_DEFAULT_COL_WIDTH = 100;
+export var XLSX_DEFAULT_ROW_HEIGHT = 24;
+/** 单表最多解析单元格数量，避免超大表把内存打爆 */
+export var XLSX_MAX_CELLS = 200000;
+
+/** Word 默认页面为 A4 @96dpi */
+export var WORD_PAGE_WIDTH = 794;
+export var WORD_PAGE_HEIGHT = 1123;
+export var WORD_PAGE_PADDING = 72;
+
+/** PDF 缩略图宽度 */
+export var PDF_THUMBNAIL_WIDTH = 96;
+
+/** 默认主题 */
+export var DEFAULT_THEME = {
+  color: '#1f2329',
+  mutedColor: '#8f959e',
+  background: '#f2f3f5',
+  paper: '#ffffff',
+  accent: '#3370ff',
+  fontFamily: '-apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif',
+  fontSize: 14,
+  lineHeight: 1.7
+};

package/dist/core/context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 预览上下文：解析容器、合并主题、注入样式、统一销毁。
+ */
+import type { BasePreviewOptions, PreviewProgress, PreviewTheme } from '../types/common';
+export interface PreviewContext {
+    readonly container: HTMLElement;
+    readonly root: HTMLElement;
+    readonly viewport: HTMLElement;
+    readonly theme: Required<PreviewTheme>;
+    readonly options: BasePreviewOptions;
+    /** 注册销毁回调，按注册顺序逆序执行 */
+    onDestroy(callback: () => void): void;
+    /** 汇报进度 */
+    emitProgress(progress: PreviewProgress): void;
+    /** 渲染错误态 */
+    fail(error: unknown): void;
+    /** 释放容器与全部副作用 */
+    destroy(): void;
+}
+export declare const resolveContainer: (target: HTMLElement | string) => HTMLElement;
+export declare const createPreviewContext: (options: BasePreviewOptions) => PreviewContext;

package/dist/core/context.js

@@ -0,0 +1,78 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 预览上下文：解析容器、合并主题、注入样式、统一销毁。
+ */
+
+import { DEFAULT_THEME, PREVIEW_CLASS } from "../constant";
+import { ensurePreviewStyles } from "./style";
+export var resolveContainer = function resolveContainer(target) {
+  if (typeof target !== 'string') return target;
+  var element = document.querySelector(target);
+  if (!element) {
+    throw new Error("[preview] \u627E\u4E0D\u5230\u5BB9\u5668\uFF1A".concat(target));
+  }
+  return element;
+};
+var toErrorMessage = function toErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return '预览失败';
+};
+export var createPreviewContext = function createPreviewContext(options) {
+  ensurePreviewStyles();
+  var container = resolveContainer(options.container);
+  var theme = _objectSpread(_objectSpread({}, DEFAULT_THEME), options.theme);
+  var callbacks = [];
+  var root = document.createElement('div');
+  root.className = [PREVIEW_CLASS.root, options.className].filter(Boolean).join(' ');
+  root.style.setProperty('--wa-preview-color', theme.color);
+  root.style.setProperty('--wa-preview-muted', theme.mutedColor);
+  root.style.setProperty('--wa-preview-background', theme.background);
+  root.style.setProperty('--wa-preview-paper', theme.paper);
+  root.style.setProperty('--wa-preview-accent', theme.accent);
+  root.style.setProperty('--wa-preview-font-family', theme.fontFamily);
+  root.style.setProperty('--wa-preview-font-size', "".concat(theme.fontSize, "px"));
+  root.style.setProperty('--wa-preview-line-height', String(theme.lineHeight));
+  var viewport = document.createElement('div');
+  viewport.className = PREVIEW_CLASS.viewport;
+  root.appendChild(viewport);
+  container.appendChild(root);
+  var destroyed = false;
+  var context = {
+    container: container,
+    root: root,
+    viewport: viewport,
+    theme: theme,
+    options: options,
+    onDestroy: function onDestroy(callback) {
+      callbacks.push(callback);
+    },
+    emitProgress: function emitProgress(progress) {
+      var _options$onProgress;
+      (_options$onProgress = options.onProgress) === null || _options$onProgress === void 0 || _options$onProgress.call(options, progress);
+    },
+    fail: function fail(error) {
+      var message = toErrorMessage(error);
+      var box = document.createElement('div');
+      box.className = PREVIEW_CLASS.error;
+      box.textContent = message;
+      viewport.innerHTML = '';
+      viewport.appendChild(box);
+    },
+    destroy: function destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      while (callbacks.length > 0) {
+        var _callbacks$pop;
+        (_callbacks$pop = callbacks.pop()) === null || _callbacks$pop === void 0 || _callbacks$pop();
+      }
+      root.remove();
+    }
+  };
+  return context;
+};

package/dist/core/lazy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 可视区域懒渲染池。
+ *
+ * 每个可渲染单元（文本块、PDF 页、表格行、Word 页）注册进来，
+ * 进入视口才执行 render，离开视口按 keepAlive 决定是否调用 release 释放位图。
+ */
+export interface LazyTarget {
+    element: HTMLElement;
+    render: () => void | Promise<void>;
+    /** 离开视口时释放，例如把 canvas 宽高置 0 */
+    release?: () => void;
+}
+export interface LazyPoolOptions {
+    /** IntersectionObserver 的 root，通常是滚动容器 */
+    root?: HTMLElement | null;
+    /** 提前渲染的边距，默认 1 屏 */
+    rootMargin?: string;
+    /** 离开视口是否保留渲染结果，默认 true */
+    keepAlive?: boolean;
+    /** 同时渲染的最大数量，默认 2 */
+    maxConcurrent?: number;
+}
+export declare class LazyRenderPool {
+    private readonly observer?;
+    private readonly entries;
+    private readonly queue;
+    private readonly keepAlive;
+    private readonly maxConcurrent;
+    private running;
+    private destroyed;
+    constructor(options?: LazyPoolOptions);
+    get renderedCount(): number;
+    /** 注册一个懒渲染单元，返回取消注册函数 */
+    register(target: LazyTarget): () => void;
+    /** 立即渲染全部单元，用于打印、导出或关闭懒加载 */
+    renderAll(): void;
+    /** 丢弃已渲染结果并重新观察，用于容器尺寸变化后重排 */
+    reset(): void;
+    destroy(): void;
+    private readonly handleIntersect;
+    private enqueue;
+    private pump;
+}

package/dist/core/lazy.js

@@ -0,0 +1,175 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 可视区域懒渲染池。
+ *
+ * 每个可渲染单元（文本块、PDF 页、表格行、Word 页）注册进来，
+ * 进入视口才执行 render，离开视口按 keepAlive 决定是否调用 release 释放位图。
+ */
+
+export var LazyRenderPool = /*#__PURE__*/function () {
+  function LazyRenderPool() {
+    var _this = this,
+      _options$keepAlive,
+      _options$maxConcurren;
+    var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classCallCheck(this, LazyRenderPool);
+    _defineProperty(this, "observer", void 0);
+    _defineProperty(this, "entries", new Map());
+    _defineProperty(this, "queue", []);
+    _defineProperty(this, "keepAlive", void 0);
+    _defineProperty(this, "maxConcurrent", void 0);
+    _defineProperty(this, "running", 0);
+    _defineProperty(this, "destroyed", false);
+    _defineProperty(this, "handleIntersect", function (records) {
+      var _iterator = _createForOfIteratorHelper(records),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var record = _step.value;
+          var entry = _this.entries.get(record.target);
+          if (!entry) continue;
+          if (record.isIntersecting) {
+            _this.enqueue(entry);
+            continue;
+          }
+          if (!_this.keepAlive && entry.rendered) {
+            var _entry$target$release, _entry$target;
+            (_entry$target$release = (_entry$target = entry.target).release) === null || _entry$target$release === void 0 || _entry$target$release.call(_entry$target);
+            entry.rendered = false;
+          }
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+    });
+    this.keepAlive = (_options$keepAlive = options.keepAlive) !== null && _options$keepAlive !== void 0 ? _options$keepAlive : true;
+    this.maxConcurrent = Math.max(1, (_options$maxConcurren = options.maxConcurrent) !== null && _options$maxConcurren !== void 0 ? _options$maxConcurren : 2);
+    if (typeof IntersectionObserver !== 'undefined') {
+      var _options$root, _options$rootMargin;
+      this.observer = new IntersectionObserver(this.handleIntersect, {
+        root: (_options$root = options.root) !== null && _options$root !== void 0 ? _options$root : null,
+        rootMargin: (_options$rootMargin = options.rootMargin) !== null && _options$rootMargin !== void 0 ? _options$rootMargin : '100% 0px',
+        threshold: 0.01
+      });
+    }
+  }
+  _createClass(LazyRenderPool, [{
+    key: "renderedCount",
+    get: function get() {
+      var count = 0;
+      this.entries.forEach(function (entry) {
+        if (entry.rendered) count += 1;
+      });
+      return count;
+    }
+
+    /** 注册一个懒渲染单元，返回取消注册函数 */
+  }, {
+    key: "register",
+    value: function register(target) {
+      var _this2 = this;
+      var entry = {
+        target: target,
+        rendered: false,
+        queued: false
+      };
+      this.entries.set(target.element, entry);
+      if (!this.observer) {
+        // 没有 IntersectionObserver 时直接全量渲染
+        this.enqueue(entry);
+        return function () {
+          return _this2.entries.delete(target.element);
+        };
+      }
+      this.observer.observe(target.element);
+      return function () {
+        var _this2$observer;
+        (_this2$observer = _this2.observer) === null || _this2$observer === void 0 || _this2$observer.unobserve(target.element);
+        _this2.entries.delete(target.element);
+      };
+    }
+
+    /** 立即渲染全部单元，用于打印、导出或关闭懒加载 */
+  }, {
+    key: "renderAll",
+    value: function renderAll() {
+      var _this3 = this;
+      this.entries.forEach(function (entry) {
+        return _this3.enqueue(entry);
+      });
+    }
+
+    /** 丢弃已渲染结果并重新观察，用于容器尺寸变化后重排 */
+  }, {
+    key: "reset",
+    value: function reset() {
+      var _this4 = this;
+      this.queue.length = 0;
+      this.entries.forEach(function (entry) {
+        var _entry$target$release2, _entry$target2;
+        entry.rendered = false;
+        entry.queued = false;
+        (_entry$target$release2 = (_entry$target2 = entry.target).release) === null || _entry$target$release2 === void 0 || _entry$target$release2.call(_entry$target2);
+        if (!_this4.observer) {
+          _this4.enqueue(entry);
+          return;
+        }
+
+        // 重新 observe 会重新触发一次 intersect 回调
+        _this4.observer.unobserve(entry.target.element);
+        _this4.observer.observe(entry.target.element);
+      });
+    }
+  }, {
+    key: "destroy",
+    value: function destroy() {
+      var _this$observer;
+      this.destroyed = true;
+      (_this$observer = this.observer) === null || _this$observer === void 0 || _this$observer.disconnect();
+      this.entries.clear();
+      this.queue.length = 0;
+    }
+  }, {
+    key: "enqueue",
+    value: function enqueue(entry) {
+      if (entry.rendered || entry.queued) return;
+      entry.queued = true;
+      this.queue.push(entry);
+      this.pump();
+    }
+  }, {
+    key: "pump",
+    value: function pump() {
+      var _this5 = this;
+      var _loop = function _loop() {
+        var entry = _this5.queue.shift();
+        if (!entry || entry.rendered) return 1; // continue
+        _this5.running += 1;
+        Promise.resolve(entry.target.render()).then(function () {
+          entry.rendered = true;
+        }).catch(function (error) {
+          console.error('[preview] 渲染单元失败', error);
+        }).finally(function () {
+          entry.queued = false;
+          _this5.running -= 1;
+          _this5.pump();
+        });
+      };
+      while (!this.destroyed && this.running < this.maxConcurrent && this.queue.length > 0) {
+        if (_loop()) continue;
+      }
+    }
+  }]);
+  return LazyRenderPool;
+}();

package/dist/core/source.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 输入来源解析：把 File / Blob / ArrayBuffer / URL 统一成可识别的字节流。
+ */
+import type { PreviewInput } from '../types/common';
+import type { FileCategory } from '@wapri/gbase';
+export interface ResolvedSource {
+    /** 预览能力分类 */
+    kind: 'text' | 'pdf' | 'word' | 'xlsx';
+    /** 原始识别分类，便于调用方判断 doc/ppt 等不支持的类型 */
+    category: FileCategory;
+    name: string;
+    extension: string;
+    mime: string;
+    buffer: ArrayBuffer;
+}
+export declare class PreviewUnsupportedError extends Error {
+    constructor(message: string);
+}
+/** 解析来源并读取整个文件；远程文件支持自定义请求头 */
+export declare const resolvePreviewSource: (input: PreviewInput) => Promise<ResolvedSource>;