核心概念

坐标约定

• 左上原点、y 向下、单位 pt（1pt = 1/72 英寸）。
• 这是屏幕与设计工具的直觉坐标系，不同于 PDF 内部的"左下原点、y 向上"。所有工具返回的 x/y、bbox、region 都遵循此约定。
• bbox 恒为 [x0, y0, x1, y1]。

设备空间坐标

pdf_extract 返回的路径线段坐标已处于设备空间（页面 CTM 与当前变换均已应用），因此可直接当作设计稿坐标使用，无需再叠加变换。

隐藏文本层（重点）

Chrome / Skia 系导出器常这么做：可见文字被画成矢量轮廓，底下垫一层不可见的文本对象（供搜索/选择）。该文本层的颜色、有时连位置都与可见内容无关。

本工具会识别该模式，并做两件事：

1. 被后续不透明图形完全覆盖的文本，标记 "covered": true（不要当作可见内容）；
2. 若同位置存在"文字轮廓"图形，则用其颜色还原 color，并置 "colorFrom": "outline"；若找不到，则不报告 color。

{ "text": "Mailboxes", "x": 24, "y": 56.64, "fontSize": 24,
  "color": "#e8e8ea", "covered": true, "colorFrom": "outline",
  "bbox": [24, 37.44, 141.79, 61.44] }

结论

对 covered: true 的文本：字符串内容可信；颜色与几何应以还原后的值为准。

在真实文档上实测（Skia/PDF m117 导出的移动端设计稿）：13/13 与 20/23 条文本的颜色被正确还原。

图案填充与渐变

• 渐变仅做位置标记（paint: "shading"），不抽取色标；渲染渐变请用 pdf_render。
• 图案（TilingPattern）填充：fill 为 null（图案没有单一颜色）；图案单元格内绘制的位图会被抽取并标 pattern: true，但只报告该单元格与填充区相交的部分，不把平铺副本展开成多条。

已知限制

• 文本颜色：普通 PDF 直接取绘制算子的颜色；隐藏文本层走上述还原逻辑，还原失败则不报告颜色（绝不报告错误颜色）。
• 渐变：只做位置标记，不抽色标。
• 图案填充：fill 为 null；位图只报告单元格可见部分。
• 透明度组（isolated）：内部坐标会映射到最终合成位置，正常情况正确；极少数带自定义 group.matrix 的 Form XObject 可能略有偏差。
• 位图：只报告放置框与原始像素尺寸，不含像素数据（要看像素请用 pdf_render）。
• 图形被后续不透明填充覆盖时，文本会标 covered，图形暂不追踪遮挡。
• 超大页面注意输出体积：用 detail: "box"、include、limit 控制。

文档缓存

文档按"路径 + mtime"缓存复用；调用 closeAllDocuments() 释放它们。