@darialan/web-printer 0.0.0-stage → 1.0.1

package/dist/types/application/print-service.d.ts

@@ -0,0 +1,55 @@
+import { OutputFormat } from '../output';
+import { Interval, MeasurementStats, PageSlice } from '../core/types';
+import { LayoutOptions, PreparedLayout } from './print-pipeline';
+export interface ExportOptions extends LayoutOptions {
+    filename: string;
+    download?: boolean;
+    onProgress?: (completed: number, total: number) => void;
+}
+export interface DocumentExportOptions extends ExportOptions {
+    format?: OutputFormat;
+}
+export interface PreviewPaginationOptions extends Omit<LayoutOptions, 'element'> {
+    contentElement: HTMLElement | null;
+}
+export interface PrintInspectionResult {
+    pageBreaks: number[];
+    pages: PageSlice[];
+    totalHeight: number;
+    capacity: number;
+    protectedRanges: Interval[];
+    stats?: MeasurementStats;
+    timing: {
+        measurementMs: number;
+        paginationMs: number;
+        totalMs: number;
+    };
+}
+/** Share snapshot, pagination and page capture across all output formats. */
+export declare function outputDocument({ format, filename, download, onProgress, ...options }: DocumentExportOptions): Promise<{
+    blob: Blob;
+    pages: number;
+    layoutMs: number;
+    totalMs: number;
+    bytes: number;
+}>;
+/** Export an already frozen layout. The session owns its cleanup. */
+export declare function exportPreparedLayout(layout: PreparedLayout, options: Omit<DocumentExportOptions, 'element'>, layoutMs?: number): Promise<{
+    blob: Blob;
+    pages: number;
+    layoutMs: number;
+    totalMs: number;
+    bytes: number;
+}>;
+/** Backward-compatible PDF entry point. */
+export declare function outputPDF(options: ExportOptions): Promise<{
+    blob: Blob;
+    pages: number;
+    layoutMs: number;
+    totalMs: number;
+    bytes: number;
+}>;
+/** Run full snapshot measurement and pagination validation, returning structured diagnostics. */
+export declare function inspectPrintLayout({ contentElement, ...options }: PreviewPaginationOptions): Promise<PrintInspectionResult>;
+/** Uses the exact snapshot measurement and page planner used by PDF export, with coordinates relative to the prepared print snapshot. */
+export declare function calculatePagesArray(options: PreviewPaginationOptions): Promise<number[]>;

package/dist/types/application/print-session.d.ts

@@ -0,0 +1,17 @@
+import { LayoutOptions } from './print-pipeline';
+import { DocumentExportOptions } from './print-service';
+/** A frozen document shared by preview, inspection and all output formats. */
+export declare function createPrintSession(options: LayoutOptions): Promise<{
+    layout: any;
+    preparedMs: number;
+    thumbnail(index: number, maxWidth?: number): Promise<string>;
+    exportDocument(params: Omit<DocumentExportOptions, 'element' | 'settings'>): Promise<{
+        blob: Blob;
+        pages: number;
+        layoutMs: number;
+        totalMs: number;
+        bytes: number;
+    }>;
+    dispose(): void;
+}>;
+export type PrintSession = Awaited<ReturnType<typeof createPrintSession>>;

package/dist/types/core/geometry/index.d.ts

@@ -0,0 +1,2 @@
+export * from './paper';
+export * from './page-geometry';

package/dist/types/core/geometry/page-geometry.d.ts

@@ -0,0 +1,18 @@
+import { ResolvedPaper } from './paper';
+import { PageNumberConfig } from '../types';
+export interface PageGeometry {
+    pageWidth: number;
+    pageHeight: number;
+    contentWidth: number;
+    ratio: number;
+    headerHeight: number;
+    footerHeight: number;
+    bodyTop: number;
+    left: number;
+    headerY: number;
+    footerY: number;
+    pageNumberY: number;
+    capacity: number;
+}
+/** Paper units (pt) and DOM units (CSS px) meet only at this boundary. */
+export declare function calculateGeometry(paper: ResolvedPaper, width: number, headerPx: number | undefined, footerPx: number | undefined, pageNumber?: boolean | PageNumberConfig): PageGeometry;

package/dist/types/core/geometry/paper.d.ts

