From 3b3d25fbaaff1f2d1935ca527270423afd5434b9 Mon Sep 17 00:00:00 2001 From: eric8810 Date: Thu, 30 Jul 2026 19:05:05 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(release):=20=E5=A2=A8=E5=8D=B7?= =?UTF-8?q?=E5=BE=85=E5=90=AF=EF=BC=8C=E5=85=AD=E5=A2=83=E7=9A=86=E6=98=8E?= =?UTF-8?q?=20=C2=B7=20prepare=20npm=200.5.6=20release?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record the successful six-platform unpublished release rehearsal, exact candidate closure, native package sizes and hashes, and the remaining publication sequence. Move the user-visible PDF fallback fix into the 0.5.6 changelog entry and add a GitHub Release notes draft. --- CHANGELOG.md | 2 + docs/implementation-status.md | 11 +-- docs/releases/npm-0.5.6.md | 130 ++++++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 4 deletions(-) create mode 100644 docs/releases/npm-0.5.6.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a3df507..6010da7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ This file records user-visible changes to `light-ocr`. Published artifact detail ## [Unreleased] +## [0.5.6] - 2026-07-30 + ### Fixed - Bundled the checksum-pinned Noto Sans SC regional subset into every native diff --git a/docs/implementation-status.md b/docs/implementation-status.md index a4796a2..98ee0d8 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -1,7 +1,7 @@ # C++ Core 与 Node-API 实施状态 -更新时间：2026-07-28
-结论：npm `0.5.5` 已发布，但其平台包只内置 PDFium addon 与共享库，未内置 fallback 字体，因此对非嵌入中文字体的 PDF 不能视为可靠。`0.5.6` 补丁候选现已把校验锁定的官方 Noto Sans SC 区域子集及 OFL 许可证装入六个平台包，并在 patched PDFium 初始化时只使用包内字体目录；用户安装与运行仍无二次下载。当前本机 macOS arm64 已验证 `STSong-Light` 非嵌入字体映射、PNG 渲染与 `中文测试` 端到端 OCR，六平台 release smoke 尚待 CI 实跑。D116 记录修复契约，已发布 `0.5.5` 的原始证据仍见 [npm 0.5.5 发布记录](releases/npm-0.5.5.md)。 +更新时间：2026-07-30
+结论：npm `0.5.5` 已发布，但其平台包只内置 PDFium addon 与共享库，未内置 fallback 字体，因此对非嵌入中文字体的 PDF 不能视为可靠。`0.5.6` 补丁候选已把校验锁定的官方 Noto Sans SC 区域子集及 OFL 许可证装入六个平台包，并在 patched PDFium 初始化时只使用包内字体目录；用户安装与运行仍无二次下载。合并后的 Core、sanitizer/fuzzer、oracle 和 WebGPU CI 已全绿，[npm 发布演练 30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) 也已完成六平台构建、离线安装、图片 OCR 与非嵌入中文字体 PDF 端到端 smoke；该次演练明确跳过 registry 发布。D116 记录修复契约，候选闭包与后续发布步骤见 [npm 0.5.6 发布准备记录](releases/npm-0.5.6.md)。 状态含义： @@ -27,7 +27,7 @@ ## PDF fallback 字体修复（0.5.6 候选） -状态：本机工程验证完成 / 六平台 release CI 待运行 +状态：工程验证与六平台 release CI 完成 / npm registry 发布待执行 - Noto Sans SC 官方区域子集和 OFL 文本以固定 revision、bytes 与 SHA-256 锁定；release staging 对缺失、篡改、重复或不完整 inventory @@ -40,7 +40,10 @@ `fontFamily = Noto Sans SC`、`isEmbedded = false`、有效 PNG，并由 默认 OCR 模型识别出 `中文测试`。 - 六个平台的离线 tarball smoke 同时检查字体选择、渲染结果和 OCR - 文本；在该矩阵全部通过前，不能把本机结论写成跨平台发布完成。 + 文本；[run 30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) + 已全部通过，且 `publish` job 因演练参数保持 skipped。 +- 相对 `0.5.5`，每个用户实际安装的平台 native tarball 增加 + `7,226,822–7,232,623` bytes，解包增加约 `8.34 MB`；模型包不变。 ## 需求验收矩阵 diff --git a/docs/releases/npm-0.5.6.md b/docs/releases/npm-0.5.6.md new file mode 100644 index 0000000..3a46069 --- /dev/null +++ b/docs/releases/npm-0.5.6.md @@ -0,0 +1,130 @@ +# npm 0.5.6 发布准备记录 + +状态：发布前验证完成，尚未发布。npm registry 与 dist-tag 均保持 +`0.5.5` 发布后的状态。 + +发布身份： + +- PDF fallback 实现提交： + [`196ebde`](https://github.com/arcships/light-ocr/commit/196ebdee7c3adead047b485e6a558133bd0263c5) +- Windows release builder 修复： + [`d80a868`](https://github.com/arcships/light-ocr/commit/d80a8681485c470b48699e24fa18661d6a60b718) +- 合并后基线： + [Core 30534418143](https://github.com/arcships/light-ocr/actions/runs/30534418143)、 + [Native WebGPU 30534418001](https://github.com/arcships/light-ocr/actions/runs/30534418001) +- 首次诊断演练： + [30535427156](https://github.com/arcships/light-ocr/actions/runs/30535427156) + （macOS/Linux 通过，Windows 暴露 `npx.cmd` 寻址问题，未组装、未发布） +- 完整发布演练： + [30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) + （六平台通过，`publish_to_registry=false`） + +## 用户可见变化 + +- 修复常见非嵌入中文字体 PDF 的渲染前置缺陷。PDFium 现在从当前 + native npm 包内的 Noto Sans SC fallback 字体绘制页面，再把正确的 + 像素交给 OCR。 +- 字体、OFL 许可证、PDFium addon 与共享库全部随匹配平台的 npm 包 + 交付。支持 `npm install --ignore-scripts`；客户机安装和运行均不下载 + 字体、不编译 native addon，也不要求系统预装中文字体。 +- 锁定的 `NotoSansSC-Regular.otf` 为 `8,331,336` bytes，SHA-256 为 + `faa6c9df652116dde789d351359f3d7e5d2285a2b2a1f04a2d7244df706d5ea9`。 +- 没有 public API 或 schema 破坏。`@arcships/light-ocr` 的图片、PDF + 与多页图片入口保持不变。 +- `0.5.5` 的不可变包继续保留，但不应再用于需要可靠处理非嵌入中文 + 字体 PDF 的场景。 + +## 待发布版本闭包 + +| 成熟度 | 包 | 候选版本 | 发布后标签计划 | +| --- | --- | ---: | --- | +| stable | `@arcships/light-ocr` | `0.5.6` | `next` 验证后晋升 `latest` | +| stable | `@arcships/light-ocr-runtime` | `0.1.6` | `next` 验证后晋升 `latest` | +| stable | 六个平台 native | `0.5.6` | `next` 验证后晋升 `latest` | +| compatibility | `@arcships/light-ocr-document` | `0.1.2` | 保持 `next` | +| preview | `@arcships/light-ocr-tiny` | `0.1.5` | 保持 `next` | +| preview | `@arcships/light-ocr-medium` | `0.1.5` | 保持 `next` | + +模型包不重发新版本：Small 继续使用 `0.3.4`，Tiny/Medium 继续使用 +`0.1.0`。演练会重建或取得模型 tarball 来完成离线安装验证；发布器只在 +registry 中的同版本 integrity 完全一致时跳过这些不可变包。 + +## 六平台 native 候选 + +下表来自完整演练的 `release-manifest.json`。增量以已发布 `0.5.5` +tarball 为基线；用户只安装当前平台对应的一个 native 包。 + +| 平台包 | 压缩 bytes | 相对 0.5.5 | 解包 bytes | SHA-256 | +| --- | ---: | ---: | ---: | --- | +| `darwin-arm64` | 22,889,542 | +7,227,406 | 56,356,978 | `ae325aaf9a3ff79cd184a862ea36687fa32227bf5a048136f02591626ce16342` | +| `darwin-x64` | 24,853,681 | +7,229,542 | 62,109,821 | `4f3d2f9cb6fba776181e327e7321787d91b516c0a39497d8ebf2ad56bf6112cc` | +| `linux-arm64-gnu` | 20,453,485 | +7,227,462 | 40,261,084 | `6dfbedc1637ff17aa13117925ca08f80b07367d62216f90a05b7614bff038078` | +| `linux-x64-gnu` | 27,033,591 | +7,226,822 | 59,390,897 | `eb67edb08db86998c8b232c42df90eda47c0b1a30311f78e1f7f5023f0c22a15` | +| `win32-arm64` | 16,663,753 | +7,232,623 | 30,985,476 | `0ad4e90cadd230405c244a309f9dbaac33b371ae9e6a4868d7eaf31c5962723d` | +| `win32-x64` | 30,387,143 | +7,232,239 | 63,070,260 | `bcbd5b92526f0a640db53154f6482ee0c58a4a9d3c559c5ecac0611f2b21a2dd` | + +## 已通过的发布门 + +- [x] 合并后的六平台 Core、sanitizer、fuzzer 与 oracle +- [x] Linux/Windows Native WebGPU contract +- [x] 11 个新 package identity 的 npm registry 空位检查 +- [x] 六个平台从锁定源码重建 PDFium addon +- [x] 六个平台 native 包包含 fallback 字体与 OFL 许可证 +- [x] 六个平台在离线模式且禁用安装脚本的条件下安装完整闭包 +- [x] 六个平台运行真实图片 OCR +- [x] 六个平台验证非嵌入 `STSong-Light` 映射到 `Noto Sans SC` +- [x] 六个平台验证非空 PDF raster 与端到端 `中文测试` OCR +- [x] 候选 tarball manifest、bytes、SHA-256 与 npm integrity +- [ ] 以 `publish_to_registry=true` 发布不可变候选到 `next` +- [ ] 从 npm registry 回装并核对 integrity +- [ ] 将 stable Small/runtime/native 闭包晋升到 `latest` +- [ ] 创建 `v0.5.6` GitHub Release + +## 实际发布顺序 + +1. 从 `main` 重新运行 `npm release`，版本 `0.5.6`， + `publish_to_registry=true`；流水线先重复相同构建与 smoke，再只向 + `next` 写入候选。 +2. 核对 registry integrity 与完整闭包回装结果。 +3. 运行 `npm promote`，只把 Small `0.5.6`、runtime `0.1.6` 与六个 + native `0.5.6` 晋升到 `latest`。 +4. 创建 `v0.5.6` tag/GitHub Release，并把本记录状态和最终 run ID + 更新为已发布。 + +Tiny、Medium 与 Document 不属于 stable promotion；它们继续停留在 +`next`。整个发布不依赖外部用户验证或采用证明，所有阻断门均由源码、 +候选 tarball、真实六平台 runner 和 npm registry identity 自证完成。 + +## GitHub Release 文案草案 + +Release name： + +`墨字归真，六境同明 · Restore Chinese PDF rendering in 0.5.6` + +Highlights： + +- Fix PDF rasterization when documents reference common non-embedded Chinese + fonts. +- Bundle a checksum-pinned Noto Sans SC fallback font and its OFL license in + every supported native package. +- Keep installation and runtime fully self-contained: no postinstall download, + system-font requirement, GitHub access, or local compilation. +- Preserve the existing image, PDF, and multi-page APIs without schema changes. +- Add about 7.23 MB compressed and 8.34 MB unpacked to the one native package + selected for the customer's platform. + +Versions： + +- `@arcships/light-ocr@0.5.6` +- `@arcships/light-ocr-runtime@0.1.6` +- six native platform packages at `0.5.6` +- Document compatibility facade `0.1.2` under `next` +- Tiny/Medium preview facades `0.1.5` under `next` +- unchanged Small `0.3.4` and Tiny/Medium `0.1.0` model packages + +Verification： + +- pre-release dry-run: + +- release workflow: 待实际发布后补入 +- stable promotion: 待晋升后补入 From 724f3796e12b42f6eda15e4000cdb038b0bf649b Mon Sep 17 00:00:00 2001 From: eric8810 Date: Thu, 30 Jul 2026 19:12:20 +0800 Subject: [PATCH 2/4] =?UTF-8?q?docs(release):=20=E5=8F=8C=E5=8D=B7?= =?UTF-8?q?=E5=B9=B6=E9=99=88=EF=BC=8C=E5=9B=9B=E6=B5=B7=E5=90=8C=E8=AF=BB?= =?UTF-8?q?=20=C2=B7=20add=20English=200.5.6=20record?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a complete English companion for the npm 0.5.6 release preparation record, including the candidate closure, artifact evidence, release gates, publication sequence, and Release draft. Cross-link both languages from the release record, implementation status, and changelog. --- CHANGELOG.md | 3 + docs/implementation-status.md | 2 +- docs/releases/npm-0.5.6.en.md | 145 ++++++++++++++++++++++++++++++++++ docs/releases/npm-0.5.6.md | 2 + 4 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 docs/releases/npm-0.5.6.en.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6010da7..eaf5ee7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,9 @@ This file records user-visible changes to `light-ocr`. Published artifact detail page bytes, and end-to-end Chinese OCR without install-time or runtime downloads. +Release preparation: [English](docs/releases/npm-0.5.6.en.md) / +[中文](docs/releases/npm-0.5.6.md). + ## [0.5.5] - 2026-07-27 ### Changed diff --git a/docs/implementation-status.md b/docs/implementation-status.md index 98ee0d8..06bc760 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -1,7 +1,7 @@ # C++ Core 与 Node-API 实施状态 更新时间：2026-07-30
-结论：npm `0.5.5` 已发布，但其平台包只内置 PDFium addon 与共享库，未内置 fallback 字体，因此对非嵌入中文字体的 PDF 不能视为可靠。`0.5.6` 补丁候选已把校验锁定的官方 Noto Sans SC 区域子集及 OFL 许可证装入六个平台包，并在 patched PDFium 初始化时只使用包内字体目录；用户安装与运行仍无二次下载。合并后的 Core、sanitizer/fuzzer、oracle 和 WebGPU CI 已全绿，[npm 发布演练 30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) 也已完成六平台构建、离线安装、图片 OCR 与非嵌入中文字体 PDF 端到端 smoke；该次演练明确跳过 registry 发布。D116 记录修复契约，候选闭包与后续发布步骤见 [npm 0.5.6 发布准备记录](releases/npm-0.5.6.md)。 +结论：npm `0.5.5` 已发布，但其平台包只内置 PDFium addon 与共享库，未内置 fallback 字体，因此对非嵌入中文字体的 PDF 不能视为可靠。`0.5.6` 补丁候选已把校验锁定的官方 Noto Sans SC 区域子集及 OFL 许可证装入六个平台包，并在 patched PDFium 初始化时只使用包内字体目录；用户安装与运行仍无二次下载。合并后的 Core、sanitizer/fuzzer、oracle 和 WebGPU CI 已全绿，[npm 发布演练 30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) 也已完成六平台构建、离线安装、图片 OCR 与非嵌入中文字体 PDF 端到端 smoke；该次演练明确跳过 registry 发布。D116 记录修复契约，候选闭包与后续发布步骤见 [npm 0.5.6 发布准备记录](releases/npm-0.5.6.md)（[English](releases/npm-0.5.6.en.md)）。 状态含义： diff --git a/docs/releases/npm-0.5.6.en.md b/docs/releases/npm-0.5.6.en.md new file mode 100644 index 0000000..d525529 --- /dev/null +++ b/docs/releases/npm-0.5.6.en.md @@ -0,0 +1,145 @@ +# npm 0.5.6 Release Preparation Record + +[中文版](npm-0.5.6.md) + +Status: pre-release validation is complete, but the release has not been +published. The npm registry and all dist-tags remain unchanged from the +`0.5.5` release. + +Release identity: + +- PDF fallback implementation: + [`196ebde`](https://github.com/arcships/light-ocr/commit/196ebdee7c3adead047b485e6a558133bd0263c5) +- Windows release builder fix: + [`d80a868`](https://github.com/arcships/light-ocr/commit/d80a8681485c470b48699e24fa18661d6a60b718) +- Post-merge baselines: + [Core 30534418143](https://github.com/arcships/light-ocr/actions/runs/30534418143) and + [Native WebGPU 30534418001](https://github.com/arcships/light-ocr/actions/runs/30534418001) +- Initial diagnostic rehearsal: + [30535427156](https://github.com/arcships/light-ocr/actions/runs/30535427156) + (macOS and Linux passed; Windows exposed the `npx.cmd` resolution issue; + assembly and publication did not run) +- Complete release rehearsal: + [30535822947](https://github.com/arcships/light-ocr/actions/runs/30535822947) + (all six platforms passed with `publish_to_registry=false`) + +## User-visible changes + +- Fix PDF rasterization for common documents that reference non-embedded + Chinese fonts. PDFium now renders those pages with the Noto Sans SC fallback + font carried by the current native npm package before passing the resulting + pixels to OCR. +- Ship the font, its OFL license, the PDFium addon, and the matching shared + library in each platform package. The supported installation works with + `npm install --ignore-scripts`; customer installation and runtime perform no + font download or native compilation and do not require a system Chinese + font. +- Pin `NotoSansSC-Regular.otf` at `8,331,336` bytes with SHA-256 + `faa6c9df652116dde789d351359f3d7e5d2285a2b2a1f04a2d7244df706d5ea9`. +- Preserve the existing public API and schema. The image, PDF, and multi-page + entry points in `@arcships/light-ocr` are unchanged. +- Keep the immutable `0.5.5` packages available, but do not recommend them for + workloads that require reliable rendering of PDFs with non-embedded Chinese + fonts. + +## Candidate version closure + +| Maturity | Package | Candidate version | Planned tags after release | +| --- | --- | ---: | --- | +| stable | `@arcships/light-ocr` | `0.5.6` | publish to `next`, then promote to `latest` | +| stable | `@arcships/light-ocr-runtime` | `0.1.6` | publish to `next`, then promote to `latest` | +| stable | six native platform packages | `0.5.6` | publish to `next`, then promote to `latest` | +| compatibility | `@arcships/light-ocr-document` | `0.1.2` | remain on `next` | +| preview | `@arcships/light-ocr-tiny` | `0.1.5` | remain on `next` | +| preview | `@arcships/light-ocr-medium` | `0.1.5` | remain on `next` | + +No model receives a new version. Small continues to use `0.3.4`, while Tiny +and Medium continue to use `0.1.0`. The rehearsal rebuilds or retrieves model +tarballs for offline installation testing. During publication, an immutable +model package is skipped only when the same version already exists in the +registry with identical integrity. + +## Six-platform native candidates + +The following values come from the complete rehearsal's +`release-manifest.json`. Each delta uses the published `0.5.5` tarball as its +baseline. A customer installs only the one native package selected for the +current platform. + +| Platform package | Compressed bytes | Delta from 0.5.5 | Unpacked bytes | SHA-256 | +| --- | ---: | ---: | ---: | --- | +| `darwin-arm64` | 22,889,542 | +7,227,406 | 56,356,978 | `ae325aaf9a3ff79cd184a862ea36687fa32227bf5a048136f02591626ce16342` | +| `darwin-x64` | 24,853,681 | +7,229,542 | 62,109,821 | `4f3d2f9cb6fba776181e327e7321787d91b516c0a39497d8ebf2ad56bf6112cc` | +| `linux-arm64-gnu` | 20,453,485 | +7,227,462 | 40,261,084 | `6dfbedc1637ff17aa13117925ca08f80b07367d62216f90a05b7614bff038078` | +| `linux-x64-gnu` | 27,033,591 | +7,226,822 | 59,390,897 | `eb67edb08db86998c8b232c42df90eda47c0b1a30311f78e1f7f5023f0c22a15` | +| `win32-arm64` | 16,663,753 | +7,232,623 | 30,985,476 | `0ad4e90cadd230405c244a309f9dbaac33b371ae9e6a4868d7eaf31c5962723d` | +| `win32-x64` | 30,387,143 | +7,232,239 | 63,070,260 | `bcbd5b92526f0a640db53154f6482ee0c58a4a9d3c559c5ecac0611f2b21a2dd` | + +## Release gates + +- [x] Post-merge six-platform Core, sanitizers, fuzzer, and oracle +- [x] Linux and Windows Native WebGPU contracts +- [x] npm registry availability for all 11 new package identities +- [x] PDFium addon rebuilt from the pinned source on all six platforms +- [x] Fallback font and OFL license present in all six native packages +- [x] Complete closure installed on all six platforms in offline mode with + installation scripts disabled +- [x] Real image OCR on all six platforms +- [x] Non-embedded `STSong-Light` mapped to `Noto Sans SC` on all six platforms +- [x] Non-empty PDF raster and end-to-end `中文测试` OCR on all six platforms +- [x] Candidate tarball manifest, byte counts, SHA-256 values, and npm integrity +- [ ] Publish the immutable candidate to `next` with + `publish_to_registry=true` +- [ ] Reinstall from the npm registry and verify integrity +- [ ] Promote the stable Small/runtime/native closure to `latest` +- [ ] Create the `v0.5.6` GitHub Release + +## Publication sequence + +1. Run `npm release` again from `main` with version `0.5.6` and + `publish_to_registry=true`. The workflow repeats the same build and smoke + tests before publishing only to `next`. +2. Verify registry integrity and reinstall the complete closure. +3. Run `npm promote` to move only Small `0.5.6`, runtime `0.1.6`, and the six + native `0.5.6` packages to `latest`. +4. Create the `v0.5.6` tag and GitHub Release, then update this record with the + final status and workflow IDs. + +Tiny, Medium, and Document are not part of stable promotion and remain on +`next`. No external user validation or adoption evidence blocks this release. +Every blocking gate is satisfied by the source, candidate tarballs, real +six-platform runners, and npm registry identity. + +## GitHub Release draft + +Release name: + +`墨字归真，六境同明 · Restore Chinese PDF rendering in 0.5.6` + +Highlights: + +- Fix PDF rasterization when documents reference common non-embedded Chinese + fonts. +- Bundle a checksum-pinned Noto Sans SC fallback font and its OFL license in + every supported native package. +- Keep installation and runtime fully self-contained: no postinstall download, + system-font requirement, GitHub access, or local compilation. +- Preserve the existing image, PDF, and multi-page APIs without schema changes. +- Add about 7.23 MB compressed and 8.34 MB unpacked to the one native package + selected for the customer's platform. + +Versions: + +- `@arcships/light-ocr@0.5.6` +- `@arcships/light-ocr-runtime@0.1.6` +- six native platform packages at `0.5.6` +- Document compatibility facade `0.1.2` under `next` +- Tiny/Medium preview facades `0.1.5` under `next` +- unchanged Small `0.3.4` and Tiny/Medium `0.1.0` model packages + +Verification: + +- pre-release dry-run: + +- release workflow: add after publication +- stable promotion: add after promotion diff --git a/docs/releases/npm-0.5.6.md b/docs/releases/npm-0.5.6.md index 3a46069..96ab542 100644 --- a/docs/releases/npm-0.5.6.md +++ b/docs/releases/npm-0.5.6.md @@ -1,5 +1,7 @@ # npm 0.5.6 发布准备记录 +[English version](npm-0.5.6.en.md) + 状态：发布前验证完成，尚未发布。npm registry 与 dist-tag 均保持 `0.5.5` 发布后的状态。 From cb7f7cd70216c12cf603d81dfaaadcb1ee0ed557 Mon Sep 17 00:00:00 2001 From: eric8810 Date: Thu, 30 Jul 2026 19:51:37 +0800 Subject: [PATCH 3/4] =?UTF-8?q?docs(readme):=20=E5=8D=B7=E9=A6=96=E6=96=B0?= =?UTF-8?q?=E9=99=88=EF=BC=8C=E5=BC=80=E5=8D=B7=E5=8D=B3=E6=98=8E=20=C2=B7?= =?UTF-8?q?=20rebuild=20project=20and=20npm=20guides?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize the English and Chinese project overviews around installation, primary workflows, PDF support, platform acceleration, and model selection. Replace the minimal npm README with a self-contained package guide covering image and document APIs, CLI usage, bundled offline components, resource limits, platforms, errors, and support links. --- CHANGELOG.md | 6 + README.md | 102 ++++++++---- README.zh-CN.md | 98 ++++++++---- bindings/node/README.md | 13 +- packages/light-ocr/README.md | 291 +++++++++++++++++++++++++++++++++-- 5 files changed, 432 insertions(+), 78 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index eaf5ee7..9a1374e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ This file records user-visible changes to `light-ocr`. Published artifact detail ## [0.5.6] - 2026-07-30 +### Changed + +- Reorganized the project README and replaced the minimal npm package README + with a complete install, image/PDF API, CLI, offline distribution, platform, + model-tier, resource-limit, and troubleshooting guide. + ### Fixed - Bundled the checksum-pinned Noto Sans SC regional subset into every native diff --git a/README.md b/README.md index 51b8336..d1bf7a6 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,18 @@ English | [简体中文](README.zh-CN.md) **Fast, offline OCR for Node.js and C++.** -Recognize text in PDF, JPEG, PNG, or raw image data directly on your machine. `light-ocr` returns lines in reading order with confidence scores and quadrilateral coordinates. For Node.js, the npm package includes PP-OCRv6 Small, PDFium, and prebuilt components for macOS, Linux, and Windows. +Recognize text in PDF, JPEG, PNG, or raw image data directly on your machine. +`light-ocr` returns lines in reading order with confidence scores and +quadrilateral coordinates. The Node.js package includes PP-OCRv6 Small, +PDFium, a Chinese fallback font, and prebuilt components for macOS, Linux, and +Windows—without postinstall or first-run downloads. + +| | | +| --- | --- | +| **Best for** | local OCR in Node.js apps, CLIs, desktop software, and native C++ integrations | +| **Inputs** | JPEG, PNG, PDF, encoded bytes, or decoded pixel buffers | +| **Outputs** | text, confidence, quadrilateral boxes, page metadata, and timing | +| **Distribution** | one npm install; CommonJS, ESM, TypeScript, and six prebuilt platforms | ## Quick start @@ -29,30 +40,36 @@ import { createEngine } from "@arcships/light-ocr"; import { readFile } from "node:fs/promises"; const engine = await createEngine(); -const result = await engine.recognizeEncoded( - await readFile("image.jpg"), -); -for (const line of result.lines) { - console.log(line.text, line.confidence, line.box); -} +try { + const result = await engine.recognizeEncoded( + await readFile("image.jpg"), + ); -await engine.close(); + for (const line of result.lines) { + console.log(line.text, line.confidence, line.box); + } +} finally { + await engine.close(); +} ``` -`createEngine()` automatically chooses the right execution mode for the current platform. If your application already decodes images, [`recognize()`](bindings/node/README.md#usage) also accepts `GRAY8`, `RGB8`, `BGR8`, and `RGBA8` pixel data. +`createEngine()` automatically chooses the right execution mode for the +current platform. If your application already decodes images, +[`recognize()`](packages/light-ocr/README.md#recognize-decoded-pixels) also +accepts `GRAY8`, `RGB8`, `BGR8`, and `RGBA8` pixel data. -### Model tiers +PDF pages use the same package: -Small remains the stable default. N2 also provides two opt-in preview packages under the `next` tag; all three expose the same API, types, result schema, and error model, while each install contains only its selected model. +```ts +import { recognizeDocument } from "@arcships/light-ocr"; -| Tier | Package / command | Model payload | Status | -| --- | --- | ---: | --- | -| Small | `@arcships/light-ocr` / `light-ocr` | ~30 MB | stable default | -| Tiny | `@arcships/light-ocr-tiny@next` / `light-ocr-tiny` | ~6.3 MB | preview; 49 languages, no Japanese | -| Medium | `@arcships/light-ocr-medium@next` / `light-ocr-medium` | ~139 MB | preview; quality-first | +for await (const page of recognizeDocument("report.pdf", { dpi: 200 })) { + console.log(page.index, page.lines.map((line) => line.text)); +} +``` -Tiny and Medium stay on `next` until real use shows a clear reason to promote them; they do not change what `npm install @arcships/light-ocr` installs. +CommonJS uses the same exports through `require("@arcships/light-ocr")`. ## CLI @@ -86,9 +103,10 @@ Image commands are `recognize` (default), `detect` (boxes only), `info` directly to document OCR; `document` handles explicit multi-source jobs. Output uses a versioned `schemaVersion: 1` contract. EXIF orientation is corrected automatically. See the [CLI design](docs/cli-design.md) and -[npm README](bindings/node/README.md#cli) for full reference. +[npm package README](packages/light-ocr/README.md) for the complete +install-and-use reference. -### PDF and multi-page documents +## PDF and multi-page documents PDF and multi-page OCR are built into `@arcships/light-ocr`. The matching PDFium binary and checksum-pinned Noto Sans SC fallback font are carried by @@ -124,15 +142,6 @@ for await (const page of recognizeDocument([buf1, buf2, buf3])) { } ``` -## Agent Skill - -An [Agent Skill](.agents/skills/local-ocr/SKILL.md) is included for AI agents that can call local commands. It provides scenario-driven workflows, a decision flow for command selection, and exit code reference: - -- When to use OCR vs. a multimodal model -- Detect-then-recognize two-step pattern for large images -- ROI field extraction for receipts and forms -- Verifying multimodal output against deterministic OCR - ## What you get - **Local processing.** Images, PDFs, and OCR results stay on your machine. @@ -158,7 +167,24 @@ The npm package provides the following six builds. The default `createEngine()` | Windows x64 | WebGPU through D3D12, then CPU | | Windows arm64 | CPU | -Applications that need explicit control can choose `auto`, `cpu`, `apple`, or `webgpu` through the [`execution` option](bindings/node/README.md#with-options). +Applications that need explicit control can choose `auto`, `cpu`, `apple`, or +`webgpu` through the +[`execution` option](packages/light-ocr/README.md#platform-acceleration). + +## Model tiers + +Small remains the stable default. Tiny and Medium are opt-in preview packages +under the `next` tag. All three expose the same API, types, result schema, and +error model, while each install contains only its selected model. + +| Tier | Package / command | Model payload | Status | +| --- | --- | ---: | --- | +| Small | `@arcships/light-ocr` / `light-ocr` | ~30 MB | stable default | +| Tiny | `@arcships/light-ocr-tiny@next` / `light-ocr-tiny` | ~6.3 MB | preview; 49 languages, no Japanese | +| Medium | `@arcships/light-ocr-medium@next` / `light-ocr-medium` | ~139 MB | preview; quality-first | + +Tiny and Medium stay on `next`; they do not change what +`npm install @arcships/light-ocr` installs. ## Measured performance @@ -178,10 +204,22 @@ These are same-machine comparisons with the CPU path, and results vary by worklo C++ projects build the static library from source and link the `light_ocr::core` CMake target. The API accepts decoded `GRAY8`, `RGB8`, `BGR8`, or `RGBA8` pixels; start with the [C++ API guide](docs/native-api.md) and [build instructions](docs/build-and-release.md). +## Agent Skill + +An [Agent Skill](.agents/skills/local-ocr/SKILL.md) is included for AI agents +that can call local commands. It provides scenario-driven workflows, command +selection guidance, and exit code reference: + +- When to use OCR vs. a multimodal model +- Detect-then-recognize workflows for large images +- ROI field extraction for receipts and forms +- Verifying multimodal output against deterministic OCR + ## Documentation +- [npm package README](packages/light-ocr/README.md) - [CLI reference](docs/cli-design.md) -- [Node.js API and examples](bindings/node/README.md) +- [Node.js image engine and CLI details](bindings/node/README.md) - [Agent Skill](.agents/skills/local-ocr/SKILL.md) - [C++ API](docs/native-api.md) - [Apple Silicon acceleration](docs/apple-device-acceleration.md) @@ -191,9 +229,9 @@ C++ projects build the static library from source and link the `light_ocr::core` - [Build and release](docs/build-and-release.md) - [Roadmap](docs/roadmap.md) - [Changelog](CHANGELOG.md) +- [npm 0.5.6 release preparation — English](docs/releases/npm-0.5.6.en.md) +- [npm 0.5.6 发布准备记录 — 中文](docs/releases/npm-0.5.6.md) - [npm 0.3.0 release report](docs/releases/npm-0.3.0.md) -- [npm 0.4.0 N2 candidate record](docs/releases/npm-0.4.0.md) -- [npm 0.5.0 N3 release record](docs/releases/npm-0.5.0.md) ## Community and license diff --git a/README.zh-CN.md b/README.zh-CN.md index fc0fa48..4d5ff53 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,17 @@ **面向 Node.js 与 C++ 的快速离线 OCR。** -直接在本机识别 PDF、JPEG、PNG 或像素数据，返回按阅读顺序排列的文字、置信度和四边形坐标。Node.js 用户安装的 npm 包内置 PP-OCRv6 Small 模型、PDFium，以及 macOS、Linux 和 Windows 的预编译组件。 +直接在本机识别 PDF、JPEG、PNG 或像素数据，返回按阅读顺序排列的 +文字、置信度和四边形坐标。Node.js 用户安装的 npm 包内置 PP-OCRv6 +Small 模型、PDFium、中文 fallback 字体，以及 macOS、Linux 和 Windows +的预编译组件；安装后或首次运行时无需二次下载。 + +| | | +| --- | --- | +| **适合场景** | Node.js 应用、CLI、桌面软件与原生 C++ 集成中的本地 OCR | +| **输入** | JPEG、PNG、PDF、编码后的字节或解码后的像素 | +| **输出** | 文字、置信度、四边形坐标、页面元数据与耗时 | +| **分发方式** | 一次 npm 安装；同时提供 CommonJS、ESM、TypeScript 与六个平台预编译包 | ## 快速开始 @@ -27,30 +37,35 @@ import { createEngine } from "@arcships/light-ocr"; import { readFile } from "node:fs/promises"; const engine = await createEngine(); -const result = await engine.recognizeEncoded( - await readFile("image.jpg"), -); -for (const line of result.lines) { - console.log(line.text, line.confidence, line.box); -} +try { + const result = await engine.recognizeEncoded( + await readFile("image.jpg"), + ); -await engine.close(); + for (const line of result.lines) { + console.log(line.text, line.confidence, line.box); + } +} finally { + await engine.close(); +} ``` -`createEngine()` 会根据当前平台自动选择合适的执行方式。如果应用已经完成图片解码，[`recognize()`](bindings/node/README.md#使用) 也可以直接接收 `GRAY8`、`RGB8`、`BGR8` 和 `RGBA8` 像素数据。 +`createEngine()` 会根据当前平台自动选择合适的执行方式。如果应用已经 +完成图片解码，[`recognize()`](packages/light-ocr/README.md#recognize-decoded-pixels) +也可以直接接收 `GRAY8`、`RGB8`、`BGR8` 和 `RGBA8` 像素数据。 -### 模型杯型 +PDF 页面使用同一个包： -Small 继续作为稳定默认。N2 在 `next` tag 下增加两个可选 preview 包；三档使用完全相同的 API、类型、结果 schema 和错误模型，每次安装只携带所选的一份模型。 +```ts +import { recognizeDocument } from "@arcships/light-ocr"; -| 杯型 | Package / 命令 | 模型 payload | 状态 | -| --- | --- | ---: | --- | -| Small | `@arcships/light-ocr` / `light-ocr` | 约 30 MB | 稳定默认 | -| Tiny | `@arcships/light-ocr-tiny@next` / `light-ocr-tiny` | 约 6.3 MB | Preview；49 种语言，不含日语 | -| Medium | `@arcships/light-ocr-medium@next` / `light-ocr-medium` | 约 139 MB | Preview；精度优先 | +for await (const page of recognizeDocument("report.pdf", { dpi: 200 })) { + console.log(page.index, page.lines.map((line) => line.text)); +} +``` -Tiny/Medium 只有在真实使用证明存在明确受众后才会提升 stable；它们不会改变 `npm install @arcships/light-ocr` 的安装内容。 +CommonJS 可以通过 `require("@arcships/light-ocr")` 使用同一组导出。 ## CLI @@ -83,9 +98,9 @@ light-ocr doctor --json `doctor`（系统诊断）。传入 `.pdf` 路径会直接进入文档 OCR；显式 `document` 命令用于多输入任务。输出遵循版本化的 `schemaVersion: 1` 契约，EXIF 方向自动修正。完整参考见 [CLI 设计](docs/cli-design.md) 和 -[npm README](bindings/node/README.md#cli)。 +[npm package README](packages/light-ocr/README.md)。 -### PDF 和多页文档 +## PDF 和多页文档 PDF 和多页 OCR 已直接内置于 `@arcships/light-ocr`。匹配当前平台的 PDFium 二进制、校验锁定的 Noto Sans SC fallback 字体与 OCR @@ -120,15 +135,6 @@ for await (const page of recognizeDocument([buf1, buf2, buf3])) { } ``` -## Agent Skill - -内置 [Agent Skill](.agents/skills/local-ocr/SKILL.md)，供可调用本地命令的 AI Agent 使用。提供场景驱动的工作流、命令选择决策流和退出码参考： - -- 何时使用 OCR 而非多模态模型 -- 大图先 detect 再 recognize 的两步模式 -- 票据/表单的 ROI 字段提取 -- 用确定性 OCR 验证多模态模型输出 - ## 主要能力 - **本地处理。**图片、PDF 和 OCR 结果始终留在本机。 @@ -154,7 +160,24 @@ npm 包提供以下六个平台版本。默认的 `createEngine()` 使用 Auto | Windows x64 | 通过 D3D12 使用 WebGPU，然后使用 CPU | | Windows arm64 | CPU | -需要明确控制时，可以通过 [`execution` 选项](bindings/node/README.md#使用)选择 `auto`、`cpu`、`apple` 或 `webgpu`。 +需要明确控制时，可以通过 +[`execution` 选项](packages/light-ocr/README.md#platform-acceleration) +选择 `auto`、`cpu`、`apple` 或 `webgpu`。 + +## 模型档位 + +Small 继续作为稳定默认。Tiny 和 Medium 是 `next` tag 下的可选 preview +包。三档使用完全相同的 API、类型、结果 schema 和错误模型，每次安装 +只携带所选的一份模型。 + +| 档位 | Package / 命令 | 模型 payload | 状态 | +| --- | --- | ---: | --- | +| Small | `@arcships/light-ocr` / `light-ocr` | 约 30 MB | 稳定默认 | +| Tiny | `@arcships/light-ocr-tiny@next` / `light-ocr-tiny` | 约 6.3 MB | Preview；49 种语言，不含日语 | +| Medium | `@arcships/light-ocr-medium@next` / `light-ocr-medium` | 约 139 MB | Preview；精度优先 | + +Tiny/Medium 保持在 `next`；它们不会改变 +`npm install @arcships/light-ocr` 的安装内容。 ## 实测性能 @@ -174,10 +197,21 @@ npm 包提供以下六个平台版本。默认的 `createEngine()` 使用 Auto C++ 项目从源码构建静态库，并链接 `light_ocr::core` CMake target。API 可以直接识别解码后的 `GRAY8`、`RGB8`、`BGR8` 或 `RGBA8` 像素；接入方式见 [C++ API](docs/native-api.md)，各平台准备方式见 [构建说明](docs/build-and-release.md)。 +## Agent Skill + +内置 [Agent Skill](.agents/skills/local-ocr/SKILL.md)，供可调用本地命令的 +AI Agent 使用。它提供场景驱动的工作流、命令选择建议和退出码参考： + +- 何时使用 OCR 而非多模态模型 +- 大图先 detect 再 recognize 的工作流 +- 票据/表单的 ROI 字段提取 +- 用确定性 OCR 验证多模态模型输出 + ## 文档 +- [npm package README](packages/light-ocr/README.md) - [CLI 参考](docs/cli-design.md) -- [Node.js API 与示例](bindings/node/README.md) +- [Node.js 图片引擎与 CLI 细节](bindings/node/README.md) - [Agent Skill](.agents/skills/local-ocr/SKILL.md) - [C++ API](docs/native-api.md) - [Apple Silicon 加速](docs/apple-device-acceleration.md) @@ -187,9 +221,9 @@ C++ 项目从源码构建静态库，并链接 `light_ocr::core` CMake target。 - [构建与发布](docs/build-and-release.md) - [路线图](docs/roadmap.md) - [更新日志](CHANGELOG.md) +- [npm 0.5.6 release preparation — English](docs/releases/npm-0.5.6.en.md) +- [npm 0.5.6 发布准备记录 — 中文](docs/releases/npm-0.5.6.md) - [npm 0.3.0 发布报告](docs/releases/npm-0.3.0.md) -- [npm 0.4.0 N2 候选记录](docs/releases/npm-0.4.0.md) -- [npm 0.5.0 N3 发布记录](docs/releases/npm-0.5.0.md) ## 社区与协议 diff --git a/bindings/node/README.md b/bindings/node/README.md index df67395..6a56169 100644 --- a/bindings/node/README.md +++ b/bindings/node/README.md @@ -2,6 +2,11 @@ Local OCR for Node.js and Agents. Offline, no Python, no network calls. Returns text with coordinates and confidence. +> Installing from npm? Start with the +> [`@arcships/light-ocr` package guide](../../packages/light-ocr/README.md). +> This document keeps the lower-level image engine, CLI contract, and +> source-build details. + ## Install ```bash @@ -23,6 +28,9 @@ light-ocr image.png --format json # Just text, no coordinates light-ocr image.png --format text +# PDF pages through the renderer bundled by the main package +light-ocr report.pdf --pages 1-10 --format jsonl + # Engine info light-ocr info --version light-ocr info --model-info @@ -170,7 +178,8 @@ TypeScript types are included in the shared runtime [`index.d.ts`](../../package ## Capabilities -- **Formats**: JPEG, PNG (memory input via `Uint8Array`) +- **Formats**: JPEG and PNG through the image engine; PDF and multi-page image + jobs through the main package's document API - **EXIF orientation**: JPEG orientation tags 1–8 automatically corrected - **ROI**: pageSpace axis-aligned rectangle, coordinates offset back to full page - **Providers**: CPU (all platforms), Apple Core ML (macOS arm64), WebGPU (Linux x64, Windows x64) @@ -181,7 +190,7 @@ TypeScript types are included in the shared runtime [`index.d.ts`](../../package ### Not supported -- WebP, GIF, PDF, TIFF +- WebP, GIF, TIFF - Character-level coordinates (recognition is line-level) - Multi-engine fan-out as default architecture - Bun (Node-API lifecycle not fully verified) diff --git a/packages/light-ocr/README.md b/packages/light-ocr/README.md index 4ca65fc..890f139 100644 --- a/packages/light-ocr/README.md +++ b/packages/light-ocr/README.md @@ -1,32 +1,299 @@ # @arcships/light-ocr -The stable PP-OCRv6 Small entry for local image and PDF OCR on Node.js 22 and 24. +[![npm version](https://img.shields.io/npm/v/%40arcships%2Flight-ocr?color=CB3837)](https://www.npmjs.com/package/@arcships/light-ocr) +[![Node.js 22 and 24](https://img.shields.io/badge/Node.js-22%20%7C%2024-339933)](https://nodejs.org/) +[![Apache-2.0](https://img.shields.io/npm/l/%40arcships%2Flight-ocr)](https://github.com/arcships/light-ocr/blob/main/LICENSE) + +![light-ocr](https://raw.githubusercontent.com/arcships/light-ocr/main/docs/assets/light-ocr-banner.png) + +**Offline image and PDF OCR for Node.js — prebuilt, typed, and +self-contained.** + +`@arcships/light-ocr` is the stable PP-OCRv6 Small package. It recognizes +JPEG, PNG, PDF, decoded pixels, and multi-page image jobs without Python, +cloud APIs, postinstall downloads, or local native compilation. + +| | | +| --- | --- | +| **Input** | JPEG, PNG, PDF, `Uint8Array`, or decoded pixel buffers | +| **Output** | text lines in reading order, confidence, quadrilateral boxes, and timing | +| **Runtime** | CommonJS + ESM + bundled TypeScript declarations | +| **Platforms** | macOS, Linux glibc, and Windows on x64 and ARM64 | +| **Node.js** | 22 and 24 | + +## Install ```bash npm install @arcships/light-ocr +``` + +That single command installs the Small model, shared JavaScript runtime, and +the native OCR/PDF package matching the current platform. The package has no +install script and remains installable with scripts disabled. + +## Quick start + +### Recognize an image + +```js +import { createEngine } from "@arcships/light-ocr"; +import { readFile } from "node:fs/promises"; + +const engine = await createEngine(); + +try { + const result = await engine.recognizeEncoded( + await readFile("receipt.png"), + ); + + for (const line of result.lines) { + console.log(line.text, line.confidence, line.box); + } +} finally { + await engine.close(); +} +``` + +CommonJS uses the same API: + +```js +const { createEngine } = require("@arcships/light-ocr"); +``` + +### Stream pages from a PDF + +```js +import { recognizeDocument } from "@arcships/light-ocr"; + +for await (const page of recognizeDocument("report.pdf", { + dpi: 200, + pageRange: { start: 1, end: 10 }, +})) { + console.log(`page ${page.index + 1}`); + for (const line of page.lines) console.log(line.text); +} +``` + +`recognizeDocument()` accepts a file path, PDF/image bytes, or an array of +image paths and byte buffers. Pages are yielded as they finish, so callers do +not need to retain the complete document result. + +### Use the CLI + +The `light-ocr` command is included: + +```bash +# Image OCR light-ocr image.png --format text + +# PDF OCR; PDFium and the fallback font are already installed light-ocr report.pdf --pages 1-10 --format jsonl + +# Multiple images as one document +light-ocr document scan-1.png scan-2.png scan-3.png --format text + +# Detection only +light-ocr detect screenshot.png + +# Voluntary hardware/provider diagnostics light-ocr doctor --json ``` -The package exact-pins one model-free runtime, the Small model, and the native -component, PDFium renderer, and Noto Sans SC fallback font for the current -platform. It has no install script and its complete release closure is tested -with npm offline and scripts disabled. +## Everything needed for PDF OCR is included + +The package does not defer essential files to an installer or first-run +download: + +| Component | Distribution | +| --- | --- | +| PP-OCRv6 Small model | exact-pinned required npm dependency | +| JavaScript runtime and types | exact-pinned required npm dependency | +| Native OCR addon and runtime libraries | matching platform npm dependency | +| PDFium addon and shared library | inside the matching platform package | +| Noto Sans SC fallback font and OFL license | inside the matching platform package | + +The bundled, checksum-pinned fallback font is used when a PDF references a +common Chinese font without embedding its glyphs. PDFium therefore renders the +page correctly before OCR instead of handing missing-glyph boxes to the model. + +There is no postinstall fetch, runtime font/model/PDFium download, GitHub +access, compiler requirement, or system Chinese-font requirement on customer +machines. + +## Node.js API + +### Main exports + +| Export | Purpose | +| --- | --- | +| `createEngine(options?)` | Create a reusable image OCR engine | +| `recognizeDocument(source, options?)` | Stream PDF or image pages with automatic cleanup | +| `createDocumentEngine(options?)` | Reuse one engine across multiple document jobs | +| `hasPdfSupport()` | Check that the bundled PDF renderer can be loaded | +| `modelProfile` | Inspect the selected model tier and language metadata | +| `OcrError` | Stable typed error with a machine-readable `code` | + +### Recognize decoded pixels + +Applications that already decode images can avoid re-encoding: + +```js +const result = await engine.recognize({ + data: rgbaBytes, + width, + height, + stride: width * 4, + pixelFormat: "rgba8", +}); +``` + +Supported pixel formats are `gray8`, `rgb8`, `bgr8`, and `rgba8`. + +### Region, cancellation, and execution provider ```js -const { createEngine } = require('@arcships/light-ocr'); +const controller = new AbortController(); + +const engine = await createEngine({ + execution: { provider: "auto" }, + queueCapacity: 4, +}); -const engine = await createEngine(); try { - const result = await engine.recognizeEncoded(imageBytes); + const result = await engine.recognizeEncoded(imageBytes, { + region: { x: 100, y: 80, width: 640, height: 320 }, + applyExif: true, + signal: controller.signal, + }); + console.log(result.lines); + console.log(engine.info.execution.selectionTrace); } finally { await engine.close(); } ``` -The main package exports `recognizeDocument()` and `createDocumentEngine()`. -PDFium's native files and the checksum-pinned fallback font are inside the -platform npm package, so neither install nor runtime performs a secondary -download or requires a system Chinese font. +Recognition runs on a dedicated worker instead of blocking the JavaScript main +thread. Queues are bounded, `AbortSignal` is supported, and engines must be +closed explicitly when the application is finished with them. + +### Document resource limits + +PDF and multi-page calls apply conservative defaults before or during +rendering: + +| Option | Default | +| --- | ---: | +| `dpi` | 150 | +| `maxFileBytes` | 100 MiB per input | +| `maxPages` | 100 | +| `maxPagePixels` | 4096 × 4096 | +| `maxTotalPixels` | 100 Mi pixels | + +Limits are configurable per call. Violations reject with +`OcrError.code === "resource_limit_exceeded"`. + +### Result shape + +Image OCR returns one line entry per recognized line: + +```json +{ + "text": "TOTAL 42.00", + "confidence": 0.98, + "box": [ + { "x": 24, "y": 80 }, + { "x": 190, "y": 80 }, + { "x": 190, "y": 108 }, + { "x": 24, "y": 108 } + ] +} +``` + +Coordinates use `pageSpace`: top-left origin, positive x to the right, and +positive y downward after EXIF correction. Document pages add a stable page +index, source metadata, dimensions, applied PDF transforms, and timing. + +## CLI reference + +| Command | Purpose | +| --- | --- | +| `light-ocr [recognize] ` | Full image OCR; `recognize` is optional | +| `light-ocr ` | Stream a PDF through document OCR | +| `light-ocr document ` | Process a PDF or multiple page images | +| `light-ocr detect ` | Return text-region boxes without recognition | +| `light-ocr info --version` | Print package/Core version information | +| `light-ocr info --model-info` | Print model and execution information | +| `light-ocr doctor --json` | Print voluntary system/provider diagnostics | + +Image OCR supports `--format json|jsonl|text`, `--region x,y,w,h`, +`--provider auto|cpu|apple|webgpu`, `--stdin`, and automatic EXIF correction. +Document OCR adds `--pages N-M`, `--dpi`, and the page/file/pixel limit flags. + +`detect` always emits structured JSON and does not accept `--format`. +Diagnostics do not include the hostname or a stable device identifier. + +## Platform acceleration + +The default `provider: "auto"` chooses a qualified accelerator when available +and ends with CPU as the stable fallback: + +| Platform | Auto path | +| --- | --- | +| macOS 15+ on Apple Silicon | Core ML, then CPU | +| macOS on Intel | CPU | +| Linux x64 with glibc | WebGPU through Vulkan, then CPU | +| Linux arm64 with glibc | CPU | +| Windows x64 | WebGPU through D3D12, then CPU | +| Windows arm64 | CPU | + +Explicit `cpu`, `apple`, and `webgpu` requests fail closed when the requested +provider is unavailable; they do not silently switch providers. + +## Model tiers + +This package is the stable Small tier. Tiny and Medium are opt-in previews with +the same API, types, result schema, and error model: + +| Tier | Install | Model payload | Status | +| --- | --- | ---: | --- | +| Small | `npm install @arcships/light-ocr` | about 30 MB | stable default | +| Tiny | `npm install @arcships/light-ocr-tiny@next` | about 6.3 MB | preview; 49 languages, no Japanese | +| Medium | `npm install @arcships/light-ocr-medium@next` | about 139 MB | preview; quality-first | + +Each facade installs only its selected model. + +## Errors and diagnostics + +Expected failures reject with `OcrError` and a stable `code`, including +`invalid_argument`, `invalid_image`, `resource_limit_exceeded`, +`package_load_failed`, and `inference_failed`. + +For environment reports: + +```bash +light-ocr doctor --json +``` + +For package/PDF capability checks: + +```js +import { hasPdfSupport, modelProfile } from "@arcships/light-ocr"; + +console.log(hasPdfSupport()); +console.log(modelProfile); +``` + +## Documentation + +- [Project overview](https://github.com/arcships/light-ocr) +- [Node.js and CLI reference](https://github.com/arcships/light-ocr/blob/main/bindings/node/README.md) +- [PDF 0.5.6 release notes](https://github.com/arcships/light-ocr/blob/main/docs/releases/npm-0.5.6.en.md) +- [Agent Skill](https://github.com/arcships/light-ocr/blob/main/.agents/skills/local-ocr/SKILL.md) +- [Changelog](https://github.com/arcships/light-ocr/blob/main/CHANGELOG.md) +- [Issues](https://github.com/arcships/light-ocr/issues) + +## License + +Apache-2.0. The package also carries the applicable licenses and notices for +the bundled PP-OCRv6 model, native runtimes, PDFium, and Noto Sans SC font. From 2830981a880d44e43abc068dab72c0a7637cbb96 Mon Sep 17 00:00:00 2001 From: eric8810 Date: Fri, 31 Jul 2026 10:28:27 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs(release):=20=E6=96=B0=E5=8D=B7?= =?UTF-8?q?=E7=BD=B2=E6=97=A5=EF=BC=8C=E5=A2=A8=E5=90=AF=E4=BB=8A=E6=9C=9D?= =?UTF-8?q?=20=C2=B7=20date=20the=200.5.6=20release?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align the changelog with the actual npm publication date before merging the release documentation. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a1374e..3003751 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ This file records user-visible changes to `light-ocr`. Published artifact detail ## [Unreleased] -## [0.5.6] - 2026-07-30 +## [0.5.6] - 2026-07-31 ### Changed