pdf-textlayer 0.1.0__tar.gz

pdf_textlayer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek Patel
+
+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.

pdf_textlayer-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: pdf-textlayer
+Version: 0.1.0
+Summary: Add an invisible, searchable text layer to a PDF from OCR JSON (PyMuPDF).
+Keywords: pdf,ocr,searchable,textlayer,pymupdf,liteparse,accessibility
+Author: Vivek Patel
+Author-email: Vivek Patel <me@patelvivek.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Text Processing
+Requires-Dist: pymupdf>=1.27.2.3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/patelvivekdev/pdf-textlayer
+Project-URL: Issues, https://github.com/patelvivekdev/pdf-textlayer/issues
+Project-URL: Repository, https://github.com/patelvivekdev/pdf-textlayer
+Description-Content-Type: text/markdown
+
+# pdf-textlayer
+
+Add an invisible, searchable text layer to a PDF from OCR JSON. Pages without OCR text are left exactly as in the input — native text, embedded fonts, and annotations are preserved. Built on **[PyMuPDF](https://pymupdf.readthedocs.io/)**.
+
+Published on **[PyPI](https://pypi.org/project/pdf-textlayer/)** · Developed on **[GitHub](https://github.com/patelvivekdev/pdf-textlayer)**.
+
+## What it does
+
+Given a PDF and a JSON file from an OCR pipeline, `pdf-textlayer` writes a new PDF where every OCR-detected word is drawn at its bounding box in **PDF render mode 3** (invisible glyphs). The original page content is unchanged; the new layer is what `Ctrl+F`, screen readers, and indexers see.
+
+- **Mixed PDFs are handled correctly.** A 200-page document with two scanned exhibits gets the overlay only on the scanned pages. Pages with native text are passed through untouched.
+- **Adapter-based.** Out of the box it understands [liteparse](https://github.com/run-llama/liteparse) JSON. Other sources (Azure Document Intelligence, Textract, hOCR, MinerU, your own pipeline) can be added by writing a small adapter — see [Adapters](#adapters).
+- **Minimal dependencies.** Only `pymupdf`.
+
+## Installation
+
+Python **3.11+**.
+
+```bash
+pip install pdf-textlayer
+# or
+uv add pdf-textlayer
+```
+
+This installs the `pdf-textlayer` CLI and the `pdf_textlayer` Python package.
+
+## CLI
+
+```bash
+# 1. Produce OCR JSON for your PDF (example: liteparse)
+liteparse input.pdf --format json -o parsed.json
+
+# 2. Build the searchable PDF
+pdf-textlayer input.pdf parsed.json output.pdf
+```
+
+Options:
+
+```bash
+pdf-textlayer input.pdf parsed.json output.pdf \
+    --from liteparse \           # adapter name (default: liteparse)
+    --min-confidence 0.5 \       # drop low-confidence OCR items
+    --font china-s               # CJK font for Asian-language documents
+```
+
+## Python API
+
+```python
+from pdf_textlayer import make_searchable_pdf, Options
+
+stats = make_searchable_pdf(
+    "input.pdf",
+    "parsed.json",                       # path, or already-loaded dict
+    "output.pdf",
+    adapter="liteparse",                 # default
+    options=Options(min_confidence=0.5, font="helv"),
+)
+print(stats)
+# {'pages': 19, 'ocr_pages': [1, 2, ..., 19], 'items_drawn': 7643}
+```
+
+If you already have the OCR results in memory (e.g. from another library), build `ParsedPage` objects directly and skip the adapter:
+
+```python
+from pdf_textlayer import ParsedPage, TextBox, write_textlayer
+
+pages = [
+    ParsedPage(
+        page_number=1,
+        boxes=[
+            TextBox(text="Hello", x=72.0, y=108.0, width=46.0, height=12.0, confidence=0.98),
+            TextBox(text="world", x=124.0, y=108.0, width=48.0, height=12.0, confidence=0.97),
+        ],
+    ),
+]
+write_textlayer("input.pdf", pages, "output.pdf")
+```
+
+Coordinates use PyMuPDF's convention: origin at the **top-left** of the page, `x` right, `y` down, in PDF user-space points. `(x, y)` is the top-left corner of the box.
+
+## How mixed pages are handled
+
+For each page in the input PDF, the adapter decides whether the page has OCR content to overlay:
+
+1. If the adapter yields a `ParsedPage` with non-empty `boxes` → the page receives an invisible overlay (subject to `min_confidence`).
+2. If the adapter omits the page, or yields it with no boxes → the page is left exactly as-is.
+
+For the bundled liteparse adapter, "has OCR content" means the page contains at least one `textItems` entry with `fontName == "OCR"`. Native-text items keep the real font name and are skipped, so the original PDF text is never duplicated.
+
+## Adapters
+
+An adapter is a small class that turns a source's JSON into normalized `ParsedPage` objects. The protocol is one method:
+
+```python
+from collections.abc import Iterable
+from pdf_textlayer import ParsedPage, register_adapter
+
+class MyAdapter:
+    def parse(self, data) -> Iterable[ParsedPage]:
+        for page in data["pages"]:
+            yield ParsedPage(
+                page_number=page["index"] + 1,        # 1-indexed
+                boxes=[...],                          # list[TextBox]
+            )
+
+register_adapter("mine", MyAdapter())
+# pdf-textlayer in.pdf in.json out.pdf --from mine
+```
+
+Bundled adapters:
+
+| Name | Source | Notes |
+|------|--------|-------|
+| `liteparse` | [liteparse](https://github.com/run-llama/liteparse) `--format json` | Items with `fontName == "OCR"` per the [OCR API spec](https://github.com/run-llama/liteparse/blob/main/OCR_API_SPEC.md). |
+
+PRs adding more adapters (Azure DI, Textract, hOCR, …) are welcome.
+
+## Fonts and non-Latin text
+
+The default font (`helv` = Helvetica) covers Latin-1. Unsupported glyphs are replaced with `?` so each item still emits a usable text run; set `Options(sanitize_unsupported=False)` to drop those items instead.
+
+For CJK documents, pass a bundled PyMuPDF font:
+
+```bash
+pdf-textlayer in.pdf parsed.json out.pdf --font china-s
+# china-s, china-t, japan, korea — bundled with PyMuPDF
+```
+
+## How the overlay is drawn
+
+For each box, the font is scaled so the rendered text width matches the box width. The insertion point is the glyph baseline, placed at `(x, y + height)`. Text is written with PDF render mode 3 — present in the content stream, never painted — so search, copy/paste, and assistive tech work, but the visible page is unchanged.
+
+## Limitations
+
+- **Rotated text is drawn upright.** OCR sources that don't include rotation metadata can't be rendered rotated; in practice most pipelines de-rotate before emitting boxes.
+- **Invisible text uses PDF render mode 3.** All modern viewers and search indexers handle this correctly; very old tooling may not extract it.
+- **No de-duplication across overlay and native text.** If you point the tool at native-text pages but the adapter treats them as OCR, you'll get duplicated search hits. The bundled `liteparse` adapter avoids this by filtering on `fontName`.
+
+## Contributing
+
+Bug reports, docs improvements, and new adapters are welcome — open an issue or PR on [GitHub](https://github.com/patelvivekdev/pdf-textlayer/issues).
+
+## License
+
+Released under the **MIT License**. See [`LICENSE`](LICENSE) for the full text.

pdf_textlayer-0.1.0/README.md

@@ -0,0 +1,145 @@
+# pdf-textlayer
+
+Add an invisible, searchable text layer to a PDF from OCR JSON. Pages without OCR text are left exactly as in the input — native text, embedded fonts, and annotations are preserved. Built on **[PyMuPDF](https://pymupdf.readthedocs.io/)**.
+
+Published on **[PyPI](https://pypi.org/project/pdf-textlayer/)** · Developed on **[GitHub](https://github.com/patelvivekdev/pdf-textlayer)**.
+
+## What it does
+
+Given a PDF and a JSON file from an OCR pipeline, `pdf-textlayer` writes a new PDF where every OCR-detected word is drawn at its bounding box in **PDF render mode 3** (invisible glyphs). The original page content is unchanged; the new layer is what `Ctrl+F`, screen readers, and indexers see.
+
+- **Mixed PDFs are handled correctly.** A 200-page document with two scanned exhibits gets the overlay only on the scanned pages. Pages with native text are passed through untouched.
+- **Adapter-based.** Out of the box it understands [liteparse](https://github.com/run-llama/liteparse) JSON. Other sources (Azure Document Intelligence, Textract, hOCR, MinerU, your own pipeline) can be added by writing a small adapter — see [Adapters](#adapters).
+- **Minimal dependencies.** Only `pymupdf`.
+
+## Installation
+
+Python **3.11+**.
+
+```bash
+pip install pdf-textlayer
+# or
+uv add pdf-textlayer
+```
+
+This installs the `pdf-textlayer` CLI and the `pdf_textlayer` Python package.
+
+## CLI
+
+```bash
+# 1. Produce OCR JSON for your PDF (example: liteparse)
+liteparse input.pdf --format json -o parsed.json
+
+# 2. Build the searchable PDF
+pdf-textlayer input.pdf parsed.json output.pdf
+```
+
+Options:
+
+```bash
+pdf-textlayer input.pdf parsed.json output.pdf \
+    --from liteparse \           # adapter name (default: liteparse)
+    --min-confidence 0.5 \       # drop low-confidence OCR items
+    --font china-s               # CJK font for Asian-language documents
+```
+
+## Python API
+
+```python
+from pdf_textlayer import make_searchable_pdf, Options
+
+stats = make_searchable_pdf(
+    "input.pdf",
+    "parsed.json",                       # path, or already-loaded dict
+    "output.pdf",
+    adapter="liteparse",                 # default
+    options=Options(min_confidence=0.5, font="helv"),
+)
+print(stats)
+# {'pages': 19, 'ocr_pages': [1, 2, ..., 19], 'items_drawn': 7643}
+```
+
+If you already have the OCR results in memory (e.g. from another library), build `ParsedPage` objects directly and skip the adapter:
+
+```python
+from pdf_textlayer import ParsedPage, TextBox, write_textlayer
+
+pages = [
+    ParsedPage(
+        page_number=1,
+        boxes=[
+            TextBox(text="Hello", x=72.0, y=108.0, width=46.0, height=12.0, confidence=0.98),
+            TextBox(text="world", x=124.0, y=108.0, width=48.0, height=12.0, confidence=0.97),
+        ],
+    ),
+]
+write_textlayer("input.pdf", pages, "output.pdf")
+```
+
+Coordinates use PyMuPDF's convention: origin at the **top-left** of the page, `x` right, `y` down, in PDF user-space points. `(x, y)` is the top-left corner of the box.
+
+## How mixed pages are handled
+
+For each page in the input PDF, the adapter decides whether the page has OCR content to overlay:
+
+1. If the adapter yields a `ParsedPage` with non-empty `boxes` → the page receives an invisible overlay (subject to `min_confidence`).
+2. If the adapter omits the page, or yields it with no boxes → the page is left exactly as-is.
+
+For the bundled liteparse adapter, "has OCR content" means the page contains at least one `textItems` entry with `fontName == "OCR"`. Native-text items keep the real font name and are skipped, so the original PDF text is never duplicated.
+
+## Adapters
+
+An adapter is a small class that turns a source's JSON into normalized `ParsedPage` objects. The protocol is one method:
+
+```python
+from collections.abc import Iterable
+from pdf_textlayer import ParsedPage, register_adapter
+
+class MyAdapter:
+    def parse(self, data) -> Iterable[ParsedPage]:
+        for page in data["pages"]:
+            yield ParsedPage(
+                page_number=page["index"] + 1,        # 1-indexed
+                boxes=[...],                          # list[TextBox]
+            )
+
+register_adapter("mine", MyAdapter())
+# pdf-textlayer in.pdf in.json out.pdf --from mine
+```
+
+Bundled adapters:
+
+| Name | Source | Notes |
+|------|--------|-------|
+| `liteparse` | [liteparse](https://github.com/run-llama/liteparse) `--format json` | Items with `fontName == "OCR"` per the [OCR API spec](https://github.com/run-llama/liteparse/blob/main/OCR_API_SPEC.md). |
+
+PRs adding more adapters (Azure DI, Textract, hOCR, …) are welcome.
+
+## Fonts and non-Latin text
+
+The default font (`helv` = Helvetica) covers Latin-1. Unsupported glyphs are replaced with `?` so each item still emits a usable text run; set `Options(sanitize_unsupported=False)` to drop those items instead.
+
+For CJK documents, pass a bundled PyMuPDF font:
+
+```bash
+pdf-textlayer in.pdf parsed.json out.pdf --font china-s
+# china-s, china-t, japan, korea — bundled with PyMuPDF
+```
+
+## How the overlay is drawn
+
+For each box, the font is scaled so the rendered text width matches the box width. The insertion point is the glyph baseline, placed at `(x, y + height)`. Text is written with PDF render mode 3 — present in the content stream, never painted — so search, copy/paste, and assistive tech work, but the visible page is unchanged.
+
+## Limitations
+
+- **Rotated text is drawn upright.** OCR sources that don't include rotation metadata can't be rendered rotated; in practice most pipelines de-rotate before emitting boxes.
+- **Invisible text uses PDF render mode 3.** All modern viewers and search indexers handle this correctly; very old tooling may not extract it.
+- **No de-duplication across overlay and native text.** If you point the tool at native-text pages but the adapter treats them as OCR, you'll get duplicated search hits. The bundled `liteparse` adapter avoids this by filtering on `fontName`.
+
+## Contributing
+
+Bug reports, docs improvements, and new adapters are welcome — open an issue or PR on [GitHub](https://github.com/patelvivekdev/pdf-textlayer/issues).
+
+## License
+
+Released under the **MIT License**. See [`LICENSE`](LICENSE) for the full text.

pdf_textlayer-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "pdf-textlayer"
+version = "0.1.0"
+description = "Add an invisible, searchable text layer to a PDF from OCR JSON (PyMuPDF)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Vivek Patel", email = "me@patelvivek.dev" }
+]
+requires-python = ">=3.11"
+keywords = ["pdf", "ocr", "searchable", "textlayer", "pymupdf", "liteparse", "accessibility"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Text Processing",
+]
+dependencies = [
+    "pymupdf>=1.27.2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/patelvivekdev/pdf-textlayer"
+Repository = "https://github.com/patelvivekdev/pdf-textlayer"
+Issues = "https://github.com/patelvivekdev/pdf-textlayer/issues"
+
+[project.scripts]
+pdf-textlayer = "pdf_textlayer:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.9.0",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "SIM",    # flake8-simplify
+]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["pdf_textlayer"]

pdf_textlayer-0.1.0/src/pdf_textlayer/__init__.py

@@ -0,0 +1,28 @@
+"""Add an invisible, searchable text layer to a PDF from OCR JSON."""
+
+from __future__ import annotations
+
+from .adapters import Adapter, LiteparseAdapter, get_adapter, register_adapter
+from .cli import main
+from .core import (
+    Options,
+    ParsedPage,
+    Stats,
+    TextBox,
+    make_searchable_pdf,
+    write_textlayer,
+)
+
+__all__ = [
+    "Adapter",
+    "LiteparseAdapter",
+    "Options",
+    "ParsedPage",
+    "Stats",
+    "TextBox",
+    "get_adapter",
+    "main",
+    "make_searchable_pdf",
+    "register_adapter",
+    "write_textlayer",
+]

pdf_textlayer-0.1.0/src/pdf_textlayer/adapters.py

@@ -0,0 +1,131 @@
+"""Adapters that translate OCR-source JSON into :class:`ParsedPage` objects.
+
+An adapter is anything that implements the :class:`Adapter` protocol —
+typically a small class with a ``parse(data) -> Iterable[ParsedPage]``
+method. New adapters can be plugged in at runtime with
+:func:`register_adapter`.
+
+Currently bundled:
+
+* ``"liteparse"`` — :class:`LiteparseAdapter`, for JSON produced by
+  `liteparse <https://github.com/run-llama/liteparse>`_'s ``--format json``
+  output. liteparse tags OCR-derived text items with
+  ``fontName == "OCR"``; native-text items keep the real font name and
+  are skipped here so the original PDF text stays untouched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol, runtime_checkable
+
+from .core import ParsedPage, TextBox
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Protocol for OCR-source adapters.
+
+    Implementations take a deserialized JSON document and yield one
+    :class:`ParsedPage` per page that carries OCR text. Pages with no OCR
+    text may be omitted (or yielded with an empty ``boxes`` list — both
+    are treated identically by the core).
+    """
+
+    def parse(self, data: Any) -> Iterable[ParsedPage]: ...
+
+
+class LiteparseAdapter:
+    """Adapter for `liteparse <https://github.com/run-llama/liteparse>`_ JSON.
+
+    Expected shape (simplified)::
+
+        {
+          "pages": [
+            {
+              "page": 1,
+              "textItems": [
+                {
+                  "text": "Hello",
+                  "x": 10, "y": 20,
+                  "width": 60, "height": 14,
+                  "fontName": "OCR",
+                  "confidence": 0.95
+                },
+                ...
+              ]
+            },
+            ...
+          ]
+        }
+
+    Only items with ``fontName == "OCR"`` are emitted — native-text items
+    are left to the original PDF.
+    """
+
+    OCR_FONT_MARKER = "OCR"
+
+    def parse(self, data: dict[str, Any]) -> Iterable[ParsedPage]:
+        for page in data.get("pages", []):
+            page_no = page.get("page")
+            if not isinstance(page_no, int):
+                continue
+            boxes = list(self._page_boxes(page))
+            if boxes:
+                yield ParsedPage(page_number=page_no, boxes=boxes)
+
+    def _page_boxes(self, page: dict[str, Any]) -> Iterable[TextBox]:
+        for item in page.get("textItems", []):
+            if item.get("fontName") != self.OCR_FONT_MARKER:
+                continue
+            text = (item.get("text") or "").strip()
+            if not text:
+                continue
+            try:
+                width = float(item.get("width") or 0)
+                height = float(item.get("height") or 0)
+                x = float(item["x"])
+                y = float(item["y"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if width <= 0 or height <= 0:
+                continue
+            yield TextBox(
+                text=text,
+                x=x,
+                y=y,
+                width=width,
+                height=height,
+                confidence=float(item.get("confidence") or 1.0),
+            )
+
+
+_REGISTRY: dict[str, Adapter] = {
+    "liteparse": LiteparseAdapter(),
+}
+
+
+def get_adapter(name: str) -> Adapter:
+    """Look up a registered adapter by name.
+
+    Raises:
+        KeyError: If ``name`` is not registered.
+    """
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        known = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise KeyError(f"Unknown adapter {name!r}. Registered: {known}") from None
+
+
+def register_adapter(name: str, adapter: Adapter) -> None:
+    """Register a custom adapter under ``name``.
+
+    Overwrites any existing entry with the same name.
+    """
+    _REGISTRY[name] = adapter
+
+
+def available_adapters() -> list[str]:
+    """Return the names of all registered adapters."""
+    return sorted(_REGISTRY)

pdf_textlayer-0.1.0/src/pdf_textlayer/cli.py

@@ -0,0 +1,89 @@
+"""CLI: take a raw PDF + OCR JSON, write a PDF with an invisible text layer."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .adapters import available_adapters
+from .core import DEFAULT_FONT, Options, make_searchable_pdf
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="pdf-textlayer",
+        description=(
+            "Add an invisible, searchable text layer to a PDF using OCR JSON. "
+            "Pages without OCR text are left untouched."
+        ),
+    )
+    p.add_argument(
+        "input_pdf",
+        type=Path,
+        help="Source PDF (scanned, native, or mixed).",
+    )
+    p.add_argument(
+        "parsed_json",
+        type=Path,
+        help="OCR JSON for the source PDF (see --from for supported formats).",
+    )
+    p.add_argument(
+        "output_pdf",
+        type=Path,
+        help="Path to write the resulting PDF.",
+    )
+    p.add_argument(
+        "--from",
+        dest="adapter",
+        default="liteparse",
+        choices=available_adapters(),
+        help="JSON adapter to use. Default: liteparse.",
+    )
+    p.add_argument(
+        "--min-confidence",
+        type=float,
+        default=0.0,
+        help="Drop OCR items below this confidence (0–1). Default: 0.",
+    )
+    p.add_argument(
+        "--font",
+        default=DEFAULT_FONT,
+        help=(
+            "PyMuPDF font name. Use a CJK font (china-s, china-t, japan, "
+            f"korea) for Asian docs. Default: {DEFAULT_FONT}."
+        ),
+    )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not args.input_pdf.exists():
+        print(f"Input PDF not found: {args.input_pdf}", file=sys.stderr)
+        return 1
+    if not args.parsed_json.exists():
+        print(f"Parsed JSON not found: {args.parsed_json}", file=sys.stderr)
+        return 1
+
+    stats = make_searchable_pdf(
+        args.input_pdf,
+        args.parsed_json,
+        args.output_pdf,
+        adapter=args.adapter,
+        options=Options(min_confidence=args.min_confidence, font=args.font),
+    )
+
+    print(f"Wrote: {args.output_pdf}")
+    print(f"Pages: {stats['pages']}")
+    print(
+        f"Text layer added on {len(stats['ocr_pages'])} page(s): "
+        f"{', '.join(map(str, stats['ocr_pages'])) or '(none)'}"
+    )
+    print(f"Items drawn: {stats['items_drawn']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdf_textlayer-0.1.0/src/pdf_textlayer/core.py

@@ -0,0 +1,277 @@
+"""Draw an invisible text layer over a PDF.
+
+The package separates two concerns:
+
+* **Adapters** (see :mod:`pdf_textlayer.adapters`) translate a source-specific
+  JSON shape into :class:`ParsedPage` objects.
+* **Core** (this module) takes those :class:`ParsedPage` objects and draws an
+  invisible PDF text layer at each box's location, so the page becomes
+  selectable and searchable in any viewer.
+
+Pages without OCR boxes are left exactly as in the input PDF — native text and
+embedded searchability are preserved. This handles mixed scanned / native
+documents without re-rasterizing.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypedDict
+
+import pymupdf
+
+if TYPE_CHECKING:
+    from .adapters import Adapter
+
+log = logging.getLogger(__name__)
+
+# PyMuPDF render mode 3 = "neither fill nor stroke". The glyphs are present in
+# the content stream (so text extraction, search, and accessibility tools find
+# them) but never painted.
+_INVISIBLE_RENDER_MODE = 3
+
+# Base-14 font available in every PDF reader without embedding. CJK and other
+# non-Latin characters get transliterated to "?" unless an embedded font is
+# selected — the text layer is for search, not visual fidelity.
+DEFAULT_FONT = "helv"
+
+
+@dataclass(frozen=True)
+class TextBox:
+    """A single piece of OCR text to draw, in PDF user-space points.
+
+    Coordinates use PyMuPDF's convention: origin at the top-left of the
+    page, X increases right, Y increases down. ``(x, y)`` is the top-left
+    corner of the box.
+    """
+
+    text: str
+    x: float
+    y: float
+    width: float
+    height: float
+    confidence: float = 1.0
+
+
+@dataclass(frozen=True)
+class ParsedPage:
+    """OCR boxes for a single page of the source PDF.
+
+    ``page_number`` is 1-indexed and matches the page in the input PDF
+    that should receive the overlay. Pages not present in the iterable
+    are left untouched.
+    """
+
+    page_number: int
+    boxes: list[TextBox] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Options:
+    """Drawing options for :func:`write_textlayer` / :func:`make_searchable_pdf`."""
+
+    min_confidence: float = 0.0
+    """Drop boxes whose confidence is below this threshold (0.0–1.0).
+
+    ``0.0`` keeps everything.
+    """
+
+    font: str = DEFAULT_FONT
+    """PyMuPDF font name.
+
+    Built-in: ``helv``, ``cour``, ``tiro``. Bundled CJK fonts: ``china-s``,
+    ``china-t``, ``japan``, ``korea``.
+    """
+
+    sanitize_unsupported: bool = True
+    """If True, replace glyphs the font cannot encode with ``?``.
+
+    If False, items containing unsupported glyphs are dropped so they
+    don't silently emit empty content streams.
+    """
+
+
+class Stats(TypedDict):
+    """Summary returned from a successful overlay pass."""
+
+    pages: int
+    ocr_pages: list[int]
+    items_drawn: int
+
+
+def _sanitize(text: str, font: pymupdf.Font) -> str:
+    """Replace characters the font can't encode with ``?``.
+
+    ``page.insert_text`` silently drops unsupported glyphs, which means
+    a single bad codepoint can erase the entire item. Sanitizing
+    preserves the rest of the string so search still hits the word.
+    """
+    out: list[str] = []
+    for ch in text:
+        try:
+            keep = font.glyph_advance(ord(ch)) > 0
+        except Exception:
+            keep = False
+        out.append(ch if keep else "?")
+    return "".join(out)
+
+
+def _draw_box(
+    page: pymupdf.Page,
+    font: pymupdf.Font,
+    box: TextBox,
+    opts: Options,
+) -> bool:
+    """Draw a single invisible text box. Returns True if anything was drawn."""
+    text = box.text
+    if opts.sanitize_unsupported:
+        text = _sanitize(text, font)
+    if not text:
+        return False
+
+    # Scale font so the string's rendered width matches the OCR bbox width.
+    # This is what makes word-level highlights line up when a user
+    # searches inside Acrobat / Preview / browser PDF viewers.
+    width_at_1pt = font.text_length(text, fontsize=1)
+    if width_at_1pt <= 0:
+        return False
+    font_size = box.width / width_at_1pt
+    # Sanity cap: if the bbox is wide-but-short (single tall glyph or an
+    # unhandled rotation), don't blow the font size up absurdly.
+    font_size = min(font_size, max(box.height * 1.2, 1.0))
+
+    # The insertion point is the glyph baseline, so add `height` to drop
+    # from the top of the bbox down to where the baseline should sit.
+    page.insert_text(
+        (box.x, box.y + box.height),
+        text,
+        fontname=opts.font,
+        fontsize=font_size,
+        render_mode=_INVISIBLE_RENDER_MODE,
+        # Color is irrelevant under render_mode=3, but PyMuPDF requires it.
+        color=(0, 0, 0),
+    )
+    return True
+
+
+def write_textlayer(
+    input_pdf: str | Path,
+    pages: Iterable[ParsedPage],
+    output_pdf: str | Path,
+    *,
+    options: Options | None = None,
+) -> Stats:
+    """Draw an invisible text layer onto ``input_pdf`` and save it to ``output_pdf``.
+
+    This is the low-level entry point: it takes already-normalized
+    :class:`ParsedPage` objects, so any OCR source can be plugged in by
+    writing an adapter (see :mod:`pdf_textlayer.adapters`) or by
+    constructing :class:`ParsedPage` instances directly.
+
+    Pages whose ``page_number`` does not appear in ``pages`` — or that
+    contribute no drawable boxes after filtering — are left untouched.
+
+    Args:
+        input_pdf: Path to the source PDF.
+        pages: Iterable of :class:`ParsedPage`. Order does not matter.
+        output_pdf: Where to write the result. Overwritten if it exists.
+        options: Drawing options.
+
+    Returns:
+        :class:`Stats` summarizing what was written.
+    """
+    opts = options or Options()
+    pages_by_num: dict[int, ParsedPage] = {p.page_number: p for p in pages}
+
+    doc = pymupdf.open(str(input_pdf))
+    try:
+        font = pymupdf.Font(opts.font)
+        ocr_page_nums: list[int] = []
+        items_drawn = 0
+
+        for idx in range(doc.page_count):
+            pageno = idx + 1
+            parsed = pages_by_num.get(pageno)
+            if parsed is None or not parsed.boxes:
+                continue
+
+            page = doc[idx]
+            drawn_on_page = 0
+            for box in parsed.boxes:
+                if box.confidence < opts.min_confidence:
+                    continue
+                if box.width <= 0 or box.height <= 0:
+                    continue
+                if not box.text.strip():
+                    continue
+                if _draw_box(page, font, box, opts):
+                    drawn_on_page += 1
+
+            if drawn_on_page:
+                ocr_page_nums.append(pageno)
+                items_drawn += drawn_on_page
+
+        # Plain save keeps the input PDF's structure intact (image streams,
+        # fonts, annotations) and just appends the overlay objects.
+        doc.save(str(output_pdf))
+
+        return Stats(
+            pages=doc.page_count,
+            ocr_pages=ocr_page_nums,
+            items_drawn=items_drawn,
+        )
+    finally:
+        doc.close()
+
+
+def make_searchable_pdf(
+    input_pdf: str | Path,
+    source: str | Path | dict[str, Any] | Iterable[ParsedPage],
+    output_pdf: str | Path,
+    *,
+    adapter: Adapter | str = "liteparse",
+    options: Options | None = None,
+) -> Stats:
+    """Generate a searchable PDF from a raw PDF plus an OCR JSON source.
+
+    This is the convenience entry point: it accepts a JSON path / dict /
+    pre-built iterable of :class:`ParsedPage`, runs it through the chosen
+    adapter, and writes the overlay.
+
+    Args:
+        input_pdf: Path to the source PDF (scanned, native, or mixed).
+        source: One of —
+
+            * a path (``str`` / ``Path``) to a JSON file,
+            * an already-loaded ``dict``,
+            * or an iterable of :class:`ParsedPage` (in which case
+              ``adapter`` is ignored).
+        output_pdf: Where to write the searchable PDF.
+        adapter: An :class:`~pdf_textlayer.adapters.Adapter` instance or
+            the name of a registered adapter. Defaults to ``"liteparse"``.
+        options: Drawing options.
+
+    Returns:
+        :class:`Stats` summarizing what was written.
+    """
+    if _looks_like_pages(source):
+        return write_textlayer(input_pdf, source, output_pdf, options=options)  # type: ignore[arg-type]
+
+    from .adapters import get_adapter
+
+    adp = get_adapter(adapter) if isinstance(adapter, str) else adapter
+    data = source if isinstance(source, dict) else json.loads(Path(source).read_text())  # type: ignore[arg-type]
+    return write_textlayer(input_pdf, adp.parse(data), output_pdf, options=options)
+
+
+def _looks_like_pages(source: Any) -> bool:
+    """True if ``source`` is already an iterable of ParsedPage."""
+    if isinstance(source, (str, Path, dict, bytes)):
+        return False
+    if isinstance(source, list):
+        return all(isinstance(p, ParsedPage) for p in source)
+    return False