@@ -0,0 +1,83 @@
+import { Orientation, Paper, PrintSettings } from '../types';
+export type { Orientation, Paper, PrintSettings } from '../types';
+export declare const PT_PER_MM: number;
+export declare const MM_PER_PX: number;
+export declare const PX_PER_MM: number;
+/** 社媒 / 图片画框：以像素定义，边距按画框宽度的内边距给默认值 */
+export declare const IMAGE_PAPER_SIZES: {
+    readonly 'card-3x4': {
+        readonly widthPx: 1242;
+        readonly heightPx: 1656;
+        readonly marginPx: 60;
+    };
+    readonly 'square-1x1': {
+        readonly widthPx: 1080;
+        readonly heightPx: 1080;
+        readonly marginPx: 54;
+    };
+    readonly 'card-4x5': {
+        readonly widthPx: 1080;
+        readonly heightPx: 1350;
+        readonly marginPx: 54;
+    };
+    readonly 'story-9x16': {
+        readonly widthPx: 1080;
+        readonly heightPx: 1920;
+        readonly marginPx: 54;
+    };
+    readonly 'ecom-750x1000': {
+        readonly widthPx: 750;
+        readonly heightPx: 1000;
+        readonly marginPx: 0;
+    };
+};
+export type ImagePaper = keyof typeof IMAGE_PAPER_SIZES;
+export declare const IMAGE_PAPERS: ("card-3x4" | "square-1x1" | "card-4x5" | "story-9x16" | "ecom-750x1000")[];
+export declare function isImagePaper(paper: Paper): paper is ImagePaper;
+/** 预设自带的自然单位：纸张用 mm，社媒图片用 px，选中时自动切换，避免出现 328.61 mm 这种数字 */
+export declare function getPresetUnit(paper: Paper): 'mm' | 'px';
+export declare const PAPER_SIZES: Record<Exclude<Paper, 'custom'>, [number, number]>;
+export interface PaperPreset {
+    widthMm: number;
+    heightMm: number;
+    marginTopMm: number;
+    marginRightMm: number;
+    marginBottomMm: number;
+    marginLeftMm: number;
+}
+/**
+ * 各纸张预设标准（基准存储单位：mm）：
+ * - A4、A3、A5、Letter 具有固定的标准物理宽高与统一默认页边距（10mm）
+ * - 自定义尺寸（custom）：
+ *   - 宽默认为 A4 纸宽度：210 mm (96 DPI 下对应 793.7 px)
+ *   - 高度默认为 200 px (对应 200 * 25.4 / 96 ≈ 52.92 mm)
+ *   - 上下左右边距默认为 2 px (对应 2 * 25.4 / 96 ≈ 0.53 mm)
+ */
+export declare const PAPER_PRESETS: Record<Paper, PaperPreset>;
+export declare const DEFAULT_SETTINGS: PrintSettings;
+/**
+ * 根据纸张类型、纸张方向以及目标单位获取联动标准数值
+ */
+export declare function getPresetDimensions(paper: Paper, orientation?: Orientation, unit?: 'mm' | 'px'): {
+    width: number;
+    height: number;
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+};
+export declare function mmToPt(mm: number): number;
+export declare function resolvePaper(settings: PrintSettings): {
+    pageWidth: number;
+    pageHeight: number;
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    widthMm: number;
+    heightMm: number;
+};
+export type ResolvedPaper = ReturnType<typeof resolvePaper>;
+export declare const UNIT_FIELDS: readonly ["widthMm", "heightMm", "marginTopMm", "marginRightMm", "marginBottomMm", "marginLeftMm"];
+/** Storage stays in mm; px means CSS pixels at 96 DPI, independent of devicePixelRatio. */
+export declare function convertFields<T extends PrintSettings>(value: T, factor: number): T;

package/dist/types/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './rules';
+export * from './pagination';
+export * from './geometry';

package/dist/types/core/pagination/index.d.ts

@@ -0,0 +1 @@
+export * from './paginator';

package/dist/types/core/pagination/paginator.d.ts

@@ -0,0 +1,6 @@
+import { Interval, PageSlice } from '../types';
+export type { Interval, PageSlice } from '../types';
+/** CSS-pixel intervals relative to the print root. No DOM or UI dependencies. */
+export declare function paginate(height: number, capacity: number, protectedRanges: Interval[], maxPages?: number): PageSlice[];
+/** Verify that planned page breaks do not cut through protected intervals. */
+export declare function validatePageBreaks(pages: PageSlice[], ranges: Interval[], tolerance?: number): void;

