PDF 处理设计

接口用法和参数见组件 README。PDFsharp 负责页面改写，PdfPig 负责内容解析和密码校验，PDFtoImage／PDFium 负责栅格渲染；公开类型保持为 .NET 类型，组件不依赖 Core、Media 或 ASP.NET Core。

页面与渲染坐标

页面选择保留请求顺序，允许重复，重复页计入输出页数预算；空选择与空合并均拒绝。合并按输入流顺序拼接页面。新文档复制原文档或首个合并文档的标题、作者、主题和关键词，保留页面内容、尺寸与旋转；不承诺恢复目录、表单关系、签名或全部文档级结构。

InspectAsync 返回标题、作者、加密状态及每页媒体框尺寸和显示旋转。ExtractTextAsync 使用 PdfPig 的内容顺序提取器返回逐页文字；PDF 本身没有可靠的纯文本阅读顺序保证，复杂布局应结合后续版面分析。只有扫描图像的页面返回空字符串，不自动调用 OCR。

渲染尺寸遵循 PDFium 的可见页面与方向。PDFtoImage 5.4 将缩放后的正浮点尺寸向下取整，栅格预算检查采用同样规则，并在得到实际位图后复查。渲染包含页面批注，使用白色背景；原生调用前检查打包所支持的桌面 OS，避免将平台注解当作警告屏蔽。

AddOverlayAsync(pdf, pngOverlay, output) 将静态 PNG 拉伸到每页的可见区域，按 CropBox 偏移和页面显示旋转映射坐标，透明区域保留底层内容。可先由 Media 的文字或 Logo 叠加接口生成目标尺寸 PNG，应用负责组合；Documents 不依赖 Media、不自行创建字体，也不修改进程全局字体解析器。

输入加密与输出保护

PDFsharp 在解密后会重置保存用的保护设置，直接检查 DOM 会误报原始加密状态，直接保存还会生成明文。OwnedPdf 因此通过 PdfPig 记录源状态，共享保存层对叠加、合并、选择、拆分执行同一规则：任一源加密时，输出必须有密码对或显式明文授权。AES-256 输出由后端的 V5 安全处理器生成。

输出密码须为有效 Unicode、非空，且原值及 NFKC 规范化后都不超过 127 个 UTF-8 字节，防止后端截断。PDF 标准中的密码规范化仍由后端处理。加密结果在写给调用方之前会再次解析：无密码必须被明确拒绝，配置的 user/owner 密码均须能打开且页数一致；规范化导致任一密码成为可无密码访问的空值时拒绝发布，而不维护特殊字符黑名单。加密输出因此有额外解析开销。

读取和输出校验共享密码候选规则：先尝试原字符串，只有明确密码拒绝且 NFKC 候选不同才尝试规范候选；旧加密密码的原值优先，不无条件改写。解析、检查、提取与渲染使用同一解析出的候选。后端完整 SASLprep 行为存在差异，若指定密码及 NFKC 候选无法被读取后端确认，输出会在发布前拒绝，不保证任意 Unicode 密码跨后端通用。

输出密码不从输入密码自动推断；若需要继续使用原有 user/owner 密码，应显式提供相同的一对。PNG 渲染和文本提取是明确的明文提取操作，不受 PDF 改写的输出密码策略限制。文档重写不保留原数字签名有效性。密码配置为普通类，不包含会自动打印密码的 record 字符串。

资源预算与生命周期

合并会保留各源 DOM 及编码快照到保存结束，所以单文件上限不足以控制累计输入。读取下一个源时，使用 MaximumMergedInputBytes 剩余额度与单文件上限中较小值，超限最多额外探测一个字节。页数同时约束源文档和选择／合并结果；PDF 输出在有界自有缓冲区中序列化，扩容前检查实际写入。栅格在渲染前后检查，PNG 编码大小在复制到托管结果前检查，并限制单个 RGBA 栅格小于 2 GiB。默认预算集中在 README 参数表。

PDF 解析使用完整 DOM，输入缓冲、解析对象、输出缓冲和编码栅格会同时占用内存；输入字节限额不是解压对象或整个进程的峰值内存保证。宿主仍需限制并发。PDFtoImage 的 PDFium 调用由其内部锁串行化，单进程不提供原生 PDF 渲染并行。

全部输入输出从当前位置读写并保持打开；支持不可定位的分段输入。同一流实例不能兼作输入与输出。校验和序列化在写入调用方输出之前完成，I/O 错误或取消仍可能留下部分输出，应由宿主通过临时文件发布。逐页枚举一次只创建当前结果，调用方应及时消费或释放枚举器；中途取消会释放自有解析资源。原生解析、保存和单次渲染的中断能力受后端限制，取消检查在阶段及页面之间执行。

验证与依赖

实际文件测试覆盖选择顺序与重复页、累计输入的精确预算与最多一字节探测、不可定位流、取消和所有权。Windows 上使用 PDFium 157.0.8086 与 SkiaSharp 4.153.1 验证四种旋转、CropBox、非零媒体框原点、DPI 舍入、AES-256 及 Unicode 密码候选。加密回归包含规范化后空化的密码、原值优先与 NFKC 兼容正例；Linux／macOS 资产未在该 Windows 环境实际运行。

依赖为 PDFsharp 6.2.4（MIT）、PdfPig 0.1.16（Apache-2.0）、PDFtoImage 5.4.0（MIT）、匹配的 SkiaSharp 与 PDFium 原生资产。原生 PDFium 及其第三方组件须保留相应许可证和 notices；bblanchon NuGet 分发声明与上游原生源码许可证分别记录。组件不依赖浏览器或办公软件完成这些操作。