package/dist/types/core/rules/index.d.ts

@@ -0,0 +1 @@
+export * from './print-rules';

package/dist/types/core/rules/print-rules.d.ts

@@ -0,0 +1,80 @@
+import { ElementRule, PrintRule, PrintRuleConfig } from '../types';
+export type { ElementRule, PrintRule, PrintRuleConfig } from '../types';
+export interface ClassifiableNode {
+    nodeType: number;
+    textContent?: string | null;
+    matches?: (selector: string) => boolean;
+}
+/**
+ * 打印系统三大标准属性协议 (Data Attributes & Classes)
+ * 纯原生技术无关的标准协议，业务方自写组件或页面时直接绑定：
+ * 1. atomic: 最小原子单元，不可分割，跨页整块推移
+ * 2. splittable: 可分割流式内容，允许分页线从中穿透
+ * 3. ignore: 不打印，完全排除在打印纸张外
+ */
+export declare const PRINT_ATTRIBUTES: {
+    /** 不可分割：最小原子化单元，严禁跨页切断，当前页放不下整块换到下一页 */
+    readonly ATOMIC: "data-print-atomic=\"true\"";
+    /** 可分割：声明为流式内容，允许分页线直接穿透内部 */
+    readonly SPLITTABLE: "data-print-splittable=\"true\"";
+    /** 打印忽略：不参与测量、快照与打印渲染 */
+    readonly IGNORE: "data-print-ignore=\"true\"";
+    readonly KEEP_TOGETHER: "data-print-keep-together=\"true\"";
+    readonly KEEP_OR_SPLIT: "data-print-keep-together=\"split\"";
+    readonly FORCE_SPLIT: "data-print-break=\"split\"";
+};
+export declare const PRINT_CLASSES: {
+    readonly ATOMIC: "print-atomic";
+    readonly SPLITTABLE: "print-splittable";
+    readonly IGNORE: "print-ignore";
+    readonly KEEP_TOGETHER: "print-keep-together";
+    readonly KEEP_OR_SPLIT: "print-keep-or-split";
+    readonly FORCE_SPLIT: "print-force-split";
+};
+/** @deprecated Use PRINT_ATTRIBUTES. Legacy attributes remain accepted. */
+export declare const PDF_PRINT_ATTRIBUTES: {
+    readonly ATOMIC: "data-pdf-atomic=\"true\"";
+    readonly SPLITTABLE: "data-pdf-splittable=\"true\"";
+    readonly IGNORE: "data-pdf-ignore=\"true\"";
+    readonly KEEP_TOGETHER: "data-pdf-keep-together=\"true\"";
+    readonly KEEP_OR_SPLIT: "data-pdf-keep-together=\"split\"";
+    readonly FORCE_SPLIT: "data-pdf-break=\"split\"";
+};
+/** @deprecated Use PRINT_CLASSES. Legacy classes remain accepted. */
+export declare const PDF_PRINT_CLASSES: {
+    readonly ATOMIC: "pdf-atomic";
+    readonly SPLITTABLE: "pdf-splittable";
+    readonly IGNORE: "pdf-ignore";
+    readonly KEEP_TOGETHER: "pdf-keep-together";
+    readonly KEEP_OR_SPLIT: "pdf-keep-or-split";
+    readonly FORCE_SPLIT: "pdf-force-split";
+};
+/**
+ * 核心基础规则（BASE_PRINT_RULES）
+ * 遵循技术无关、纯原生标准原则：只包含 HTML 标准元素与通用打印协议，绝不硬编码任何具体前端组件库类名
+ */
+export declare const BASE_PRINT_RULES: readonly PrintRule[];
+export declare const DEFAULT_PRINT_RULES: readonly PrintRule[];
+/**
+ * 根据基础规则与配置构造最终生效的规则列表
+ */
+export declare function buildPrintRules(config?: PrintRuleConfig): PrintRule[];
+/**
+ * 全局统一配置打印规则（业务层通过此处注册各自技术栈/组件库的选择器）
+ */
+export declare function configurePrint(config: PrintRuleConfig): void;
+/**
+ * 获取当前全局生效的打印规则列表
+ */
+export declare function getPrintRules(): readonly PrintRule[];
+/**
+ * 重置全局规则为原生基础规则
+ */
+export declare function resetPrintRules(): void;
+/**
+ * 对节点进行分类匹配，首个匹配的选择器生效
+ */
+export declare function classifyPrintNode(node: ClassifiableNode, rules?: readonly PrintRule[]): ElementRule;
+export declare function resolveAtomicOverflow(rule: Extract<ElementRule, {
+    kind: 'atomic';
+}>, height: number, capacity: number, customLabel?: string | null): 'protect' | 'descend';

package/dist/types/core/types.d.ts

@@ -0,0 +1,77 @@
+/** Geometry and rule types shared by pure core algorithms and external adapters. */
+export interface Interval {
+    top: number;
+    bottom: number;
+}
+export interface PageSlice {
+    start: number;
+    end: number;
+}
+export type Orientation = 'portrait' | 'landscape';
+export type Paper = 'a4' | 'a3' | 'a5' | 'letter' | 'card-3x4' | 'square-1x1' | 'card-4x5' | 'story-9x16' | 'ecom-750x1000' | 'custom';
+/** 声明式页眉/页脚基础配置（开发者代码配置） */
+export interface DeclarativeHeaderFooterConfig {
+    enabled?: boolean;
+    text?: string;
+    align?: 'left' | 'center' | 'right';
+    showDivider?: boolean;
+}
+/** 独立页码系统配置（可由设置面板 UI 控制，亦可代码配置） */
+export interface PageNumberConfig {
+    enabled: boolean;
+    position?: 'bottom-right' | 'bottom-center' | 'top-right' | 'top-center';
+    format?: 'slash' | 'chinese' | 'hyphen';
+}
+export interface PrintSettings {
+    paper: Paper;
+    unit?: 'mm' | 'px';
+    widthMm: number;
+    heightMm: number;
+    orientation: Orientation;
+    marginTopMm: number;
+    marginRightMm: number;
+    marginBottomMm: number;
+    marginLeftMm: number;
+    header?: DeclarativeHeaderFooterConfig;
+    footer?: DeclarativeHeaderFooterConfig;
+    pageNumber?: PageNumberConfig;
+}
+export type ElementRule = {
+    kind: 'ignore';
+} | {
+    kind: 'container';
+} | {
+    kind: 'text';
+} | {
+    kind: 'atomic';
+    label: string;
+    overflow: 'split' | 'error';
+};
+export interface PrintRule {
+    selector: string;
+    result: ElementRule;
+}
+export interface PrintRuleConfig {
+    /** 不可分割的选择器列表（最小原子化单元，严禁中间切断，当前页放不下则整块推入下一页） */
+    atomic?: string[];
+    /** 可分割的选择器列表（流式文本、段落容器，允许被物理分页线切断） */
+    splittable?: string[];
+    /** 不打印的选择器列表（排除在打印渲染之外的交互控件，如分页器、操作按钮） */
+    ignore?: string[];
+    keepTogether?: string[];
+    keepOrSplit?: string[];
+    forceSplit?: string[];
+    /** 自定义高级规则列表（前置优先匹配） */
+    customRules?: PrintRule[];
+}
+export interface MeasurementStats {
+    visitedNodes: number;
+    atomicElements: number;
+    textNodes: number;
+    textFragments: number;
+}
+export interface DocumentMeasurement {
+    height: number;
+    ranges: Interval[];
+    stats?: MeasurementStats;
+}

package/dist/types/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './use-web-printer';
+export { usePdfPrint } from './use-pdf-print';
+export type { UsePdfPrintState, UsePdfPrintProgress } from './use-pdf-print';

package/dist/types/hooks/use-pdf-print.d.ts

@@ -0,0 +1,6 @@
+/** @deprecated Import useWebPrinter from @darialan/web-printer/react. */
+export { useWebPrinter as usePdfPrint } from './use-web-printer';
+export type { UseWebPrinterProgress as UsePdfPrintProgress, ExportPdfParams, InspectLayoutParams } from './use-web-printer';
+export type UsePdfPrintState = Omit<import('./use-web-printer').UseWebPrinterState, 'isExporting'> & {
+    isPrinting: boolean;
+};

package/dist/types/hooks/use-web-printer.d.ts

@@ -0,0 +1,46 @@
+import { DocumentExportOptions, ExportOptions, PreviewPaginationOptions, PrintInspectionResult } from '../application/print-service';
+export interface UseWebPrinterProgress {
+    completed: number;
+    total: number;
+    percent: number;
+}
+export interface UseWebPrinterState {
+    isExporting: boolean;
+    isInspecting: boolean;
+    progress: UseWebPrinterProgress;
+    error: Error | null;
+    inspection: PrintInspectionResult | null;
+}
+export type ExportDocumentParams = Omit<DocumentExportOptions, 'signal' | 'onProgress'>;
+export interface ExportPdfParams extends Omit<ExportOptions, 'signal' | 'onProgress'> {
+    showOverlay?: boolean;
+}
+export interface InspectLayoutParams extends PreviewPaginationOptions {
+    showOverlay?: boolean;
+}
+/** React adapter for all output formats. The core package does not load React. */
+export declare function useWebPrinter(): {
+    isPrinting: boolean;
+    exportDocument: (params: ExportDocumentParams) => Promise<{
+        blob: Blob;
+        pages: number;
+        layoutMs: number;
+        totalMs: number;
+        bytes: number;
+    }>;
+    exportPDF: (params: ExportPdfParams) => Promise<{
+        blob: Blob;
+        pages: number;
+        layoutMs: number;
+        totalMs: number;
+        bytes: number;
+    }>;
+    inspectLayout: ({ showOverlay, ...params }: InspectLayoutParams) => Promise<PrintInspectionResult>;
+    clearVisualOverlay: () => void;
+    cancel: () => void;
+    isExporting: boolean;
+    isInspecting: boolean;
+    progress: UseWebPrinterProgress;
+    error: Error | null;
+    inspection: PrintInspectionResult | null;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Web Printer (@darialan/web-printer)
+ * High-performance, pixel-accurate client-side HTML pagination engine with PDF and PNG output.
+ */
+export * from './core/types';
+export * from './core/geometry';
+export * from './core/pagination';
+export * from './core/rules';
+export * from './adapters/dom';
+export * from './adapters/resources';
+export * from './adapters/canvas';
+export * from './adapters/pdf';
+export * from './application/cancellation';
+export * from './application/print-pipeline';
+export * from './application/print-service';
+export { visualizePageBreaks, clearPageBreaks, } from './overlay/page-break-overlay';
+export type { ObservabilityStats } from './overlay/page-break-overlay';
+export * from './output';
+export * from "./application/print-session";

package/dist/types/output/image-writer.d.ts

@@ -0,0 +1,5 @@
+import { OutputWriter, OutputWriterOptions } from './types';
+/** Same paper composition for PNG files and extension thumbnails. Caller releases the canvas. */
+export declare function composePageCanvas(body: HTMLCanvasElement, heightPt: number, index: number, { geometry: g, settings, headerCanvas, footerCanvas, totalPages }: OutputWriterOptions): HTMLCanvasElement;
+/** Compose full paper pages, encode each immediately, and release its canvas before the next page. */
+export declare function createImageWriter({ geometry: g, settings, headerCanvas, footerCanvas, totalPages, signal }: OutputWriterOptions): OutputWriter;

package/dist/types/output/index.d.ts

@@ -0,0 +1,4 @@
+import { OutputFormat, OutputWriter, OutputWriterOptions } from './types';
+export * from './types';
+export declare function validateOutputFormat(format: OutputFormat): void;
+export declare function createOutputWriter(format: OutputFormat, options: OutputWriterOptions): Promise<OutputWriter> | OutputWriter;

package/dist/types/output/page-number.d.ts

@@ -0,0 +1 @@
+export declare function formatPageNumber(pageIndex: number, totalPages: number, format?: 'slash' | 'chinese' | 'hyphen'): string;

package/dist/types/output/types.d.ts

@@ -0,0 +1,17 @@
+import { PageGeometry } from '../core/geometry/page-geometry';
+import { PrintSettings } from '../core/types';
+export type OutputFormat = 'pdf' | 'png';
+/** Writers consume the same rendered page slices; pagination is format-independent. */
+export interface OutputWriterOptions {
+    geometry: PageGeometry;
+    settings?: Partial<PrintSettings>;
+    headerCanvas?: HTMLCanvasElement;
+    footerCanvas?: HTMLCanvasElement;
+    totalPages: number;
+    signal?: AbortSignal;
+}
+export interface OutputWriter {
+    addPageSlice(index: number, canvas: HTMLCanvasElement, heightPt: number): void | Promise<void>;
+    finalize(filename: string, download?: boolean): Promise<Blob>;
+    dispose?(): void;
+}

package/dist/types/output/zip.d.ts

@@ -0,0 +1,5 @@
+/** ZIP STORE: PNG is already compressed. Keeping entries as Blobs avoids copying image buffers. */
+export declare function createZipArchive(entries: {
+    name: string;
+    data: Uint8Array;
+}[]): Blob;

package/dist/types/overlay/page-break-overlay.d.ts

@@ -0,0 +1,8 @@
+import { PrintRule } from '../core/types';
+export interface ObservabilityStats {
+    atomic: number;
+    splittable: number;
+    ignore: number;
+}
+export declare function clearPageBreaks(owner?: Document | HTMLElement): void;
+export declare function visualizePageBreaks(pages: number[], element: HTMLElement, rules?: readonly PrintRule[]): ObservabilityStats;

package/dist/types/react.d.ts

@@ -0,0 +1,2 @@
+/** Optional React integration. Install React in the host application. */
+export * from './hooks';

package/docs/migration-to-web-printer.md

@@ -0,0 +1,42 @@
+# 从 WebPDF Printer 迁移至 Web Printer
+
+新品牌为 **Web Printer**；新包为 `@darialan/web-printer`。原 `@darialan/web-pdf-printer@1.0.2` 保持可下载。
+
+```sh
+npm uninstall @darialan/web-pdf-printer
+npm install @darialan/web-printer
+```
+
+## 导出 API
+
+`outputDocument({ format: 'pdf' | 'png' })` 是通用接口。`outputPDF()` 仍是仅输出 PDF 的兼容接口；真正与 PDF 格式有关的名称不作无意义替换。
+
+```ts
+import { outputDocument, outputPDF } from '@darialan/web-printer';
+await outputDocument({ element: document.getElementById('content'), filename: 'report', format: 'png' });
+```
+
+React 集成改从独立入口导入，保证普通 JS/Vue 项目导入核心库时不必安装 React：
+
+```tsx
+import { useWebPrinter } from '@darialan/web-printer/react';
+const { exportDocument, isExporting, progress, cancel } = useWebPrinter();
+await exportDocument({ element: document.getElementById('content'), filename: 'report', format: 'png' });
+```
+
+旧 Hook 名称 `usePdfPrint`、`UsePdfPrintState`、`UsePdfPrintProgress` 在 `/react` 子入口保留；返回值仍有 `exportPDF`、`isPrinting`。不要从新包根入口导入 React Hook。旧包自己的入口不变。
+
+## HTML 标记
+
+| 推荐 | 仍可识别的旧标记 |
+| --- | --- |
+| `data-print-atomic="true"` / `.print-atomic` | `data-pdf-atomic="true"` / `.pdf-atomic` |
+| `data-print-splittable="true"` / `.print-splittable` | `data-pdf-splittable="true"` / `.pdf-splittable` |
+| `data-print-ignore="true"` / `.print-ignore` | `data-pdf-ignore="true"` / `.pdf-ignore` |
+| `data-print-keep-together="true"` / `.print-keep-together` | 对应 `data-pdf-*` / `.pdf-*` |
+| `data-print-keep-together="split"` / `.print-keep-or-split` | 对应旧属性 / `.pdf-keep-or-split` |
+| `data-print-break="split"` / `.print-force-split` | 对应旧属性 / `.pdf-force-split` |
+
+推荐常量为 `PRINT_ATTRIBUTES`、`PRINT_CLASSES`；`PDF_PRINT_ATTRIBUTES`、`PDF_PRINT_CLASSES` 保留旧值。业务选择器配置优先级与分页算法不变。检查事件使用 `print-inspection`；旧 `pdf-print-inspection` 事件继续发送。内部快照/调试属性改为 `data-print-snapshot` / `data-print-debug`，它们属于内部实现，不应由业务代码生成。
+
+GitHub 源码仓库和现有站点 URL 保持稳定；产品名称与 npm 安装入口已更名。工作区目录和 Vercel 项目 ID 属于部署基础设施，不改变内容或下载能力。

package/docs/output-formats.md

@@ -0,0 +1,47 @@
+# 分页输出层：PDF 与 PNG
+
+以当前四个 playground 场景为基础。分页是核心能力，PDF 和分页图片是同一份分页结果的两种输出；本次不调整测量、保护规则或分页算法。
+
+## 使用
+
+工作台通过导出按钮右侧的箭头选择格式，按钮主体直接导出当前格式。默认 PDF；「PNG 分页图片」将每一页保存为一张完整纸张图片，并统一打包下载，避免多文件自动下载被浏览器拦截。文件按 `page-001.png`、`page-002.png` 排序。图片包含当前纸张尺寸、方向、边距、页眉页脚与页码，末页保留完整纸张高度。切换输出格式不改变分页或关闭预览。输出设置提供 A4/A3/A5/Letter、常见社媒图片比例（3:4、4:5、1:1、9:16）、电商长图和自定义尺寸；社媒图片预设使用像素单位，页面宽高和内边距仍统一换算为毫米保存。设置区同时显示扣除边距后的正文可用尺寸。
+
+```ts
+import { outputDocument, outputPDF } from '@darialan/web-printer';
+
+const controller = new AbortController();
+const result = await outputDocument({
+  element: document.getElementById('content'),
+  filename: '报告',
+  format: 'png', // 'pdf' | 'png'，默认 'pdf'
+  download: false, // true 时直接下载；false 时由调用方处理 Blob
+  signal: controller.signal,
+  onProgress: (completed, total) => console.log(completed, total),
+});
+// PNG 模式：result.blob 是 application/zip，内含逐页 PNG。
+// PDF 模式：result.blob 是 application/pdf。
+// result.pages / bytes / layoutMs / totalMs 两种格式均可用。
+
+// 原有 PDF 调用保持兼容：
+await outputPDF({ element: document.getElementById('content'), filename: '报告' });
+```
+
+图片采用与 PDF 正文相同的逐页截图，图片尺寸取决于源区域宽度及截图像素预算，纸张宽高比来自输出设置；不是额外设置的固定 DPI。PNG 是无损光栅图片。页内不含可搜索的文本层。
+
+## 模块边界
+
+- `application/print-service.ts`：共享 prepareLayout、逐页 capture、进度、取消和资源清理。
+- `output/types.ts`：输出格式与 `OutputWriter` 协议。writer 接收页截图与纸张坐标，不测量 DOM、不重新分页。
+- `output/index.ts`：格式分发。PDF 使用原有 jsPDF adapter；PNG 使用 image writer。
+- `output/image-writer.ts`：按共享 geometry 合成完整纸张，逐页编码 PNG 后立即释放合成 canvas。
+- `output/zip.ts`：PNG 已压缩，ZIP 使用 STORE，无新增运行时依赖；写入 CRC32 与中央目录。页码文件名固定 ASCII，文档标题仅用于下载包名称。
+
+扩展格式时实现 `OutputWriter`，注册到格式工厂，并增加工具栏选项即可；分页算法、快照和截图链路不需要增加格式判断。React 项目可从 `@darialan/web-printer/react` 导入 `useWebPrinter()`，用 `exportDocument()` 选择格式；`usePdfPrint().exportPDF()` 作为兼容接口保留。非 React 和 React 调用方均可直接调用核心入口的 `outputDocument()`。
+
+## 失败与取消
+
+任一页截图或编码失败，整个任务失败，不下载不完整文件。导出前及每页处理后检查取消状态；编码中的原生 canvas 操作结束后停止，不开始下一页或最终下载。所有路径释放快照、截图 canvas 和输出 writer。PNG 字节保留到 ZIP 完成，因此总内存仍随压缩图片总量增长；整篇正文不会合成一张超长 canvas。ZIP 不支持 ZIP64，超出标准 ZIP 容量会明确报错。
+
+## 验证
+
+单测覆盖 ZIP CRC32/目录偏移、纸张合成坐标、页眉页脚与页码、编码失败/取消清理和共享导出链路。浏览器自动化覆盖四个场景的真实 ZIP 下载，逐页解码 PNG、检查非空像素、纸张比例、连续文件名，以及与预览一致的页数；原有 PDF 自动化作为回归继续执行。